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

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

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

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

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

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

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

• Azure SDK Instrumentation
• MassTransit .NET client
• 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, яке наразі знаходиться в бета-версії.