Semantic Conventions for URL
Status: Experimental
This document defines semantic conventions that describe URL and its components.
Attributes
Attribute | Type | Description | Examples | Requirement Level | Stability |
---|---|---|---|---|---|
url.fragment | string | The URI fragment component | SemConv | Recommended | |
url.full | string | Absolute URL describing a network resource according to RFC3986 [1] | https://www.foo.bar/search?q=OpenTelemetry#SemConv ; //localhost | Recommended | |
url.path | string | The URI path component [2] | /search | Recommended | |
url.query | string | The URI query component [3] | q=OpenTelemetry | Recommended | |
url.scheme | string | The URI scheme component identifying the used protocol. | https ; ftp ; telnet | Recommended |
[1] url.full
: For network calls, URL usually has scheme://host[:port][path][?query][#fragment]
format, where the fragment
is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless.
url.full
MUST NOT contain credentials passed via URL in form of https://username:password@www.example.com/
.
In such case username and password SHOULD be redacted and attribute’s value SHOULD be https://REDACTED:REDACTED@www.example.com/
.
url.full
SHOULD capture the absolute URL when it is available (or can be reconstructed).
Sensitive content provided in url.full
SHOULD be scrubbed when instrumentations can identify it.
Query string values for the following keys SHOULD be redacted by default and replaced by the
value
REDACTED
:
This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
https://www.example.com/path?color=blue&sig=REDACTED
.
[2] url.path
: Sensitive content provided in url.path
SHOULD be scrubbed when instrumentations can identify it.
[3] url.query
: Sensitive content provided in url.query
SHOULD be scrubbed when instrumentations can identify it.
Query string values for the following keys SHOULD be redacted by default and replaced by the value
REDACTED
:
This list is subject to change over time.
When a query string value is redacted, the query string key SHOULD still be preserved, e.g.
q=OpenTelemetry&sig=REDACTED
.
Sensitive information
Capturing URL and its components MAY impose security risk. User and password information, when they are provided in User Information subcomponent, MUST NOT be recorded.
Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing url.query
attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties.
Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely.
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!