> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/administrator-guide/telemetria/como-habilitar-opentelemetry-no-oz-api.md). # Como habilitar OpenTelemetry no Oz API {% hint style="warning" %} OpenTelemetry requer a versão do Oz API **6.6.1** ou superior. {% endhint %} A solução descrita abaixo é baseada em [instrumentação zero-code do Python](https://opentelemetry.io/docs/zero-code/python). Oz API oferece suporte à auto-instrumentação de **traces** somente – métricas e logs não são suportados. A ativação depende do método de implantação – veja as seções Kubernetes e Docker abaixo. O conjunto de variáveis de ambiente é o mesmo para ambas as opções e está listado na seção Variáveis de ambiente. Exemplo de traces no Jaeger:

### Kubernetes {% hint style="info" %} Com suporte desde a versão **oz-k8s/0.20.29**. {% endhint %} Quando `opentelemetry` está habilitado, o chart envolve o processo do Oz API em `opentelemetry-instrument` e envia traces para o coletor OTLP. Ative a auto-instrumentação e especifique o endereço do coletor. `OTEL_EXPORTER_OTLP_ENDPOINT` é a única variável obrigatória: ```yaml Parâmetros: gunicorn: opentelemetry: enable: true envs: OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317" # ponto de extremidade gRPC do coletor OTLP OTEL_EXPORTER_OTLP_INSECURE: "true" # defina isto se o coletor não tiver TLS ``` As variáveis restantes são passadas da mesma forma, por meio de `Params.gunicorn.envs`. ### Docker Para ativar a auto-instrumentação, defina a variável de ambiente `OTEL_ENABLE=true` e especifique o endpoint gRPC do coletor na `OTEL_EXPORTER_OTLP_ENDPOINT` variável ao iniciar o contêiner: ```shell docker run -e OTEL_ENABLE=true -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 ... ``` Isso é suficiente – traces começarão a ser enviados ao coletor OTLP especificado por gRPC. {% hint style="info" %} Se `OTEL_ENABLE` não está definido como `true`, a aplicação inicia sem o `opentelemetry-instrument` wrapper. {% endhint %} ### Variáveis de ambiente A seguir estão os principais parâmetros de configuração da `OTEL_TRACES_EXPORTER=otlp` opção. Informações detalhadas sobre a configuração do agente OTEL estão disponíveis no [OpenTelemetry](https://opentelemetry.io/docs/zero-code/python/configuration/) site.

Variável	Descrição	Valor padrão
`OTEL_ENABLE`	Somente Docker. Ativa a auto-instrumentação do OTEL (`true` / não definido). Quando definido como `true`, ele inicia a auto-instrumentação do OpenTelemetry via o script start.sh. Esse script é usado por padrão ao iniciar a imagem oz-api. Se você substituir o `ENTRYPOINT` ao iniciar o contêiner, é necessário adicionar explicitamente a inicialização da aplicação com o `opentelemetry-instrument` wrapper: `opentelemetry-instrument gunicorn oz_api.asgi:application <...>`. Esta variável não é usada no chart do Kubernetes – a ativação é definida por meio de `opentelemetry.enable: true`.	não definido (desativado)
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endereço do coletor OTLP	não definido (deve ser especificado ao ativar)
`OTEL_SERVICE_NAME`	Nome do serviço nos traces	`oz-api.python.otel`
`OTEL_TRACES_EXPORTER`	Exportador de traces. Valores possíveis: `otlp` – OTLP; `jaeger` – exportar no modelo de dados do Jaeger; `zipkin` – Zipkin; `console` – Saída padrão; `nenhuma` – não são usados exportadores com configuração automática	`otlp`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Protocolo de exportação. Valores possíveis: `grpc` para OTLP/gRPC; `http/protobuf` para OTLP/HTTP + `protobuf`; `http/json` para OTLP/HTTP + JSON	`grpc`
`OTEL_METRICS_EXPORTER`	Exportador de métricas, não suportado	`nenhuma`
`OTEL_LOGS_EXPORTER`	Exportador de logs, não suportado	`nenhuma`
`OTEL_PROPAGATORS`	Formatos de contexto de propagação. Valores possíveis: `tracecontext` – W3C Trace Context; `baggage` – W3C Baggage; `b3` – B3 Single; `b3multi` – B3 Multi; `jaeger` – Jaeger; `xray` – AWS X-Ray; `ottrace` – OT Trace; `nenhuma` – não são usados propagadores com configuração automática	`tracecontext,baggage`
`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`	Auto-instrumentações desativadas	`psycopg2`
`OTEL_EXPORTER_OTLP_INSECURE`	Desativa TLS para a chamada gRPC à API do coletor OTLP. Para endpoints que não usam criptografia TLS, defina `true`.	não definido (TLS é usado)

### Notas * `psycopg2` a auto-instrumentação está desativada por padrão, caso contrário os dados coletados podem ser excessivos. Spans detalhados são entregues por meio de `sqlalchemy` auto-instrumentação. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/administrator-guide/telemetria/como-habilitar-opentelemetry-no-oz-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.