配置和设置

配置方法

您可以通过以下方式应用或编辑配置设置，其中环境变量优先于 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]_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
   • 如果不是这种情况，它将使用应用程序 入口程序集的名称。

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

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

全局设置

[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 的注意事项

• OpenTelemetry .NET 自动仪器默认使用 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：为 Counter、Asynchronous Counter 和 Histogram 仪器种类选择 Delta 聚合临时性，为 UpDownCounter 和 Asynchronous UpDownCounter 仪器种类选择 Cumulative 聚合。
• LowMemory：此配置对 Synchronous Counter 和 Histogram 使用 Delta 聚合临时性，对 Synchronous UpDownCounter、Asynchronous Counter 和 Asynchronous UpDownCounter 仪器种类使用 Cumulative 聚合临时性。
  • ⚠️ 此值来自 规范，但不受支持。

Prometheus

状态：实验性的

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

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

请参阅 Prometheus Exporter HttpListener 文档 以了解更多信息。

Zipkin

状态：稳定

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

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

附加设置

RuleEngine

RuleEngine 是一项功能，用于验证 OpenTelemetry API、SDK、仪器和导出器程序集是否存在不受支持的场景，通过回退而不是崩溃来确保 OpenTelemetry 自动仪器的稳定性。它适用于 .NET 8 及更高版本。

仅在应用程序首次运行时、部署更改或升级自动仪器库时启用 RuleEngine。验证后，无需在应用程序重新启动时重新验证规则。

.NET CLR Profiler

CLR 使用以下环境变量来设置 Profiler。有关更多信息，请参阅 .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 上，如果未使用 .NET CLR Profiler，则必须设置 DOTNET_STARTUP_HOOKS 环境变量。

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

如果使用了 .NET CLR Profiler 且未设置 DOTNET_STARTUP_HOOKS 环境变量，则 Profiler 会在相对于 OpenTelemetry.AutoInstrumentation.Native.dll 文件位置的适当目录中查找 OpenTelemetry.AutoInstrumentation.StartupHook.dll。文件夹结构可以匹配 ZIP 存档结构或 NuGet 包结构（平台相关或独立）。如果找不到启动挂钩程序集，则会中止 Profiler 加载。

内部日志

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

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

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