Експортери

Надсилайте телеметрію до OpenTelemetry Collector, щоб переконатися, що вона експортується правильно. Використання Collector у виробничих середовищах є найкращою практикою. Щоб візуалізувати вашу телеметрію, експортуйте її до бекенду, такого як Jaeger, Zipkin, Prometheus або бекенд, специфічний для постачальника.

Доступні експортери

Реєстр містить список експортерів для .NET.

Серед експортерів, експортери OpenTelemetry Protocol (OTLP) розроблені з урахуванням моделі даних OpenTelemetry, що передають дані OTel без втрати інформації. Крім того, багато інструментів, які працюють з телеметричними даними, підтримують OTLP (таких як Prometheus, Jaeger і більшість постачальників), надаючи вам високий ступінь гнучкості, коли це потрібно. Щоб дізнатися більше про OTLP, дивіться Специфікацію OTLP.

Ця сторінка охоплює основні експортери OpenTelemetry .NET та як їх налаштувати.

OTLP

Налаштування Collector

Щоб спробувати та перевірити ваші OTLP експортери, ви можете запустити collector у docker контейнері, який записує телеметрію безпосередньо в консоль.

У порожній теці створіть файл з назвою collector-config.yaml з наступним вмістом:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

Тепер запустіть collector у docker контейнері:

docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector

Цей collector тепер може приймати телеметрію через OTLP. Пізніше ви можете налаштувати collector, щоб надсилати вашу телеметрію до вашого бекенду для спостереження.

Залежності

Якщо ви хочете надсилати телеметричні дані на точку доступу OTLP (наприклад, OpenTelemetry Collector, Jaeger або Prometheus), ви можете вибрати між двома різними протоколами для транспортування ваших даних:

  • HTTP/protobuf
  • gRPC

Почніть з встановлення пакунка OpenTelemetry.Exporter.OpenTelemetryProtocol як залежності для вашого проєкту:

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Якщо ви використовуєте ASP.NET Core, встановіть також пакунок OpenTelemetry.Extensions.Hosting:

dotnet add package OpenTelemetry.Extensions.Hosting

Використання

ASP.NET Core

Налаштуйте експортери у своїх службах ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        // The rest of your setup code goes here
        .AddOtlpExporter())
    .WithMetrics(metrics => metrics
        // The rest of your setup code goes here
        .AddOtlpExporter());

builder.Logging.AddOpenTelemetry(logging => {
    // The rest of your setup code goes here
    logging.AddOtlpExporter();
});

Це стандартно надсилатиме телеметрію за допомогою gRPC на http://localhost:4317, щоб налаштувати це для використання HTTP та формату protobuf, ви можете додати опції таким чином:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        // The rest of your setup code goes here
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("your-endpoint-here/v1/traces");
            options.Protocol = OtlpExportProtocol.HttpProtobuf;
        }))
    .WithMetrics(metrics => metrics
        // The rest of your setup code goes here
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("your-endpoint-here/v1/metrics");
            options.Protocol = OtlpExportProtocol.HttpProtobuf;
        }));

builder.Logging.AddOpenTelemetry(logging => {
    // The rest of your setup code goes here
    logging.AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("your-endpoint-here/v1/logs");
        options.Protocol = OtlpExportProtocol.HttpProtobuf;
    });
});

Non-ASP.NET Core

Налаштуйте експортер під час створення TracerProvider, MeterProvider або LoggerFactory:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // Other setup code, like setting a resource goes here too
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("your-endpoint-here/v1/traces");
        options.Protocol = OtlpExportProtocol.HttpProtobuf;
    })
    .Build();

var meterProvider = Sdk.CreateMeterProviderBuilder()
    // Other setup code, like setting a resource goes here too
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("your-endpoint-here/v1/metrics");
        options.Protocol = OtlpExportProtocol.HttpProtobuf;
    })
    .Build();

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("your-endpoint-here/v1/logs");
            options.Protocol = OtlpExportProtocol.HttpProtobuf;
        })
    });
});

