# 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](https://opentelemetry.io/docs/kubernetes/operator/)
* [Exemplo no repositório Elven Observability](https://github.com/elven-observability/stack-observability-k8s/tree/main/opentelemetry-operator)

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!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elven.works/elven-platform/elven-observability/integracao-e-instrumentacao/opentelemetry/instrumentacao-com-opentelemetry-operator.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.