Skip to content

Commit 7deea05

Browse files
ashu658ashu658
authored
Add docs to capture HTTP request/response headers (#1038)
1 parent 45448f8 commit 7deea05

File tree

4 files changed

+204
-0
lines changed
  • instrumentation
    • opentelemetry-instrumentation-falcon/src/opentelemetry/instrumentation/falcon
    • opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask
    • opentelemetry-instrumentation-tornado/src/opentelemetry/instrumentation/tornado
    • opentelemetry-instrumentation-wsgi/src/opentelemetry/instrumentation/wsgi

4 files changed

+204
-0
lines changed

‎instrumentation/opentelemetry-instrumentation-falcon/src/opentelemetry/instrumentation/falcon/__init__.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,57 @@ def response_hook(span, req, resp):
8686
8787
FalconInstrumentation().instrument(request_hook=request_hook, response_hook=response_hook)
8888
89+
Capture HTTP request and response headers
90+
*****************************************
91+
You can configure the agent to capture predefined HTTP headers as span attributes, according to the `semantic convention <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers>`_.
92+
93+
Request headers
94+
***************
95+
To capture predefined HTTP request headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST``
96+
to a comma-separated list of HTTP header names.
97+
98+
For example,
99+
100+
::
101+
102+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header"
103+
104+
will extract ``content-type`` and ``custom_request_header`` from request headers and add them as span attributes.
105+
106+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
107+
Request header names in falcon are case insensitive and - characters are replaced by _. So, giving header name as ``CUStom_Header`` in environment variable will be able capture header with name ``custom-header``.
108+
109+
The name of the added span attribute will follow the format ``http.request.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
110+
The value of the attribute will be single item list containing all the header values.
111+
112+
Example of the added span attribute,
113+
``http.request.header.custom_request_header = ["<value1>,<value2>"]``
114+
115+
Response headers
116+
****************
117+
To capture predefined HTTP response headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE``
118+
to a comma-separated list of HTTP header names.
119+
120+
For example,
121+
122+
::
123+
124+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header"
125+
126+
will extract ``content-type`` and ``custom_response_header`` from response headers and add them as span attributes.
127+
128+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
129+
Response header names captured in falcon are case insensitive. So, giving header name as ``CUStomHeader`` in environment variable will be able capture header with name ``customheader``.
130+
131+
The name of the added span attribute will follow the format ``http.response.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
132+
The value of the attribute will be single item list containing all the header values.
133+
134+
Example of the added span attribute,
135+
``http.response.header.custom_response_header = ["<value1>,<value2>"]``
136+
137+
Note:
138+
Environment variable names to caputre http headers are still experimental, and thus are subject to change.
139+
89140
API
90141
---
91142
"""

‎instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,57 @@ def response_hook(span: Span, status: str, response_headers: List):
8585
8686
Flask Request object reference: https://flask.palletsprojects.com/en/2.0.x/api/#flask.Request
8787
88+
Capture HTTP request and response headers
89+
*****************************************
90+
You can configure the agent to capture predefined HTTP headers as span attributes, according to the `semantic convention <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers>`_.
91+
92+
Request headers
93+
***************
94+
To capture predefined HTTP request headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST``
95+
to a comma-separated list of HTTP header names.
96+
97+
For example,
98+
99+
::
100+
101+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header"
102+
103+
will extract ``content-type`` and ``custom_request_header`` from request headers and add them as span attributes.
104+
105+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
106+
Request header names in flask are case insensitive and - characters are replaced by _. So, giving header name as ``CUStom_Header`` in environment variable will be able capture header with name ``custom-header``.
107+
108+
The name of the added span attribute will follow the format ``http.request.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
109+
The value of the attribute will be single item list containing all the header values.
110+
111+
Example of the added span attribute,
112+
``http.request.header.custom_request_header = ["<value1>,<value2>"]``
113+
114+
Response headers
115+
****************
116+
To capture predefined HTTP response headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE``
117+
to a comma-separated list of HTTP header names.
118+
119+
For example,
120+
121+
::
122+
123+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header"
124+
125+
will extract ``content-type`` and ``custom_response_header`` from response headers and add them as span attributes.
126+
127+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
128+
Response header names captured in flask are case insensitive. So, giving header name as ``CUStomHeader`` in environment variable will be able capture header with name ``customheader``.
129+
130+
The name of the added span attribute will follow the format ``http.response.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
131+
The value of the attribute will be single item list containing all the header values.
132+
133+
Example of the added span attribute,
134+
``http.response.header.custom_response_header = ["<value1>,<value2>"]``
135+
136+
Note:
137+
Environment variable names to caputre http headers are still experimental, and thus are subject to change.
138+
88139
API
89140
---
90141
"""

‎instrumentation/opentelemetry-instrumentation-tornado/src/opentelemetry/instrumentation/tornado/__init__.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,57 @@ def client_resposne_hook(span, future):
9797
client_response_hook=client_resposne_hook
9898
)
9999
100+
Capture HTTP request and response headers
101+
*****************************************
102+
You can configure the agent to capture predefined HTTP headers as span attributes, according to the `semantic convention <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers>`_.
103+
104+
Request headers
105+
***************
106+
To capture predefined HTTP request headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST``
107+
to a comma-separated list of HTTP header names.
108+
109+
For example,
110+
111+
::
112+
113+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header"
114+
115+
will extract ``content-type`` and ``custom_request_header`` from request headers and add them as span attributes.
116+
117+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
118+
Request header names in tornado are case insensitive. So, giving header name as ``CUStomHeader`` in environment variable will be able capture header with name ``customheader``.
119+
120+
The name of the added span attribute will follow the format ``http.request.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
121+
The value of the attribute will be single item list containing all the header values.
122+
123+
Example of the added span attribute,
124+
``http.request.header.custom_request_header = ["<value1>,<value2>"]``
125+
126+
Response headers
127+
****************
128+
To capture predefined HTTP response headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE``
129+
to a comma-separated list of HTTP header names.
130+
131+
For example,
132+
133+
::
134+
135+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header"
136+
137+
will extract ``content-type`` and ``custom_response_header`` from response headers and add them as span attributes.
138+
139+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
140+
Response header names captured in tornado are case insensitive. So, giving header name as ``CUStomHeader`` in environment variable will be able capture header with name ``customheader``.
141+
142+
The name of the added span attribute will follow the format ``http.response.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
143+
The value of the attribute will be single item list containing all the header values.
144+
145+
Example of the added span attribute,
146+
``http.response.header.custom_response_header = ["<value1>,<value2>"]``
147+
148+
Note:
149+
Environment variable names to caputre http headers are still experimental, and thus are subject to change.
150+
100151
API
101152
---
102153
"""

‎instrumentation/opentelemetry-instrumentation-wsgi/src/opentelemetry/instrumentation/wsgi/__init__.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,57 @@ def response_hook(span: Span, environ: WSGIEnvironment, status: str, response_he
100100
101101
OpenTelemetryMiddleware(request_hook=request_hook, response_hook=response_hook)
102102
103+
Capture HTTP request and response headers
104+
*****************************************
105+
You can configure the agent to capture predefined HTTP headers as span attributes, according to the `semantic convention <https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-request-and-response-headers>`_.
106+
107+
Request headers
108+
***************
109+
To capture predefined HTTP request headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST``
110+
to a comma-separated list of HTTP header names.
111+
112+
For example,
113+
114+
::
115+
116+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header"
117+
118+
will extract ``content-type`` and ``custom_request_header`` from request headers and add them as span attributes.
119+
120+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
121+
Request header names in wsgi are case insensitive and - characters are replaced by _. So, giving header name as ``CUStom_Header`` in environment variable will be able capture header with name ``custom-header``.
122+
123+
The name of the added span attribute will follow the format ``http.request.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
124+
The value of the attribute will be single item list containing all the header values.
125+
126+
Example of the added span attribute,
127+
``http.request.header.custom_request_header = ["<value1>,<value2>"]``
128+
129+
Response headers
130+
****************
131+
To capture predefined HTTP response headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE``
132+
to a comma-separated list of HTTP header names.
133+
134+
For example,
135+
136+
::
137+
138+
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header"
139+
140+
will extract ``content-type`` and ``custom_response_header`` from response headers and add them as span attributes.
141+
142+
It is recommended that you should give the correct names of the headers to be captured in the environment variable.
143+
Response header names captured in wsgi are case insensitive. So, giving header name as ``CUStomHeader`` in environment variable will be able capture header with name ``customheader``.
144+
145+
The name of the added span attribute will follow the format ``http.response.header.<header_name>`` where ``<header_name>`` being the normalized HTTP header name (lowercase, with - characters replaced by _ ).
146+
The value of the attribute will be single item list containing all the header values.
147+
148+
Example of the added span attribute,
149+
``http.response.header.custom_response_header = ["<value1>,<value2>"]``
150+
151+
Note:
152+
Environment variable names to caputre http headers are still experimental, and thus are subject to change.
153+
103154
API
104155
---
105156
"""

0 commit comments

Comments
 (0)