Використовуйте змінні середовища для встановлення значень, таких як заголовки та URL точки для доступу для промислового використання.

Консоль

Залежності

Консольний експортер корисний для розробки та налагодження, і є найпростішим для налаштування. Почніть з встановлення пакунка OpenTelemetry.Exporter.Console як залежності для вашого проєкта:

dotnet add package OpenTelemetry.Exporter.Console

Якщо ви використовуєте ASP.NET Core, встановіть також пакунок OpenTelemetry.Extensions.Hosting:

dotnet add package OpenTelemetry.Extensions.Hosting

Використання

ASP.NET Core

Налаштуйте експортер у своїх службах ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        // The rest of your setup code goes here
        .AddConsoleExporter()
    )
    .WithMetrics(metrics => metrics
        // The rest of your setup code goes here
        .AddConsoleExporter()
    );

builder.Logging.AddOpenTelemetry(logging => {
    // The rest of your setup code goes here
    logging.AddConsoleExporter();
});

Non-ASP.NET Core

Налаштуйте експортер під час створення TracerProvider, MeterProvider або LoggerFactory:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // The rest of your setup code goes here
    .AddConsoleExporter()
    .Build();

var meterProvider = Sdk.CreateMeterProviderBuilder()
    // The rest of your setup code goes here
    .AddConsoleExporter()
    .Build();

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddConsoleExporter();
    });
});

Jaeger

Налаштування бекенду

Jaeger нативно підтримує OTLP для отримання даних трасування. Ви можете запустити Jaeger у docker контейнері з доступом до UI на порту 16686 та увімкненим OTLP на портах 4317 та 4318:

docker run --rm \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

Використання

Тепер дотримуйтесь інструкцій для налаштування OTLP експортерів.

Prometheus

Щоб надіслати ваші метрики до Prometheus, ви можете або увімкнути OTLP Receiver Prometheus і використовувати OTLP експортер, або ви можете використовувати експортер Prometheus, MetricReader, який запускає HTTP сервер, що збирає метрики та серіалізує їх у текстовий формат Prometheus за запитом.

Налаштування бекенду

Ви можете запустити Prometheus у docker контейнері, доступному на порту 9090, дотримуючись цих інструкцій:

Створіть файл під назвою prometheus.yml з наступним вмістом:

scrape_configs:
  - job_name: dice-service
    scrape_interval: 5s
    static_configs:
      - targets: [host.docker.internal:9464]

Запустіть Prometheus у docker контейнері з доступом до UI на порту 9090:

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --web.enable-otlp-receiver

У наступних розділах наведено докладні інструкції щодо налаштування експортера Prometheus, специфічні для .NET.

Існує два підходи до експорту метрик до Prometheus:

  1. Використання OTLP Exporter (Push): Передавайте метрики до Prometheus за допомогою протоколу OTLP. Для цього необхідно увімкнути OTLP Receiver від Prometheus. Це рекомендований підхід для виробничих середовищ, оскільки він підтримує зразки та є стабільним.

  2. Використання Prometheus Exporter (Pull/Scrape): відкрийте в застосунку точку доступу з якої Prometheus може зчитувати. Це традиційний підхід Prometheus.

Використання OTLP Exporter (Push)

Цей підхід використовує OTLP exporter для передачі метрик безпосередньо до точки доступу OTLP-приймача Prometheus. Рекомендується для робочих середовищ, оскільки підтримує зразки та використовує стабільний протокол OTLP.

Залежності

Встановіть пакунок OpenTelemetry.Exporter.OpenTelemetryProtocol як залежність для вашого проєкту:

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Якщо ви використовуєте ASP.NET Core, також встановіть пакунок OpenTelemetry.Extensions.Hosting:

dotnet add package OpenTelemetry.Extensions.Hosting
Використання
ASP.NET Core

Налаштуйте експортер OTLP для надсилання метрик до приймача Prometheus OTLP:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics
        // Решта вашого коду налаштування знаходиться тут
        .AddOtlpExporter(options =>
        {
            options.Endpoint = new Uri("http://localhost:9090/api/v1/otlp/v1/metrics");
            options.Protocol = OtlpExportProtocol.HttpProtobuf;
        }));
