Усунення несправностей

Усі компоненти, що постачаються з репозиторіїв OpenTelemetry .NET (opentelemetry-dotnet та opentelemetry-dotnet-contrib), використовують EventSource для внутрішнього логування. Назва EventSource, що використовується SDK OpenTelemetry, — “OpenTelemetry-Sdk”. Щоб дізнатися назви EventSource, що використовуються іншими компонентами, зверніться до документації окремих компонентів.

Хоча ці журнали можна переглянути за допомогою таких інструментів, як PerfView або dotnet-trace, SDK також має функцію самодіагностики, яка допомагає усунути несправності.

Самодіагностика

SDK OpenTelemetry постачається з вбудованою функцією самодіагностики. Ця функція, коли вона ввімкнена, прослуховує внутрішні журнали, що генеруються всіма компонентами OpenTelemetry (тобто EventSources, імʼя яких починається з “OpenTelemetry-”), і записує їх у файл журналу.

Функцію самодіагностики можна ввімкнути, змінити або вимкнути під час роботи процесу (без його перезапуску). SDK намагається читати файл конфігурації кожні 10 секунд у невиключному режимі тільки для читання. SDK створює або перезаписує файл з новими журналами відповідно до конфігурації. Цей файл не перевищує заданий максимальний розмір і перезаписується циклічно.

Щоб увімкнути самодіагностику, перейдіть до поточної робочої теки вашого процесу та створіть файл конфігурації з назвою OTEL_DIAGNOSTICS.json із таким вмістом:

{
  "LogDirectory": ".",
  "FileSize": 32768,
  "LogLevel": "Warning",
  "FormatMessage": "true"
}

Щоб вимкнути самодіагностику, видаліть файл конфігурації.

Параметри конфігурації

Файл конфігурації підтримує наступні параметри:

LogDirectory

Тека, в якій зберігається вихідний файл журналу. Це може бути абсолютний шлях або відносний шлях до поточної теки.

FileSize

Додатне ціле число, яке визначає розмір файлу журналу в KiB. Це значення повинно бути в діапазоні [1024, 131072] (1 MiB <= розмір <= 128 MiB), інакше воно буде округлено до найближчого верхньої або нижньої межі. Файл журналу ніколи не перевищує цей заданий розмір і перезаписується циклічно.

LogLevel

Найнижчий рівень подій, що підлягають фіксації. Він повинен бути одним із значень EventLevel enum. Рівень означає серйозність події. Нижчі рівні серйозності охоплюють вищі рівні серйозності. Наприклад, Warning включає рівні Error та Critical.

FormatMessage

Булеве значення, яке контролює, чи слід форматувати повідомлення журналу, замінюючи заповнювачі ({0}, {1} тощо) їхніми фактичними значеннями параметрів. Якщо встановлено значення false (стандартно), повідомлення реєструються з неформатованими заповнювачами, за якими йдуть необроблені значення параметрів. Якщо встановлено значення true, заповнювачі замінюються форматованими значеннями параметрів для покращення читабельності.

Приклад з FormatMessage: false (стандартно):

2025-07-24T01:45:04.1020880Z:Measurements from Instrument '{0}', Meter '{1}' will be ignored. Reason: '{2}'. Suggested action: '{3}'{dotnet.gc.collections}{System.Runtime}{Instrument belongs to a Meter not subscribed by the provider.}{Use AddMeter to add the Meter to the provider.}

Приклад з FormatMessage: true:

2025-07-24T01:44:44.7059260Z:Measurements from Instrument 'dotnet.gc.collections', Meter 'System.Runtime' will be ignored. Reason: 'Instrument belongs to a Meter not subscribed by the provider.'. Suggested action: 'Use AddMeter to add the Meter to the provider.'

Примітки

У вказаній теці LogDirectory створюється файл журналу з назвою ExecutableName.ProcessId.log (наприклад, myapp.exe.12345.log), в який записуються журнали.

Якщо SDK не вдається проаналізувати поля LogDirectory, FileSize або LogLevel, файл конфігурації вважається недійсним і файл журналу не створюється.

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

Файл журналу може не відповідати формату текстового файлу, необхідному для досягнення мети мінімальних накладних витрат і обмеженого використання ресурсів: він може містити кінцеві символи NUL, якщо текст журналу менший за заданий розмір; коли операція запису досягає кінця, вона починається з початку і перезаписує поточний текст.