Використання бібліотек інструментування

Під час розробки застосунку ви можете використовувати сторонні бібліотеки та фреймворки для прискорення роботи. Якщо ви потім інструментуєте свій застосунок за допомогою OpenTelemetry, ви можете не витрачати додатковий час на ручне додавання трейсів, логів та метрик до сторонніх бібліотек та фреймворків, які ви використовуєте.

Багато бібліотек та фреймворків вже підтримують OpenTelemetry або підтримуються через інструментування OpenTelemetry, тому вони можуть генерувати телеметричні дані, які ви можете експортувати до бекенду спостереження.

Якщо ви інструментуєте застосунок або сервіс, який використовує сторонні бібліотеки або фреймворки, дотримуйтесь цих інструкцій, щоб дізнатися, як використовувати вбудовані бібліотеки інструментування та бібліотеки інструментування для ваших залежностей.

Використання вбудованих бібліотек

Якщо бібліотека стандартно постачається з підтримкою OpenTelemetry, ви можете отримувати трейси, метрики та логи, що генеруються цією бібліотекою, додавши та налаштувавши OpenTelemetry SDK у вашому застосунку.

Бібліотека може вимагати додаткової конфігурації інструментування. Перейдіть до документації для цієї бібліотеки, щоб дізнатися більше.

• Azure SDK Instrumentation
• FusionCache .NET caching library
• MassTransit .NET client
• nservicebus OpenTelemetry Integration
• ThrottlingTroll

Використання бібліотек інструментування

Якщо бібліотека не постачається з OpenTelemetry з коробки, ви можете використовувати бібліотеки інструментування для генерації телеметричних даних для бібліотеки або фреймворку.

Наприклад, бібліотека інструментування для ASP.NET Core автоматично створюватиме відрізки та метрики на основі вхідних HTTP-запитів.

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

Кожна бібліотека інструментування є пакунком NuGet, і їх встановлення зазвичай виконується так:

dotnet add package OpenTelemetry.Instrumentation.{library-name-or-type}

Зазвичай вони реєструються під час запуску програми, наприклад, при створенні TracerProvider.

Примітка щодо версій

Семантичні домовленості (стандарти) для імен атрибутів наразі не є стабільними, тому бібліотека інструментування наразі не знаходиться в випущеному стані. Це не означає, що сама функціональність не є стабільною, лише те, що імена деяких атрибутів можуть змінюватися в майбутньому, деякі можуть бути додані, деякі можуть бути видалені. Це означає, що вам потрібно використовувати прапорець --prerelease, або встановити конкретну версію пакунка.

Приклад з ASP.NET Core та HttpClient

Наприклад, ось як ви можете інструментувати вхідні та вихідні запити з ASP.NET Core застосунку.

Спочатку отримайте відповідні пакунки OpenTelemetry Core:

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.Console

Потім ви можете встановити бібліотеки інструментування:

dotnet add package OpenTelemetry.Instrumentation.AspNetCore --prerelease
dotnet add package OpenTelemetry.Instrumentation.Http --prerelease

Далі налаштуйте кожну бібліотеку інструментування під час запуску та використовуйте їх!

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
  .WithTracing(b =>
  {
      b
      .AddHttpClientInstrumentation()
      .AddAspNetCoreInstrumentation();
  });

var app = builder.Build();

var httpClient = new HttpClient();

app.MapGet("/hello", async () =>
{
    var html = await httpClient.GetStringAsync("https://example.com/");
    if (string.IsNullOrWhiteSpace(html))
    {
        return "Hello, World!";
    }
    else
    {
        return "Hello, World!";
    }
});

app.Run();

Коли ви запустите цей код і звернетеся до точки доступу /hello, бібліотеки інструментування:

• Почнуть нове трасування
• Згенерують відрізок, що представляє запит до точки доступу
• Згенерують дочірній відрізок, що представляє HTTP GET запит до https://example.com/

Якщо ви додасте більше бібліотек інструментування, ви отримаєте більше відрізків для кожної з них.

Доступні бібліотеки інструментування

Повний список бібліотек інструментування, створених OpenTelemetry, доступний в репозиторії opentelemetry-dotnet.

Ви також можете знайти більше інструментів в реєстрі.

Наступні кроки

Після налаштування бібліотек інструментування, ви можете додати власне інструментування до вашого коду, щоб збирати користувацькі телеметричні дані.

Якщо ви використовуєте .NET Framework 4.x замість сучасного .NET, зверніться до документації .NET Framework для налаштування OpenTelemetry та бібліотек інструментування на .NET Framework.

Вам також потрібно налаштувати відповідний експортер для експорту ваших телеметричних даних до одного або більше бекендів телеметрії.

Ви також можете перевірити автоматичне інструментування для .NET, яке наразі знаходиться в бета-версії.