How to Enable OpenTelemetry in Oz API

OpenTelemetry requires Oz API version 6.6.1 or higher.

The solution described below is based on Python zero-code instrumentation.

Oz API supports auto-instrumentation of traces only – metrics and logs are not supported.

Enabling it depends on the deployment method – see the Kubernetes and Docker sections below. The set of environment variables is the same for both options and is listed in the Environment variables section.

Example of traces in Jaeger:

Kubernetes

Supported since version oz-k8s/0.20.29.

When opentelemetry is enabled, the chart wraps the Oz API process in opentelemetry-instrument and sends traces to the OTLP collector.

Enable auto-instrumentation and specify the collector address. OTEL_EXPORTER_OTLP_ENDPOINT is the only required variable:

Params:
  gunicorn:
    opentelemetry:
      enable: true
    envs:
      OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"   # gRPC endpoint of the OTLP collector
      OTEL_EXPORTER_OTLP_INSECURE: "true"                         # set this if the collector has no TLS

The remaining variables are passed the same way, through Params.gunicorn.envs.

Docker

To enable auto-instrumentation, set the environment variable OTEL_ENABLE=true and specify the collector's gRPC endpoint in the OTEL_EXPORTER_OTLP_ENDPOINT variable when starting the container:

docker run -e OTEL_ENABLE=true -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 ...

This is enough – traces will start being sent to the specified OTLP collector over gRPC.

If OTEL_ENABLE is not set to true, the application starts without the opentelemetry-instrument wrapper.

Environment variables

Below are the main configuration parameters for the OTEL_TRACES_EXPORTER=otlp option. Detailed information on configuring the OTEL agent is available on the OpenTelemetry website.

Variable	Description	Default value
OTEL_ENABLE	Docker only. Enables OTEL auto-instrumentation (true / not set). When set to true, it starts OpenTelemetry auto-instrumentation via the start.sh script. This script is used by default when starting the oz-api image. If you override the ENTRYPOINT when starting the container, you must explicitly add the application launch with the opentelemetry-instrument wrapper: opentelemetry-instrument gunicorn oz_api.asgi:application <...>. This variable is not used in the Kubernetes chart – enabling is set through opentelemetry.enable: true.	not set (disabled)
OTEL_EXPORTER_OTLP_ENDPOINT	Address of the OTLP collector	not set (must be specified when enabling)
OTEL_SERVICE_NAME	Service name in traces	oz-api.python.otel
OTEL_TRACES_EXPORTER	Traces exporter. Possible values: otlp – OTLP; jaeger – export in Jaeger data model; zipkin – Zipkin; console – Standard Output; none – no exporters with automatic configuration are used	otlp
OTEL_EXPORTER_OTLP_PROTOCOL	Export protocol. Possible values: grpc for OTLP/gRPC; http/protobuf for OTLP/HTTP + protobuf; http/json for OTLP/HTTP + JSON	grpc
OTEL_METRICS_EXPORTER	Metrics exporter, not supported	none
OTEL_LOGS_EXPORTER	Logs exporter, not supported	none
OTEL_PROPAGATORS	Propagation context formats. Possible values: tracecontext – W3C Trace Context; baggage – W3C Baggage; b3 – B3 Single; b3multi – B3 Multi; jaeger – Jaeger; xray – AWS X-Ray; ottrace – OT Trace; none – no propagators with automatic configuration are used	tracecontext,baggage
OTEL_PYTHON_DISABLED_INSTRUMENTATIONS	Disabled auto-instrumentations	psycopg2
OTEL_EXPORTER_OTLP_INSECURE	Disables TLS for the gRPC call to the OTLP collector API. For endpoints that do not use TLS encryption, set true.	not set (TLS is used)

Notes

• psycopg2 auto-instrumentation is disabled by default, otherwise the collected data may be excessive. Detailed spans are delivered through sqlalchemy auto-instrumentation.