-
Notifications
You must be signed in to change notification settings - Fork 755
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
107 changed files
with
1,699 additions
and
639 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # OpenTelemetry Diagnostics | ||
|
|
||
| This document describes the diagnostic categories used in OpenTelemetry .NET | ||
| components. Diagnostics are used by the compiler to report information to users | ||
| about experimental and/or obsolete code being invoked or to suggest improvements | ||
| to specific code patterns identified through static analysis. | ||
|
|
||
| ## Experimental APIs | ||
|
|
||
| Range: OTEL1XXX | ||
|
|
||
| Experimental APIs exposed in OpenTelemetry .NET pre-relase builds. APIs are | ||
| exposed experimentally when either the OpenTelemetry Specification has | ||
| explicitly marked some feature as | ||
| [experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) | ||
| or when the SIG members are still working through the design for a feature and | ||
| want to solicit feedback from the community. | ||
|
|
||
| > **Note** Experimental APIs are exposed as `public` in pre-release builds and | ||
| > `internal` in stable builds. | ||
| For defined diagnostics see: [OpenTelemetry .NET Experimental | ||
| APIs](./experimental-apis/README.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # OpenTelemetry .NET Diagnostic: OTEL1000 | ||
|
|
||
| ## Overview | ||
|
|
||
| This is an Experimental API diagnostic covering the following APIs: | ||
|
|
||
| * `LoggerProviderBuilder` | ||
| * `LoggerProvider` | ||
| * `IDeferredLoggerProviderBuilder` | ||
|
|
||
| Experimental APIs may be changed or removed in the future. | ||
|
|
||
| ## Details | ||
|
|
||
| The OpenTelemetry Specification defines a `LoggerProvider` as part of its | ||
| [API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md) | ||
| & | ||
| [SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md) | ||
| components. | ||
|
|
||
| The SDK allows calling `Shutdown` and `ForceFlush` on the `LoggerProvider` and | ||
| also allows processors to be added dynamically to a pipeline after its creation. | ||
|
|
||
| Today the OpenTelemetry .NET log pipeline is built on top of the | ||
| Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory` | ||
| APIs which do not expose such features. | ||
|
|
||
| We also have an issue with the `ILoggingBuilder.AddOpenTelemetry` API in that it | ||
| interacts with the `OpenTelemetryLoggerOptions` class. Options classes are NOT | ||
| available until the `IServiceProvider` is available and services can no longer | ||
| be registered at that point. This prevents the current logging pipeline from | ||
| exposing the same dependency injection surface we have for traces and metrics. | ||
|
|
||
| We are exposing these APIs to solve these issues and gather feedback about their | ||
| usefulness. | ||
|
|
||
| ## Logs Bridge API | ||
|
|
||
| The OpenTelemetry Specification defines a Logs Bridge API which is rooted off of | ||
| the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log | ||
| records. See [OTEL1001](./OTEL1001.md) for details about the Logs Bridge API | ||
| implementation status. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # OpenTelemetry .NET Diagnostic: OTEL1001 | ||
|
|
||
| ## Overview | ||
|
|
||
| This is an Experimental API diagnostic covering the following APIs: | ||
|
|
||
| * `LoggerProvider.GetLogger` | ||
| * `Logger` | ||
| * `LogRecordAttributeList` | ||
| * `LogRecordData` | ||
| * `LogRecordSeverity` | ||
|
|
||
| Experimental APIs may be changed or removed in the future. | ||
|
|
||
| ## Details | ||
|
|
||
| The OpenTelemetry Specification defines a [Logs Bridge | ||
| API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md). | ||
|
|
||
| The Logs Bridge API is used by library authors to build log appenders which | ||
| route messages from different log frameworks into OpenTelemetry. | ||
|
|
||
| Today the OpenTelemetry .NET log pipeline is built on top of the | ||
| Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory` | ||
| APIs. | ||
|
|
||
| We are exposing these APIs gather feedback about their usefulness. An | ||
| alternative approach may be taken which would be to append into `ILogger` | ||
| instead of OpenTelemetry directly. | ||
|
|
||
| ## LoggerProvider API | ||
|
|
||
| The OpenTelemetry Specification defines a `LoggerProvider` API. See | ||
| [OTEL1000](./OTEL1000.md) for details about the `LoggerProvider` implementation | ||
| status. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| # OpenTelemetry .NET Diagnostic: OTEL1002 | ||
|
|
||
| ## Overview | ||
|
|
||
| This is an Experimental API diagnostic covering the following APIs: | ||
|
|
||
| * `AlwaysOnExemplarFilter` | ||
| * `AlwaysOffExemplarFilter` | ||
| * `Exemplar` | ||
| * `ExemplarFilter` | ||
| * `MeterProviderBuilder.SetExemplarFilter` extension method | ||
| * `TraceBasedExemplarFilter` | ||
|
|
||
| Experimental APIs may be changed or removed in the future. | ||
|
|
||
| ## Details | ||
|
|
||
| The OpenTelemetry Specification defines an [Exemplar | ||
| API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar) | ||
| in the Metrics SDK. | ||
|
|
||
| From the specification: | ||
|
|
||
| > Exemplars are example data points for aggregated data. They provide specific | ||
| > context to otherwise general aggregations. Exemplars allow correlation between | ||
| > aggregated metric data and the original API calls where measurements are | ||
| > recorded. | ||
| We are exposing these APIs experimentally until the specification declares them | ||
| stable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # OpenTelemetry .NET Experimental APIs | ||
|
|
||
| This document describes experimental APIs exposed in OpenTelemetry .NET | ||
| pre-relase builds. APIs are exposed experimentally when either the OpenTelemetry | ||
| Specification has explicitly marked some feature as | ||
| [experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) | ||
| or when the SIG members are still working through the design for a feature and | ||
| want to solicit feedback from the community. | ||
|
|
||
| > **Note** | ||
| > Experimental APIs are exposed as `public` in pre-release builds and `internal` | ||
| > in stable builds. | ||
| ## Active | ||
|
|
||
| Experimental APIs available in the pre-release builds: | ||
|
|
||
| ### OTEL1000 | ||
|
|
||
| Description: `LoggerProvider` and `LoggerProviderBuilder` | ||
|
|
||
| Details: [OTEL1000](./OTEL1000.md) | ||
|
|
||
| ### OTEL1001 | ||
|
|
||
| Description: Logs Bridge API | ||
|
|
||
| Details: [OTEL1001](./OTEL1001.md) | ||
|
|
||
| ### OTEL1002 | ||
|
|
||
| Description: Metrics Exemplar Support | ||
|
|
||
| Details: [OTEL1002](./OTEL1002.md) | ||
|
|
||
| ## Inactive | ||
|
|
||
| Experimental APIs which have been released stable or removed: | ||
|
|
||
| <!-- When an experimental API is released or removed: | ||
| 1) Move the section from above down here. | ||
| 2) Delete the individual file from the repo and switch the link here to a | ||
| permalink to the last version. | ||
| 3) Add the version info for when the API was released stable or removed. If | ||
| removed add details for alternative solution or reasoning. | ||
| --> | ||
|
|
||
| None |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -48,4 +48,3 @@ services: | |
| - GF_FEATURE_TOGGLES_ENABLE=traceqlEditor | ||
| ports: | ||
| - "3000:3000" | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.