Конфігурація та налаштування

Методи конфігурації

Ви можете застосувати або змінити налаштування конфігурації наступними способами, при цьому змінні середовища мають пріоритет над файлами App.config або Web.config:

1. Змінні середовища

   Змінні середовища є основним способом налаштування параметрів.

2. Файл App.config або Web.config

   Для застосунку, що працює на .NET Framework, ви можете використовувати файл веб-конфігурації (web.config) або файл конфігурації застосунку (app.config) для налаштування параметрів OTEL_*.

   ⚠️ Тільки налаштування, що починаються з OTEL_, можуть бути встановлені за допомогою App.config або Web.config. Однак наступні налаштування не підтримуються:

   • OTEL_DOTNET_AUTO_HOME
   • OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
   • OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_{INSTRUMENTATION_ID}_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_LOG_DIRECTORY
   • OTEL_LOG_LEVEL
   • OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED
   • OTEL_DOTNET_AUTO_SQLCLIENT_NETFX_ILREWRITE_ENABLED

   Приклад з налаштуванням OTEL_SERVICE_NAME:

   <configuration>
   <appSettings>
       <add key="OTEL_SERVICE_NAME" value="my-service-name" />
   </appSettings>
   </configuration>
   

3. Автоматичне визначення імені сервісу

   Якщо імʼя сервісу явно не налаштоване, воно буде згенероване автоматично. Це може бути корисно в деяких випадках.

   • Якщо застосунок розміщений на IIS у .NET Framework, це буде SiteName\VirtualPath, наприклад: MySite\MyApp
   • Якщо це не так, буде використано імʼя застосунку entry Assembly.

Типово ми рекомендуємо використовувати змінні середовища для конфігурації. Однак, якщо налаштування підтримує це, то:

• використовуйте Web.config для налаштування ASP.NET застосунку (.NET Framework),
• використовуйте App.config для налаштування Windows Service (.NET Framework).

Глобальні налаштування

[1] Якщо OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED встановлено в true, то процеси, виключені з інструментації за допомогою OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES, завершаться замість продовження роботи.

[2] Зверніть увагу, що застосунки, запущені через dotnet MyApp.dll, мають імʼя процесу dotnet або dotnet.exe.

Ресурси

Ресурс — це незмінне представлення сутності, що генерує телеметрію. Дивіться семантичні домовленості ресурсів для отримання додаткової інформації.

Атрибути ресурсу

Детектори ресурсів

Наступні детектори ресурсів стандартно включені та активовані:

Поширювачі

Поширювачі дозволяють застосункам обмінюватися контекстом. Дивіться специфікацію OpenTelemetry для отримання додаткової інформації.

Семплери

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

[1]: Підтримувані значення:

• always_on,
• always_off,
• traceidratio,
• parentbased_always_on,
• parentbased_always_off,
• parentbased_traceidratio.

[2]: Для семплерів traceidratio та parentbased_traceidratio: Ймовірність семплінгу, число в діапазоні [0..1], наприклад “0.25”. Стандартно 1.0.

Експортери

Експортери виводять телеметрію.

[1]: zipkin визнано застарілим і буде видалено у наступному релізі.

Експортер трасувань

Експортер метрик

Експортер логів

OTLP

Статус: Стабільний

Щоб увімкнути експортер OTLP, встановіть змінну середовища OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER/OTEL_LOGС_EXPORTЕР на otlp.

Щоб налаштувати експортер OTLP за допомогою змінних середовища, дивіться документацію експорту OTLP. Важливі змінні середовища включають:

[1]: Міркування щодо OTEL_EXPORTER_OTLP_PROTOCOL:

• OpenTelemetry .NET Automatic Instrumentation стандартно використовує http/protobuf, що відрізняється від значення стандартно OpenTelemetry .NET SDK grpc.
• У .NET 8 і вище, застосунок повинен посилатися на Grpc.Net.Client для використання протоколу експортера grpc OTLP. Наприклад, додавши <PackageReference Include="Grpc.Net.Client" Version="2.65.0" /> до файлу .csproj.
• У .NET Framework протокол експортера grpc OTLP не підтримується.

