Skip to content

Latest commit

 

History

History
145 lines (112 loc) · 5.46 KB

README.md

File metadata and controls

145 lines (112 loc) · 5.46 KB
Raw

OpenTelemetry .NET SDK

NuGet NuGet

Installation

dotnet add package OpenTelemetry

Introduction

OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It implements the Tracing API, the Metrics API, and the Context API. OpenTelemetry SDK deals with concerns such as sampling, processing pipeline, exporting telemetry to a particular backend etc. The default implementation consists of the following.

  • Set of Built-in samplers
  • Set of Built-in processors.
    • SimpleProcessor which sends Activities to the exporter without any batching.
    • BatchingProcessor which batches and sends Activities to the exporter.
  • Extensibility options for users to customize SDK.

Getting started

Please follow the tutorial and get started in 5 minutes.

Configuration

Instrumentation

Processor

Resource

Sampler

Samplers are used to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend. If no sampler is explicitly specified, the default is to use AlwaysOnSampler. The following example shows how to change it to TraceIdRatioBasedSampler with sampling probability of 25%.

using OpenTelemetry;
using OpenTelemetry.Trace;

using var otel = Sdk.CreateTracerProvider(b => b
    .AddActivitySource("MyCompany.MyProduct.MyLibrary")
    .SetSampler(new TraceIdRatioBasedSampler(0.25))
    .UseConsoleExporter());

Advanced topics

Troubleshooting

Self diagnostics module is provided to help troubleshooting. When enabled, internal events generated by OpenTelemetry will be written to a log file. These events contain important debugging information and error messages.

To enable self diagnostics, go to the current directory of your process and create a configuration file named OTEL_DIAGNOSTICS.json with the following content:

{
    "LogDirectory": ".",
    "FileSize": 1024,
    "LogLevel": "Error"
}

Configuration Parameters

  1. LogDirectory is the directory of the output file. 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.

  3. LogLevel is the lowest level of the events to be captured. It has to be one of the values of the EventLevel enum. (The level signifies the severity of an event. Lower severity levels encompass higher severity levels. For example, Warning includes the Error and Critical levels, which are higher in severity. See here for more.)

Remarks

A FileSize-KiB log file named as ExecutableName.ProcessId.log (e.g. foobar.exe.12345.log) will be generated at the specific directory LogDirectory.

The SDK will attempt to open the configuration file in non-exclusive read-only mode, read the file and parse it as the configuration file every 10 seconds. 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. Otherwise, it will create or overwrite the log file as described above.

Note that the FileSize has to be between 1 MiB and 128 MiB (inclusive), or it will be rounded to the closest upper or lower limit. 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.

References