Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Dotnet8 metrics: proposals #2

Closed
wants to merge 12 commits into from
Closed

Dotnet8 metrics: proposals #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
daeaa1b
First stub
lmolkova Jul 21, 2023
1686a07
return http metrics back
lmolkova Jul 21, 2023
72ae36d
draft done
lmolkova Jul 21, 2023
d4a0053
nits
lmolkova Jul 21, 2023
092b502
nits
lmolkova Jul 21, 2023
42860c0
nits
lmolkova Jul 21, 2023
bac15e0
proposed changes
lmolkova Jul 21, 2023
37dc1ec
workaround build-tool errors
lmolkova Jul 21, 2023
9a9cbd2
mroe fixes
lmolkova Jul 22, 2023
7b96589
update
lmolkova Jul 22, 2023
3515801
update
lmolkova Jul 22, 2023
13ce5a4
tls.version
lmolkova Jul 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/dotnet/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
210 changes: 210 additions & 0 deletions docs/dotnet/dotnet-aspnet-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
# Semantic Conventions for ASP.NEt Core specific metrics

**Status**: [Experimental][DocumentStatus]

This document defines semantic conventions for ASP.NET Core metrics, not specific to HTTP

**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future.

<!-- toc -->

- [Routing](#routing)
* [Metric: `aspnet.routing.matches`](#metric-aspnetroutingmatches)
- [Exception metrics](#exception-metrics)
* [Metric: `aspnet.diagnostics_handler.exceptions`](#metric-aspnetdiagnostics_handlerexceptions)
- [Rate-limiting](#rate-limiting)
* [Metric: `aspnet.rate_limiting.active_request_leases`](#metric-aspnetrate_limitingactive_request_leases)
* [Metric: `aspnet.rate_limiting.request_lease.duration`](#metric-aspnetrate_limitingrequest_leaseduration)
* [Metric: `aspnet.rate_limiting.queued_requests`](#metric-aspnetrate_limitingqueued_requests)
* [Metric: `aspnet.rate_limiting.queued_requests.duration`](#metric-aspnetrate_limitingqueued_requestsduration)
* [Metric: `aspnet.rate_limiting.requests`](#metric-aspnetrate_limitingrequests)

<!-- tocstop -->

## Routing

All routing metrics are reported by `Microsoft.AspNetCore.Routing` meter.

### Metric: `aspnet.routing.matches`
lmolkova marked this conversation as resolved.
Show resolved Hide resolved

**Status**: [Experimental][DocumentStatus]

This metric is required.

<!-- semconv metric.aspnet.routing.matches(metric_table) -->
| Name | Instrument Type | Unit (UCUM) | Description |
| -------- | --------------- | ----------- | -------------- |
| `aspnet.routing.successful_matches` | Counter | `{match}` | Number of requests that successfully matched to an endpoint. [1] |
lmolkova marked this conversation as resolved.
Show resolved Hide resolved

**[1]:** An unmatched request may be handled by later middleware, such as the static files or authentication middleware. Meter name is `Microsoft.AspNetCore.Routing`.
<!-- endsemconv -->

<!-- semconv metric.aspnet.routing.matches(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `aspnet.match_status` | string | Match result - success or failure | `success`; `failure` | Required |
| `aspnet.routing.fallback` | string | TODO | `TODO` | Required |
| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Required |

**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.

`aspnet.match_status` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `success` | matched |
| `failure` | failure |
<!-- endsemconv -->

## Exception metrics

Metrics reported by `Microsoft.AspNetCore.Diagnostics` meter.

### Metric: `aspnet.diagnostics_handler.exceptions`

**Status**: [Experimental][DocumentStatus]

This metric is required.
<!-- 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.handler` | string | TODO | `TODO` | Required |
| `dotnet.error.code` | string | General-purpose error code reported by .NET, as a starter it supports terminal statuses of .NET task https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskstatus. | `Canceled`; `RanToCompletion` | Recommended |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diagnostics_handler metrics were created for a specific purpose to help customers understand how exceptions in the pipeline were triaged by the exception handling middleware. I'm happy to rename exception.result to something else (perhaps aspnet.handler.result?), but the goal of enumeration values is to describe how the exception was dealt with. I would not change the semantics of the enumeration without an analysis in the context of the original feature ask and the overall function of the exception handling middleware.

The feature ask is here: dotnet/aspnetcore#48625
James' description of the solution is here: dotnet/aspnetcore#48648

The enumeration values as described by James:

  • Aborted - Error occurred because the request was aborted (OperationCanceledException + RequestAborted.IsCancellationRequested)
  • Skipped - Response has already started. Middleware can't do anything with the response so skips doing anything.
  • Handled - ExceptionHandlerMiddleware has some interesting rules here. An exception is considered handled if an IExceptionHandler returns true, IProblemDetailsService returns true, or the status code is anything other than 404. If an IExceptionHandler or IProblemDetailsService return true then the type name is set for the handler tag.
    DeveloperExceptionMiddleware never reports exceptions it catches as handled
  • Unhandled - All of the above are false.

| `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.
<!-- endsemconv -->

## 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.

<!-- 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`

**Status**: [Experimental][DocumentStatus]

This metric is required.

<!-- 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 do we need attributes?, can we explain what it means better**`
<!-- endsemconv -->

<!-- semconv metric.aspnet.rate_limiting.request_lease.duration(full) -->
<!-- endsemconv -->

### Metric: `aspnet.rate_limiting.queued_requests`

**Status**: [Experimental][DocumentStatus]

This metric is required.

<!-- 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`

**Status**: [Experimental][DocumentStatus]

This metric is required.

<!-- 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`
lmolkova marked this conversation as resolved.
Show resolved Hide resolved

**Status**: [Experimental][DocumentStatus]

This metric is required.

<!-- 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`; `rejected_reason1` | Recommended |

`aspnet.rate_limiting.result` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `acquired` | lease acquired |
| `rejected_reason1` | TODO |
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
<!-- endsemconv -->


[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
51 changes: 51 additions & 0 deletions docs/dotnet/dotnet-dns-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Semantic Conventions for DNS metrics emitted by .NET

**Status**: [Experimental][DocumentStatus]

This document defines semantic conventions for DNS metrics emitted by .NET.

**Disclaimer:** These are initial .NET metric instruments available in .NET 8 but more may be added in the future.

<!-- toc -->

- [DNS metrics](#dns-metrics)
* [Metric: `dns.lookups.duration`](#metric-dnslookupsduration)

<!-- tocstop -->

## 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]`**.

<!-- 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
Loading