diff --git a/docs/dotnet/README.md b/docs/dotnet/README.md new file mode 100644 index 0000000000..6ef89a2fa4 --- /dev/null +++ b/docs/dotnet/README.md @@ -0,0 +1,24 @@ + + +# Semantic Conventions for .NET metrics + +**Status**: [Experimental][DocumentStatus] + +This document documents semantic conventions for metrics emitted by .NET runtime and individual components in .NET ecosystem. + +**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. + +Following metrics are currently supported: + +* [ASP.NET Core](dotnet-aspnet-metrics.md): Semantic Conventions for ASP.NET Core routing, exceptions, and rate-limiting *metrics*. +* [DNS](dotnet-dns-metrics.md): Semantic Conventions for client-side DNS lookups associated with *metrics*. +* [HTTP](dotnet-http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. +* [Kestrel](dotnet-kestrel-metrics.md): Semantic Conventions for Kestrel web server *metrics*. +* [SignalR](dotnet-signalr-metrics.md): Semantic Conventions for SignalR server *metrics*. + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md new file mode 100644 index 0000000000..4114c60d50 --- /dev/null +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -0,0 +1,210 @@ +# Semantic Conventions for ASP.NEt Core specific metrics + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for ASP.NET Core metrics, not specific to HTTP + +**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. + + + +- [Routing](#routing) + * [Metric: `aspnet.routing.matches`](#metric-aspnetroutingmatches) +- [Exception metrics](#exception-metrics) + * [Metric: `aspnet.diagnostics_handler.exceptions`](#metric-aspnetdiagnostics_handlerexceptions) +- [Rate-limiting](#rate-limiting) + * [Metric: `aspnet.rate_limiting.active_request_leases`](#metric-aspnetrate_limitingactive_request_leases) + * [Metric: `aspnet.rate_limiting.request_lease.duration`](#metric-aspnetrate_limitingrequest_leaseduration) + * [Metric: `aspnet.rate_limiting.queued_requests`](#metric-aspnetrate_limitingqueued_requests) + * [Metric: `aspnet.rate_limiting.queued_requests.duration`](#metric-aspnetrate_limitingqueued_requestsduration) + * [Metric: `aspnet.rate_limiting.requests`](#metric-aspnetrate_limitingrequests) + + + +## Routing + +All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. + +### Metric: `aspnet.routing.matches` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.routing.successful_matches` | Counter | `{match}` | Number of requests that successfully matched to an endpoint. [1] | + +**[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Meter name is `Microsoft.AspNetCore.Routing`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.match_status` | string | Match result - success or failure | `success`; `failure` | Required | +| `aspnet.routing.fallback` | string | TODO | `TODO` | Required | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Required | + +**[1]:** 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. + +`aspnet.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. + +| Value | Description | +|---|---| +| `success` | matched | +| `failure` | failure | + + +## Exception metrics + +Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. + +### Metric: `aspnet.diagnostics_handler.exceptions` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.diagnostics_handler.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Diagnostics` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.handler` | string | TODO | `TODO` | Required | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | Recommended | + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + + +## Rate-limiting + +All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` meter. + +### Metric: `aspnet.rate_limiting.active_request_leases` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | + + +### Metric: `aspnet.rate_limiting.request_lease.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` +**TODO do we need attributes?, can we explain what it means better**` + + + + + +### Metric: `aspnet.rate_limiting.queued_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | + + +### Metric: `aspnet.rate_limiting.queued_requests.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.queued_request.duration` | Histogram | `s` | The duration of request in a queue, waiting to acquire a rate limiting lease. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` + +**TODO: I don't really understand what this duration is, can we improve name, brief or description to explain? ** + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | + + +### Metric: `aspnet.rate_limiting.requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. [1] | + +**[1]:** Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. + +Meter name is `Microsoft.AspNetCore.RateLimiting` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | +| `aspnet.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `rejected_reason1` | Recommended | + +`aspnet.rate_limiting.result` 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. + +| Value | Description | +|---|---| +| `acquired` | lease acquired | +| `rejected_reason1` | TODO | + + + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md \ No newline at end of file diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md new file mode 100644 index 0000000000..0108597944 --- /dev/null +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -0,0 +1,51 @@ +# Semantic Conventions for DNS metrics emitted by .NET + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for DNS metrics emitted by .NET. + +**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. + + + +- [DNS metrics](#dns-metrics) + * [Metric: `dns.lookups.duration`](#metric-dnslookupsduration) + + + +## DNS metrics + +### Metric: `dns.lookups.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + +This metric SHOULD be specified with +[`ExplicitBucketBoundaries`](/~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/api.md#instrument-advice) +of **`[TODO]`**. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time take to perform a DNS lookup. [1] | + +**[1]:** Meter name is `System.Net.NameResolution`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | + +**[1]:** The name being queried. + +If the name field contains non-printable +characters (below 32 or above 126), those characters should be represented +as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. +Tabs, carriage returns, and line feeds should be converted to \t, \r, and +\n respectively. + + + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md new file mode 100644 index 0000000000..9fd58f935d --- /dev/null +++ b/docs/dotnet/dotnet-http-metrics.md @@ -0,0 +1,453 @@ +# Semantic Conventions for HTTP-relevant metrics emitted by .NET and ASP.NET Core + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for HTTP metrics emitted by .NET components and runtime. + +**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. + + + +- [HTTP client](#http-client) + * [Metric: `http.client.connections.usage`](#metric-httpclientconnectionsusage) + * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + * [Metric: `http.client.duration`](#metric-httpclientduration) + * [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) +- [HTTP server](#http-server) + * [Metric: `http.server.duration`](#metric-httpserverduration) + * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) + * [Metric: `http.server.unhandled_requests`](#metric-httpserverunhandled_requests) + + + +## HTTP client + +All Http client metrics are reported by `System.Net.Http` meter. + +### Metric: `http.client.connections.usage` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connections.usage` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client [1] | + +**[1]:** Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.connection.state` | string | Connection state. | `active`; `idle` | Required | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`url.scheme`](../url/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]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +`dotnet.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + + +### Metric: `http.client.connection.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of outbound HTTP connections. [1] | + +**[1]:** Meter name is `System.Net.Http`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.http.request.error` | string | HTTP Request error as defined in/~https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs | `extended_connection_not_supported`; `http_protocol` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`url.scheme`](../url/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]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`dotnet.http.request.error` 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. + +| Value | Description | +|---|---| +| `Unknown` | Unknown error | +| `NameResolutionError` | NameResolutionError | +| `ConnectionError` | ConnectionError | +| `SecureConnectionError` | SecureConnectionError | +| `HttpProtocolError` | HttpProtocolError | +| `ExtendedConnectNotSupported` | ExtendedConnectNotSupported | + + +### Metric: `http.client.duration` + +Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientduration), but adds non-code errors + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.duration` | Histogram | `s` | Measures the duration of outbound HTTP requests. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.http.request.error` | string | HTTP Request error as defined in/~https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs | `extended_connection_not_supported`; `http_protocol` | Recommended | +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | + +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST +set the exact method received in the request line as value of the `http.request.method_original` attribute. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[3]:** Determined by using the first of the following that applies + +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header + +SHOULD NOT be set if capturing it would require an extra DNS lookup. + +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`dotnet.http.request.error` 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. + +| Value | Description | +|---|---| +| `Unknown` | Unknown error | +| `NameResolutionError` | NameResolutionError | +| `ConnectionError` | ConnectionError | +| `SecureConnectionError` | SecureConnectionError | +| `HttpProtocolError` | HttpProtocolError | +| `ExtendedConnectNotSupported` | ExtendedConnectNotSupported | + +`http.request.method` 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. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +### Metric: `http.client.active_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of outbound HTTP requests that have failed. [1] | + +**[1]:** Corresponding `EventCounter` name is `current-requests`; Meter name is `System.Net.Http`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Logical server port number | `80`; `8080`; `443` | Recommended | +| [`server.socket.address`](../general/attributes.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`url.scheme`](../url/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]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST +set the exact method received in the request line as value of the `http.request.method_original` attribute. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +`http.request.method` 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. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +## HTTP server + +All Http server metrics are reported by `Microsoft.AspNetCore.Hosting ` meter. + +### Metric: `http.server.duration` + +**TODO: Opt-in address and port?** +**TODO: method cardinality?** + +Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverduration) + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.http.request.error` | string | HTTP Request error as defined in/~https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs | `extended_connection_not_supported`; `http_protocol` | Recommended | +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `http.response.status_code` | 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` | string | The matched route (path template in the format used by the respective server framework). See note below [2] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../url/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]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST +set the exact method received in the request line as value of the `http.request.method_original` attribute. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** 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. + +**[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[4]:** Determined by using the first of the following that applies + +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + include host identifier. +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Host identifier of the `Host` header + +SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + +**[5]:** Determined by using the first of the following that applies + +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Port identifier of the `Host` header + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`dotnet.http.request.error` 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. + +| Value | Description | +|---|---| +| `Unknown` | Unknown error | +| `NameResolutionError` | NameResolutionError | +| `ConnectionError` | ConnectionError | +| `SecureConnectionError` | SecureConnectionError | +| `HttpProtocolError` | HttpProtocolError | +| `ExtendedConnectNotSupported` | ExtendedConnectNotSupported | + +`http.request.method` 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. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +### Metric: `http.server.active_requests` + +**TODO: Opt-in address and port?** +**TODO: method cardinality?** + +Follows common [`http.server.active_requests``](../http/http-metrics.md#metric-httpserveractive_requests) + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.active_requests` | UpDownCounter | `{request}` | Measures the number of concurrent HTTP requests that are currently in-flight. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | +| [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | + +**[1]:** HTTP request method value SHOULD be "known" to the instrumentation. +By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) +and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html). + +If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST +set the exact method received in the request line as value of the `http.request.method_original` attribute. + +If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override +the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named +OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods +(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults). + +HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly. +Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent. +Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value. + +**[2]:** Determined by using the first of the following that applies + +- The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only + include host identifier. +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Host identifier of the `Host` header + +SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + +**[3]:** Determined by using the first of the following that applies + +- Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Port identifier of the `Host` header + +`http.request.method` 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. + +| Value | Description | +|---|---| +| `CONNECT` | CONNECT method. | +| `DELETE` | DELETE method. | +| `GET` | GET method. | +| `HEAD` | HEAD method. | +| `OPTIONS` | OPTIONS method. | +| `PATCH` | PATCH method. | +| `POST` | POST method. | +| `PUT` | PUT method. | +| `TRACE` | TRACE method. | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | + + +### Metric: `http.server.unhandled_requests` + +**TODO:Any chance we will need to report any attributes in future?** + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.unhandled_requests` | UpDownCounter | `{request}` | Number of requests that reached the end of the middleware pipeline without being handled by application code. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Hosting`.** + + + + + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md \ No newline at end of file diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md new file mode 100644 index 0000000000..e4fe77ad65 --- /dev/null +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -0,0 +1,417 @@ +# Semantic Conventions for Kestrel web server metrics + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for Kestrel web server. + + + +- [Metric: `kestrel.active_connections`](#metric-kestrelactive_connections) +- [Metric: `kestrel.connection.duration`](#metric-kestrelconnectionduration) +- [Metric: `kestrel.rejected_connections`](#metric-kestrelrejected_connections) +- [Metric: `kestrel.queued_connections`](#metric-kestrelqueued_connections) +- [Metric: `kestrel.queued_requests`](#metric-kestrelqueued_requests) +- [Metric: `kestrel.upgraded_connections`](#metric-kestrelupgraded_connections) +- [Metric: `kestrel.tls_handshake.duration`](#metric-kestreltls_handshakeduration) +- [Metric: `kestrel.active_tls_handshakes`](#metric-kestrelactive_tls_handshakes) + + + +## Metric: `kestrel.active_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. [1] | + +**[1]:** Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.connection.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| `tls.version` | string | TLS protocol version | `1.3` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.rejected_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. [1] | + +**[1]:** Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. +Meter name is `Microsoft.AspNetCore.Server.Kestrel` + +**TODO: do we ever will have other rejection reasons** + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.queued_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_connections` | UpDownCounter | `{connection}` | Number of connections that are currently queued and are waiting to start. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.queued_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_requests` | UpDownCounter | `{connection}` | Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.upgraded_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.upgraded_connections` | UpDownCounter | `{connection}` | Number of connections that are currently upgraded (WebSockets). . [1] | + +**[1]:** The number only tracks HTTP/1.1 connections. **TODO: can we add protocol info in dimensions so we can extend it to other versions/protocols? ** +Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.tls_handshake.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.tls_handshake.duration` | Histogram | `s` | The duration of TLS handshakes on the server. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + +## Metric: `kestrel.active_tls_handshakes` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `active_tls_handshakes` | UpDownCounter | `{handshake}` | Number of TLS handshakes that are currently in progress on the server. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| `tls.version` | string | TLS protocol version | `1.3` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +**[2]:** 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) and SHOULD NOT be validated or modified except for sanitizing purposes. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + +`network.type` 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. + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + + + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md \ No newline at end of file diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md new file mode 100644 index 0000000000..eb9c90edf6 --- /dev/null +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -0,0 +1,117 @@ +# Semantic Conventions for SignalR metrics emitted by ASP.NET Core + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for SignalR metrics emitted by .NET components and runtime. + +**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future. + + + +- [Metric: `signalr.http.server.connection.duration`](#metric-signalrhttpserverconnectionduration) +- [Metric: `signalr.http.server.active_connections`](#metric-signalrhttpserveractive_connections) + + + +## Metric: `signalr.http.server.connection.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.http.server.connection.duration` | Histogram | `s` | The duration of the HTTP connections on the server. [1] | + +**[1]:** Only reported for HTTP SignalR transport. +Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.transport` | string | SignalR transport - /~https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md [1] | `ServerSentEvents` | Conditionally Required: if HTTP SignalR transport is used | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `websockets` | Recommended: if not default (`http`) | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | + +**[1]:** websockets are recoded in `network.protocol.name` attribute and `signalr.transport` is not set. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +`signalr.transport` 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. + +| Value | Description | +|---|---| +| `ServerSentEvents` | ServerSentEvents | +| `LongPolling` | LongPolling | + +`dotnet.error.code` 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. + +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | + +**[1]:** When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, such as `http.request.error` or `http.response.status_code` for HTTP errors. + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + + +## Metric: `signalr.http.server.active_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.http.server.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | + +**[1]:** Only reported for HTTP SignalR transport. +Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.transport` | string | SignalR transport - /~https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md [1] | `ServerSentEvents` | Conditionally Required: if HTTP SignalR transport is used | +| [`network.protocol.name`](../general/attributes.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `websockets` | Recommended: if not default (`http`) | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended | + +**[1]:** websockets are recoded in `network.protocol.name` attribute and `signalr.transport` is not set. + +**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + +`signalr.transport` 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. + +| Value | Description | +|---|---| +| `ServerSentEvents` | ServerSentEvents | +| `LongPolling` | LongPolling | + +`network.transport` 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. + +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | + + + +[DocumentStatus]: /~https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md \ No newline at end of file diff --git a/model/deprecated/network.yaml b/model/deprecated/network.yaml index 17b75b90e3..cfbd95dda8 100644 --- a/model/deprecated/network.yaml +++ b/model/deprecated/network.yaml @@ -78,7 +78,7 @@ groups: type: string stability: deprecated brief: Deprecated, use `network.protocol.name`. - examples: ['amqp', 'http', 'mqtt'] + examples: ['amqp', 'http', 'mqtt', 'websockets'] - id: protocol.version type: string stability: deprecated diff --git a/model/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml new file mode 100644 index 0000000000..920d0884e5 --- /dev/null +++ b/model/metrics/dotnet-aspnet.yaml @@ -0,0 +1,148 @@ +groups: + - id: aspnet + prefix: aspnet + type: attribute_group + brief: ASP.NET Core attributes + attributes: + - id: rate_limiting.policy + type: string + brief: TODO + examples: ["TODO"] + - id: rate_limiting.result + type: + allow_custom_values: true + members: + - id: acquired + value: 'acquired' + brief: 'lease acquired' + - id: rejected_reason1 + value: 'rejected_reason1' + brief: 'TODO' + #... + brief: Rate-limiting result, shows whether lease was acquired or contains rejection reason + examples: ["acquired", "rejected_reason1"] + - id: routing.fallback + type: string + brief: TODO + examples: ["TODO"] + - id: handler + type: string + brief: TODO + examples: ["TODO"] + - id: match_status + type: + allow_custom_values: true + members: + - id: success + value: 'success' + brief: 'matched' + - id: failure + value: 'failure' + brief: 'failure' + brief: Match result - success or failure + examples: ["success", "failure"] + + # misc + - id: metric.aspnet.server.unhandled_requests + type: metric + metric_name: aspnet.unhandled_requests + brief: Number of requests that reached the end of the middleware pipeline without being handled by application code. + instrument: updowncounter + unit: "{request}" + note: | + Meter name is `Microsoft.AspNetCore.Hosting`.** + + # routing + - id: metric.aspnet.routing.matches + type: metric + metric_name: aspnet.routing.successful_matches + brief: Number of requests that successfully matched to an endpoint. + instrument: counter + unit: "{match}" + note: > + An unmatched request may be handled by later middleware, such as the static files or authentication middleware. + Meter name is `Microsoft.AspNetCore.Routing`. + attributes: + - ref: http.route + requirement_level: required + - ref: aspnet.routing.fallback + requirement_level: required + - ref: aspnet.match_status + requirement_level: required + + # diagnostics + - id: metric.aspnet.diagnostics_handler.exceptions + type: metric + metric_name: aspnet.diagnostics_handler.exceptions + brief: Number of exceptions caught by exception handling middleware. + instrument: counter + unit: "{exception}" + note: Meter name is `Microsoft.AspNetCore.Diagnostics` + attributes: + - ref: exception.type + - ref: aspnet.handler + requirement_level: required + - ref: dotnet.error.code + + # rate_limiting + - id: metric.aspnet.rate_limiting.active_request_leases + type: metric + metric_name: aspnet.rate_limiting.active_request_leases + brief: Number of requests that are currently active on the server that hold a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: Meter name is `Microsoft.AspNetCore.RateLimiting` + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + + - id: metric.aspnet.rate_limiting.request_lease.duration + type: metric + metric_name: aspnet.rate_limiting.request_lease.duration + brief: The duration of rate limiting lease held by requests on the server. + instrument: histogram + unit: "s" + note: | + Meter name is `Microsoft.AspNetCore.RateLimiting` + **TODO do we need attributes?, can we explain what it means better**` + + - id: metric.aspnet.rate_limiting.queued_request.duration + type: metric + metric_name: aspnet.rate_limiting.queued_request.duration + brief: The duration of request in a queue, waiting to acquire a rate limiting lease. + instrument: histogram + unit: "s" + note: | + Meter name is `Microsoft.AspNetCore.RateLimiting` + + **TODO: I don't really understand what this duration is, can we improve name, brief or description to explain? ** + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + + - id: metric.aspnet.rate_limiting.queued_requests + type: metric + metric_name: aspnet.rate_limiting.queued_requests + brief: Number of requests that are currently queued, waiting to acquire a rate limiting lease. + instrument: updowncounter + unit: "{request}" + note: | + Meter name is `Microsoft.AspNetCore.RateLimiting` + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + + - id: metric.aspnet.rate_limiting.requests + type: metric + metric_name: aspnet.rate_limiting.requests + brief: Number of requests that tried to acquire a rate limiting lease. + instrument: counter + unit: "{request}" + note: | + Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. + + Meter name is `Microsoft.AspNetCore.RateLimiting` + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + - ref: aspnet.rate_limiting.result diff --git a/model/metrics/dotnet-common.yaml b/model/metrics/dotnet-common.yaml new file mode 100644 index 0000000000..3c4ef833a5 --- /dev/null +++ b/model/metrics/dotnet-common.yaml @@ -0,0 +1,48 @@ +groups: + - id: dotnet.common_attributes + prefix: dotnet + type: attribute_group + brief: Common .NET attributes + attributes: + - id: error.code + type: + allow_custom_values: true + members: + - id: ran_to_completion + value: 'RanToCompletion' + brief: 'No error' + - id: canceled + value: 'Canceled' + brief: 'Canceled' + - id: faulted + value: 'Faulted' + brief: 'Faulted' + note: When error code is set to `other`, it's recommended accompany this attribute with a domain-specific error code when it's known, + such as `http.request.error` or `http.response.status_code` for HTTP errors. + brief: General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. + examples: ["Canceled", "RanToCompletion"] + - id: http.request.error + type: + allow_custom_values: true + members: + - id: unknown + value: 'Unknown' + brief: 'Unknown error' + - id: name_resolution + value: 'NameResolutionError' + brief: 'NameResolutionError' + - id: connection + value: 'ConnectionError' + brief: 'ConnectionError' + - id: secure_connection + value: 'SecureConnectionError' + brief: 'SecureConnectionError' + - id: http_protocol + value: 'HttpProtocolError' + brief: 'HttpProtocolError' + - id: extended_connection_not_supported + value: 'ExtendedConnectNotSupported' + brief: 'ExtendedConnectNotSupported' + # ... + brief: HTTP Request error as defined in/~https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs + examples: ['extended_connection_not_supported', 'http_protocol'] diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/dotnet-http.yaml new file mode 100644 index 0000000000..f5a4351d60 --- /dev/null +++ b/model/metrics/dotnet-http.yaml @@ -0,0 +1,139 @@ +groups: + - id: metric.dotnet.dns.lookup.duration + type: metric + metric_name: dns.lookup.duration + brief: Measures the time take to perform a DNS lookup. + instrument: histogram + unit: "s" + note: Meter name is `System.Net.NameResolution`. + attributes: + - id: dns.question.name + type: string + brief: The name being queried. + requirement_level: required + examples: ["www.example.com", "dot.net"] + note: | + The name being queried. + + If the name field contains non-printable + characters (below 32 or above 126), those characters should be represented + as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped. + Tabs, carriage returns, and line feeds should be converted to \t, \r, and + \n respectively. + + - id: metric.dotnet.http.client.connections.usage + type: metric + metric_name: http.client.connections.usage + brief: "Number of outbound HTTP connections that are currently active or idle on the client" + instrument: updowncounter + unit: "{connection}" + note: + Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. + attributes: + - id: dotnet.connection.state + type: + members: + - id: active + value: "active" + brief: 'active state.' + - id: idle + value: "idle" + brief: 'idle state.' + brief: Connection state. + requirement_level: required + examples: ["active", "idle"] + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port + + - id: metric.dotnet.http.client.connection.duration + type: metric + metric_name: http.client.connection.duration + brief: "The duration of outbound HTTP connections." + instrument: histogram + unit: "s" + note: Meter name is `System.Net.Http`. + attributes: + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port + - ref: dotnet.error.code + - ref: dotnet.http.request.error + + - id: metric.dotnet.http.client.duration + type: metric + metric_name: http.client.duration + brief: "Measures the duration of outbound HTTP requests." + instrument: histogram + unit: "s" + extends: metric_attributes.http.client + attributes: + - ref: dotnet.error.code + - ref: dotnet.http.request.error + - ref: server.address + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + + SHOULD NOT be set if capturing it would require an extra DNS lookup. + - ref: server.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. + + - id: metric.dotnet.http.server.duration + type: metric + metric_name: http.server.duration + brief: "Measures the duration of inbound HTTP requests." + instrument: histogram + unit: "s" + extends: metric_attributes.http.server + attributes: + - ref: dotnet.error.code + - ref: dotnet.http.request.error + - ref: http.route + - ref: url.scheme + + - id: metric.dotnet.http.client.active_requests + type: metric + metric_name: http.client.active_requests + brief: "Number of outbound HTTP requests that have failed." + instrument: updowncounter + unit: "{request}" + note: Corresponding `EventCounter` name is `current-requests`; Meter name is `System.Net.Http`. + attributes: + - ref: http.request.method + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port + + - id: dotnet.http.client.request.time_in_queue + type: metric + metric_name: http.client.request.time_in_queue + brief: "The amount of time requests spent on a queue waiting for an available connection." + instrument: histogram + unit: "s" + note: Corresponding `EventCounter` name is `*-requests-queue-duration`; Meter name is `System.Net.Http`. + attributes: + - ref: http.request.method + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml new file mode 100644 index 0000000000..ad6286d404 --- /dev/null +++ b/model/metrics/dotnet-kestrel.yaml @@ -0,0 +1,111 @@ +groups: + - id: kestrel.common_attributes + prefix: kestrel + type: attribute_group + brief: Common kestrel attributes + note: "**TODO: Let's pick relevant attributes instead of kestrel.endpoint from this list, and/or use `url.full`**" + attributes: + #- ref: server.address + #- ref: server.port + #- ref: server.socket.address + #- ref: url.scheme + - ref: url.full + - ref: network.protocol.name + - ref: network.protocol.version + - ref: network.transport + - ref: network.type + + - id: tls.common_attributes + prefix: tls + type: attribute_group + brief: Common TLS attributes + attributes: + - id: version + type: string + brief: TLS protocol version + examples: ["1.3"] + + - id: metric.kestrel.active_connections + type: metric + metric_name: kestrel.active_connections + brief: Number of connections that are currently active on the server. + instrument: updowncounter + unit: "{connection}" + note: Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + + - id: metric.kestrel.connection.duration + type: metric + metric_name: kestrel.connection.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + attributes: + - ref: dotnet.error.code + - ref: tls.version + + - id: metric.kestrel.rejected_connections + type: metric + metric_name: kestrel.rejected_connections + brief: Number of connections rejected by the server. + instrument: counter + unit: "{connection}" + note: | + Connections are rejected when the currently active count exceeds the value configured with MaxConcurrentConnections. + Meter name is `Microsoft.AspNetCore.Server.Kestrel` + + **TODO: do we ever will have other rejection reasons** + extends: kestrel.common_attributes + + - id: metric.kestrel.queued_connections + type: metric + metric_name: kestrel.queued_connections + brief: Number of connections that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{connection}" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + + - id: metric.kestrel.queued_requests + type: metric + metric_name: kestrel.queued_requests + brief: Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. + instrument: updowncounter + unit: "{connection}" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + + - id: metric.kestrel.upgraded_connections + type: metric + metric_name: kestrel.upgraded_connections + brief: Number of connections that are currently upgraded (WebSockets). . + instrument: updowncounter + unit: "{connection}" + note: | + The number only tracks HTTP/1.1 connections. **TODO: can we add protocol info in dimensions so we can extend it to other versions/protocols? ** + Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + + - id: metric.kestrel.tls_handshake.duration + type: metric + metric_name: kestrel.tls_handshake.duration + brief: The duration of TLS handshakes on the server. + instrument: histogram + unit: "s" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + attributes: + - ref: dotnet.error.code + + - id: metric.kestrel.active_tls_handshakes + type: metric + metric_name: active_tls_handshakes + brief: Number of TLS handshakes that are currently in progress on the server. + instrument: updowncounter + unit: "{handshake}" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes + attributes: + - ref: tls.version \ No newline at end of file diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml new file mode 100644 index 0000000000..8eaa4a8f3b --- /dev/null +++ b/model/metrics/dotnet-signalr.yaml @@ -0,0 +1,51 @@ +groups: + - id: signalr.common_attributes + prefix: signalr + type: attribute_group + brief: SignalR attributes + attributes: + - id: transport + brief: SignalR transport - /~https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md + type: + allow_custom_values: true + members: + - id: server_sent_events + value: 'ServerSentEvents' + brief: 'ServerSentEvents' + - id: long_polling + value: 'LongPolling' + brief: 'LongPolling' + note: websockets are recoded in `network.protocol.name` attribute and `signalr.transport` is not set. + requirement_level: + conditionally_required: if HTTP SignalR transport is used + - ref: network.protocol.name + requirement_level: + recommended: if not default (`http`) + examples: ["http", "websockets"] + - ref: network.protocol.version + - ref: network.transport + + - id: metric.signalr.http.server.connection.duration + type: metric + metric_name: signalr.http.server.connection.duration + brief: The duration of the HTTP connections on the server. + instrument: histogram + unit: "s" + note: | + Only reported for HTTP SignalR transport. + Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + extends: signalr.common_attributes + attributes: + - ref: http.response.status_code + - ref: dotnet.error.code + + - id: metric.signalr.http.server.active_connections + type: metric + metric_name: signalr.http.server.active_connections + brief: Number of connections that are currently active on the server. + instrument: histogram + unit: "s" + note: | + Only reported for HTTP SignalR transport. + Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + extends: signalr.common_attributes