Non-ASP.NET Core

Налаштуйте експортер під час створення MeterProvider:

var meterProvider = Sdk.CreateMeterProviderBuilder()
    // Інший код налаштування, наприклад, налаштування ресурсу, також розміщується тут.
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("http://localhost:9090/api/v1/otlp/v1/metrics");
        options.Protocol = OtlpExportProtocol.HttpProtobuf;
    })
    .Build();

Використання Prometheus Exporter (Pull/Scrape)

Цей підхід експонує точку доступу метрик у вашій програмі (наприклад, /metrics), яку Prometheus регулярно сканує.

Залежності

Встановіть пакунок експортера як залежність для вашого застосунку:

dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --version 1.15.0-beta.1

Якщо ви використовуєте ASP.NET Core, встановіть також пакунок OpenTelemetry.Extensions.Hosting:

dotnet add package OpenTelemetry.Extensions.Hosting
Використання
ASP.NET Core

Налаштуйте експортер у своїх службах ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics.AddPrometheusExporter());

Потім вам потрібно буде зареєструвати програмне забезпечення Prometheus для збору даних, щоб Prometheus міг збирати дані з вашої програми. Використовуйте метод розширення UseOpenTelemetryPrometheusScrapingEndpoint на IApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

// ... Setup

var app = builder.Build();

app.UseOpenTelemetryPrometheusScrapingEndpoint();

await app.RunAsync();

Стандартно це експонує точку доступу метрик за адресою /metrics. Ви можете налаштувати шлях до точки доступу або використовувати функцію предиката для більш розширеної конфігурації:

app.UseOpenTelemetryPrometheusScrapingEndpoint(
    context => context.Request.Path == "/internal/metrics"
        && context.Connection.LocalPort == 5067);

Non-ASP.NET Core

Для застосунків, які не використовують ASP.NET Core, ви можете використовувати версію HttpListener, яка доступна в іншому пакунку:

dotnet add package OpenTelemetry.Exporter.Prometheus.HttpListener --version 1.15.0-beta.1

Потім це налаштовується безпосередньо на MeterProviderBuilder:

var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter(MyMeter.Name)
    .AddPrometheusHttpListener(
        options => options.UriPrefixes = new string[] { "http://localhost:9464/" })
    .Build();
Конфігурація Prometheus (Scrape)

При використанні експортера Prometheus (підхід pull/scrape) необхідно налаштувати Prometheus для зчитування даних з вашої програми. Додайте наступне до файлу prometheus.yml:

scrape_configs:
  - job_name: 'your-app-name'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:5000'] # Хост:порт вашої програми

Для більш детальної інформації про налаштування експортера Prometheus див. OpenTelemetry.Exporter.Prometheus.AspNetCore.

Zipkin

Налаштування бекенду

Ви можете запустити Zipkin у Docker контейнері, виконавши наступну команду:

docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin

Залежності

Щоб надсилати ваші дані трасування до Zipkin, встановіть пакунок експортера як залежність для вашого застосунку:

dotnet add package OpenTelemetry.Exporter.Zipkin

Якщо ви використовуєте ASP.NET Core, встановіть також пакунок OpenTelemetry.Extensions.Hosting:

dotnet add package OpenTelemetry.Extensions.Hosting

Використання

ASP.NET Core

Налаштуйте експортер у своїх службах ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        // The rest of your setup code goes here
        .AddZipkinExporter(options =>
        {
            options.Endpoint = new Uri("your-zipkin-uri-here");
        }));

Non-ASP.NET Core

Налаштуйте експортер під час створення постачальника трасування:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // The rest of your setup code goes here
    .AddZipkinExporter(options =>
    {
        options.Endpoint = new Uri("your-zipkin-uri-here");
    })
    .Build();

Востаннє змінено December 26, 2024: [uk] Ukrainian documentation for OpenTelemetry (2a3c5648)