Skip to content

Commit

Permalink
Tracing doc - clarify that activities should be stopped (#5320)
Browse files Browse the repository at this point in the history
  • Loading branch information
reyang authored Feb 7, 2024
1 parent 98e9b6a commit 72889f2
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions docs/trace/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
* [Best Practices](#best-practices)
* [Package Version](#package-version)
* [Tracing API](#tracing-api)
* [ActivitySource](#activitysource)
* [Activity](#activity)
* [TracerProvider Management](#tracerprovider-management)
* [Correlation](#correlation)

Expand Down Expand Up @@ -41,6 +43,8 @@ package, regardless of the .NET runtime version being used:

## Tracing API

### ActivitySource

:stop_sign: You should avoid creating
[`ActivitySource`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activitysource)
too frequently. `ActivitySource` is fairly expensive and meant to be reused
Expand All @@ -58,6 +62,8 @@ In many cases, using the fully qualified class name might be a good option.
static readonly ActivitySource MyActivitySource = new("MyCompany.MyProduct.MyLibrary");
```

### Activity

:heavy_check_mark: You should check
[`Activity.IsAllDataRequested`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.isalldatarequested)
before [setting
Expand All @@ -79,6 +85,16 @@ using (var activity = MyActivitySource.StartActivity("SayHello"))
to [set
attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes).

:heavy_check_mark: You should finish/stop the activity properly. This can be
done implicitly via a `using` statement, which is recommended. You can also
explicitly call
[Activity.Dispose](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.dispose)
or
[Activity.Stop](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.stop).

> [!NOTE]
> Activities which are not yet finished/stopped will not be exported.
## TracerProvider Management

:stop_sign: You should avoid creating `TracerProvider` instances too frequently,
Expand Down

0 comments on commit 72889f2

Please sign in to comment.