dotnet http metrics

docs/dotnet/README.md

@@ -0,0 +1,24 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: .NET
+path_base_for_github_subdir:
+  from: content/en/docs/specs/semconv/dotnet/_index.md
+  to: dotnet/README.md
+--->
+
+# 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

docs/dotnet/dotnet-aspnet-metrics.md

@@ -0,0 +1,201 @@
+# Semantic Conventions for ASP.NEt Core specific metrics
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for ASP.NET Core metrics, not specific to HTTP
+
+**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future.
+
+<!-- toc -->
+
+- [Server](#server)
+  * [Metric: `aspnet.unhandled_requests`](#metric-aspnetunhandled_requests)
+- [Routing](#routing)
+  * [Metric: `aspnet.routing.successful_matches`](#metric-aspnetroutingsuccessful_matches)
+- [Exception metrics](#exception-metrics)
+  * [Metric: `aspnet.diagnostics_handler.exceptions`](#metric-aspnetdiagnostics_handlerexceptions)
+- [Rate-limiting](#rate-limiting)
+  * [Metric: `aspnet.rate_limiting.active_request_leases`](#metric-aspnetrate_limitingactive_request_leases)
+  * [Metric: `aspnet.rate_limiting.request_lease.duration`](#metric-aspnetrate_limitingrequest_leaseduration)
+  * [Metric: `aspnet.rate_limiting.queued_requests`](#metric-aspnetrate_limitingqueued_requests)
+  * [Metric: `aspnet.rate_limiting.queued_requests.duration`](#metric-aspnetrate_limitingqueued_requestsduration)
+  * [Metric: `aspnet.rate_limiting.requests`](#metric-aspnetrate_limitingrejected_requests)
+
+<!-- tocstop -->
+
+## Server
+
+### Metric: `aspnet.unhandled_requests`
+
+<!-- semconv metric.aspnet.unhandled_requests(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.unhandled_requests` | UpDownCounter | `{request}` | Number of requests that reached the end of the middleware pipeline without being handled by application code. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.Hosting`.
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.unhandled_requests(full) -->
+<!-- endsemconv -->
+
+## Routing
+
+All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter.
+
+### Metric: `aspnet.routing.successful_matches`
+
+<!-- semconv metric.aspnet.routing.match_attempts(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.routing.match_attempts` | Counter | `{match}` | Number of requests that were attempted to be matched to an endpoint. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.Routing`.
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.routing.match_attempts(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `match_status` | string | Match result - success or failure | `success`; `failure` | Recommended |
+| `aspnet.routing.fallback` | string | TODO | `TODO` | Required |
+| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Required |
+
+**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
+SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
+
+`match_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `success` | Match succeeded |
+| `failure` | Match failed |
+<!-- endsemconv -->
+
+## Exception metrics
+
+Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter.
+
+### Metric: `aspnet.diagnostics_handler.exceptions`
+
+<!-- semconv metric.aspnet.diagnostics_handler.exceptions(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.diagnostics_handler.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.Diagnostics`
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.diagnostics_handler.exceptions(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aspnet.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Required |
+| `aspnet.handler` | string | TODO | `TODO` | Required |
+| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | Recommended |
+
+`aspnet.exception.result` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `handled` | Exception was handled by the exception handling middleware. |
+| `unhandled` | Exception was not handled by the exception handling middleware. |
+| `skipped` | Exception was skipped. TODO |
+| `aborted` | Request was aborted. TODO |
+<!-- endsemconv -->
+
+## Rate-limiting
+
+All rate-limiting metrics are reported by `Microsoft.AspNetCore.RateLimiting` meter.
+
+### Metric: `aspnet.rate_limiting.active_request_leases`
+
+<!-- semconv metric.aspnet.rate_limiting.active_request_leases(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting`
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.rate_limiting.active_request_leases(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required |
+<!-- endsemconv -->
+
+### Metric: `aspnet.rate_limiting.request_lease.duration`
+
+<!-- semconv metric.aspnet.rate_limiting.request_lease.duration(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of rate limiting lease held by requests on the server. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting`
+**TODO: Can we explain what it means better**`
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.rate_limiting.request_lease.duration(full) -->
+<!-- endsemconv -->
+
+### Metric: `aspnet.rate_limiting.queued_requests`
+
+<!-- semconv metric.aspnet.rate_limiting.queued_requests(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued, waiting to acquire a rate limiting lease. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting`
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.rate_limiting.queued_requests(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required |
+<!-- endsemconv -->
+
+### Metric: `aspnet.rate_limiting.queued_requests.duration`
+
+<!-- semconv metric.aspnet.rate_limiting.queued_request.duration(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.rate_limiting.queued_request.duration` | Histogram | `s` | The duration of request in a queue, waiting to acquire a rate limiting lease. [1] |
+
+**[1]:** Meter name is `Microsoft.AspNetCore.RateLimiting`
+
+**TODO: I don't really understand what this duration is, can we improve name, brief or description to explain? **
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.rate_limiting.queued_request.duration(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required |
+<!-- endsemconv -->
+
+### Metric: `aspnet.rate_limiting.requests`
+
+<!-- semconv metric.aspnet.rate_limiting.requests(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `aspnet.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. [1] |
+
+**[1]:** Requests could be rejected by global or endpoint rate limiting policies. Or the request could be cancelled while waiting for the lease.
+
+Meter name is `Microsoft.AspNetCore.RateLimiting`
+<!-- endsemconv -->
+
+<!-- semconv metric.aspnet.rate_limiting.requests(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `aspnet.rate_limiting.policy` | string | TODO | `TODO` | Required |
+| `aspnet.rate_limiting.result` | string | Rate-limiting result, shows whether lease was acquired or contains rejection reason | `acquired`; `request_canceled` | Recommended |
+
+`aspnet.rate_limiting.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `acquired` | lease acquired |
+| `endpoint_limiter` | Lease request was rejected by the endpoint limiter |
+| `global_limiter` | Lease request was rejected by the global limiter |
+| `request_canceled` | Lease request was canceled |
+<!-- endsemconv -->
+
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/dotnet/dotnet-dns-metrics.md

@@ -0,0 +1,43 @@
+# Semantic Conventions for DNS metrics emitted by .NET
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for DNS metrics emitted by .NET.
+
+**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future.
+
+<!-- toc -->
+
+- [DNS metrics](#dns-metrics)
+  * [Metric: `dns.lookups.duration`](#metric-dnslookupsduration)
+
+<!-- tocstop -->
+
+## DNS metrics
+
+### Metric: `dns.lookups.duration`
+
+<!-- semconv metric.dotnet.dns.lookup.duration(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `dns.lookup.duration` | Histogram | `s` | Measures the time take to perform a DNS lookup. [1] |
+
+**[1]:** Meter name is `System.Net.NameResolution`.
+<!-- endsemconv -->
+
+<!-- semconv metric.dotnet.dns.lookup.duration(full) -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `dns.question.name` | string | The name being queried. [1] | `www.example.com`; `dot.net` | Required |
+
+**[1]:** The name being queried.
+
+If the name field contains non-printable
+characters (below 32 or above 126), those characters should be represented
+as escaped base 10 integers (\DDD). Back slashes and quotes should be escaped.
+Tabs, carriage returns, and line feeds should be converted to \t, \r, and
+\n respectively.
+<!-- endsemconv -->
+
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md