配置和设置

配置方法

可以通过以下方式应用或编辑配置设置，其中环境变量优先于 App.config 或 Web.config 文件：

1. 环境变量

   环境变量是配置设置的主要方式。

2. App.config 或 Web.config 文件

   对于运行在 .NET Framework 上的应用程序，可以使用 Web 配置文件 (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]_INSTRUMENTATIONS_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_SERVICE_NAME 设置示例：

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

3. 服务名称的自动检测

   如果未显式配置服务名称，则会自动生成一个服务名称。这在某些情况下很有帮助。

• 如果应用程序在 .NET Framework 上托管于 IIS，则服务名称为 SiteName\VirtualPath，例如 MySite\MyApp。
• 如果不是这种情况，则使用应用程序的名称作为服务名称。 entry Assembly。

默认情况下，我们建议使用环境变量进行配置。然而，如果给定的设置支持，则：

• 使用 Web.config 配置 ASP.NET 应用程序（.NET Framework），
• 使用 App.config 配置 Windows 服务（.NET Framework）。

全局设置

[1] 如果 OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED 设置为 true，则由 OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES 排除的进程将失败，而不是继续运行。[2] 注意通过 dotnet MyApp.dll 启动的应用程序的进程名称为 dotnet 或 dotnet.exe。

默认情况下，我们建议使用环境变量进行配置。然而，如果给定的设置支持，则：

• 使用 Web.config 配置 ASP.NET 应用程序（.NET Framework），
• 使用 App.config 配置 Windows 服务（.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。

导出器

导出器输出遥测数据。

跟踪导出器

指标导出器

日志导出器

OTLP

状态: 稳定

要启用 OTLP 导出器，请将 OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER/OTEL_LOGS_EXPORTER 环境变量设置为 otlp。

要使用环境变量自定义 OTLP 导出器，请参阅 OTLP 导出器文档。 重要的环境变量包括：

[1] 关于 OTEL_EXPORTER_OTLP_PROTOCOL 可能需要考虑的问题：

• .NET 自动仪表默认为 http/protobuf，这与 .NET SDK 默认值 grpc 不同。
• 在 .NET 6 及更高版本中，应用程序必须引用 Grpc.Net.Client 才能使用 grpc OTLP 导出器协议。例如，通过将 <PackageReference Include="Grpc.Net.Client" Version="2.43.0" /> 添加到 .csproj 文件。
• 在 .NET Framework 上，不支持 grpc OTLP 导出器协议。

Prometheus

状态: 实验性

要启用 Prometheus 导出器，请将 OTEL_METRICS_EXPORTER 环境变量设置为 prometheus。

导出器在 http://localhost:9464/metrics 上公开指标 HTTP 端点，并将响应缓存 300 毫秒。

有关更多信息，请参阅 Prometheus Exporter HttpListener 文档。

Zipkin

状态: 稳定

要启用 Zipkin 导出器，请将 OTEL_TRACES_EXPORTER 环境变量设置为 zipkin。

要使用环境变量自定义 Zipkin 导出器，请参阅 Zipkin Exporter 文档。 重要的环境变量包括：

附加设置

RuleEngine

RuleEngine 是一项功能，用于验证 OpenTelemetry 的 API、SDK、工具包和导出器程序集是否存在不支持的情况，以确保 OpenTelemetry 自动工具包的稳定性，避免崩溃。该功能适用于 .NET 6 及更高版本。

只在首次运行应用程序时、部署更改或自动工具包程序库升级时启用 RuleEngine。一旦验证完成，在应用程序重新启动时无需重新验证规则。

.NET CLR Profiler

CLR 使用以下环境变量来设置配置分析器。有关更多信息，请参阅 .NET Runtime Profiler Loading。

将 OpenTelemetry .NET 自动工具包设置为 .NET CLR Profiler 对 .NET Framework 是必需的。

在 .NET 上，.NET CLR Profiler 仅用于字节码工具包。如果只需要源代码工具包，可以取消设置或删除以下环境变量：

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 环境变量。

DOTNET_ADDITIONAL_DEPS 和 DOTNET_SHARED_STORE 环境变量用于解决 .NET 中的程序集版本冲突。

内部日志

内部日志的默认目录路径如下：

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

如果无法创建默认日志目录，则仪表使用当前用户的临时文件夹路径。