Como habilitar OpenTelemetry no Oz API

OpenTelemetry requer a versão do Oz API 6.6.1 ou superior.

A solução descrita abaixo é baseada em instrumentação zero-code do 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

Com suporte desde a versão oz-k8s/0.20.29.

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:

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:

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.

Se OTEL_ENABLE não está definido como true, a aplicação inicia sem o opentelemetry-instrument wrapper.

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 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.