{"id":7317,"library":"jaeger-client","title":"Jaeger Python Client","description":"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.","status":"active","version":"4.8.0","language":"en","source_language":"en","source_url":"https://github.com/jaegertracing/jaeger-client-python","tags":["tracing","observability","opentracing","jaeger","distributed-tracing","telemetry"],"install":[{"cmd":"pip install jaeger-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the OpenTracing API interface that jaeger-client implements.","package":"opentracing","optional":false},{"reason":"Used for exposing metrics related to the tracer's operation (e.g., span counts, errors).","package":"prometheus_client","optional":true}],"imports":[{"symbol":"Config","correct":"from jaeger_client import Config"},{"symbol":"Tracer","correct":"from jaeger_client import Tracer"},{"symbol":"ConstSampler","correct":"from jaeger_client.sampler import ConstSampler"},{"symbol":"NullReporter","correct":"from jaeger_client.reporter import NullReporter"}],"quickstart":{"code":"import os\nfrom jaeger_client import Config\n\n# Configure Jaeger client\nconfig = Config(\n    config={\n        'sampler': {\n            'type': 'const',\n            'param': 1,\n        },\n        'logging': True,\n        'local_agent': {\n            'reporting_host': os.environ.get('JAEGER_AGENT_HOST', 'localhost'),\n            'reporting_port': int(os.environ.get('JAEGER_AGENT_PORT', 6831)),\n        },\n    },\n    service_name='my-python-app',\n    validate=True,\n)\n\n# Initialize tracer (it's recommended to do this once per application lifetime)\ntracer = config.initialize_tracer()\n\n# Create a root span\nwith tracer.start_active_span('my-root-operation') as scope:\n    scope.span.log_kv({'event': 'root_span_started'})\n    print(f\"Root Span Trace ID: {scope.span.trace_id:x}\")\n\n    # Create a child span automatically inheriting from the active span\n    with tracer.start_active_span('my-child-operation'):\n        print(\"Doing some work in a child span...\")\n        scope.span.log_kv({'event': 'child_work_done'})\n\nprint(\"Spans created and ready to be flushed.\")\n\n# It is crucial to close the tracer to ensure all buffered spans are flushed.\n# In a long-running application, this should be done during graceful shutdown.\ntracer.close()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"4.0.0+"},{"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.","message":"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+.","severity":"breaking","affected_versions":"4.5.0+, 4.7.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Spans not appearing in the Jaeger UI is often due to misconfigured Jaeger agent host/port, incorrect sampler settings, or network issues.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install jaeger-client` to install the package.","cause":"The `jaeger-client` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'jaeger_client'"},{"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': ...}}`.","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`.","error":"TypeError: Config.__init__() got an unexpected keyword argument 'udp_sender'"},{"fix":"Upgrade your `opentracing` package to the latest version (`pip install --upgrade opentracing`) and review your code for compatibility with OpenTracing v2 API.","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.","error":"DeprecationWarning: Jaeger tracer support for OpenTracing API v1.x is deprecated, please use opentracing>=2.0.0"},{"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.","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.","error":"The following option was not recognized: validate=True"}]}