Clarify routes may contain static and dynamic segments (#2734)
Signed-off-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
This commit is contained in:
Matthew Hensley
GitHub
parent
5ee549b1ce
commit
e2dab49586
|
|
@ -0,0 +1,4 @@
|
|||
change_type: enhancement
|
||||
component: http
|
||||
note: Clarify value for `http.route` attribute may contain static and dynamic segments.
|
||||
issues: [2616]
|
||||
|
|
@ -75,11 +75,19 @@ All routing metrics are reported by the `Microsoft.AspNetCore.Routing` meter.
|
|||
|---|---|---|---|---|---|
|
||||
| [`aspnetcore.routing.match_status`](/docs/registry/attributes/aspnetcore.md) | string | Match result - success or failure | `success`; `failure` | `Required` |  |
|
||||
| [`aspnetcore.routing.is_fallback`](/docs/registry/attributes/aspnetcore.md) | boolean | A value that indicates whether the matched route is a fallback route. | `true` | `Conditionally Required` if and only if a route was successfully matched. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` if and only if a route was successfully matched. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [1] | `/users/:userID?`; `my-controller/my-action/{id?}` | `Conditionally Required` if and only if a route was successfully matched. |  |
|
||||
|
||||
**[1] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
---
|
||||
|
||||
`aspnetcore.routing.match_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
|
|||
| [`url.scheme`](/docs/registry/attributes/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` |  |
|
||||
| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. |  |
|
||||
| [`http.response.status_code`](/docs/registry/attributes/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [4] | `/users/:userID?`; `my-controller/my-action/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`network.protocol.name`](/docs/registry/attributes/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] |  |
|
||||
| [`network.protocol.version`](/docs/registry/attributes/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
|
||||
| [`server.address`](/docs/registry/attributes/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
|
||||
|
|
@ -129,6 +129,14 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
|
|||
**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
|
||||
|
|
@ -281,7 +289,7 @@ This metric is optional.
|
|||
| [`url.scheme`](/docs/registry/attributes/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` |  |
|
||||
| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. |  |
|
||||
| [`http.response.status_code`](/docs/registry/attributes/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [4] | `/users/:userID?`; `my-controller/my-action/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`network.protocol.name`](/docs/registry/attributes/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] |  |
|
||||
| [`network.protocol.version`](/docs/registry/attributes/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
|
||||
| [`server.address`](/docs/registry/attributes/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
|
||||
|
|
@ -326,6 +334,14 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
|
|||
**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
|
||||
|
|
@ -407,7 +423,7 @@ This metric is optional.
|
|||
| [`url.scheme`](/docs/registry/attributes/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [2] | `http`; `https` | `Required` |  |
|
||||
| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. |  |
|
||||
| [`http.response.status_code`](/docs/registry/attributes/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [4] | `/users/:userID?`; `my-controller/my-action/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`network.protocol.name`](/docs/registry/attributes/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] |  |
|
||||
| [`network.protocol.version`](/docs/registry/attributes/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` |  |
|
||||
| [`server.address`](/docs/registry/attributes/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` |  |
|
||||
|
|
@ -452,6 +468,14 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
|
|||
**[4] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
**[5] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
**[6] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
|
||||
|
|
|
|||
|
|
@ -451,7 +451,7 @@ This span represents an inbound HTTP request.
|
|||
| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [4] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If request has ended with an error. |  |
|
||||
| [`http.request.method_original`](/docs/registry/attributes/http.md) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | `Conditionally Required` [5] |  |
|
||||
| [`http.response.status_code`](/docs/registry/attributes/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | `Conditionally Required` If and only if one was received/sent. |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [6] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`http.route`](/docs/registry/attributes/http.md) | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [6] | `/users/:userID?`; `my-controller/my-action/{id?}` | `Conditionally Required` If and only if it's available |  |
|
||||
| [`network.protocol.name`](/docs/registry/attributes/network.md) | string | [OSI application layer](https://wikipedia.org/wiki/Application_layer) or non-OSI equivalent. [7] | `http`; `spdy` | `Conditionally Required` [8] |  |
|
||||
| [`server.port`](/docs/registry/attributes/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Conditionally Required` If available and `server.address` is set. |  |
|
||||
| [`url.query`](/docs/registry/attributes/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [10] | `q=OpenTelemetry` | `Conditionally Required` If and only if one was received/sent. |  |
|
||||
|
|
@ -515,6 +515,14 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro
|
|||
**[6] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
**[7] `network.protocol.name`:** The value SHOULD be normalized to lowercase.
|
||||
|
||||
**[8] `network.protocol.name`:** If not `http` and `network.protocol.version` is set.
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ This document defines semantic convention attributes in the HTTP namespace.
|
|||
| <a id="http-response-header" href="#http-response-header">`http.response.header.<key>`</a> | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `["application/json"]`; `["abc", "def"]` |  |
|
||||
| <a id="http-response-size" href="#http-response-size">`http.response.size`</a> | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` |  |
|
||||
| <a id="http-response-status-code" href="#http-response-status-code">`http.response.status_code`</a> | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` |  |
|
||||
| <a id="http-route" href="#http-route">`http.route`</a> | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` |  |
|
||||
| <a id="http-route" href="#http-route">`http.route`</a> | string | The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. [5] | `/users/:userID?`; `my-controller/my-action/{id?}` |  |
|
||||
|
||||
**[1] `http.request.header.<key>`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
|
||||
Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
|
||||
|
|
@ -79,6 +79,14 @@ Examples:
|
|||
**[5] `http.route`:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
|
||||
---
|
||||
|
||||
`http.connection.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
||||
|
|
|
|||
|
|
@ -170,12 +170,19 @@ groups:
|
|||
stability: stable
|
||||
type: string
|
||||
brief: >
|
||||
The matched route, that is, the path template in the format used by the respective server framework.
|
||||
examples: ['/users/:userID?', '{controller}/{action}/{id?}']
|
||||
note: >
|
||||
The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders.
|
||||
examples: ['/users/:userID?', 'my-controller/my-action/{id?}']
|
||||
note: |
|
||||
MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
||||
|
||||
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
||||
|
||||
A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that
|
||||
are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`.
|
||||
|
||||
A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments.
|
||||
|
||||
Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY
|
||||
support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string.
|
||||
- id: http.connection.state
|
||||
type:
|
||||
members:
|
||||
|
|
|
|||
Loading…
Reference in New Issue