diff --git a/docs/trace/README.md b/docs/trace/README.md new file mode 100644 index 00000000000..e9925cf6565 --- /dev/null +++ b/docs/trace/README.md @@ -0,0 +1,49 @@ +# OpenTelemetry .NET Traces + +## Best Practices + +### ActivitySource singleton + +`ActivitySource` SHOULD only be created once and reused throughout the +application lifetime. This +[example](./getting-started-console/Program.cs) shows how +`ActivitySource` is created as a `static` field and then used in the +application. You could also look at this ASP.NET Core +[example](../../examples/AspNetCore/Program.cs) which shows a more Dependency +Injection friendly way of doing this by extracting the `ActivitySource` into a +dedicated class called +[Instrumentation](../../examples/AspNetCore/Instrumentation.cs) which is then +added as a `Singleton` service. + +### Manually creating Activities + +As shown in the [getting started](getting-started-console/README.md) guide, it +is very easy to manually create `Activity`. Due to this, it can be tempting to +create too many activities (eg: for each method call). In addition to being +expensive, excessive activities can also make trace visualization harder. +Instead of manually creating `Activity`, check if you can leverage +instrumentation libraries, such as [ASP.NET +Core](../../src/OpenTelemetry.Instrumentation.AspNetCore/README.md), +[HttpClient](../../src/OpenTelemetry.Instrumentation.Http/README.md) which will +not only create and populate `Activity` with tags(attributes), but also take +care of propagating/restoring the context across process boundaries. If the +`Activity` produced by the instrumentation library is missing some information +you need, it is generally recommended to enrich the existing Activity with that +information, as opposed to creating a new one. + +## Common issues that lead to missing traces + +- The `ActivitySource` used to create the `Activity` is not added to the + `TracerProvider`. Use `AddSource` method to enable the activity from a given + `ActivitySource`. +- `TracerProvider` is disposed too early. You need to ensure that the + `TracerProvider` instance is kept active for traces to be collected. In a + typical application, a single TracerProvider is built at application startup, + and is disposed of at application shutdown. For an ASP.NET Core application, + use `AddOpenTelemetry` and `WithTraces` methods from the + `OpenTelemetry.Extensions.Hosting` package to correctly setup + `TracerProvider`. Here's a [sample ASP.NET Core + app](../../examples/AspNetCore/Program.cs) for reference. For simpler + applications such as Console apps, refer to this + [example](../../docs/trace/getting-started-console/Program.cs). +- TODO: Sampling diff --git a/examples/AspNetCore/Controllers/WeatherForecastController.cs b/examples/AspNetCore/Controllers/WeatherForecastController.cs index 5cd6f2cfe8d..3d09fe9ed61 100644 --- a/examples/AspNetCore/Controllers/WeatherForecastController.cs +++ b/examples/AspNetCore/Controllers/WeatherForecastController.cs @@ -49,7 +49,7 @@ public IEnumerable Get() // that calculating the forecast is an expensive operation and therefore // something to be distinguished from the overall request. // Note: Tags can be added to the current activity without the need for - // a manual activity using Acitivty.Current?.SetTag() + // a manual activity using Activity.Current?.SetTag() using var activity = this.activitySource.StartActivity("calculate forecast"); var rng = new Random();