95 lines
5.5 KiB
Markdown
95 lines
5.5 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: URL
|
|
--->
|
|
|
|
# Semantic conventions for URL
|
|
|
|
**Status**: [Development][DocumentStatus]
|
|
|
|
This document defines semantic conventions that describe URL and its components.
|
|
|
|
<details>
|
|
<summary>Table of Contents</summary>
|
|
|
|
<!-- toc -->
|
|
|
|
- [Attributes](#attributes)
|
|
- [Sensitive information](#sensitive-information)
|
|
|
|
<!-- tocstop -->
|
|
|
|
</details>
|
|
|
|
## Attributes
|
|
|
|
<!-- semconv url -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`url.fragment`](/docs/attributes-registry/url.md) | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | `Recommended` |  |
|
|
| [`url.full`](/docs/attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | `Recommended` |  |
|
|
| [`url.path`](/docs/attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | `Recommended` |  |
|
|
| [`url.query`](/docs/attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | `Recommended` |  |
|
|
| [`url.scheme`](/docs/attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) 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`:
|
|
|
|
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
|
|
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
|
|
* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
|
|
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
|
|
|
|
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`:
|
|
|
|
* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
|
|
* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth)
|
|
* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token)
|
|
* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls)
|
|
|
|
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`.
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
## Sensitive information
|
|
|
|
Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) 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._
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|