Skip to content

Commit

Permalink
[HttpClient & Asp.Net Core] Update Readme.md (#5168)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vishweshbankwar
vishweshbankwar authored Dec 14, 2023
1 parent 2bccad8 commit 4842364
Show file tree
Hide file tree
Showing 2 changed files with 118 additions and 37 deletions.
88 changes: 72 additions & 16 deletions src/OpenTelemetry.Instrumentation.AspNetCore/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,13 @@ which instruments [ASP.NET Core](https://docs.microsoft.com/aspnet/core) and
collect metrics and traces about incoming web requests. This instrumentation
also collects traces from incoming gRPC requests using
[Grpc.AspNetCore](https://www.nuget.org/packages/Grpc.AspNetCore).
Instrumentation support for gRPC server requests is supported via an
[experimental](#experimental-support-for-grpc-requests) feature flag.

**Note: This component is based on the OpenTelemetry semantic conventions for
[metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md)
and
[traces](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md).
These conventions are
[Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md),
and hence, this package is a [pre-release](../../VERSIONING.md#pre-releases).
Until a [stable
version](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md)
is released, there can be breaking changes. You can track the progress from
[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).**
This component is based on the
[v1.23](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http)
of http semantic conventions. For details on the default set of attributes that
are added, checkout [Traces](#traces) and [Metrics](#metrics) sections below.

## Steps to enable OpenTelemetry.Instrumentation.AspNetCore

Expand All @@ -31,7 +26,7 @@ Add a reference to the
package. Also, add any other instrumentations & exporters you will need.

```shell
dotnet add package --prerelease OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
```

### Step 2: Enable ASP.NET Core Instrumentation at application startup
Expand Down Expand Up @@ -66,6 +61,26 @@ public void ConfigureServices(IServiceCollection services)
}
```

Following list of attributes are added by default on activity. See
[http-spans](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-spans.md)
for more details about each individual attribute:

* `error.type`
* `http.request.method`
* `http.request.method_original`
* `http.response.status_code`
* `http.route`
* `network.protocol.version`
* `user_agent.original`
* `server.address`
* `server.port`
* `url.path`
* `url.query`
* `url.scheme`

[Enrich Api](#enrich) can be used if any additional attributes are
required on activity.

#### Metrics

The following example demonstrates adding ASP.NET Core instrumentation with the
Expand All @@ -88,6 +103,20 @@ public void ConfigureServices(IServiceCollection services)
}
```

Following list of attributes are added by default on
`http.server.request.duration` metric. See
[http-metrics](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-metrics.md)
for more details about each individual attribute. `.NET8.0` and above supports
additional metrics, see [list of metrics produced](#list-of-metrics-produced) for
more details.

* `error.type`
* `http.response.status_code`
* `http.request.method`
* `http.route`
* `network.protocol.version`
* `url.scheme`

#### List of metrics produced

When the application targets `.NET6.0` or `.NET7.0`, the instrumentation emits
Expand Down Expand Up @@ -138,6 +167,8 @@ newer versions.

## Advanced configuration

### Tracing

This instrumentation can be configured to change the default behavior by using
`AspNetCoreTraceInstrumentationOptions`, which allows adding [`Filter`](#filter),
[`Enrich`](#enrich) as explained below.
Expand Down Expand Up @@ -166,7 +197,7 @@ services.AddOpenTelemetry()
.AddConsoleExporter());
```

### Filter
#### Filter

This instrumentation by default collects all the incoming http requests. It
allows filtering of requests by using the `Filter` function in
Expand Down Expand Up @@ -194,7 +225,7 @@ instrumentation. OpenTelemetry has a concept of a
[Sampler](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#sampling),
and the `Filter` option does the filtering *after* the Sampler is invoked.

### Enrich
#### Enrich

This instrumentation library provides `EnrichWithHttpRequest`,
`EnrichWithHttpResponse` and `EnrichWithException` options that can be used to
Expand Down Expand Up @@ -231,13 +262,13 @@ is the general extensibility point to add additional properties to any activity.
The `Enrich` option is specific to this instrumentation, and is provided to
get access to `HttpRequest` and `HttpResponse`.

### RecordException
#### RecordException

This instrumentation automatically sets Activity Status to Error if an unhandled
exception is thrown. Additionally, `RecordException` feature may be turned on,
to store the exception to the Activity itself as ActivityEvent.

## Activity Duration and http.server.request.duration metric calculation
## Activity duration and http.server.request.duration metric calculation

`Activity.Duration` and `http.server.request.duration` values represents the
time used to handle an inbound HTTP request as measured at the hosting layer of
Expand All @@ -254,6 +285,31 @@ The time ends when:
* All response data has been sent.
* The context data structures for the request are being disposed.

## Experimental support for gRPC requests

gRPC instrumentation can be enabled by setting
`OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION` flag to
`True`. The flag can be set as an environment variable or via IConfiguration as
shown below.

```csharp
var appBuilder = WebApplication.CreateBuilder(args);

appBuilder.Configuration.AddInMemoryCollection(
new Dictionary<string, string?>
{
["OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION"] = "true",
});

appBuilder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing
.AddAspNetCoreInstrumentation());
```

Semantic conventions for RPC are still
[experimental](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/rpc)
and hence the instrumentation only offers it as an experimental feature.

## Troubleshooting

This component uses an
Expand Down
67 changes: 46 additions & 21 deletions src/OpenTelemetry.Instrumentation.Http/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,10 @@ and
[System.Net.HttpWebRequest](https://docs.microsoft.com/dotnet/api/system.net.httpwebrequest)
and collects metrics and traces about outgoing HTTP requests.

**Note: This component is based on the OpenTelemetry semantic conventions for
[metrics](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md)
and
[traces](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md).
These conventions are
[Experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md),
and hence, this package is a [pre-release](../../VERSIONING.md#pre-releases).
Until a [stable
version](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md)
is released, there can be [breaking changes](./CHANGELOG.md). You can track the
progress from
[milestones](https://github.com/open-telemetry/opentelemetry-dotnet/milestone/23).**
This component is based on the
[v1.23](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http)
of http semantic conventions. For details on the default set of attributes that
are added, checkout [Traces](#traces) and [Metrics](#metrics) sections below.

## Steps to enable OpenTelemetry.Instrumentation.Http

Expand All @@ -33,7 +25,7 @@ Add a reference to the
package. Also, add any other instrumentations & exporters you will need.

```shell
dotnet add package --prerelease OpenTelemetry.Instrumentation.Http
dotnet add package OpenTelemetry.Instrumentation.Http
```

### Step 2: Enable HTTP Instrumentation at application startup
Expand Down Expand Up @@ -65,6 +57,22 @@ public class Program
}
```

Following list of attributes are added by default on activity. See
[http-spans](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-spans.md)
for more details about each individual attribute:

* `error.type`
* `http.request.method`
* `http.request.method_original`
* `http.response.status_code`
* `network.protocol.version`
* `server.address`
* `server.port`
* `url.full`

[Enrich Api](#enrich-httpclient-api) can be used if any additional attributes are
required on activity.

#### Metrics

The following example demonstrates adding `HttpClient` instrumentation with the
Expand Down Expand Up @@ -97,6 +105,21 @@ Refer to this
[example](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNet/README.md)
to see how to enable this instrumentation in an ASP.NET application.

Following list of attributes are added by default on
`http.client.request.duration` metric. See
[http-metrics](https://github.com/open-telemetry/semantic-conventions/tree/v1.23.0/docs/http/http-metrics.md)
for more details about each individual attribute. `.NET8.0` and above supports
additional metrics, see [list of metrics produced](#list-of-metrics-produced) for
more details.

* `error.type`
* `http.request.method`
* `http.response.status_code`
* `network.protocol.version`
* `server.address`
* `server.port`
* `url.scheme`

#### List of metrics produced

When the application targets `NETFRAMEWORK`, `.NET6.0` or `.NET7.0`, the
Expand Down Expand Up @@ -147,6 +170,8 @@ newer versions.

## Advanced configuration

### Tracing

This instrumentation can be configured to change the default behavior by using
`HttpClientTraceInstrumentationOptions`. It is important to note that there are
differences between .NET Framework and newer .NET/.NET Core runtimes which
Expand All @@ -155,9 +180,9 @@ govern what options are used. On .NET Framework, `HttpClient` uses the
`HttpClient` API. As such, depending on the runtime, only one half of the
"filter" & "enrich" options are used.

### .NET & .NET Core
#### .NET & .NET Core

#### Filter HttpClient API
##### Filter HttpClient API

This instrumentation by default collects all the outgoing HTTP requests. It
allows filtering of requests by using the `FilterHttpRequestMessage` function
Expand Down Expand Up @@ -189,7 +214,7 @@ to this instrumentation. OpenTelemetry has a concept of a
and the `FilterHttpRequestMessage` option does the filtering *after* the Sampler
is invoked.

#### Enrich HttpClient API
##### Enrich HttpClient API

This instrumentation library provides options that can be used to
enrich the activity with additional information. These actions are called
Expand Down Expand Up @@ -228,9 +253,9 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder()
.Build();
```

### .NET Framework
#### .NET Framework

#### Filter HttpWebRequest API
##### Filter HttpWebRequest API

This instrumentation by default collects all the outgoing HTTP requests. It
allows filtering of requests by using the `FilterHttpWebRequest` function
Expand Down Expand Up @@ -262,7 +287,7 @@ this instrumentation. OpenTelemetry has a concept of a
and the `FilterHttpWebRequest` option does the filtering *after* the Sampler is
invoked.

#### Enrich HttpWebRequest API
##### Enrich HttpWebRequest API

This instrumentation library provides options that can be used to
enrich the activity with additional information. These actions are called
Expand Down Expand Up @@ -306,13 +331,13 @@ general extensibility point to add additional properties to any activity. The
`Enrich` option is specific to this instrumentation, and is provided to get
access to raw request, response, and exception objects.

### RecordException
#### RecordException

This instrumentation automatically sets Activity Status to Error if the Http
StatusCode is >= 400. Additionally, `RecordException` feature may be turned on,
to store the exception to the Activity itself as ActivityEvent.

## Activity Duration and http.client.request.duration metric calculation
## Activity duration and http.client.request.duration metric calculation

`Activity.Duration` and `http.client.request.duration` values represents the
time the underlying client handler takes to complete the request. Completing the
Expand Down

0 comments on commit 4842364

Please sign in to comment.