You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this tutorial, we will introduce how to manually instrument your application step-by-step using AWS Distro for OpenTelemetry .NET SDK.
12
+
The AWS Distro for OpenTelemetry .NET SDK contains an extension library for using OpenTelemetry with AWS X-Ray and for instrumenting the AWS SDK. In this tutorial, we will introduce how to manually instrument your application step-by-step using AWS Distro for OpenTelemetry .NET SDK.
13
13
14
14
<SectionSeparator />
15
15
16
-
## Getting Started
16
+
## Requirements
17
+
18
+
The AWS Distro for OpenTelemetry .NET SDK is compatible for .NET framework (net452 and above) and .NET Core (netstandard2.0 and above).
19
+
20
+
**Note**: You’ll also need to have the [AWS Distro for OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector) running to export traces to X-Ray.
21
+
22
+
<SectionSeparator />
23
+
24
+
## Installation
17
25
18
26
In order to instrument your .NET application for tracing, start by downloading the `OpenTelemetry` nuget package to your application.
19
27
20
28
```shell
21
29
dotnet add package OpenTelemetry
22
30
```
23
31
24
-
This is the OpenTelemetry SDK for .NET. The SDK deals with concerns such as sampling, processing pipeline, exporting telemetry to a particular backend etc.
32
+
The OpenTelemetry SDK for .NETdeals with concerns such as sampling, a processing pipeline, and exporting telemetry to a particular backend.
25
33
This generally requires additional packages to be downloaded for specific instrumentation or exporter.
26
34
27
-
<SectionSeparator />
28
-
29
-
## Sending Traces to AWS X-Ray
30
-
31
-
By default, the OpenTelemetry SDK generates traces with W3C random ID which X-Ray backend doesn’t currently support.
35
+
The OpenTelemetry SDK generates traces with W3C random ID which X-Ray backend doesn’t currently support.
32
36
You need to install the `OpenTelemetry.Contrib.Extensions.AWSXRay` to be able to use the `AWSXRayIdGenerator` which generates X-Ray compatible trace IDs.
33
37
If you plan to call another application instrumented with AWS X-Ray SDK, you’ll need to configure the `AWSXRayPropagator` as well.
Configure `AWSXRayIdGenerator` and `AWSXRayPropagator` globally in your application as follows. Make sure to call `AddXRayTraceId()` in the very **beginning** when creating `TracerProviderBuilder`
43
+
In order to export traces from your application to ADOT Collector, you need to install `OpenTelemetry.Exporter.OpenTelemetryProtocol`.
By default the OpenTelemetry exporter sends data to an OpenTelemetry collector at `localhost:4317`.
50
+
51
+
<SectionSeparator />
52
+
53
+
## Setting up the Global Tracer
54
+
55
+
### Sending Traces to AWS X-Ray
56
+
57
+
Configure AWS X-Ray ID generator, propagator and OpenTelemetry Protocol (OTLP) exporter globally in your application as follows. Make sure to call `AddXRayTraceId()` in the very **beginning** when creating `TracerProvider`
**Note**: You’ll also need to have the [AWS Distro for OpenTelemetry Collector](https://github.com/aws-observability/aws-otel-collector) running to export traces to X-Ray.
72
+
### Using the AWS resource Detectors
73
+
74
+
The ADOT .NET SDK supports automatically recording metadata in EC2, Elastic Beanstalk, ECS, and EKS environments. You can configure the corresponding resource detector to the `TracerProvider` following the EC2 example below.
Once you have configured all necessary X-Ray components to the `TracerProvider`, you can proceed to [OpenTelemetry .NET SDK's developer guide](https://github.com/open-telemetry/opentelemetry-dotnet#getting-started) to instrument your .NET application.
95
+
96
+
OpenTelemetry provides a wide range of instrumentations for popular .NET libraries: [Asp.Net](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.AspNet#readme), [Asp.Net Core](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#readme), [Http](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.Http#readme), [Grpc](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.GrpcNetClient#readme), [Redis](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.StackExchangeRedis/README.md), [Sql](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Instrumentation.SqlClient#readme) and [EntityFramework](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Contrib.Instrumentation.EntityFrameworkCore#readme). Instrumenting a library means that every time the library is used to make or handle a request, that library's calls are automatically wrapped within a span. That span is automatically populated with attributes describing the values used by the library call.
97
+
98
+
### AWS SDK Instrumentation
58
99
59
-
Start by downloading the ASP.NET Core and OTLP exporter instrumentation
60
-
packages
100
+
For tracing downstream calls to AWS services from your .NET application, you will need to install the `OpenTelemetry.Contrib.Instrumentation.AWS` package.
The ASP.NET instrumentation requires [modification](https://github.com/open-telemetry/opentelemetry-dotnet/blob/master/src/OpenTelemetry.Instrumentation.AspNet/README.md#step-2-modify-webconfig)
99
-
to **Web.config** to add a module to your web server. When installing `OpenTelemetry.Instrumentation.AspNet` nuget package, the `TelemetryCorrelationHttpModule` should be automatically added.
Now all you need to do is add the instrumentation and exporter to `TracerProviderBuilder` and build. This is done in the **Global.asax.cs** as shown below.
130
+
In .NET, you can use the activity API to create custom spans to monitor the performance of internal activities that are not captured by instrumentation libraries.
varactivity=activitySource.StartActivity("ActivityName", ActivityKind.Server); // this will be translated to a X-Ray Segment
137
+
varinternalActivity=activitySource.StartActivity("ActivityName", ActivityKind.Internal); // this will be translated to an X-Ray Subsegment
134
138
```
135
139
136
-
<SubSectionSeparator />
137
-
138
-
### AWS SDK Instrumentation
140
+
Note that only spans of kind `Server` are converted into X-Ray segments, all other kind of spans (`Internal`, `Client`, etc.) are converted into X-Ray subsegments. For more on segments and subsegments, see the [AWS X-Ray developer guide](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments).
139
141
140
-
For tracing downstream call to AWS services from your .NET application, you will need AWS client instrumentation.
142
+
### Adding Custom Attributes
141
143
142
-
Download the `OpenTelemetry.Contrib.Instrumentation.AWS` package:
144
+
You can also add custom key-value pairs as attributes onto your spans.
Add AWS client instrumentation to `TracerProviderBuilder` and build. The below example is for an ASP.NET Core application.
151
+
Attributes are converted to metadata by default. If you configure your collector, you can convert some or all of the attributes to annotations. To read more about X-Ray annotations and metadata see the [AWS X-Ray developer guide](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations).
For more information about the activity API, see the [OpenTelemetry .NET SDK's developer guide](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Api#instrumenting-a-libraryapplication-with-net-activity-api).
.AddAWSInstrumentation() // for tracing calls to AWS services via AWS SDK for .NET
161
-
.AddAspNetCoreInstrumentation()
162
-
.AddOtlpExporter()
163
-
.Build();
164
-
}
165
-
```
155
+
<SectionSeparator />
156
+
157
+
## Sample Application
158
+
159
+
Take a reference to the [sample application](https://github.com/aws-observability/aws-otel-dotnet/tree/main/integration-test-app) that is instrumented by ADOT and OpenTelemetry .NET SDK.
0 commit comments