> 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/guides/administrator-guide/telemetry/how-to-enable-opentelemetry-in-oz-api.md).

# How to Enable OpenTelemetry in Oz API

{% hint style="warning" %}
OpenTelemetry requires Oz API version **6.6.1** or higher.
{% endhint %}

The solution described below is based on [Python zero-code instrumentation](https://opentelemetry.io/docs/zero-code/python).

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:

<figure><img src="/files/l8tA2ZsnYYPCQzt2ezw0" alt=""><figcaption></figcaption></figure>

### Kubernetes

{% hint style="info" %}
Supported since version **oz-k8s/0.20.29**.
{% endhint %}

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:

```yaml
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:

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

{% hint style="info" %}
If `OTEL_ENABLE` is not set to `true`, the application starts without the `opentelemetry-instrument` wrapper.
{% endhint %}

### 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](https://opentelemetry.io/docs/zero-code/python/configuration/) website.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Variable</th><th>Description</th><th>Default value</th></tr></thead><tbody><tr><td><code>OTEL_ENABLE</code></td><td><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Docker only.</strong></p></div><p>Enables OTEL auto-instrumentation (<code>true</code> / not set). When set to <code>true</code>, 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 <code>ENTRYPOINT</code> when starting the container, you must explicitly add the application launch with the <code>opentelemetry-instrument</code> wrapper: <code>opentelemetry-instrument gunicorn oz_api.asgi:application &#x3C;...></code>. This variable is not used in the Kubernetes chart – enabling is set through <code>opentelemetry.enable: true</code>.</p></td><td>not set (disabled)</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td><td>Address of the OTLP collector</td><td>not set (must be specified when enabling)</td></tr><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Service name in traces</td><td><code>oz-api.python.otel</code></td></tr><tr><td><code>OTEL_TRACES_EXPORTER</code></td><td><p>Traces exporter. Possible values:</p><ul><li><code>otlp</code> – <a href="https://opentelemetry.io/docs/specs/otlp/">OTLP</a>;</li><li><code>jaeger</code> – export in Jaeger data model;</li><li><code>zipkin</code> – <a href="https://zipkin.io/zipkin-api/">Zipkin</a>;</li><li><code>console</code> – <a href="https://opentelemetry.io/docs/specs/otel/trace/sdk_exporters/stdout/">Standard Output</a>;</li><li><code>none</code> – no exporters with automatic configuration are used</li></ul></td><td><code>otlp</code></td></tr><tr><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code></td><td><p>Export protocol. Possible values:</p><ul><li><code>grpc</code> for OTLP/gRPC;</li><li><code>http/protobuf</code> for OTLP/HTTP + <code>protobuf</code>;</li><li><code>http/json</code> for OTLP/HTTP + JSON</li></ul></td><td><code>grpc</code></td></tr><tr><td><code>OTEL_METRICS_EXPORTER</code></td><td>Metrics exporter, not supported</td><td><code>none</code></td></tr><tr><td><code>OTEL_LOGS_EXPORTER</code></td><td>Logs exporter, not supported</td><td><code>none</code></td></tr><tr><td><code>OTEL_PROPAGATORS</code></td><td><p>Propagation context formats. Possible values:</p><ul><li><code>tracecontext</code> – <a href="https://www.w3.org/TR/trace-context/">W3C Trace Context</a>;</li><li><code>baggage</code> – <a href="https://www.w3.org/TR/baggage/">W3C Baggage</a>;</li><li><code>b3</code> – <a href="https://opentelemetry.io/docs/specs/otel/context/api-propagators/#configuration">B3 Single</a>;</li><li><code>b3multi</code> – <a href="https://opentelemetry.io/docs/specs/otel/context/api-propagators/#configuration">B3 Multi</a>;</li><li><code>jaeger</code> – <a href="https://www.jaegertracing.io/sdk-migration/">Jaeger</a>;</li><li><code>xray</code> – <a href="https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader">AWS X-Ray</a>;</li><li><code>ottrace</code> – <a href="https://github.com/opentracing?q=basic&#x26;type=&#x26;language=">OT Trace</a>;</li><li><code>none</code> – no propagators with automatic configuration are used</li></ul></td><td><code>tracecontext,baggage</code></td></tr><tr><td><code>OTEL_PYTHON_DISABLED_INSTRUMENTATIONS</code></td><td>Disabled auto-instrumentations</td><td><code>psycopg2</code></td></tr><tr><td><code>OTEL_EXPORTER_OTLP_INSECURE</code></td><td>Disables TLS for the gRPC call to the OTLP collector API. For endpoints that do not use TLS encryption, set <code>true</code>.</td><td>not set (TLS is used)</td></tr></tbody></table>

### Notes

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


---

# 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/guides/administrator-guide/telemetry/how-to-enable-opentelemetry-in-oz-api.md?ask=<question>&goal=<endgoal>
```

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