From ad9bbc7589a725c4e1e31871ee26ef2b830d4a4c Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 24 Jul 2023 10:24:06 -0700 Subject: [PATCH] dotnet http metrics --- docs/dotnet/README.md | 24 ++ docs/dotnet/dotnet-aspnet-metrics.md | 201 ++++++++++++ docs/dotnet/dotnet-dns-metrics.md | 43 +++ docs/dotnet/dotnet-http-metrics.md | 420 ++++++++++++++++++++++++++ docs/dotnet/dotnet-kestrel-metrics.md | 212 +++++++++++++ docs/dotnet/dotnet-signalr-metrics.md | 83 +++++ docs/http/http-spans.md | 33 +- model/http-common.yaml | 26 ++ model/metrics/dotnet-aspnet.yaml | 199 ++++++++++++ model/metrics/dotnet-http.yaml | 148 +++++++++ model/metrics/dotnet-kestrel.yaml | 118 ++++++++ model/metrics/dotnet-signalr.yaml | 59 ++++ 12 files changed, 1558 insertions(+), 8 deletions(-) create mode 100644 docs/dotnet/README.md create mode 100644 docs/dotnet/dotnet-aspnet-metrics.md create mode 100644 docs/dotnet/dotnet-dns-metrics.md create mode 100644 docs/dotnet/dotnet-http-metrics.md create mode 100644 docs/dotnet/dotnet-kestrel-metrics.md create mode 100644 docs/dotnet/dotnet-signalr-metrics.md create mode 100644 model/metrics/dotnet-aspnet.yaml create mode 100644 model/metrics/dotnet-http.yaml create mode 100644 model/metrics/dotnet-kestrel.yaml create mode 100644 model/metrics/dotnet-signalr.yaml 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..9c0ceb0379 --- /dev/null +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -0,0 +1,201 @@ +# 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. + + + +- [Server](#server) + * [Metric: `aspnet.unhandled_requests`](#metric-aspnetunhandled_requests) +- [Routing](#routing) + * [Metric: `aspnet.routing.successful_matches`](#metric-aspnetroutingsuccessful_matches) +- [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_limitingrejected_requests) + + + +## Server + +### Metric: `aspnet.unhandled_requests` + + +| 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`. + + + + + +## Routing + +All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. + +### Metric: `aspnet.routing.successful_matches` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.routing.match_attempts` | Counter | `{match}` | Number of requests that were attempted to be matched to an endpoint. [1] | + +**[1]:** Meter name is `Microsoft.AspNetCore.Routing`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `match_status` | string | Match result - success or failure | `success`; `failure` | Recommended | +| `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. + +`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` | Match succeeded | +| `failure` | Match failed | + + +## Exception metrics + +Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter. + +### Metric: `aspnet.diagnostics_handler.exceptions` + + +| 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.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required | +| `aspnet.handler` | string | TODO | `TODO` | Required | +| `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 | + +`aspnet.exception.result` MUST be one of the following: + +| Value | Description | +|---|---| +| `handled` | Exception was handled by the exception handling middleware. | +| `unhandled` | Exception was not handled by the exception handling middleware. | +| `skipped` | Exception was skipped. TODO | +| `aborted` | Request was aborted. TODO | + + +## Rate-limiting + +All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` meter. + +### Metric: `aspnet.rate_limiting.active_request_leases` + + +| 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` + + +| 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: Can we explain what it means better**` + + + + + +### Metric: `aspnet.rate_limiting.queued_requests` + + +| 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` + + +| 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` + + +| 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`; `request_canceled` | 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 | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + + + +[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..aff98194fb --- /dev/null +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -0,0 +1,43 @@ +# 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` + + +| 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..2b59ef781b --- /dev/null +++ b/docs/dotnet/dotnet-http-metrics.md @@ -0,0 +1,420 @@ +# 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.open_connections`](#metric-httpclientopen_connections) + * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) + * [Metric: `http.client.duration`](#metric-httpclientduration) + * [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue) + * [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) + + + +## HTTP client + +All Http client metrics are reported by `System.Net.Http` meter. + +### Metric: `http.client.open_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | 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 | +|---|---|---|---|---| +| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `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`. + +`http.connection.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `active` | active state. | +| `idle` | idle state. | + + +### Metric: `http.client.connection.duration` + + +| 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.http.error.reason` | string | Request error such as timeout, cancellation or one of [HTTP Request error](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs) [1] | `timeout`; `http_protocol_error` | 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 | 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]:** **TODO: there is a open discussion/proposal in otel for http error code - https://github.com/open-telemetry/semantic-conventions/pull/205** + +**[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`. + +`dotnet.http.error.reason` 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 | +|---|---| +| `timeout` | Operation timed out | +| `cancellation` | Operation was cancelled | +| `unknown_error` | Unknown error | +| `name_resolution_error` | NameResolutionError | +| `connection_error` | ConnectionError | +| `secure_connection_error` | SecureConnectionError | +| `http_protocol_error` | HttpProtocolError | +| `extended_connection_not_supported` | ExtendedConnectNotSupported | + + +### Metric: `http.client.duration` + + +| 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.http.error.reason` | string | Request error such as timeout, cancellation or one of [HTTP Request error](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs) [1] | `timeout`; `http_protocol_error` | Recommended | +| `http.request.method` | string | HTTP request method. [2] | `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.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 | 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]:** **TODO: there is a open discussion/proposal in otel for http error code - https://github.com/open-telemetry/semantic-conventions/pull/205** + +**[2]:** 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. + +**[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`. + +`dotnet.http.error.reason` 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 | +|---|---| +| `timeout` | Operation timed out | +| `cancellation` | Operation was cancelled | +| `unknown_error` | Unknown error | +| `name_resolution_error` | NameResolutionError | +| `connection_error` | ConnectionError | +| `secure_connection_error` | SecureConnectionError | +| `http_protocol_error` | HttpProtocolError | +| `extended_connection_not_supported` | 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. | + + +Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientduration), but does not report `server.socket.address`. + +### Metric: `http.client.request.time_in_queue` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. [1] | + +**[1]:** Corresponding `EventCounter` name is `*-requests-queue-duration`; 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. | + + + +### Metric: `http.client.active_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. [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 | +| [`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?** + + +| 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.http.error.reason` | string | Request error such as timeout, cancellation or one of [HTTP Request error](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs) [1] | `timeout`; `http_protocol_error` | Recommended | +| `http.request.method` | string | HTTP request method. [2] | `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 [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [4] | `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. [5] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Logical server port number [6] | `80`; `8080`; `443` | Recommended | +| [`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]:** **TODO: there is a open discussion/proposal in otel for http error code - https://github.com/open-telemetry/semantic-conventions/pull/205** + +**[2]:** 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. + +**[3]:** 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. + +**[4]:** `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`. + +**[5]:** **TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported** + +**[6]:** **TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported** + +`dotnet.http.error.reason` 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 | +|---|---| +| `timeout` | Operation timed out | +| `cancellation` | Operation was cancelled | +| `unknown_error` | Unknown error | +| `name_resolution_error` | NameResolutionError | +| `connection_error` | ConnectionError | +| `secure_connection_error` | SecureConnectionError | +| `http_protocol_error` | HttpProtocolError | +| `extended_connection_not_supported` | 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?** + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.active_requests` | Histogram | `s` | Number of HTTP requests that are currently active on the server. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | +| `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.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 | Logical server hostname, matches server FQDN if available, and IP or socket address if FQDN is not known. [4] | `example.com` | Recommended | +| [`server.port`](../general/attributes.md) | int | Logical server port number [5] | `80`; `8080`; `443` | Recommended | +| [`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]:** **TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported** + +**[5]:** **TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported** + +`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. | + + +[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..6400f91752 --- /dev/null +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -0,0 +1,212 @@ +# Semantic Conventions for Kestrel web server metrics + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for Kestrel web server. + + + +- [Metric: `aspnet.kestrel.active_connections`](#metric-aspnetkestrelactive_connections) +- [Metric: `aspnet.kestrel.connection.duration`](#metric-aspnetkestrelconnectionduration) +- [Metric: `aspnet.kestrel.rejected_connections`](#metric-aspnetkestrelrejected_connections) +- [Metric: `aspnet.kestrel.queued_connections`](#metric-aspnetkestrelqueued_connections) +- [Metric: `aspnet.kestrel.queued_requests`](#metric-aspnetkestrelqueued_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: `aspnet.kestrel.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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 | +|---|---|---|---|---| +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** 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. + + +## Metric: `aspnet.kestrel.connection.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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 | +|---|---|---|---|---| +| `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. [1] | `java.net.ConnectException`; `OSError` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | +| `tls.protocol.name` | string | Normalized lowercase protocol name. | `tls`; `ssl` | Recommended: if not 'tls' | +| `tls.protocol.version` | string | Protocol version | `1.3`; `3` | Recommended | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [3] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** **TODO: Let's define common attribute for error reason/status** + +**[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]:** 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. + +`tls.protocol.name` 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 | +|---|---| +| `ssl` | SSL protocol | +| `tls` | TLS protocol. Default value. | + + +## Metric: `aspnet.kestrel.rejected_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** 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. + + +## Metric: `aspnet.kestrel.queued_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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 | +|---|---|---|---|---| +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** 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. + + +## Metric: `aspnet.kestrel.queued_requests` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | 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. + + +## Metric: `kestrel.upgraded_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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 | +|---|---|---|---|---| +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** 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. + + +## Metric: `kestrel.tls_handshake.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.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 | +|---|---|---|---|---| +| `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. [1] | `java.net.ConnectException`; `OSError` | Recommended | +| `tls.protocol.name` | string | Normalized lowercase protocol name. | `tls`; `ssl` | Recommended: if not 'tls' | +| `tls.protocol.version` | string | Protocol version | `1.3`; `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]:** **TODO: Let's define common attribute for error reason/status** + +**[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. + +`tls.protocol.name` 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 | +|---|---| +| `ssl` | SSL protocol | +| `tls` | TLS protocol. Default value. | + + +## Metric: `kestrel.active_tls_handshakes` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.kestrel.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 | +|---|---|---|---|---| +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | + +**[1]:** 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. + + +[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..2f686d400c --- /dev/null +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -0,0 +1,83 @@ +# 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_transport.connection.duration`](#metric-signalr_http_transportconnectionduration) +- [Metric: `signalr_http_transport.active_connections`](#metric-signalr_http_transportactive_connections) + + + +## Metric: `signalr_http_transport.connection.duration` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.http_transport.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | + +**[1]:** Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.http_transport.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended | +| `signalr.transport` | string | SignalR transport - https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md | `web_sockets`; `long_polling` | Recommended | + +`signalr.http_transport.status` MUST be one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`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 | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + + +## Metric: `signalr_http_transport.active_connections` + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.http_transport.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | + +**[1]:** Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.http_transport.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Recommended | +| `signalr.transport` | string | SignalR transport - https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md | `web_sockets`; `long_polling` | Recommended | + +`signalr.http_transport.status` MUST be one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`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 | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + + + +[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/http/http-spans.md b/docs/http/http-spans.md index 946e1be2ca..25af0c5212 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -96,19 +96,25 @@ sections below. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `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.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [1] | +| `http.request.error.reason` | string | Request failure reason. [1] | `timeout`; `name_resolution_error`; `server_certificate_invalid` | Conditionally Required: [2] | +| `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | Conditionally Required: [3] | | `http.request.body.size` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | +| `http.request.method` | string | HTTP request method. [4] | `GET`; `POST`; `HEAD` | Required | | [`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`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | 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` | Conditionally Required: [4] | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [5] | `1.0`; `1.1`; `2.0` | 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` | Conditionally Required: [6] | | [`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 | | `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | -**[1]:** If and only if it's different than `http.request.method`. +**[1]:** HTTP instrumentations that decide to report additional error codes SHOULD document them. Additional values MUST be a closed set of error reasons known at the development time of the instrumentation. +MUST NOT be set if `http.response.status_code is set. -**[2]:** HTTP request method value SHOULD be "known" to the instrumentation. +**[2]:** If and only if request has failed before HTTP response headers were sent or received. + +**[3]:** If and only if it's different than `http.request.method`. + +**[4]:** 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). @@ -124,14 +130,25 @@ HTTP method names are case-sensitive and `http.request.method` attribute value M 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. -**[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`. +**[5]:** `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]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). +**[6]:** If not default (`tcp` for `HTTP/1.1` and `HTTP/2`, `udp` for `HTTP/3`). Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * `http.request.method` +`http.request.error.reason` 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 | +|---|---| +| `timeout` | The request timed out. | +| `canceled` | The request was canceled. | +| `name_resolution_error` | DNS name resolution failed | +| `_OTHER` | unknown error [1] | + +**[1]:** Any other error instrumentation has no prior knowledge of. + `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 | diff --git a/model/http-common.yaml b/model/http-common.yaml index 682b2cb984..26ca906b1d 100644 --- a/model/http-common.yaml +++ b/model/http-common.yaml @@ -63,6 +63,32 @@ groups: conditionally_required: If and only if one was received/sent. brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' examples: [200] + - id: request.error.reason + type: + allow_custom_values: true + members: + - id: timeout + value: "timeout" + brief: 'The request timed out.' + - id: canceled + value: "canceled" + brief: 'The request was canceled.' + - id: name_resolution_error + value: "name_resolution_error" + brief: 'DNS name resolution failed' + - id: other + value: "_OTHER" + brief: 'unknown error' + note: Any other error instrumentation has no prior knowledge of. + requirement_level: + conditionally_required: If and only if request has failed before HTTP response headers were sent or received. + brief: 'Request failure reason.' + examples: ['timeout', 'name_resolution_error', 'server_certificate_invalid'] + note: > + HTTP instrumentations that decide to report additional error codes SHOULD document them. Additional values MUST be a closed set of + error reasons known at the development time of the instrumentation. + + MUST NOT be set if `http.response.status_code is set. - ref: network.protocol.name examples: ['http', 'spdy'] requirement_level: diff --git a/model/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml new file mode 100644 index 0000000000..684db8ed16 --- /dev/null +++ b/model/metrics/dotnet-aspnet.yaml @@ -0,0 +1,199 @@ +groups: + - id: aspnet + prefix: aspnet + type: attribute_group + brief: ASP.NET Core attributes + attributes: + - id: rate_limiting.policy + type: string + brief: TODO + examples: ["TODO"] + requirement_level: required + - id: rate_limiting.result + type: + allow_custom_values: true + members: + - id: acquired + value: 'acquired' + brief: 'lease acquired' + - id: endpoint_limiter + value: 'endpoint_limiter' + brief: 'Lease request was rejected by the endpoint limiter' + - id: global_limiter + value: 'global_limiter' + brief: 'Lease request was rejected by the global limiter' + - id: request_canceled + value: 'request_canceled' + brief: 'Lease request was canceled' + brief: Rate-limiting result, shows whether lease was acquired or contains rejection reason + examples: ["acquired", "request_canceled"] + requirement_level: required + - id: routing.fallback + type: string + brief: TODO + examples: ["TODO"] + - id: handler + type: string + brief: TODO + examples: ["TODO"] + + # http + - 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" + attributes: + - ref: network.protocol.version + - ref: url.scheme + - ref: http.response.status_code + - ref: http.route + - ref: http.request.method + - ref: server.address + note: "**TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported**" + - ref: server.port + note: "**TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported**" + - ref: dotnet.http.error.reason + + - id: metric.dotnet.http.server.active_requests + type: metric + metric_name: http.server.active_requests + brief: "Number of HTTP requests that are currently active on the server." + instrument: histogram + unit: "s" + attributes: + - ref: network.protocol.version + - ref: http.route + - ref: http.request.method + - ref: url.scheme + - ref: server.address + note: "**TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported**" + - ref: server.port + note: "**TODO: this is opt-in in otel, i.e. it needs explicit configuration option to be reported**" + + - id: metric.aspnet.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.match_attempts + type: metric + metric_name: aspnet.routing.match_attempts + brief: Number of requests that were attempted to be matched to an endpoint. + instrument: counter + unit: "{match}" + note: Meter name is `Microsoft.AspNetCore.Routing`. + attributes: + - ref: http.route + requirement_level: required + - ref: aspnet.routing.fallback + requirement_level: required + - id: match_status + type: + allow_custom_values: true + members: + - id: success + value: 'success' + brief: 'Match succeeded' + - id: failure + value: 'failure' + brief: 'Match failed' + brief: Match result - success or failure + examples: ["success", "failure"] + + # 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 + - id: aspnet.exception.result + type: + members: + - id: handled + value: 'handled' + brief: 'Exception was handled by the exception handling middleware.' + - id: unhandled + value: 'unhandled' + brief: 'Exception was not handled by the exception handling middleware.' + - id: skipped + value: 'skipped' + brief: 'Exception was skipped. TODO' + - id: aborted + value: 'aborted' + brief: 'Request was aborted. TODO' + requirement_level: required + brief: ASP.NET Core exception middleware handling result + examples: ["handled", "unhandled"] + + # 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 + + - 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: Can we explain what it means better**` + attributes: + - ref: aspnet.rate_limiting.policy + + - 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 + - ref: aspnet.rate_limiting.result + + - 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 + + - 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 + - ref: aspnet.rate_limiting.result diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/dotnet-http.yaml new file mode 100644 index 0000000000..ba1a9352b4 --- /dev/null +++ b/model/metrics/dotnet-http.yaml @@ -0,0 +1,148 @@ +groups: + - id: dotnet.common_attributes + prefix: dotnet + type: attribute_group + brief: Common .NET attributes + attributes: + - id: http.error.reason + type: + allow_custom_values: true + members: + - id: timeout + value: 'timeout' + brief: 'Operation timed out' + - id: cancellation + value: 'cancellation' + brief: 'Operation was cancelled' + - id: unknown_error + value: 'unknown_error' + brief: 'Unknown error' + - id: name_resolution_error + value: 'name_resolution_error' + brief: 'NameResolutionError' + - id: connection_error + value: 'connection_error' + brief: 'ConnectionError' + - id: secure_connection_error + value: 'secure_connection_error' + brief: 'SecureConnectionError' + - id: http_protocol_error + value: 'http_protocol_error' + brief: 'HttpProtocolError' + - id: extended_connection_not_supported + value: 'extended_connection_not_supported' + brief: 'ExtendedConnectNotSupported' + # ... + brief: > + Request error such as timeout, cancellation or one of [HTTP Request error](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs) + examples: ['timeout', 'http_protocol_error'] + note: "**TODO: there is a open discussion/proposal in otel for http error code - https://github.com/open-telemetry/semantic-conventions/pull/205**" + + - 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.open_connections + type: metric + metric_name: http.client.open_connections + 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: http.connection.state + type: + members: + - id: active + value: "active" + brief: 'active state.' + - id: idle + value: "idle" + brief: 'idle state.' + brief: State of HTTP connection in the HTTP connection pool. + 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.http.error.reason + + - id: metric.dotnet.http.client.active_requests + type: metric + metric_name: http.client.active_requests + brief: "Number of active HTTP requests." + 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.port + + - 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" + attributes: + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port + - ref: http.request.method + - ref: http.response.status_code + - ref: dotnet.http.error.reason + + - id: metric.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..62f097681e --- /dev/null +++ b/model/metrics/dotnet-kestrel.yaml @@ -0,0 +1,118 @@ +groups: + - id: tls + prefix: tls.protocol + type: attribute_group + brief: TLS attributes + attributes: + - id: version + type: string + brief: Protocol version + examples: ["1.3", "3"] + - id: name + requirement_level: + recommended: if not 'tls' + brief: Normalized lowercase protocol name. + type: + allow_custom_values: true + members: + - id: ssl + value: ssl + brief: "SSL protocol" + - id: tls + value: tls + brief: "TLS protocol. Default value." + examples: ["tls", "ssl"] + + - id: metric.aspnet.kestrel.active_connections + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + + - id: metric.aspnet.kestrel.connection.duration + type: metric + metric_name: aspnet.kestrel.connection.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + attributes: + - ref: url.full + - ref: network.protocol.version + - ref: tls.protocol.name + - ref: tls.protocol.version + - ref: exception.type + note: "**TODO: Let's define common attribute for error reason/status**" + + - id: metric.aspnet.kestrel.rejected_connections + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + + - id: metric.aspnet.kestrel.queued_connections + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + + - id: metric.aspnet.kestrel.queued_requests + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + - ref: network.protocol.version + + - id: metric.aspnet.kestrel.upgraded_connections + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + + - id: metric.aspnet.kestrel.tls_handshake.duration + type: metric + metric_name: aspnet.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` + attributes: + - ref: url.full + - ref: tls.protocol.name + - ref: tls.protocol.version + - ref: exception.type + note: "**TODO: Let's define common attribute for error reason/status**" + + - id: metric.aspnet.kestrel.active_tls_handshakes + type: metric + metric_name: aspnet.kestrel.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` + attributes: + - ref: url.full diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml new file mode 100644 index 0000000000..714090a933 --- /dev/null +++ b/model/metrics/dotnet-signalr.yaml @@ -0,0 +1,59 @@ +groups: + - id: signalr.common_attributes + prefix: signalr + type: attribute_group + brief: SignalR attributes + attributes: + - id: http_transport.status + type: + members: + - id: normal_closure + value: 'normal_closure' + brief: 'The connection was closed normally.' + - id: timeout + value: 'timeout' + brief: 'The connection was closed due to a timeout.' + - id: app_shutdown + value: 'app_shutdown' + brief: 'The connection was closed because the app is shutting down.' + brief: SignalR HTTP connection closure status. + examples: ["app_shutdown", "timeout"] + - 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: 'server_sent_events' + brief: 'ServerSentEvents protocol' + - id: long_polling + value: 'long_polling' + brief: 'LongPolling protocol' + - id: web_sockets + value: 'web_sockets' + brief: 'WebSockets protocol' + examples: ["web_sockets", "long_polling"] + + - id: metric.signalr.server.connection.duration + type: metric + metric_name: signalr.server.http_transport.connection.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + note: | + Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + attributes: + - ref: signalr.http_transport.status + - ref: signalr.transport + + - id: metric.signalr.server.active_connections + type: metric + metric_name: signalr.server.http_transport.active_connections + brief: Number of connections that are currently active on the server. + instrument: histogram + unit: "s" + note: | + Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + attributes: + - ref: signalr.http_transport.status + - ref: signalr.transport \ No newline at end of file