Metadata-Version: 2.4
Name: opentelemetry-instrumentation-requestID
Version: 0.0.2
Summary: OpenTelemetry requestID Instrumentation
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-fastapi
Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-contrib
Author-email: OpenTelemetry Authors <zhangdeshuai@cai-inc.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Requires-Dist: opentelemetry-api>=1.29.0
Requires-Dist: opentelemetry-instrumentation>=0.50b0
Description-Content-Type: text/x-rst

opentelemetry-instrumentation-requestID
========================================

``opentelemetry-instrumentation-requestID`` provides an OpenTelemetry text-map
propagator that falls back to a request ID header when an incoming request does
not include a valid W3C ``traceparent`` header.

Installation
------------

Install the package together with your OpenTelemetry distribution::

    pip install opentelemetry-instrumentation-requestID opentelemetry-distro

Automatic initialization
------------------------

Use the standard OpenTelemetry launcher to discover the package's
``opentelemetry_instrumentor`` entry point and configure the global propagator
before the application is imported::

    opentelemetry-instrument python app.py

Plain ``python app.py`` does not modify global OpenTelemetry configuration. To
enable the propagator explicitly, call the instrumentor during application
startup::

    from opentelemetry.instrumentation.xrequest import RequestIdPropagatorInstrumentor

    RequestIdPropagatorInstrumentor().instrument()

Propagation behavior
--------------------

``traceparent`` always takes precedence. When it is absent or invalid, the
propagator looks for the ``requestid`` header by default. A 32-character
hexadecimal ID is used directly; a UUID has its dashes removed; other values
are deterministically SHA-256 hashed into a W3C-compatible trace ID.

With the default ``parent_span_id_hex`` value, the request ID becomes the trace
ID of a remote parent context. Set ``parent_span_id_hex=None`` to preserve the
incoming context instead: in that mode, a request ID alone does not create a
trace context.

Custom configuration
--------------------

The instrumentor and propagator accept alternate header names and a custom
parent span ID::

    RequestIdPropagatorInstrumentor(
        request_id_headers=("x-request-id", "requestid"),
        parent_span_id_hex="0123456789abcdef",
    ).instrument()
