Instrumentação com OpenTelemetry Operator

Depois de instalar o OpenTelemetry Operator, você precisa configurar a instrumentação para monitorar suas aplicações em namespaces específicos. A seguir, detalhamos os passos para realizar isso de forma simples, eficiente e com suporte a várias linguagens. 🌟

🧭 Caso ainda não tenha realizado a instalação do OpenTelemetry Operator, volte para o guia principal em: https://docs.elven.works/instrumentacao-em-kubernetes/

⚡ Passo 1: Criar o Arquivo de Instrumentação

No repositório stack-observability, já existe um arquivo instrumentation.yaml com configurações completas e exemplos por linguagem. Utilize-o como base e edite conforme o necessário.

Trecho do exemplo disponível:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: instrumentation
  namespace: default
spec:
  exporter:
    endpoint: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318"
  propagators:
    - tracecontext
    - baggage
    - b3
  sampler:
    type: parentbased_traceidratio
    argument: "1"

  go:
    image: "grafana/beyla:latest"
    env:
      - name: BEYLA_METRICS_ENABLED
        value: "true"
      - name: OTEL_METRICS_EXPORTER
        value: "otlp"
      - name: BEYLA_OPEN_PORT
        value: "8080"
      - name: BEYLA_BPF_TRACK_REQUEST_HEADERS
        value: "true"
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318"
  nodejs:
    env:
      - name: OTEL_NODE_RESOURCE_DETECTORS
        value: all
      - name: OTEL_TRACES_EXPORTER
        value: "otlp"
      - name: OTEL_METRICS_EXPORTER
        value: "otlp"
      - name: OTEL_NODE_ENABLED_INSTRUMENTATIONS
        value: "all"
      - name: OTEL_NODE_DISABLED_INSTRUMENTATIONS
        value: "fs"
      - name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
        value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318/v1/traces"
      - name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
        value: "http://opentelemetrycollector.monitoring.svc.cluster.local:4318/v1/metrics"
  java:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://opentelemetrycollector.monitoring.svc.cluster.local:4317
  dotnet:
    env:
      - name: OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
        value: "false"

🚀 Passo 2: Aplicar o Arquivo no Cluster

kubectl apply -f instrumentation.yaml

📌 Resultado esperado: Suas aplicações começarão a enviar traces e métricas automaticamente para o Collector.

🛠️ Passo 3: Adicionar Anotações para Instrumentação Automática

Adicione anotações específicas no Deployment, StatefulSet ou Pod para ativar a instrumentação automática.

Exemplos por Linguagem:

annotations:
  instrumentation.opentelemetry.io/inject-nodejs: "true"
  instrumentation.opentelemetry.io/inject-java: "true"
  instrumentation.opentelemetry.io/inject-python: "true"
  instrumentation.opentelemetry.io/inject-dotnet: "true"
  instrumentation.opentelemetry.io/inject-go: "true"

📝 Dica: Adicione essas anotações diretamente no deployment.yaml da aplicação.

✅ Passo 4: Verificar a Instrumentação

Após adicionar as anotações, o Operator irá injetar automaticamente os agentes nas aplicações.

Como verificar:

Confirme que os pods têm sidecars ou init containers com os agentes otel
Verifique se traces e métricas aparecem no Grafana ou outro backend

🎯 Ajustando o Sampling (Taxa de Amostragem)

No bloco spec.sampler do instrumentation.yaml, defina a taxa de amostragem para controlar a quantidade de traces gerados:

sampler:
  type: parentbased_traceidratio
  argument: "1"     # 1 = 100% das requisições, 0.5 = 50%, 0.1 = 10%, etc

Use 100% em ambientes de teste e reduza em produção para evitar sobrecarga.

🧯 Troubleshooting

Problema	Causa Possível	Solução
Aplicação não envia traces	Annotation ausente ou errada	Verifique se o `Deployment` tem a annotation correta para a linguagem
Métricas não aparecem no Grafana	Variáveis de ambiente de exportação ausentes	Confirme as variáveis `OTEL_EXPORTER_OTLP_*` no bloco da linguagem
Collector não recebe dados	Endpoint incorreto ou porta errada	Verifique a URL `http://opentelemetrycollector.monitoring.svc.cluster.local:4318`
O agente não é injetado	Namespace errado no `instrumentation.yaml`	Verifique se o namespace da aplicação é o mesmo da CRD
Uso alto de CPU	Sampling 100% em produção ou coleta de métricas desnecessárias	Ajuste `argument` para valores como `0.1` e revise os exporters habilitados

📘 Referência

✨ Agora sua aplicação está pronta para observabilidade de verdade com instrumentação automática e coleta de métricas e traces em tempo real! 🚀