146 lines
6.7 KiB
Markdown
146 lines
6.7 KiB
Markdown
# OpenTelemetry .NET SDK
|
|
|
|
[](https://www.nuget.org/packages/OpenTelemetry)
|
|
[](https://www.nuget.org/packages/OpenTelemetry)
|
|
|
|
<details>
|
|
<summary>Table of Contents</summary>
|
|
|
|
* [Installation](#installation)
|
|
* [Introduction](#introduction)
|
|
* [Troubleshooting](#troubleshooting)
|
|
* [Self-diagnostics](#self-diagnostics)
|
|
* [Configuration Parameters](#configuration-parameters)
|
|
* [Remarks](#remarks)
|
|
* [References](#references)
|
|
|
|
</details>
|
|
|
|
## Installation
|
|
|
|
```shell
|
|
dotnet add package OpenTelemetry
|
|
```
|
|
|
|
## Introduction
|
|
|
|
OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It
|
|
implements the Logging API, Metrics API, Tracing API, Resource API, and the
|
|
Context API. Once a valid SDK is installed and configured all the OpenTelemetry
|
|
API methods, which were no-ops without an SDK, will start emitting telemetry.
|
|
This SDK also ships with
|
|
[ILogger](https://learn.microsoft.com/dotnet/core/extensions/logging)
|
|
integration to automatically capture and enrich logs emitted using
|
|
`Microsoft.Extensions.Logging`.
|
|
|
|
The SDK deals with concerns such as sampling, processing pipelines (exporting
|
|
telemetry to a particular backend, etc.), metrics aggregation, and other
|
|
concerns outlined in the [OpenTelemetry
|
|
Specification](https://github.com/open-telemetry/opentelemetry-specification).
|
|
In most cases, users indirectly install and enable the SDK when they install an
|
|
exporter.
|
|
|
|
To learn how to set up and configure the OpenTelemetry SDK see: [Getting
|
|
started](https://github.com/open-telemetry/opentelemetry-dotnet/blob/core-1.12.0/src/OpenTelemetry/../../README.md#getting-started). For additional details about
|
|
initialization patterns see: [Initialize the
|
|
SDK](https://github.com/open-telemetry/opentelemetry-dotnet/blob/core-1.12.0/src/OpenTelemetry/../../docs/README.md#initialize-the-sdk).
|
|
|
|
## Troubleshooting
|
|
|
|
All the components shipped from this repo uses
|
|
[EventSource](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventsource)
|
|
for its internal logging. The name of the `EventSource` used by OpenTelemetry
|
|
SDK is "OpenTelemetry-Sdk". To know the `EventSource` names used by other
|
|
components, refer to the individual readme files.
|
|
|
|
While it is possible to view these logs using tools such as
|
|
[PerfView](https://github.com/microsoft/perfview),
|
|
[dotnet-trace](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-trace)
|
|
etc., this SDK also ships a [self-diagnostics](#self-diagnostics) feature, which
|
|
helps with troubleshooting.
|
|
|
|
### Self-diagnostics
|
|
|
|
OpenTelemetry SDK ships with built-in self-diagnostics feature. This feature,
|
|
when enabled, will listen to internal logs generated by all OpenTelemetry
|
|
components (i.e EventSources whose name starts with "OpenTelemetry-") and writes
|
|
them to a log file.
|
|
|
|
The self-diagnostics feature can be enabled/changed/disabled while the process
|
|
is running (without restarting the process). The SDK will attempt to read the
|
|
configuration file every `10` seconds in non-exclusive read-only mode. The SDK
|
|
will create or overwrite a file with new logs according to the configuration.
|
|
This file will not exceed the configured max size and will be overwritten in a
|
|
circular way.
|
|
|
|
To enable self-diagnostics, go to the
|
|
[current working directory](https://en.wikipedia.org/wiki/Working_directory) of
|
|
your process and create a configuration file named `OTEL_DIAGNOSTICS.json` with
|
|
the following content:
|
|
|
|
```json
|
|
{
|
|
"LogDirectory": ".",
|
|
"FileSize": 32768,
|
|
"LogLevel": "Warning"
|
|
}
|
|
```
|
|
|
|
To disable self-diagnostics, delete the above file.
|
|
|
|
Tip: In most cases, you could just drop the file along your application.
|
|
On Windows, you can use [Process Explorer](https://docs.microsoft.com/sysinternals/downloads/process-explorer),
|
|
double click on the process to pop up Properties dialog and find "Current
|
|
directory" in "Image" tab.
|
|
Internally, it looks for the configuration file located in
|
|
[GetCurrentDirectory](https://docs.microsoft.com/dotnet/api/system.io.directory.getcurrentdirectory),
|
|
and then [AppContext.BaseDirectory](https://docs.microsoft.com/dotnet/api/system.appcontext.basedirectory).
|
|
You can also find the exact directory by calling these methods from your code.
|
|
|
|
#### Configuration Parameters
|
|
|
|
1. `LogDirectory` is the directory where the output log file will be stored. It
|
|
can be an absolute path or a relative path to the current directory.
|
|
|
|
2. `FileSize` is a positive integer, which specifies the log file size in
|
|
[KiB](https://en.wikipedia.org/wiki/Kibibyte). This value must be within
|
|
range `[1024, 131072]` (1 MiB /<= size /<= 128 MiB), or it will be rounded to
|
|
the closest upper or lower limit. The log file will never exceed this
|
|
configured size, and will be overwritten in a circular way.
|
|
|
|
3. `LogLevel` is the lowest level of the events to be captured. It has to be one
|
|
of the
|
|
[values](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel#fields)
|
|
of the [`EventLevel`
|
|
enum](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel).
|
|
The level signifies the severity of an event. Lower severity levels encompass
|
|
higher severity levels. For example, `Warning` includes the `Error` and
|
|
`Critical` levels.
|
|
|
|
#### Remarks
|
|
|
|
A `FileSize`-KiB log file named as `ExecutableName.ProcessId.log` (e.g.
|
|
`foobar.exe.12345.log`) will be generated at the specified directory
|
|
`LogDirectory`, into which logs are written to.
|
|
|
|
If the SDK fails to parse the `LogDirectory`, `FileSize` or `LogLevel` fields as
|
|
the specified format, the configuration file will be treated as invalid and no
|
|
log file would be generated.
|
|
|
|
When the `LogDirectory` or `FileSize` is found to be changed, the SDK will create
|
|
or overwrite a file with new logs according to the new configuration. The
|
|
configuration file has to be no more than 4 KiB. In case the file is larger than
|
|
4 KiB, only the first 4 KiB of content will be read.
|
|
|
|
The log file might not be a proper text file format to achieve the goal of having
|
|
minimal overhead and bounded resource usage: it may have trailing `NUL`s if log
|
|
text is less than configured size; once write operation reaches the end, it will
|
|
start from beginning and overwrite existing text.
|
|
|
|
## References
|
|
|
|
* [OpenTelemetry Logging SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md)
|
|
* [OpenTelemetry Metrics SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md)
|
|
* [OpenTelemetry Tracing SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md)
|
|
* [OpenTelemetry Resource SDK specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)
|