.NET 无代码检测

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

使用 OpenTelemetry .NET 自动检测，无需修改源代码即可从 .NET 应用程序和服务向可观测性后端发送跟踪和指标。

有关如何检测服务或应用程序代码的说明，请阅读手动检测。

兼容性

OpenTelemetry .NET 自动检测应支持所有官方支持的操作系统以及 .NET 的版本。

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

支持的处理器架构有

CI 测试在以下操作系统上运行

设置

要自动检测 .NET 应用程序，请下载并运行适用于您操作系统的安装脚本。

Linux 和 macOS

下载并运行 .sh 脚本

# Download the bash script
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O

# Install core files
sh ./otel-dotnet-auto-install.sh

# Enable execution for the instrumentation script
chmod +x $HOME/.otel-dotnet-auto/instrument.sh

# Setup the instrumentation for the current shell session
. $HOME/.otel-dotnet-auto/instrument.sh

# Run your application with instrumentation
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment=staging,service.version=1.0.0 ./MyNetApp

Windows (PowerShell)

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

# PowerShell 5.1 is required
#Requires -PSEdition Desktop

# Download the module
$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 the module to use its functions
Import-Module $download_path

# Install core files (online vs offline method)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"

# Set up the instrumentation for the current PowerShell session
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"

# Run your application with instrumentation
.\MyNetApp.exe

# You can get usage information by calling the following commands

# List all available commands
Get-Command -Module OpenTelemetry.DotNet.Auto

# Get command's usage information
Get-Help Install-OpenTelemetryCore -Detailed

检测运行 .NET 应用程序的 Windows 服务

使用 OpenTelemetry.DotNet.Auto.psm1 PowerShell 模块为 Windows 服务设置自动检测

# Import the module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Install core files
Install-OpenTelemetryCore

# Set up your Windows Service instrumentation
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Windows 服务配置

对于 .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 应用程序

使用 OpenTelemetry.DotNet.Auto.psm1 PowerShell 模块为 IIS 设置自动检测

# Import the module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# Install core files
Install-OpenTelemetryCore

# Setup IIS instrumentation
Register-OpenTelemetryForIIS

ASP.NET 应用程序配置

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

如果未显式配置服务名称，将为您生成一个。如果应用程序在 .NET Framework 中托管在 IIS 上，它将使用 SiteName\VirtualDirectoryPath，例如：MySite\MyApp

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

高级配置

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

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

NuGet 包

您可以使用 NuGet 包来检测 自包含 应用程序。有关更多信息，请参阅NuGet 包。

检测容器

有关 Docker 容器检测的示例，请参阅 GitHub 上的示例。

您还可以使用 Kubernetes 的 OpenTelemetry Operator。

配置代理

要查看完整的配置选项，请参阅配置和设置。

日志与跟踪关联

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 自动检测支持各种库。完整列表请参阅检测。

故障排除

要直接在标准输出中查看应用程序的遥测数据，请在启动应用程序之前将 console 添加到以下环境变量的值中：

  • OTEL_TRACES_EXPORTER
  • OTEL_METRICS_EXPORTER
  • OTEL_LOGS_EXPORTER

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

下一步

配置好应用程序或服务的自动检测后，您可能希望发送自定义跟踪和指标或添加手动检测以收集自定义遥测数据。

卸载

Linux 和 macOS

在 Linux 和 macOS 上，安装步骤仅影响当前 shell 会话，因此无需显式卸载。

Windows (PowerShell)

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

# PowerShell 5.1 is required
#Requires -PSEdition Desktop

# Import the previously installed module
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# If IIS was previously registered, unregister it
Unregister-OpenTelemetryForIIS

# If Windows services were previously registered, unregister them
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# Finally, uninstall OpenTelemetry instrumentation
Uninstall-OpenTelemetryCore
入门

在不到 5 分钟内为您的应用获取遥测数据！

可用检测

OpenTelemetry .NET 自动检测支持的库。

配置和设置

创建自定义跟踪和指标

使用 .NET 自动检测创建自定义跟踪和指标。

使用 OpenTelemetry.AutoInstrumentation NuGet 包

排除 .NET 自动检测问题


最后修改于 2025 年 11 月 26 日：在 OTel .NET Auto 1.13.0 发布后更新文档 (#8509) (2651f70c)