[2]: Визнані (незалежно від регістру) значення для OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:

• Cumulative: Виберіть кумулятивну темпоральність агрегації для всіх типів інструментів.
• Delta: Виберіть темпоральність агрегації Delta для Counter, Asynchronous Counter та Histogram, виберіть кумулятивну агрегацію для UpDownCounter та асинхронного UpDownCounter.
• LowMemory: Ця конфігурація використовує темпоральність агрегації Delta для Synchronous Counter та Histogram та використовує кумулятивну темпоральність агрегації для Synchronous UpDownCounter, Asynchronous Counter та Asynchronous UpDownCounter.
  • ⚠️ Це значення, відоме з специфікації, не підтримується.

[3]: Міркування щодо конфігурації mTLS (mutual TLS):

• mTLS підтримується лише у .NET 8.0 і вище.
• Всі файли сертифікатів мають бути у форматі PEM.
• При використанні mTLS, OTEL_EXPORTER_OTLP_ENDPOINT має використовувати https://.
• mTLS не підтримується на .NET Framework.

Prometheus

Статус: Експериментальний

Щоб увімкнути експортер Prometheus, встановіть змінну середовища OTEL_METRICS_EXPORTER на prometheus.

Експортер відкриває HTTP-кінець для метрик на http://localhost:9464/metrics і кешує відповіді протягом 300 мілісекунд.

Дивіться документацію Prometheus Exporter HttpListener для отримання додаткової інформації.

Zipkin

Статус: Стабільний

Щоб увімкнути експортер Zipkin, встановіть змінну середовища OTEL_TRACES_EXPORTER на zipkin.

Щоб налаштувати експортер Zipkin за допомогою змінних середовища, дивіться документацію експортера Zipkin. Важливі змінні середовища включають:

Додаткові налаштування

RuleEngine

RuleEngine — це функція, яка перевіряє збірки OpenTelemetry API, SDK, інструментації та експортера на наявність непідтримуваних сценаріїв, забезпечуючи більшу стабільність автоматичної інструментації OpenTelemetry шляхом відступу замість аварійного завершення. Працює на .NET 8 і вище.

Увімкніть RuleEngine лише під час першого запуску застосунку або коли змінюється розгортання або оновлюється бібліотека автоматичної інструментації. Після перевірки немає необхідності повторно перевіряти правила при перезапуску застосунку.

Профайлер .NET CLR

CLR використовує наступні змінні середовища для налаштування профайлера. Дивіться Завантаження профайлера .NET Runtime для отримання додаткової інформації.

Налаштування OpenTelemetry .NET Automatic Instrumentation як профайлера .NET CLR є обовʼязковим для .NET Framework.

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

COR_ENABLE_PROFILING
COR_PROFILER
COR_PROFILER_PATH_32
COR_PROFILER_PATH_64
CORECLR_ENABLE_PROFILING
CORECLR_PROFILER
CORECLR_PROFILER_PATH
CORECLR_PROFILER_PATH_32
CORECLR_PROFILER_PATH_64

.NET Runtime

У .NET необхідно встановити змінну середовища DOTNET_STARTUP_HOOKS, якщо профайлер .NET CLR не використовується.

Змінні середовища DOTNET_ADDITIONAL_DEPS та DOTNET_SHARED_STORE використовуються для помʼякшення конфліктів версій збірок у .NET.

Якщо використовується .NET CLR Profiler і змінна середовища DOTNET_STARTUP_HOOKS не встановлена, профайлер шукає OpenTelemetry.AutoInstrumentation. StartupHook.dll у відповідній теці відносно розташування файлу OpenTelemetry.AutoInstrumentation.Native.dll. Структура теки може відповідати структурі ZIP-архіву або структурі пакета NuGet (залежно від платформи або незалежно від неї). Якщо збірка запуску не знайдена, завантаження профайлера буде припинено.

Внутрішні логи

Типові шляхи до тек внутрішніх логів:

• Windows: %ProgramData%\OpenTelemetry .NET AutoInstrumentation\logs
• Linux: /var/log/opentelemetry/dotnet
• macOS: /var/log/opentelemetry/dotnet

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