Skip to content

docs(tracing): update trace header configuration #15015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+4 −22
Open

docs(tracing): update trace header configuration #15015

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05205b9
docs(tracing): update trace header configuration
mabdinur Oct 23, 2025
4b8d7dd
Apply suggestions from code review
mabdinur Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 4 additions & 22 deletions docs/advanced_usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,34 +391,16 @@ Headers tracing

For a selected set of integrations, it is possible to store http headers from both requests and responses in tags.

The recommended method is to use the ``DD_TRACE_HEADER_TAGS`` environment variable.
Use the ``DD_TRACE_HEADER_TAGS`` environment variable to configure trace headers.

This configuration can be provided both at the global level and at the integration level in your application code, or it
can be set via the Datadog UI (UI functionality in beta as of version 2.5.0).
Example::

Examples::

from ddtrace import config

# Global config
config.trace_headers([
'user-agent',
'transfer-encoding',
])

# Integration level config, e.g. 'falcon'
config.falcon.http.trace_headers([
'user-agent',
'some-other-header',
])
export DD_TRACE_HEADER_TAGS="user-agent,content-type,authorization"

The following rules apply:
- headers configuration is based on a whitelist. If a header does not appear in the whitelist, it won't be traced.
- headers configuration is case-insensitive.
- if you configure a specific integration, e.g. 'requests', then such configuration overrides the default global
configuration, only for the specific integration.
- if you do not configure a specific integration, then the default global configuration applies, if any.
- if no configuration is provided (neither global nor integration-specific), then headers are not traced.
- if no configuration is provided, then headers are not traced.


Once you configure your application for tracing, you will have the headers attached to the trace as tags, with a
Expand Down
Loading