From daeaa1b72a45e08720313a39b4c3bf25b4323780 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 13:41:29 -0700 Subject: [PATCH 01/12] First stub --- docs/dotnet/dotnet-aspnet-metrics.md | 204 ++++++++++++++++ docs/dotnet/dotnet-dns-metrics.md | 48 ++++ docs/dotnet/dotnet-http-metrics.md | 220 ++++++++++++++++++ model/metrics/dotnet-aspnet.yaml | 146 ++++++++++++ model/metrics/dotnet-dns.yaml | 22 ++ model/metrics/dotnet-http-client.yaml | 87 +++++++ model/metrics/{http.yaml => dotnet-http.yaml} | 0 model/metrics/dotnet-kestrel.yaml | 21 ++ model/metrics/dotnet-signalr.yaml | 21 ++ 9 files changed, 769 insertions(+) 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 model/metrics/dotnet-aspnet.yaml create mode 100644 model/metrics/dotnet-dns.yaml create mode 100644 model/metrics/dotnet-http-client.yaml rename model/metrics/{http.yaml => dotnet-http.yaml} (100%) create mode 100644 model/metrics/dotnet-kestrel.yaml create mode 100644 model/metrics/dotnet-signalr.yaml diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md new file mode 100644 index 0000000000..e8625d745d --- /dev/null +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -0,0 +1,204 @@ +# 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 + +All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. + +### Metric: `aspnet.routing.successful_matches` + +**Status**: [Experimental][DocumentStatus] + +**TODO: can we try one aspnet.routing.matches** ? + +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]:** Corresponding `EventCounter` name is `routing-match-success`; Meter name is `Microsoft.AspNetCore.Routing` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `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. + + +### Metric: `aspnet.routing.failed_matches` + +**TODO: would if be useful to add method name, scheme, or other attributes?** + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.routing.failed_matches` | Counter | `{match}` | Number of requests that failed to match to an endpoint. [1] | + +**[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Corresponding `EventCounter` name is `routing-match-failure`; Meter name is `Microsoft.AspNetCore.Routing` + + + + + +## 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]:** Corresponding `EventCounter` name is `diagnostics-handler-exception`; Meter name is `Microsoft.AspNetCore.Diagnostics` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `exception.result` | string | TODO | `TODO` | 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 | + + +## 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]:** Corresponding `EventCounter` name is `rate-limiting-current-leased-requests; 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_leases.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.request_leases.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | + +**[1]:** Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; 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]:** Corresponding `EventCounter` name is `rate-limiting-current-queued-requests`; Meter name is `Microsoft.AspNetCore.RateLimiting` + +**TODO: if they are queued, should they have reject reason ? ** + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | +| `aspnet.rate_limiting.reject_reason` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO should it be an enum?** + + +### Metric: `aspnet.rate_limiting.queued_requests.duration` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.queued_requests.duration` | Histogram | `s` | The duration of request in a queue, waiting to acquire a rate limiting lease. [1] | + +**[1]:** Corresponding `EventCounter` name is `rate-limiting-queued-request-duration`; 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? ** +**TODO: if they are queued, should they have reject reason ? ** + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | + + +### Metric: `aspnet.rate_limiting.rejected_requests` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnet.rate_limiting.rejected_requests` | Counter | `{request}` | Number of requests that failed 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. + +Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` + +**TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | +| `aspnet.rate_limiting.reject_reason` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO should it be an enum?** + + + +[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..900fd8dc29 --- /dev/null +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -0,0 +1,48 @@ +# 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 + +### 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.lookups.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 | +|---|---|---|---|---| +| `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..b5a3c572a1 --- /dev/null +++ b/docs/dotnet/dotnet-http-metrics.md @@ -0,0 +1,220 @@ +# 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 + +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 `http-client-current-connections` and `http-client-current-idle-connections`; Meter name is `System.Net.Http`. + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `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`. + +`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.connections.duration` | Histogram | `s` | The duration of outbound HTTP connections. [1] | + +**[1]:** Corresponding `EventCounter` name is `http-client-requests-duration`; Meter name is `System.Net.Http`. + + + +| 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 | +| [`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`. + + +### Metric: `http.client.duration` + +**TODO: any reason not to include server.socket.address?** + +**TODO: should we add error status to http semconv ?** - https://github.com/open-telemetry/opentelemetry-specification/issues/3243 + +Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientduration) + +### Metric: `http.client.active_requests` + +**TODO: any reason not to include server.socket.address?** +**TODO: any reason we don't have this metric in generic OTEL semconv?** + + +**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 `http-client-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`. + + +### Metric: `http.client.failed_requests` + +**TODO: We still need error code to make it useful and backward compatible. If we add error code, we should also add it to http.client.duration as well and then this one should be deleted.** + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.failed_requests` | Counter | `{request}` | Number of outbound HTTP requests that have failed. [1] | + +**[1]:** Corresponding `EventCounter` name is `http-client-failed-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 server + +All Http server metrics are reported by `Microsoft.AspNetCore.Hosting ` meter. + +### Metric: `http.server.duration` + +**TODO: should we add error status to http semconv ?** - https://github.com/open-telemetry/opentelemetry-specification/issues/3243 +**TODO: Opt-in address and port?** +**TODO: method cardinality?** + +Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverduration) + +Corresponding `EventCounter` (without dimensions) is `http-client-requests-duration` + +### 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) + +Corresponding `EventCounter` (without dimensions) is `http-client-current-requests` + +### 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 | +| -------- | --------------- | ----------- | -------------- | +| `http.server.unhandled_requests` | UpDownCounter | `{request}` | Number of requests that reached the end of the middleware pipeline without being handled by application code. [1] | + +**[1]:** Corresponding `EventCounter` name is `http-server-unhandled-requests`; Meter name is `Microsoft.AspNetCore.Hosting`. +**TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** + + + + + +[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/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml new file mode 100644 index 0000000000..abb7bcba05 --- /dev/null +++ b/model/metrics/dotnet-aspnet.yaml @@ -0,0 +1,146 @@ +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.reject_reason + type: string + brief: TODO + examples: ["TODO"] + note: "**TODO should it be an enum?**" + - id: routing.fallback + type: string + brief: TODO + examples: ["TODO"] + - id: handler + type: string + brief: TODO + examples: ["TODO"] + + # misc + - id: metric.aspnet.server.unhandled_requests + type: metric + metric_name: http.server.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: | + Corresponding `EventCounter` name is `http-server-unhandled-requests`; Meter name is `Microsoft.AspNetCore.Hosting`. + **TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** + + # routing + - id: metric.aspnet.routing.successful_matches + type: metric + metric_name: aspnet.routing.successful_matches + brief: Number of requests that successfully matched to an endpoint. + instrument: counter + unit: "{match}" + note: > + Corresponding `EventCounter` name is `routing-match-success`; Meter name is `Microsoft.AspNetCore.Routing` + attributes: + - ref: http.route + requirement_level: required + - ref: aspnet.routing.fallback + requirement_level: required + + - id: metric.aspnet.routing.failed_matches + type: metric + metric_name: aspnet.routing.failed_matches + brief: Number of requests that failed to match to an endpoint. + note: > + An unmatched request may be handled by later middleware, such as the static files or authentication middleware. + Corresponding `EventCounter` name is `routing-match-failure`; Meter name is `Microsoft.AspNetCore.Routing` + instrument: counter + unit: "{match}" + + # 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: Corresponding `EventCounter` name is `diagnostics-handler-exception`; Meter name is `Microsoft.AspNetCore.Diagnostics` + attributes: + - ref: exception.type + - ref: aspnet.handler + requirement_level: required + - id: exception.result + type: string + requirement_level: required + brief: TODO + examples: ["TODO"] + + # 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: Corresponding `EventCounter` name is `rate-limiting-current-leased-requests; Meter name is `Microsoft.AspNetCore.RateLimiting` + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + + - id: metric.aspnet.rate_limiting.request_leases.duration + type: metric + metric_name: aspnet.rate_limiting.request_leases.duration + brief: The duration of rate limiting lease held by requests on the server. + instrument: histogram + unit: "s" + note: | + Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` + **TODO do we need attributes?, can we explain what it means better**` + + - id: metric.aspnet.rate_limiting.queued_requests.duration + type: metric + metric_name: aspnet.rate_limiting.queued_requests.duration + brief: The duration of request in a queue, waiting to acquire a rate limiting lease. + instrument: histogram + unit: "s" + note: | + Corresponding `EventCounter` name is `rate-limiting-queued-request-duration`; 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? ** + **TODO: if they are queued, should they have reject reason ? ** + 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: | + Corresponding `EventCounter` name is `rate-limiting-current-queued-requests`; Meter name is `Microsoft.AspNetCore.RateLimiting` + + **TODO: if they are queued, should they have reject reason ? ** + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + - ref: aspnet.rate_limiting.reject_reason + + - id: metric.aspnet.rate_limiting.rejected_requests + type: metric + metric_name: aspnet.rate_limiting.rejected_requests + brief: Number of requests that failed 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. + + Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` + + **TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** + attributes: + - ref: aspnet.rate_limiting.policy + requirement_level: required + - ref: aspnet.rate_limiting.reject_reason \ No newline at end of file diff --git a/model/metrics/dotnet-dns.yaml b/model/metrics/dotnet-dns.yaml new file mode 100644 index 0000000000..f003157cbf --- /dev/null +++ b/model/metrics/dotnet-dns.yaml @@ -0,0 +1,22 @@ +groups: + - id: metric.dotnet.dns.lookups.duration + type: metric + metric_name: dns.lookups.duration + brief: Measures the time take to perform a DNS lookup. + instrument: histogram + unit: "s" + note: Meter name is `System.Net.NameResolution`. + attributes: + - id: 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. diff --git a/model/metrics/dotnet-http-client.yaml b/model/metrics/dotnet-http-client.yaml new file mode 100644 index 0000000000..bd3a7712f2 --- /dev/null +++ b/model/metrics/dotnet-http-client.yaml @@ -0,0 +1,87 @@ +groups: + - 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 `http-client-current-connections` and `http-client-current-idle-connections`; + Meter name is `System.Net.Http`. + attributes: + - id: 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.connections.duration + brief: "The duration of outbound HTTP connections." + instrument: histogram + unit: "s" + note: Corresponding `EventCounter` name is `http-client-requests-duration`; Meter name is `System.Net.Http`. + attributes: + - ref: url.scheme + - ref: network.protocol.version + - ref: server.address + - ref: server.socket.address + - ref: server.port + + - 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 `http-client-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: metric.dotnet.http.client.failed_requests + type: metric + metric_name: http.client.failed_requests + brief: "Number of outbound HTTP requests that have failed." + instrument: counter + unit: "{request}" + note: Corresponding `EventCounter` name is `http-client-failed-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 `http-client-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/http.yaml b/model/metrics/dotnet-http.yaml similarity index 100% rename from model/metrics/http.yaml rename to model/metrics/dotnet-http.yaml diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml new file mode 100644 index 0000000000..ac8095f2ea --- /dev/null +++ b/model/metrics/dotnet-kestrel.yaml @@ -0,0 +1,21 @@ +groups: + - id: metric.dotnet.dns.lookups.duration1 + type: metric + metric_name: dns.lookups.duration + brief: Measures the time take to perform a DNS lookup. + instrument: histogram + unit: "s" + attributes: + - id: question.name2 + 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. diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml new file mode 100644 index 0000000000..f32d423633 --- /dev/null +++ b/model/metrics/dotnet-signalr.yaml @@ -0,0 +1,21 @@ +groups: + - id: metric.signalr_http_transport.connections.duration + type: metric + metric_name: signalr_http_transport.connections.duration + brief: The duration of connections on the server. + instrument: histogram + unit: "s" + attributes: + - id: question.name1 + 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. From 1686a0734b38a8169f6f131fc4c761394db9ef0a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 13:44:51 -0700 Subject: [PATCH 02/12] return http metrics back --- model/metrics/{dotnet-http.yaml => http.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename model/metrics/{dotnet-http.yaml => http.yaml} (100%) diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/http.yaml similarity index 100% rename from model/metrics/dotnet-http.yaml rename to model/metrics/http.yaml From 72ae36dc6df9ad534fc90ea7c55d798681c1cc7e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 14:37:39 -0700 Subject: [PATCH 03/12] draft done --- docs/dotnet/README.md | 24 +++ docs/dotnet/dotnet-aspnet-metrics.md | 42 +++-- docs/dotnet/dotnet-dns-metrics.md | 9 +- docs/dotnet/dotnet-http-metrics.md | 23 ++- docs/dotnet/dotnet-kestrel-metrics.md | 221 ++++++++++++++++++++++++++ docs/dotnet/dotnet-signalr-metrics.md | 68 ++++++++ model/metrics/dotnet-aspnet.yaml | 26 +-- model/metrics/dotnet-dns.yaml | 22 --- model/metrics/dotnet-http-client.yaml | 35 +++- model/metrics/dotnet-kestrel.yaml | 134 ++++++++++++++-- model/metrics/dotnet-signalr.yaml | 50 ++++-- 11 files changed, 558 insertions(+), 96 deletions(-) create mode 100644 docs/dotnet/README.md create mode 100644 docs/dotnet/dotnet-kestrel-metrics.md create mode 100644 docs/dotnet/dotnet-signalr-metrics.md delete mode 100644 model/metrics/dotnet-dns.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 index e8625d745d..2557694444 100644 --- a/docs/dotnet/dotnet-aspnet-metrics.md +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -8,6 +8,18 @@ This document defines semantic conventions for ASP.NET Core metrics, not specifi +- [Routing](#routing) + * [Metric: `aspnet.routing.successful_matches`](#metric-aspnetroutingsuccessful_matches) + * [Metric: `aspnet.routing.failed_matches`](#metric-aspnetroutingfailed_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.rejected_requests`](#metric-aspnetrate_limitingrejected_requests) + ## Routing @@ -27,7 +39,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `aspnet.routing.successful_matches` | Counter | `{match}` | Number of requests that successfully matched to an endpoint. [1] | -**[1]:** Corresponding `EventCounter` name is `routing-match-success`; Meter name is `Microsoft.AspNetCore.Routing` +**[1]:** Meter name is `Microsoft.AspNetCore.Routing`. @@ -52,7 +64,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `aspnet.routing.failed_matches` | Counter | `{match}` | Number of requests that failed to match to an endpoint. [1] | -**[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Corresponding `EventCounter` name is `routing-match-failure`; Meter name is `Microsoft.AspNetCore.Routing` +**[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Meter name is `Microsoft.AspNetCore.Routing` @@ -72,7 +84,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `aspnet.diagnostics_handler.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. [1] | -**[1]:** Corresponding `EventCounter` name is `diagnostics-handler-exception`; Meter name is `Microsoft.AspNetCore.Diagnostics` +**[1]:** Meter name is `Microsoft.AspNetCore.Diagnostics` @@ -98,7 +110,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `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]:** Corresponding `EventCounter` name is `rate-limiting-current-leased-requests; Meter name is `Microsoft.AspNetCore.RateLimiting` +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` @@ -107,22 +119,22 @@ This metric is required. | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | -### Metric: `aspnet.rate_limiting.request_leases.duration` +### Metric: `aspnet.rate_limiting.request_lease.duration` **Status**: [Experimental][DocumentStatus] This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `aspnet.rate_limiting.request_leases.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | +| `aspnet.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] | -**[1]:** Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` +**[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` @@ -136,7 +148,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `aspnet.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. [1] | -**[1]:** Corresponding `EventCounter` name is `rate-limiting-current-queued-requests`; Meter name is `Microsoft.AspNetCore.RateLimiting` +**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO: if they are queued, should they have reject reason ? ** @@ -156,18 +168,18 @@ This metric is required. This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `aspnet.rate_limiting.queued_requests.duration` | Histogram | `s` | The duration of request in a queue, waiting to acquire a rate limiting lease. [1] | +| `aspnet.rate_limiting.queued_request.duration` | Histogram | `s` | The duration of request in a queue, waiting to acquire a rate limiting lease. [1] | -**[1]:** Corresponding `EventCounter` name is `rate-limiting-queued-request-duration`; Meter name is `Microsoft.AspNetCore.RateLimiting` +**[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? ** **TODO: if they are queued, should they have reject reason ? ** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | @@ -186,7 +198,7 @@ This metric is required. **[1]:** Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. -Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` +Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 900fd8dc29..1356572ed0 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -8,6 +8,9 @@ This document defines semantic conventions for DNS metrics emitted by .NET. +- [DNS metrics](#dns-metrics) + * [Metric: `dns.lookups.duration`](#metric-dnslookupsduration) + ## DNS metrics @@ -22,15 +25,15 @@ 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.lookups.duration` | Histogram | `s` | Measures the time take to perform a DNS lookup. [1] | +| `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 | |---|---|---|---|---| | `question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index b5a3c572a1..8164445ec8 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -8,6 +8,17 @@ This document defines semantic conventions for HTTP metrics emitted by .NET comp +- [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) + * [Metric: `http.client.failed_requests`](#metric-httpclientfailed_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 @@ -25,7 +36,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `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 `http-client-current-connections` and `http-client-current-idle-connections`; Meter name is `System.Net.Http`. +**[1]:** Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. @@ -57,9 +68,9 @@ This metric is required. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.connections.duration` | Histogram | `s` | The duration of outbound HTTP connections. [1] | +| `http.client.connection.duration` | Histogram | `s` | The duration of outbound HTTP connections. [1] | -**[1]:** Corresponding `EventCounter` name is `http-client-requests-duration`; Meter name is `System.Net.Http`. +**[1]:** Meter name is `System.Net.Http`. @@ -97,7 +108,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `http.client.active_requests` | UpDownCounter | `{request}` | Number of outbound HTTP requests that have failed. [1] | -**[1]:** Corresponding `EventCounter` name is `http-client-current-requests`; Meter name is `System.Net.Http`. +**[1]:** Corresponding `EventCounter` name is `current-requests`; Meter name is `System.Net.Http`. @@ -142,7 +153,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `http.client.failed_requests` | Counter | `{request}` | Number of outbound HTTP requests that have failed. [1] | -**[1]:** Corresponding `EventCounter` name is `http-client-failed-requests`; Meter name is `System.Net.Http`. +**[1]:** Corresponding `EventCounter` name is `requests-failed`; Meter name is `System.Net.Http`. @@ -210,7 +221,7 @@ This metric is required. | -------- | --------------- | ----------- | -------------- | | `http.server.unhandled_requests` | UpDownCounter | `{request}` | Number of requests that reached the end of the middleware pipeline without being handled by application code. [1] | -**[1]:** Corresponding `EventCounter` name is `http-server-unhandled-requests`; Meter name is `Microsoft.AspNetCore.Hosting`. +**[1]:** Meter name is `Microsoft.AspNetCore.Hosting`. **TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md new file mode 100644 index 0000000000..cf77a9dc7a --- /dev/null +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -0,0 +1,221 @@ +# 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** + + +## 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 | +|---|---|---|---|---| +| `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 | +| `kestrel.endpoint` | string | TODO [2] | `TODO` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | +| `tls.protocol` | string | TODO [4] | `TODO` | 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: Let's define common attribute for error reason/status** + +**[2]:** **TODO: why not server.**? What's KEstrel-specific about it** + +**[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: why not network.protocol.***? + + +## 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** + + +## 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** + + +## 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | +| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | 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: why not server.**? What's KEstrel-specific about it** + +**[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`. + + +## 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** + + +## 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 | +|---|---|---|---|---| +| `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 | +| `kestrel.endpoint` | string | TODO [2] | `TODO` | Recommended | +| `tls.protocol` | string | TODO [3] | `TODO` | Recommended | + +**[1]:** **TODO: Let's define common attribute for error reason/status** + +**[2]:** **TODO: why not server.**? What's KEstrel-specific about it** + +**[3]:** **TODO: why not network.protocol.***? + + +## 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 | +|---|---|---|---|---| +| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** + + + +[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..93424d9f8a --- /dev/null +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -0,0 +1,68 @@ +# 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` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr_http_transport.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | + +**[1]:** **TODO: why http_transport? can we report protocol name as dimension and not a metric name?** +**TODO: we should do signalr.server** +Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.http_transport.status` | string | TODO [1] | `TODO` | Recommended | +| `signalr.http_transport.transport` | string | TODO [2] | `TODO` | Recommended | + +**[1]:** **TODO: why not signalr.status? What's HTTP-specific about it** + +**[2]:** **TODO: why not network.transport?** + + +## Metric: `signalr_http_transport.active_connections` + +**Status**: [Experimental][DocumentStatus] + +This metric is required. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr_http_transport.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | + +**[1]:** **TODO: why http_transport? can we report protocol as dimension and not a metric name?** +**TODO: we should do signalr.server** +Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `signalr.http_transport.status` | string | TODO [1] | `TODO` | Recommended | + +**[1]:** **TODO: why not signalr.status? What's HTTP-specific about it** + + + +[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/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml index abb7bcba05..696f2147ca 100644 --- a/model/metrics/dotnet-aspnet.yaml +++ b/model/metrics/dotnet-aspnet.yaml @@ -30,7 +30,7 @@ groups: instrument: updowncounter unit: "{request}" note: | - Corresponding `EventCounter` name is `http-server-unhandled-requests`; Meter name is `Microsoft.AspNetCore.Hosting`. + Meter name is `Microsoft.AspNetCore.Hosting`. **TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** # routing @@ -41,7 +41,7 @@ groups: instrument: counter unit: "{match}" note: > - Corresponding `EventCounter` name is `routing-match-success`; Meter name is `Microsoft.AspNetCore.Routing` + Meter name is `Microsoft.AspNetCore.Routing`. attributes: - ref: http.route requirement_level: required @@ -54,7 +54,7 @@ groups: brief: Number of requests that failed to match to an endpoint. note: > An unmatched request may be handled by later middleware, such as the static files or authentication middleware. - Corresponding `EventCounter` name is `routing-match-failure`; Meter name is `Microsoft.AspNetCore.Routing` + Meter name is `Microsoft.AspNetCore.Routing` instrument: counter unit: "{match}" @@ -65,7 +65,7 @@ groups: brief: Number of exceptions caught by exception handling middleware. instrument: counter unit: "{exception}" - note: Corresponding `EventCounter` name is `diagnostics-handler-exception`; Meter name is `Microsoft.AspNetCore.Diagnostics` + note: Meter name is `Microsoft.AspNetCore.Diagnostics` attributes: - ref: exception.type - ref: aspnet.handler @@ -83,29 +83,29 @@ groups: brief: Number of requests that are currently active on the server that hold a rate limiting lease. instrument: updowncounter unit: "{request}" - note: Corresponding `EventCounter` name is `rate-limiting-current-leased-requests; Meter name is `Microsoft.AspNetCore.RateLimiting` + note: Meter name is `Microsoft.AspNetCore.RateLimiting` attributes: - ref: aspnet.rate_limiting.policy requirement_level: required - - id: metric.aspnet.rate_limiting.request_leases.duration + - id: metric.aspnet.rate_limiting.request_lease.duration type: metric - metric_name: aspnet.rate_limiting.request_leases.duration + 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: | - Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` + Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO do we need attributes?, can we explain what it means better**` - - id: metric.aspnet.rate_limiting.queued_requests.duration + - id: metric.aspnet.rate_limiting.queued_request.duration type: metric - metric_name: aspnet.rate_limiting.queued_requests.duration + 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: | - Corresponding `EventCounter` name is `rate-limiting-queued-request-duration`; Meter name is `Microsoft.AspNetCore.RateLimiting` + 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? ** **TODO: if they are queued, should they have reject reason ? ** @@ -120,7 +120,7 @@ groups: instrument: updowncounter unit: "{request}" note: | - Corresponding `EventCounter` name is `rate-limiting-current-queued-requests`; Meter name is `Microsoft.AspNetCore.RateLimiting` + Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO: if they are queued, should they have reject reason ? ** attributes: @@ -137,7 +137,7 @@ groups: note: | Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease. - Corresponding `EventCounter` name is `rate-limiting-lease-failed-requests `; Meter name is `Microsoft.AspNetCore.RateLimiting` + Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** attributes: diff --git a/model/metrics/dotnet-dns.yaml b/model/metrics/dotnet-dns.yaml deleted file mode 100644 index f003157cbf..0000000000 --- a/model/metrics/dotnet-dns.yaml +++ /dev/null @@ -1,22 +0,0 @@ -groups: - - id: metric.dotnet.dns.lookups.duration - type: metric - metric_name: dns.lookups.duration - brief: Measures the time take to perform a DNS lookup. - instrument: histogram - unit: "s" - note: Meter name is `System.Net.NameResolution`. - attributes: - - id: 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. diff --git a/model/metrics/dotnet-http-client.yaml b/model/metrics/dotnet-http-client.yaml index bd3a7712f2..064003dd96 100644 --- a/model/metrics/dotnet-http-client.yaml +++ b/model/metrics/dotnet-http-client.yaml @@ -1,4 +1,26 @@ 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: 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 @@ -6,8 +28,7 @@ groups: instrument: updowncounter unit: "{connection}" note: - Corresponding `EventCounter` names are `http-client-current-connections` and `http-client-current-idle-connections`; - Meter name is `System.Net.Http`. + Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. attributes: - id: connection.state type: @@ -29,11 +50,11 @@ groups: - id: metric.dotnet.http.client.connection.duration type: metric - metric_name: http.client.connections.duration + metric_name: http.client.connection.duration brief: "The duration of outbound HTTP connections." instrument: histogram unit: "s" - note: Corresponding `EventCounter` name is `http-client-requests-duration`; Meter name is `System.Net.Http`. + note: Meter name is `System.Net.Http`. attributes: - ref: url.scheme - ref: network.protocol.version @@ -47,7 +68,7 @@ groups: brief: "Number of outbound HTTP requests that have failed." instrument: updowncounter unit: "{request}" - note: Corresponding `EventCounter` name is `http-client-current-requests`; Meter name is `System.Net.Http`. + note: Corresponding `EventCounter` name is `current-requests`; Meter name is `System.Net.Http`. attributes: - ref: http.request.method - ref: url.scheme @@ -62,7 +83,7 @@ groups: brief: "Number of outbound HTTP requests that have failed." instrument: counter unit: "{request}" - note: Corresponding `EventCounter` name is `http-client-failed-requests`; Meter name is `System.Net.Http`. + note: Corresponding `EventCounter` name is `requests-failed`; Meter name is `System.Net.Http`. attributes: - ref: http.request.method - ref: url.scheme @@ -77,7 +98,7 @@ groups: brief: "The amount of time requests spent on a queue waiting for an available connection." instrument: histogram unit: "s" - note: Corresponding `EventCounter` name is `http-client-requests-queue-duration`; Meter name is `System.Net.Http`. + note: Corresponding `EventCounter` name is `*-requests-queue-duration`; Meter name is `System.Net.Http`. attributes: - ref: http.request.method - ref: url.scheme diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml index ac8095f2ea..6474d956e4 100644 --- a/model/metrics/dotnet-kestrel.yaml +++ b/model/metrics/dotnet-kestrel.yaml @@ -1,21 +1,123 @@ groups: - - id: metric.dotnet.dns.lookups.duration1 + - id: kestrel + prefix: kestrel + type: attribute_group + brief: Kestrel attributes + attributes: + - id: endpoint + type: string + brief: TODO + examples: ["TODO"] + note: "**TODO: why not server.**? What's KEstrel-specific about it**" + - id: tls + prefix: tls + type: attribute_group + brief: TLS attributes + attributes: + - id: protocol + type: string + brief: TODO + examples: ["TODO"] + note: "**TODO: why not network.protocol.***?" + + - 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` + attributes: + - ref: kestrel.endpoint + + - id: metric.kestrel.connection.duration type: metric - metric_name: dns.lookups.duration - brief: Measures the time take to perform a DNS lookup. + 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` attributes: - - id: question.name2 - 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. + - ref: kestrel.endpoint + - ref: url.scheme + - ref: network.protocol.version + - ref: tls.protocol + - ref: exception.type + note: "**TODO: Let's define common attribute for error reason/status**" + + - 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** + attributes: + - ref: kestrel.endpoint + + - 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` + attributes: + - ref: kestrel.endpoint + + + - 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` + attributes: + - ref: kestrel.endpoint + - ref: url.scheme + - ref: network.protocol.version + + - 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` + attributes: + - ref: kestrel.endpoint + + - 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` + attributes: + - ref: kestrel.endpoint + - ref: tls.protocol + - ref: exception.type + note: "**TODO: Let's define common attribute for error reason/status**" + + + - 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` + attributes: + - ref: kestrel.endpoint diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml index f32d423633..0631aa0413 100644 --- a/model/metrics/dotnet-signalr.yaml +++ b/model/metrics/dotnet-signalr.yaml @@ -1,21 +1,43 @@ groups: - - id: metric.signalr_http_transport.connections.duration + - id: signalr + prefix: signalr + type: attribute_group + brief: SignalR attributes + attributes: + - id: http_transport.status + type: string + brief: TODO + examples: ["TODO"] + note: "**TODO: why not signalr.status? What's HTTP-specific about it**" + - id: http_transport.transport + type: string + brief: TODO + examples: ["TODO"] + note: "**TODO: why not network.transport?**" + + - id: metric.signalr.server.connection.duration type: metric - metric_name: signalr_http_transport.connections.duration + metric_name: signalr_http_transport.connection.duration brief: The duration of connections on the server. instrument: histogram unit: "s" + note: | + **TODO: why http_transport? can we report protocol name as dimension and not a metric name?** + **TODO: we should do signalr.server** + Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` attributes: - - id: question.name1 - type: string - brief: The name being queried. - requirement_level: required - examples: ["www.example.com", "dot.net"] - note: | - The name being queried. + - ref: signalr.http_transport.status + - ref: signalr.http_transport.transport - 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.signalr.server.active_connections + type: metric + metric_name: signalr_http_transport.active_connections + brief: Number of connections that are currently active on the server. + instrument: histogram + unit: "s" + note: | + **TODO: why http_transport? can we report protocol as dimension and not a metric name?** + **TODO: we should do signalr.server** + Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + attributes: + - ref: signalr.http_transport.status From d4a0053634919dd2b81ee3c68b52667bac607066 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 15:58:29 -0700 Subject: [PATCH 04/12] nits --- docs/dotnet/dotnet-http-metrics.md | 4 ---- model/metrics/dotnet-aspnet.yaml | 2 +- model/metrics/dotnet-kestrel.yaml | 14 +++++--------- model/metrics/dotnet-signalr.yaml | 2 +- 4 files changed, 7 insertions(+), 15 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 8164445ec8..15640e0c7b 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -197,8 +197,6 @@ All Http server metrics are reported by `Microsoft.AspNetCore.Hosting ` meter. Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverduration) -Corresponding `EventCounter` (without dimensions) is `http-client-requests-duration` - ### Metric: `http.server.active_requests` **TODO: Opt-in address and port?** @@ -206,8 +204,6 @@ Corresponding `EventCounter` (without dimensions) is `http-client-requests-durat Follows common [http.server.active_requests](../http/http-metrics.md#metric-httpserveractive_requests) -Corresponding `EventCounter` (without dimensions) is `http-client-current-requests` - ### Metric: `http.server.unhandled_requests` **TODO:Any chance we will need to report any attributes in future?** diff --git a/model/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml index 696f2147ca..f57d4f512c 100644 --- a/model/metrics/dotnet-aspnet.yaml +++ b/model/metrics/dotnet-aspnet.yaml @@ -143,4 +143,4 @@ groups: attributes: - ref: aspnet.rate_limiting.policy requirement_level: required - - ref: aspnet.rate_limiting.reject_reason \ No newline at end of file + - ref: aspnet.rate_limiting.reject_reason diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml index 6474d956e4..a2685057c8 100644 --- a/model/metrics/dotnet-kestrel.yaml +++ b/model/metrics/dotnet-kestrel.yaml @@ -1,5 +1,5 @@ groups: - - id: kestrel + - id: kestrel.common_attributes prefix: kestrel type: attribute_group brief: Kestrel attributes @@ -26,8 +26,7 @@ groups: 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` + note: Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Server.Kestrel` attributes: - ref: kestrel.endpoint @@ -37,8 +36,7 @@ groups: brief: The duration of connections on the server. instrument: histogram unit: "s" - note: | - Meter name is `Microsoft.AspNetCore.Server.Kestrel` + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` attributes: - ref: kestrel.endpoint - ref: url.scheme @@ -67,8 +65,7 @@ groups: 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` + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` attributes: - ref: kestrel.endpoint @@ -79,8 +76,7 @@ groups: 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` + note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` attributes: - ref: kestrel.endpoint - ref: url.scheme diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml index 0631aa0413..569b3898ec 100644 --- a/model/metrics/dotnet-signalr.yaml +++ b/model/metrics/dotnet-signalr.yaml @@ -1,5 +1,5 @@ groups: - - id: signalr + - id: signalr.common_attributes prefix: signalr type: attribute_group brief: SignalR attributes From 092b502b6979564239b48d8f987e6230161de240 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 16:17:43 -0700 Subject: [PATCH 05/12] nits --- docs/dotnet/dotnet-aspnet-metrics.md | 16 ++-- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 40 ++++++++-- docs/dotnet/dotnet-kestrel-metrics.md | 16 ++-- docs/dotnet/dotnet-signalr-metrics.md | 4 +- model/metrics/dotnet-http-client.yaml | 108 -------------------------- 6 files changed, 54 insertions(+), 132 deletions(-) delete mode 100644 model/metrics/dotnet-http-client.yaml diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md index 2557694444..fe2ff44ff2 100644 --- a/docs/dotnet/dotnet-aspnet-metrics.md +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -42,7 +42,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.Routing`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.routing.fallback` | string | TODO | `TODO` | Required | @@ -67,7 +67,7 @@ This metric is required. **[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Meter name is `Microsoft.AspNetCore.Routing` - + ## Exception metrics @@ -87,7 +87,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.Diagnostics` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `exception.result` | string | TODO | `TODO` | Required | @@ -113,7 +113,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | @@ -134,7 +134,7 @@ This metric is required. **TODO do we need attributes?, can we explain what it means better**` - + ### Metric: `aspnet.rate_limiting.queued_requests` @@ -153,7 +153,7 @@ This metric is required. **TODO: if they are queued, should they have reject reason ? ** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | @@ -179,7 +179,7 @@ This metric is required. **TODO: if they are queued, should they have reject reason ? ** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | @@ -203,7 +203,7 @@ Meter name is `Microsoft.AspNetCore.RateLimiting` **TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 1356572ed0..7969faaf83 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -33,7 +33,7 @@ of **`[TODO]`**. **[1]:** Meter name is `System.Net.NameResolution`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 15640e0c7b..60d5092759 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -39,7 +39,7 @@ This metric is required. **[1]:** Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `connection.state` | string | Connection state. | `active`; `idle` | Required | @@ -73,7 +73,7 @@ This metric is required. **[1]:** Meter name is `System.Net.Http`. - + | 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 | @@ -111,7 +111,7 @@ This metric is required. **[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 | @@ -138,6 +138,21 @@ Instrumentations for specific web frameworks that consider HTTP methods to be ca 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.failed_requests` @@ -156,7 +171,7 @@ This metric is required. **[1]:** Corresponding `EventCounter` name is `requests-failed`; Meter name is `System.Net.Http`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | @@ -183,6 +198,21 @@ Instrumentations for specific web frameworks that consider HTTP methods to be ca 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 @@ -221,7 +251,7 @@ This metric is required. **TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** - + [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 index cf77a9dc7a..57586bc560 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -31,7 +31,7 @@ This metric is required. **[1]:** Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Server.Kestrel` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | @@ -53,7 +53,7 @@ This metric is required. **[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 | @@ -88,7 +88,7 @@ Meter name is `Microsoft.AspNetCore.Server.Kestrel` **TODO: do we ever will have other rejection reasons** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | @@ -110,7 +110,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | @@ -132,7 +132,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | @@ -159,7 +159,7 @@ This metric is required. Meter name is `Microsoft.AspNetCore.Server.Kestrel` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | @@ -181,7 +181,7 @@ This metric is required. **[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 | @@ -209,7 +209,7 @@ This metric is required. **[1]:** Meter name is `Microsoft.AspNetCore.Server.Kestrel` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 93424d9f8a..b77bf9313f 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -29,7 +29,7 @@ This metric is required. Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `signalr.http_transport.status` | string | TODO [1] | `TODO` | Recommended | @@ -56,7 +56,7 @@ This metric is required. Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `signalr.http_transport.status` | string | TODO [1] | `TODO` | Recommended | diff --git a/model/metrics/dotnet-http-client.yaml b/model/metrics/dotnet-http-client.yaml deleted file mode 100644 index 064003dd96..0000000000 --- a/model/metrics/dotnet-http-client.yaml +++ /dev/null @@ -1,108 +0,0 @@ -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: 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: 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 - - - 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: metric.dotnet.http.client.failed_requests - type: metric - metric_name: http.client.failed_requests - brief: "Number of outbound HTTP requests that have failed." - instrument: counter - unit: "{request}" - note: Corresponding `EventCounter` name is `requests-failed`; 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 From 42860c01253dddd349865a852cd16990a0a28d99 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 16:18:17 -0700 Subject: [PATCH 06/12] nits --- model/metrics/dotnet-http.yaml | 108 +++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 model/metrics/dotnet-http.yaml diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/dotnet-http.yaml new file mode 100644 index 0000000000..064003dd96 --- /dev/null +++ b/model/metrics/dotnet-http.yaml @@ -0,0 +1,108 @@ +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: 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: 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 + + - 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: metric.dotnet.http.client.failed_requests + type: metric + metric_name: http.client.failed_requests + brief: "Number of outbound HTTP requests that have failed." + instrument: counter + unit: "{request}" + note: Corresponding `EventCounter` name is `requests-failed`; 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 From bac15e0a1b3f702fd75bf2c0c6c5ebc8671294bb Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 15:51:15 -0700 Subject: [PATCH 07/12] proposed changes --- docs/dotnet/dotnet-aspnet-metrics.md | 74 ++++---- docs/dotnet/dotnet-http-metrics.md | 243 ++++++++++++++++++++---- docs/dotnet/dotnet-kestrel-metrics.md | 254 +++++++++++++++++++++++--- docs/dotnet/dotnet-signalr-metrics.md | 54 ++++-- model/metrics/dotnet-aspnet.yaml | 72 ++++---- model/metrics/dotnet-common.yaml | 48 +++++ model/metrics/dotnet-http.yaml | 39 ++-- model/metrics/dotnet-kestrel.yaml | 63 +++---- model/metrics/dotnet-signalr.yaml | 36 ++-- 9 files changed, 650 insertions(+), 233 deletions(-) create mode 100644 model/metrics/dotnet-common.yaml diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md index fe2ff44ff2..0d30b8905b 100644 --- a/docs/dotnet/dotnet-aspnet-metrics.md +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -9,8 +9,7 @@ This document defines semantic conventions for ASP.NET Core metrics, not specifi - [Routing](#routing) - * [Metric: `aspnet.routing.successful_matches`](#metric-aspnetroutingsuccessful_matches) - * [Metric: `aspnet.routing.failed_matches`](#metric-aspnetroutingfailed_matches) + * [Metric: `aspnet.routing.matches`](#metric-aspnetroutingmatches) - [Exception metrics](#exception-metrics) * [Metric: `aspnet.diagnostics_handler.exceptions`](#metric-aspnetdiagnostics_handlerexceptions) - [Rate-limiting](#rate-limiting) @@ -18,7 +17,7 @@ This document defines semantic conventions for ASP.NET Core metrics, not specifi * [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.rejected_requests`](#metric-aspnetrate_limitingrejected_requests) + * [Metric: `aspnet.rate_limiting.requests`](#metric-aspnetrate_limitingrequests) @@ -26,48 +25,36 @@ This document defines semantic conventions for ASP.NET Core metrics, not specifi All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter. -### Metric: `aspnet.routing.successful_matches` +### Metric: `aspnet.routing.matches` **Status**: [Experimental][DocumentStatus] -**TODO: can we try one aspnet.routing.matches** ? - 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]:** Meter name is `Microsoft.AspNetCore.Routing`. +**[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. - - -### Metric: `aspnet.routing.failed_matches` - -**TODO: would if be useful to add method name, scheme, or other attributes?** - -**Status**: [Experimental][DocumentStatus] - -This metric is required. - -| Name | Instrument Type | Unit (UCUM) | Description | -| -------- | --------------- | ----------- | -------------- | -| `aspnet.routing.failed_matches` | Counter | `{match}` | Number of requests that failed to match 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` - +`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` | No error | +| `failure` | failure | ## Exception metrics @@ -90,9 +77,19 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `exception.result` | string | TODO | `TODO` | Required | | `aspnet.handler` | string | TODO | `TODO` | Required | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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 @@ -149,17 +146,12 @@ This metric is required. | `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` - -**TODO: if they are queued, should they have reject reason ? ** | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | -| `aspnet.rate_limiting.reject_reason` | string | TODO [1] | `TODO` | Recommended | - -**[1]:** **TODO should it be an enum?** ### Metric: `aspnet.rate_limiting.queued_requests.duration` @@ -176,7 +168,6 @@ This metric is required. **[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? ** -**TODO: if they are queued, should they have reject reason ? ** @@ -185,31 +176,34 @@ This metric is required. | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | -### Metric: `aspnet.rate_limiting.rejected_requests` +### Metric: `aspnet.rate_limiting.requests` **Status**: [Experimental][DocumentStatus] This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `aspnet.rate_limiting.rejected_requests` | Counter | `{request}` | Number of requests that failed to acquire a rate limiting lease. [1] | +| `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` - -**TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required | -| `aspnet.rate_limiting.reject_reason` | string | TODO [1] | `TODO` | Recommended | +| `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. -**[1]:** **TODO should it be an enum?** +| Value | Description | +|---|---| +| `acquired` | lease acquired | +| `rejected_reason1` | TODO | diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 60d5092759..8d3a702cd2 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -13,7 +13,6 @@ This document defines semantic conventions for HTTP metrics emitted by .NET comp * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration) * [Metric: `http.client.duration`](#metric-httpclientduration) * [Metric: `http.client.active_requests`](#metric-httpclientactive_requests) - * [Metric: `http.client.failed_requests`](#metric-httpclientfailed_requests) - [HTTP server](#http-server) * [Metric: `http.server.duration`](#metric-httpserverduration) * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests) @@ -76,6 +75,8 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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 inhttps://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 | @@ -83,43 +84,49 @@ This metric is required. | [`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`. - - -### Metric: `http.client.duration` -**TODO: any reason not to include server.socket.address?** +`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. -**TODO: should we add error status to http semconv ?** - https://github.com/open-telemetry/opentelemetry-specification/issues/3243 - -Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientduration) +| Value | Description | +|---|---| +| `RanToCompletion` | No error | +| `Canceled` | Canceled | +| `Faulted` | Faulted [1] | -### Metric: `http.client.active_requests` +**[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. -**TODO: any reason not to include server.socket.address?** -**TODO: any reason we don't have this metric in generic OTEL semconv?** +`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 | + -**Status**: [Experimental][DocumentStatus] +### Metric: `http.client.duration` -This metric is required. +Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientduration), but adds non-code errors - + | 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`. +| `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 started it supports terminal states 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 inhttps://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 | 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) @@ -139,6 +146,27 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[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.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 | @@ -155,23 +183,21 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original | `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | -### Metric: `http.client.failed_requests` - -**TODO: We still need error code to make it useful and backward compatible. If we add error code, we should also add it to http.client.duration as well and then this one should be deleted.** +### Metric: `http.client.active_requests` **Status**: [Experimental][DocumentStatus] This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.client.failed_requests` | Counter | `{request}` | Number of outbound HTTP requests that have failed. [1] | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of outbound HTTP requests that have failed. [1] | -**[1]:** Corresponding `EventCounter` name is `requests-failed`; Meter name is `System.Net.Http`. +**[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 | @@ -221,18 +247,170 @@ All Http server metrics are reported by `Microsoft.AspNetCore.Hosting ` meter. ### Metric: `http.server.duration` -**TODO: should we add error status to http semconv ?** - https://github.com/open-telemetry/opentelemetry-specification/issues/3243 **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 started it supports terminal states 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 inhttps://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 | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In | + +**[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 + +- 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. + +**[4]:** 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) +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` @@ -245,10 +423,9 @@ This metric is required. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `http.server.unhandled_requests` | UpDownCounter | `{request}` | Number of requests that reached the end of the middleware pipeline without being handled by application code. [1] | +| `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`. -**TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** +**[1]:** Meter name is `Microsoft.AspNetCore.Hosting`.** diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 57586bc560..d10b05b307 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -34,9 +34,33 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | 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]:** **TODO: why not server.**? What's KEstrel-specific about it** +**[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` @@ -56,19 +80,44 @@ This metric is required. | 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 | -| `kestrel.endpoint` | string | TODO [2] | `TODO` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [3] | `3.1.1` | Recommended | -| `tls.protocol` | string | TODO [4] | `TODO` | 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 | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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. -**[1]:** **TODO: Let's define common attribute for error reason/status** +`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. -**[2]:** **TODO: why not server.**? What's KEstrel-specific about it** +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | -**[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`. +`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. -**[4]:** **TODO: why not network.protocol.***? +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | ## Metric: `kestrel.rejected_connections` @@ -91,9 +140,33 @@ Meter name is `Microsoft.AspNetCore.Server.Kestrel` | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | 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]:** **TODO: why not server.**? What's KEstrel-specific about it** +**[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` @@ -113,9 +186,33 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | 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. + +`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. -**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | ## Metric: `kestrel.queued_requests` @@ -135,13 +232,33 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | Recommended | -| [`network.protocol.version`](../general/attributes.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | 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 | +| [`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]:** **TODO: why not server.**? What's KEstrel-specific about it** +**[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]:** `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` @@ -162,9 +279,33 @@ Meter name is `Microsoft.AspNetCore.Server.Kestrel` | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | 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`. -**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** +**[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` @@ -184,15 +325,44 @@ This metric is required. | 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 | -| `kestrel.endpoint` | string | TODO [2] | `TODO` | Recommended | -| `tls.protocol` | string | TODO [3] | `TODO` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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`. -**[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. -**[2]:** **TODO: why not server.**? What's KEstrel-specific about it** +`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. -**[3]:** **TODO: why not network.protocol.***? +| 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` @@ -212,9 +382,33 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `kestrel.endpoint` | string | TODO [1] | `TODO` | 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. + +`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. -**[1]:** **TODO: why not server.**? What's KEstrel-specific about it** +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index b77bf9313f..6dafc13b0d 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -22,22 +22,39 @@ This metric is required. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `signalr_http_transport.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | +| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | -**[1]:** **TODO: why http_transport? can we report protocol name as dimension and not a metric name?** -**TODO: we should do signalr.server** -Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` +**[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 | TODO [1] | `TODO` | Recommended | -| `signalr.http_transport.transport` | string | TODO [2] | `TODO` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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 | -**[1]:** **TODO: why not signalr.status? What's HTTP-specific about it** +**[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]:** **TODO: why not network.transport?** +`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_transport.active_connections` @@ -49,19 +66,28 @@ This metric is required. | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `signalr_http_transport.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | +| `signalr.server.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | -**[1]:** **TODO: why http_transport? can we report protocol as dimension and not a metric name?** -**TODO: we should do signalr.server** -Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` +**[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 | TODO [1] | `TODO` | 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 | + +**[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`. + +`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. -**[1]:** **TODO: why not signalr.status? What's HTTP-specific about it** +| Value | Description | +|---|---| +| `tcp` | TCP | +| `udp` | UDP | +| `pipe` | Named or anonymous pipe. See note below. | +| `unix` | Unix domain socket | diff --git a/model/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml index f57d4f512c..d670ccf0ff 100644 --- a/model/metrics/dotnet-aspnet.yaml +++ b/model/metrics/dotnet-aspnet.yaml @@ -8,11 +8,19 @@ groups: type: string brief: TODO examples: ["TODO"] - - id: rate_limiting.reject_reason - type: string - brief: TODO - examples: ["TODO"] - note: "**TODO should it be an enum?**" + - 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 @@ -21,42 +29,46 @@ groups: type: string brief: TODO examples: ["TODO"] + - id: match_status + type: + allow_custom_values: true + members: + - id: success + value: 'success' + brief: 'No error' + - 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: http.server.unhandled_requests + 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`. - **TODO Any reason not to put it into aspnet? seems ASP.NET -specific (middleware, app code), not necessarily HTTP?** + Meter name is `Microsoft.AspNetCore.Hosting`.** # routing - - id: metric.aspnet.routing.successful_matches + - 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: > - Meter name is `Microsoft.AspNetCore.Routing`. + 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 - - - id: metric.aspnet.routing.failed_matches - type: metric - metric_name: aspnet.routing.failed_matches - brief: Number of requests that failed to match to an endpoint. - note: > - An unmatched request may be handled by later middleware, such as the static files or authentication middleware. - Meter name is `Microsoft.AspNetCore.Routing` - instrument: counter - unit: "{match}" + - ref: aspnet.match_status + requirement_level: required # diagnostics - id: metric.aspnet.diagnostics_handler.exceptions @@ -70,11 +82,7 @@ groups: - ref: exception.type - ref: aspnet.handler requirement_level: required - - id: exception.result - type: string - requirement_level: required - brief: TODO - examples: ["TODO"] + - ref: dotnet.error.code # rate_limiting - id: metric.aspnet.rate_limiting.active_request_leases @@ -108,7 +116,6 @@ groups: 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? ** - **TODO: if they are queued, should they have reject reason ? ** attributes: - ref: aspnet.rate_limiting.policy requirement_level: required @@ -121,26 +128,21 @@ groups: unit: "{request}" note: | Meter name is `Microsoft.AspNetCore.RateLimiting` - - **TODO: if they are queued, should they have reject reason ? ** attributes: - ref: aspnet.rate_limiting.policy requirement_level: required - - ref: aspnet.rate_limiting.reject_reason - - id: metric.aspnet.rate_limiting.rejected_requests + - id: metric.aspnet.rate_limiting.requests type: metric - metric_name: aspnet.rate_limiting.rejected_requests - brief: Number of requests that failed to acquire a rate limiting lease. + 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` - - **TODO: can we report aspnet.rate_limiting.request count instead and have reject_reason to count failed/successful ?** attributes: - ref: aspnet.rate_limiting.policy requirement_level: required - - ref: aspnet.rate_limiting.reject_reason + - 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..9625f6e1e0 --- /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 started it supports terminal states 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 inhttps://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 index 064003dd96..3b403d1f58 100644 --- a/model/metrics/dotnet-http.yaml +++ b/model/metrics/dotnet-http.yaml @@ -61,6 +61,30 @@ groups: - 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 + + - 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 - id: metric.dotnet.http.client.active_requests type: metric @@ -77,21 +101,6 @@ groups: - ref: server.socket.address - ref: server.port - - id: metric.dotnet.http.client.failed_requests - type: metric - metric_name: http.client.failed_requests - brief: "Number of outbound HTTP requests that have failed." - instrument: counter - unit: "{request}" - note: Corresponding `EventCounter` name is `requests-failed`; 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 diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml index a2685057c8..3db021c16d 100644 --- a/model/metrics/dotnet-kestrel.yaml +++ b/model/metrics/dotnet-kestrel.yaml @@ -2,23 +2,18 @@ groups: - id: kestrel.common_attributes prefix: kestrel type: attribute_group - brief: Kestrel attributes + brief: Common kestrel attributes + note: "**TODO: Let's pick relevant attributes instead of kestrel.endpoint from this list, and/or use `url.full`**" attributes: - - id: endpoint - type: string - brief: TODO - examples: ["TODO"] - note: "**TODO: why not server.**? What's KEstrel-specific about it**" - - id: tls - prefix: tls - type: attribute_group - brief: TLS attributes - attributes: - - id: protocol - type: string - brief: TODO - examples: ["TODO"] - note: "**TODO: why not network.protocol.***?" + #- 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: metric.kestrel.active_connections type: metric @@ -27,8 +22,7 @@ groups: instrument: updowncounter unit: "{connection}" note: Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Server.Kestrel` - attributes: - - ref: kestrel.endpoint + extends: kestrel.common_attributes - id: metric.kestrel.connection.duration type: metric @@ -37,13 +31,9 @@ groups: instrument: histogram unit: "s" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes attributes: - - ref: kestrel.endpoint - - ref: url.scheme - - ref: network.protocol.version - - ref: tls.protocol - - ref: exception.type - note: "**TODO: Let's define common attribute for error reason/status**" + - ref: dotnet.error.code - id: metric.kestrel.rejected_connections type: metric @@ -56,8 +46,7 @@ groups: Meter name is `Microsoft.AspNetCore.Server.Kestrel` **TODO: do we ever will have other rejection reasons** - attributes: - - ref: kestrel.endpoint + extends: kestrel.common_attributes - id: metric.kestrel.queued_connections type: metric @@ -66,9 +55,7 @@ groups: instrument: updowncounter unit: "{connection}" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` - attributes: - - ref: kestrel.endpoint - + extends: kestrel.common_attributes - id: metric.kestrel.queued_requests type: metric @@ -77,10 +64,7 @@ groups: instrument: updowncounter unit: "{connection}" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` - attributes: - - ref: kestrel.endpoint - - ref: url.scheme - - ref: network.protocol.version + extends: kestrel.common_attributes - id: metric.kestrel.upgraded_connections type: metric @@ -91,8 +75,7 @@ groups: 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: kestrel.endpoint + extends: kestrel.common_attributes - id: metric.kestrel.tls_handshake.duration type: metric @@ -101,12 +84,9 @@ groups: instrument: histogram unit: "s" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` + extends: kestrel.common_attributes attributes: - - ref: kestrel.endpoint - - ref: tls.protocol - - ref: exception.type - note: "**TODO: Let's define common attribute for error reason/status**" - + - ref: dotnet.error.code - id: metric.kestrel.active_tls_handshakes type: metric @@ -115,5 +95,4 @@ groups: instrument: updowncounter unit: "{handshake}" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` - attributes: - - ref: kestrel.endpoint + extends: kestrel.common_attributes \ No newline at end of file diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml index 569b3898ec..605bd89548 100644 --- a/model/metrics/dotnet-signalr.yaml +++ b/model/metrics/dotnet-signalr.yaml @@ -4,40 +4,28 @@ groups: type: attribute_group brief: SignalR attributes attributes: - - id: http_transport.status - type: string - brief: TODO - examples: ["TODO"] - note: "**TODO: why not signalr.status? What's HTTP-specific about it**" - - id: http_transport.transport - type: string - brief: TODO - examples: ["TODO"] - note: "**TODO: why not network.transport?**" + - ref: dotnet.error.code + - ref: network.protocol.name + - ref: network.protocol.version + - ref: network.transport - id: metric.signalr.server.connection.duration type: metric - metric_name: signalr_http_transport.connection.duration + metric_name: signalr.server.connection.duration brief: The duration of connections on the server. instrument: histogram unit: "s" - note: | - **TODO: why http_transport? can we report protocol name as dimension and not a metric name?** - **TODO: we should do signalr.server** - Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` - attributes: - - ref: signalr.http_transport.status - - ref: signalr.http_transport.transport + note: Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + extends: signalr.common_attributes - id: metric.signalr.server.active_connections type: metric - metric_name: signalr_http_transport.active_connections + metric_name: signalr.server.active_connections brief: Number of connections that are currently active on the server. instrument: histogram unit: "s" - note: | - **TODO: why http_transport? can we report protocol as dimension and not a metric name?** - **TODO: we should do signalr.server** - Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + note: Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` attributes: - - ref: signalr.http_transport.status + - ref: network.protocol.name + - ref: network.protocol.version + - ref: network.transport From 37dc1eccaaca1a039061268f6f4de33c2c73c175 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 16:32:17 -0700 Subject: [PATCH 08/12] workaround build-tool errors --- docs/dotnet/dotnet-http-metrics.md | 31 ++++++++++++++++++++++++------ model/metrics/dotnet-http.yaml | 22 +++++++++++++++++++++ 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 8d3a702cd2..1ffa604878 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -126,6 +126,8 @@ Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientd | `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. @@ -146,6 +148,18 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[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 | @@ -265,10 +279,12 @@ Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverd | `dotnet.http.request.error` | string | HTTP Request error as defined inhttps://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. [2] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In | +| [`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) @@ -286,9 +302,12 @@ 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. -**[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`. +**[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]:** Determined by using the first of the following that applies +**[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. @@ -298,7 +317,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[4]:** Determined by using the first of the following that applies +**[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) diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/dotnet-http.yaml index 3b403d1f58..e4f7575431 100644 --- a/model/metrics/dotnet-http.yaml +++ b/model/metrics/dotnet-http.yaml @@ -74,6 +74,26 @@ groups: 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 @@ -85,6 +105,8 @@ groups: 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 From 9a9cbd254be1760e03aefd79cb7feb12face4cd1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 17:07:58 -0700 Subject: [PATCH 09/12] mroe fixes --- docs/dotnet/dotnet-aspnet-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 6 +-- docs/dotnet/dotnet-kestrel-metrics.md | 4 +- docs/dotnet/dotnet-signalr-metrics.md | 61 ++++++++++++++++++--------- model/deprecated/network.yaml | 2 +- model/metrics/dotnet-common.yaml | 2 +- model/metrics/dotnet-kestrel.yaml | 2 +- model/metrics/dotnet-signalr.yaml | 44 +++++++++++++------ 8 files changed, 83 insertions(+), 40 deletions(-) diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md index 0d30b8905b..6009150103 100644 --- a/docs/dotnet/dotnet-aspnet-metrics.md +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -78,7 +78,7 @@ This metric is required. | 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 started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 1ffa604878..7d4e06af17 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -75,7 +75,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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 inhttps://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 | @@ -120,7 +120,7 @@ Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientd | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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 inhttps://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. | @@ -275,7 +275,7 @@ Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverd | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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 inhttps://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. | diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index d10b05b307..7d795c364e 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -80,7 +80,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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 | @@ -325,7 +325,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states 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 | diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 6dafc13b0d..eaee793fde 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -8,34 +8,46 @@ This document defines semantic conventions for SignalR metrics emitted by .NET c -- [Metric: `signalr_http_transport.connection.duration`](#metric-signalr_http_transportconnectionduration) -- [Metric: `signalr_http_transport.active_connections`](#metric-signalr_http_transportactive_connections) +- [Metric: `signalr.http.server.connection.duration`](#metric-signalrhttpserverconnectionduration) +- [Metric: `signalr.http.server.active_connections`](#metric-signalrhttpserveractive_connections) -## Metric: `signalr_http_transport.connection.duration` +## Metric: `signalr.http.server.connection.duration` **Status**: [Experimental][DocumentStatus] This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. [1] | +| `signalr.http.server.connection.duration` | Histogram | `s` | The duration of the HTTP connections on the server. [1] | -**[1]:** Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` +**[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 | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a started it supports terminal states 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 | +| `signalr.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 states 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]:** `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`. +**[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.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. @@ -57,28 +69,39 @@ This metric is required. | `unix` | Unix domain socket | -## Metric: `signalr_http_transport.active_connections` +## Metric: `signalr.http.server.active_connections` **Status**: [Experimental][DocumentStatus] This metric is required. - + | Name | Instrument Type | Unit (UCUM) | Description | | -------- | --------------- | ----------- | -------------- | -| `signalr.server.active_connections` | Histogram | `s` | Number of connections that are currently active on the server. [1] | +| `signalr.http.server.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` +**[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 | |---|---|---|---|---| -| [`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 | +| `signalr.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]:** `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`. +**[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.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. 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-common.yaml b/model/metrics/dotnet-common.yaml index 9625f6e1e0..7c53a11365 100644 --- a/model/metrics/dotnet-common.yaml +++ b/model/metrics/dotnet-common.yaml @@ -19,7 +19,7 @@ groups: 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 started it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. + brief: General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. examples: ["Canceled", "RanToCompletion"] - id: http.request.error type: diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml index 3db021c16d..a27e54566c 100644 --- a/model/metrics/dotnet-kestrel.yaml +++ b/model/metrics/dotnet-kestrel.yaml @@ -95,4 +95,4 @@ groups: instrument: updowncounter unit: "{handshake}" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` - extends: kestrel.common_attributes \ No newline at end of file + extends: kestrel.common_attributes diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml index 605bd89548..98299208b4 100644 --- a/model/metrics/dotnet-signalr.yaml +++ b/model/metrics/dotnet-signalr.yaml @@ -4,28 +4,48 @@ groups: type: attribute_group brief: SignalR attributes attributes: - - ref: dotnet.error.code + - id: signalr.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.server.connection.duration + - id: metric.signalr.http.server.connection.duration type: metric - metric_name: signalr.server.connection.duration - brief: The duration of connections on the server. + metric_name: signalr.http.server.connection.duration + brief: The duration of the HTTP connections on the server. instrument: histogram unit: "s" - note: Corresponding `EventCounter` name is `connections-duration`; Meter name is `Microsoft.AspNetCore.Http.Connections` + 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.server.active_connections + - id: metric.signalr.http.server.active_connections type: metric - metric_name: signalr.server.active_connections + metric_name: signalr.http.server.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: network.protocol.name - - ref: network.protocol.version - - ref: network.transport + note: | + Only reported for HTTP SignalR transport. + Corresponding `EventCounter` name is `current-connections`; Meter name is `Microsoft.AspNetCore.Http.Connections` + extends: signalr.common_attributes From 7b96589894b25474bdad3e2f85cc82aa9915662c Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 18:17:35 -0700 Subject: [PATCH 10/12] update --- docs/dotnet/dotnet-dns-metrics.md | 2 +- docs/dotnet/dotnet-http-metrics.md | 4 ++-- docs/dotnet/dotnet-signalr-metrics.md | 8 ++++---- model/metrics/dotnet-http.yaml | 4 ++-- model/metrics/dotnet-signalr.yaml | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/dotnet/dotnet-dns-metrics.md b/docs/dotnet/dotnet-dns-metrics.md index 7969faaf83..0108597944 100644 --- a/docs/dotnet/dotnet-dns-metrics.md +++ b/docs/dotnet/dotnet-dns-metrics.md @@ -36,7 +36,7 @@ of **`[TODO]`**. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | +| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required | **[1]:** The name being queried. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index 7d4e06af17..dd0cbdb6fc 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -41,7 +41,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `connection.state` | string | Connection state. | `active`; `idle` | Required | +| `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 | @@ -50,7 +50,7 @@ This metric is required. **[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`. -`connection.state` MUST be one of the following: +`dotnet.connection.state` MUST be one of the following: | Value | Description | |---|---| diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index eaee793fde..9bada742fe 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -31,7 +31,7 @@ Corresponding `EventCounter` name is `connections-duration`; Meter name is `Micr | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `signalr.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 | +| `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 states 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`) | @@ -42,7 +42,7 @@ Corresponding `EventCounter` name is `connections-duration`; Meter name is `Micr **[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.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. +`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 | |---|---| @@ -87,7 +87,7 @@ Corresponding `EventCounter` name is `current-connections`; Meter name is `Micro | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `signalr.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 | +| `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 | @@ -96,7 +96,7 @@ Corresponding `EventCounter` name is `current-connections`; Meter name is `Micro **[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.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. +`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 | |---|---| diff --git a/model/metrics/dotnet-http.yaml b/model/metrics/dotnet-http.yaml index e4f7575431..f5a4351d60 100644 --- a/model/metrics/dotnet-http.yaml +++ b/model/metrics/dotnet-http.yaml @@ -7,7 +7,7 @@ groups: unit: "s" note: Meter name is `System.Net.NameResolution`. attributes: - - id: question.name + - id: dns.question.name type: string brief: The name being queried. requirement_level: required @@ -30,7 +30,7 @@ groups: note: Corresponding `EventCounter` names are `*-connections-current-total`; Meter name is `System.Net.Http`. attributes: - - id: connection.state + - id: dotnet.connection.state type: members: - id: active diff --git a/model/metrics/dotnet-signalr.yaml b/model/metrics/dotnet-signalr.yaml index 98299208b4..8eaa4a8f3b 100644 --- a/model/metrics/dotnet-signalr.yaml +++ b/model/metrics/dotnet-signalr.yaml @@ -4,7 +4,7 @@ groups: type: attribute_group brief: SignalR attributes attributes: - - id: signalr.transport + - id: transport brief: SignalR transport - https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md type: allow_custom_values: true From 351580199e45d98269d4541717df91ad544a9f05 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 18:18:41 -0700 Subject: [PATCH 11/12] update --- docs/dotnet/dotnet-aspnet-metrics.md | 4 ++-- docs/dotnet/dotnet-http-metrics.md | 6 +++--- docs/dotnet/dotnet-kestrel-metrics.md | 4 ++-- docs/dotnet/dotnet-signalr-metrics.md | 2 +- model/metrics/dotnet-aspnet.yaml | 2 +- model/metrics/dotnet-common.yaml | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/dotnet/dotnet-aspnet-metrics.md b/docs/dotnet/dotnet-aspnet-metrics.md index 6009150103..4114c60d50 100644 --- a/docs/dotnet/dotnet-aspnet-metrics.md +++ b/docs/dotnet/dotnet-aspnet-metrics.md @@ -53,7 +53,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | Value | Description | |---|---| -| `success` | No error | +| `success` | matched | | `failure` | failure | @@ -78,7 +78,7 @@ This metric is required. | 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 states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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. diff --git a/docs/dotnet/dotnet-http-metrics.md b/docs/dotnet/dotnet-http-metrics.md index dd0cbdb6fc..9fd58f935d 100644 --- a/docs/dotnet/dotnet-http-metrics.md +++ b/docs/dotnet/dotnet-http-metrics.md @@ -75,7 +75,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 inhttps://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 | @@ -120,7 +120,7 @@ Follows common [http.client.duration](../http/http-metrics.md#metric-httpclientd | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 inhttps://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. | @@ -275,7 +275,7 @@ Follows common [http.server.duration](../http/http-metrics.md#metric-httpserverd | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 inhttps://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. | diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index 7d795c364e..b43e8aa1a4 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -80,7 +80,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 | @@ -325,7 +325,7 @@ This metric is required. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 | diff --git a/docs/dotnet/dotnet-signalr-metrics.md b/docs/dotnet/dotnet-signalr-metrics.md index 9bada742fe..eb9c90edf6 100644 --- a/docs/dotnet/dotnet-signalr-metrics.md +++ b/docs/dotnet/dotnet-signalr-metrics.md @@ -32,7 +32,7 @@ Corresponding `EventCounter` name is `connections-duration`; Meter name is `Micr | 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 states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended | +| `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 | diff --git a/model/metrics/dotnet-aspnet.yaml b/model/metrics/dotnet-aspnet.yaml index d670ccf0ff..920d0884e5 100644 --- a/model/metrics/dotnet-aspnet.yaml +++ b/model/metrics/dotnet-aspnet.yaml @@ -35,7 +35,7 @@ groups: members: - id: success value: 'success' - brief: 'No error' + brief: 'matched' - id: failure value: 'failure' brief: 'failure' diff --git a/model/metrics/dotnet-common.yaml b/model/metrics/dotnet-common.yaml index 7c53a11365..3c4ef833a5 100644 --- a/model/metrics/dotnet-common.yaml +++ b/model/metrics/dotnet-common.yaml @@ -19,7 +19,7 @@ groups: 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 states of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. + 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: From 13ce5a4496f005cbf132103b1f7fd510093e334b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 21 Jul 2023 18:41:35 -0700 Subject: [PATCH 12/12] tls.version --- docs/dotnet/dotnet-kestrel-metrics.md | 2 ++ model/metrics/dotnet-kestrel.yaml | 13 +++++++++++++ 2 files changed, 15 insertions(+) diff --git a/docs/dotnet/dotnet-kestrel-metrics.md b/docs/dotnet/dotnet-kestrel-metrics.md index b43e8aa1a4..e4fe77ad65 100644 --- a/docs/dotnet/dotnet-kestrel-metrics.md +++ b/docs/dotnet/dotnet-kestrel-metrics.md @@ -85,6 +85,7 @@ This metric is required. | [`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`. @@ -386,6 +387,7 @@ This metric is required. | [`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`. diff --git a/model/metrics/dotnet-kestrel.yaml b/model/metrics/dotnet-kestrel.yaml index a27e54566c..ad6286d404 100644 --- a/model/metrics/dotnet-kestrel.yaml +++ b/model/metrics/dotnet-kestrel.yaml @@ -15,6 +15,16 @@ groups: - 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 @@ -34,6 +44,7 @@ groups: extends: kestrel.common_attributes attributes: - ref: dotnet.error.code + - ref: tls.version - id: metric.kestrel.rejected_connections type: metric @@ -96,3 +107,5 @@ groups: unit: "{handshake}" note: Meter name is `Microsoft.AspNetCore.Server.Kestrel` extends: kestrel.common_attributes + attributes: + - ref: tls.version \ No newline at end of file