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.

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

• Documentação Oficial do Operator

• Exemplo no repositório Elven Observability

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!