自动化仪表化

从.NET应用程序和服务发送跟踪和指标数据。

使用OpenTelemetry .NET自动化仪表化来将跟踪和指标数据从.NET应用程序和服务发送到可观测性后端，而无需修改其源代码。

要了解如何手动仪表化您的服务或应用程序代码，请参阅手动仪表化。

兼容性

OpenTelemetry .NET自动化仪表化应能与所有官方支持的操作系统和版本的.NET一起正常工作。 .NET。

最低支持的 .NET Framework 版本是 4.6.2。

CI 测试针对以下操作系统运行：

注意

不支持 ARM 架构。更多信息请参见 #2181。

设置

要自动化仪表化.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

注意

在 macOS 上，需要安装 coreutils。如果您已经安装了 homebrew，可以通过运行以下命令获取:

brew install coreutils

Windows (PowerShell)

在 Windows 上，以管理员身份使用 PowerShell 模块：

# PowerShell 5.1 或更高版本是必需的
# 下载模块
$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

仪表化运行 .NET 应用程序的 Windows 服务

使用 OpenTelemetry.DotNet.Auto.psm1 PowerShell 模块为 Windows 服务设置自动仪表化：

# 导入模块
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# 安装核心文件
Install-OpenTelemetryCore

# 设置 Windows 服务的仪表化
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

注意

Register-OpenTelemetryForWindowsService 将执行服务重启。

Windows 服务的配置

注意

在进行配置更改后，请记得重新启动 Windows 服务。您可以在 PowerShell 中运行 Restart-Service -Name $WindowsServiceName -Force 来完成。

对于.NET Framework应用程序，您可以通过 App.config 中的 appSettings 来配置最常见的 OTEL_ 设置（如 OTEL_RESOURCE_ATTRIBUTES）。

另一种方法是为 Windows 服务设置环境变量，可以在 Windows 注册表中的相应 Windows 服务（名为 $svcName）下找到注册表键：

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

环境变量以一种名为 Environment 的 REG_MULTI_SZ （多行注册表值）的格式定义。格式如下：

Var1=Value1
Var2=Value2

仪表化运行于 IIS 上的 ASP.NET 应用程序

注意

以下说明适用于.NET Framework应用程序。

使用 OpenTelemetry.DotNet.Auto.psm1 PowerShell 模块为 IIS 设置自动化仪表化：

# 导入模块
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# 安装核心文件
Install-OpenTelemetryCore

# 设置 IIS 仪表化
Register-OpenTelemetryForIIS

注意

Register-OpenTelemetryForIIS 将执行 IIS 重启。

ASP.NET 应用程序的配置

注意

以下说明适用于.NET Framework应用程序。

对于 ASP.NET 应用程序，您可以在 Web.config 的 <aspNetCore> 块内使用 <environmentVariable> 元素来通过环境变量设置配置。

注意

在进行配置更改后，请记得重新启动 IIS。您可以执行 iisreset.exe 来完成。

高级配置

您可以在 applicationHost.config 中添加 <environmentVariables> 来为给定应用程序池设置环境变量。

考虑为部署到 IIS 的所有应用程序设置通用环境变量，通过为 W3SVC 和 WAS Windows 服务设置环境变量。

注意

对于老于 10.0 版本的 IIS，您可以考虑创建单独的用户，设置其环境变量，并将其用作应用程序池用户。

NuGet 包

您可以使用 NuGet 包为自包含的应用程序进行仪表化。更多信息请参见 NuGet packages。

仪表化容器环境

有关 Docker 容器仪表化的示例，请参见 GitHub 上的示例。

您还可以使用 OpenTelemetry 运算符适配器进行 Kubernetes 的仪表化。

配置代理

有关配置选项的完整范围，请参见 Configuration and settings。

日志与跟踪关联

注意

OpenTelemetry .NET 自动化仪表化提供的自动日志与跟踪关联目前仅适用于使用 Microsoft.Extensions.Logging 的 .NET 应用程序。详情请参见 #2310。

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 自动化仪表化支持各种库。详细列表请参见 Instrumentations。

故障排除

要直接在标准输出中查看来自应用程序的遥测数据，请在启动应用程序之前将以下环境变量设置为 true：

OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED

有关一般故障排除步骤和特定问题的解决方案，请参阅 Troubleshooting。

下一步

在为您的应用程序或服务配置自动化仪表化后，您可能想要发送自定义跟踪和指标或添加手动仪表化以收集自定义遥测数据。