For the complete documentation index, see llms.txt. This page is also available as Markdown.

Como habilitar OpenTelemetry no Oz API

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:

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:

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

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:

  • otlpOTLP;

  • jaeger – exportar no modelo de dados do Jaeger;

  • zipkinZipkin;

  • consoleSaí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,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.

Atualizado

Isto foi útil?