Інструментування .NET без коду

Використовуйте OpenTelemetry .NET Automatic Instrumentation для надсилання трасування та метрик з .NET застосунків та сервісів до систем спостереження без необхідності змінювати їх вихідний код.

Щоб дізнатися, як інструментувати ваш сервіс або застосунок, прочитайте Ручне інструментування.

Сумісність

OpenTelemetry .NET Automatic Instrumentation має працювати з усіма офіційно підтримуваними операційними системами та версіями .NET.

Мінімально підтримувана версія .NET Framework - 4.6.2.

Підтримувані архітектури процесорів:

• x86
• AMD64 (x86-64)
• ARM64 (Експериментально)

CI тести виконуються на наступних операційних системах:

• Alpine ARM64
• Debian x64
• Debian ARM64
• CentOS Stream 9 x64
• macOS Sonoma 14 ARM64
• Microsoft Windows Server 2022 x64
• Microsoft Windows Server 2025 x64
• Ubuntu 22.04 LTS x64
• Ubuntu 22.04 LTS ARM64

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

Щоб автоматично інструментувати .NET застосунок, завантажте та запустіть інсталяційний скрипт для вашої операційної системи.

Linux та macOS

Завантажте та запустіть .sh скрипт:

# Завантажте bash скрипт
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Встановіть основні файли
sh ./otel-dotnet-auto-install.sh

# Дозвольте виконання інструментального скрипта
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Налаштуйте інструментування для поточної shell сесії
. $HOME/.otel-dotnet-auto/instrument.sh

# Запустіть ваш застосунок з інструментуванням
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 ./MyNetApp

brew install coreutils

Windows (PowerShell)

У Windows використовуйте PowerShell модуль як Адміністратор.

# Потрібен PowerShell 5.1
# Потрібен -PSEdition Desktop

# Завантажте модуль
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

# Імпортуйте модуль для використання його функцій
Import-Module $download_path

# Встановіть основні файли (онлайн або офлайн метод)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"

# Налаштуйте інструментування для поточної сесії PowerShell
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Запустіть ваш застосунок з інструментуванням
.\MyNetApp.exe

# Ви можете отримати інформацію про використання, викликавши наступні команди

# Список всіх доступних команд
Get-Command -Module OpenTelemetry.DotNet.Auto

# Отримати інформацію про використання команди
Get-Help Install-OpenTelemetryCore -Detailed

Інструментування Windows Service, що виконує .NET застосунок

Використовуйте PowerShell модуль OpenTelemetry.DotNet.Auto.psm1 для налаштування автоматичного інструментування для Windows Service:

# Імпортуйте модуль
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Встановіть основні файли
Install-OpenTelemetryCore

# Налаштуйте інструментування для вашого Windows Service
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Налаштування для Windows Service

Для .NET Framework застосунків ви можете налаштувати найбільш поширені OTEL_ параметри (наприклад, OTEL_RESOURCE_ATTRIBUTES) через appSettings у App.config.

Альтернативою є встановлення змінних середовища для Windows Service у реєстрі Windows.

Ключ реєстру для даного Windows Service (з назвою $svcName) знаходиться за адресою:

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

Змінні середовища визначаються у REG_MULTI_SZ (багаторядкове значення реєстру) з назвою Environment у наступному форматі:

Var1=Value1
Var2=Value2

Інструментування ASP.NET застосунку, розгорнутого на IIS

Використовуйте PowerShell модуль OpenTelemetry.DotNet.Auto.psm1 для налаштування автоматичного інструментування для IIS:

# Імпортуйте модуль
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Встановіть основні файли
Install-OpenTelemetryCore

# Налаштуйте інструментування для IIS
Register-OpenTelemetryForIIS

Налаштування для ASP.NET застосунків

Для ASP.NET додатків ви можете налаштувати найбільш поширені OTEL_ налаштування (наприклад, OTEL_SERVICE_NAME) через appSettings у Web.config.

Якщо імʼя сервісу не налаштоване явно, воно буде згенероване автоматично. Якщо застосунок розгорнуто на IIS у .NET Framework, це буде використовувати SiteName\VirtualDirectoryPath наприклад: MySite\MyApp

Для ASP.NET Core застосунків ви можете використовувати <environmentVariable> елементи всередині блоку <aspNetCore> вашого файлу Web.config для налаштування через змінні середовища.

Розширене налаштування

Ви можете додати <environmentVariables> у applicationHost.config для встановлення змінних середовища для певних пулів застосунків.

Розгляньте можливість встановлення загальних змінних середовища для всіх застосунків, розгорнутих на IIS, встановивши змінні середовища для Windows Services W3SVC та WAS.

NuGet пакунок

Ви можете інструментувати самостійні застосунки, використовуючи NuGet пакунки. Дивіться NuGet пакунки для отримання додаткової інформації.

Інструментування контейнера

Для прикладу інструментування Docker контейнера, дивіться приклад на GitHub.

Ви також можете використовувати OpenTelemetry Operator для Kubernetes.

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

Щоб побачити повний спектр налаштувань, дивіться Налаштування та параметри.

Кореляція логів з трейсами

OpenTelemetry .NET SDK автоматично корелює логи з даними трасування. Коли логи генеруються в контексті активного трасування, поля контексту трасування TraceId, SpanId, TraceState заповнюються автоматично.

Наступні логи створені демонстраційним консольним застосунком:

"logRecords": [
    {
        "timeUnixNano": "1679392614538226700",
        "severityNumber": 9,
        "severityText": "Information",
        "body": {
            "stringValue": "Success! Today is: {Date:MMMM dd, yyyy}"
        },
        "flags": 1,
        "traceId": "21df288eada1ce4ace6c40f39a6d7ce1",
        "spanId": "a80119e5a05fed5a"
    }
]

Для отримання додаткової інформації, дивіться:

• OpenTelemetry .NET SDK
• Специфікація OpenTelemetry

Підтримувані бібліотеки та фреймворки

OpenTelemetry .NET Automatic Instrumentation підтримує широкий спектр бібліотек. Для повного списку, дивіться Інструментування.

Розвʼязання проблем

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

• OTEL_TRACES_EXPORTER
• OTEL_METRICS_EXPORTER
• OTEL_LOGS_EXPORTER

Для загальних кроків розвʼязання проблем та отримання вирішень для конкретних питань, дивіться Розвʼязання проблем.

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

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

Видалення

Linux та macOS

У Linux та macOS кроки встановлення впливають лише на поточну сесію оболонки, тому явне видалення не потрібне.

Windows (PowerShell)

У Windows використовуйте модуль PowerShell як адміністратор.

# Потрібен PowerShell 5.1
# Потрібен -PSEdition Desktop

# Імпортуйте раніше встановлений модуль
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Якщо IIS був раніше зареєстрований, скасуйте його реєстрацію
Unregister-OpenTelemetryForIIS

# Якщо служби Windows були раніше зареєстровані, скасуйте їх реєстрацію
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# Нарешті, видаліть інструментування OpenTelemetry
Uninstall-OpenTelemetryCore