Jaeger Python Client

4.8.0 · active · verified Thu Apr 16

The `jaeger-client` library provides a Python implementation for OpenTracing tracers, enabling applications to send traces to a Jaeger backend. It is currently at version 4.8.0, actively maintained, and primarily used for distributed tracing and observability. Releases typically occur every few months, aligning with new features or Python version updates.

Common errors

```
ModuleNotFoundError: No module named 'jaeger_client'
```
cause The `jaeger-client` package is not installed in the current Python environment.

fix Run `pip install jaeger-client` to install the package.
```
TypeError: Config.__init__() got an unexpected keyword argument 'udp_sender'
```
cause Configuration parameters have changed. Older keyword arguments like `udp_sender` are no longer directly accepted by the `Config` constructor. They are now typically nested within the `config` dictionary under `local_agent`.

fix Refer to the latest documentation for `jaeger-client.Config` for the correct configuration structure. For `udp_sender`, migrate to `config={'local_agent': {'reporting_host': '...', 'reporting_port': ...}}`.
```
DeprecationWarning: Jaeger tracer support for OpenTracing API v1.x is deprecated, please use opentracing>=2.0.0
```
cause You are using `jaeger-client` v4.0.0+ with an `opentracing` dependency older than v2.0.0, or your code is using deprecated OpenTracing v1 API patterns.

fix Upgrade your `opentracing` package to the latest version (`pip install --upgrade opentracing`) and review your code for compatibility with OpenTracing v2 API.
```
The following option was not recognized: validate=True
```
cause The `validate` option was a feature of older `jaeger-client` versions, often part of `Config`. Newer versions may not support this top-level argument or have moved its functionality.

fix Remove the `validate=True` argument from your `Config` initialization. If validation is critical, check the latest documentation for alternative methods or assume validation by default.

Warnings

breaking Jaeger-client v4.0.0 introduced support for OpenTracing API v2.0. This may require updating your application's `opentracing` dependency to `v2.0.0` or higher and potentially adjusting API calls.
Fix: Ensure `opentracing` is updated to `v2.0.0` or later (`pip install --upgrade opentracing`). Review your code for deprecated OpenTracing v1 API patterns and migrate to v2 equivalents if necessary.
breaking Python 2 support was officially dropped in version 4.5.0. Furthermore, version 4.7.0 raised the minimum required Python version to 3.7+.
Fix: Upgrade your Python interpreter to version 3.7 or newer. If you must use Python 2.x or 3.6, you will need to pin `jaeger-client<4.5.0` or `jaeger-client<4.7.0` respectively, but this is strongly discouraged for security and maintenance reasons.
gotcha If `tracer.close()` is not called, especially in short-lived scripts or serverless functions, spans may not be flushed from the buffer and will never appear in Jaeger.
Fix: Always ensure `tracer.close()` is called at the end of your application's lifecycle or after the last span has been created, to guarantee all buffered spans are sent to the Jaeger agent.
gotcha Spans not appearing in the Jaeger UI is often due to misconfigured Jaeger agent host/port, incorrect sampler settings, or network issues.
Fix: Verify `JAEGER_AGENT_HOST` and `JAEGER_AGENT_PORT` environment variables or `local_agent` config. Ensure the `sampler` type (e.g., `const`, `ratelimiting`) and `param` are correctly set to allow spans through. Check network connectivity to the Jaeger agent.

Install

pip install jaeger-client Install latest version

Imports

Config
```
from jaeger_client import Config
```
Tracer
```
from jaeger_client import Tracer
```

ConstSampler

from jaeger_client.sampler import ConstSampler

NullReporter

from jaeger_client.reporter import NullReporter

Quickstart

This quickstart demonstrates how to initialize the Jaeger tracer using `Config`, create root and child spans, and log key-value pairs. It leverages environment variables for agent host/port, falling back to defaults. Crucially, `tracer.close()` is called to ensure all buffered spans are sent to the Jaeger agent.

import os
from jaeger_client import Config

# Configure Jaeger client
config = Config(
    config={
        'sampler': {
            'type': 'const',
            'param': 1,
        },
        'logging': True,
        'local_agent': {
            'reporting_host': os.environ.get('JAEGER_AGENT_HOST', 'localhost'),
            'reporting_port': int(os.environ.get('JAEGER_AGENT_PORT', 6831)),
        },
    },
    service_name='my-python-app',
    validate=True,
)

# Initialize tracer (it's recommended to do this once per application lifetime)
tracer = config.initialize_tracer()

# Create a root span
with tracer.start_active_span('my-root-operation') as scope:
    scope.span.log_kv({'event': 'root_span_started'})
    print(f"Root Span Trace ID: {scope.span.trace_id:x}")

    # Create a child span automatically inheriting from the active span
    with tracer.start_active_span('my-child-operation'):
        print("Doing some work in a child span...")
        scope.span.log_kv({'event': 'child_work_done'})

print("Spans created and ready to be flushed.")

# It is crucial to close the tracer to ensure all buffered spans are flushed.
# In a long-running application, this should be done during graceful shutdown.
tracer.close()

view raw JSON →