Skip to main content

.NET 配置说明

配置方法

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

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

  • 使用 Web.config 配置 ASP.NET 应用程序(.NET Framework)
  • 使用 App.config 配置 Windows 服务(.NET Framework)

全局设置

环境变量描述默认值状态
OTEL_DOTNET_AUTO_HOME安装位置。Experimental
OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES分析器不能检测的可执行文件名称。支持多个逗号分隔的值，例如：ReservedProcess.exe,powershell.exe。如果未设置，分析器默认附加到所有进程。Experimental
OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED启用当自动检测无法执行时使进程失败的可能性。它是为调试目的而设计的。不应在生产环境中使用。[1]falseExperimental
OTEL_DOTNET_AUTO_LOGGER自动检测诊断日志接收器。(支持的值: none,file,console)fileExperimental
OTEL_LOG_LEVELSDK 日志级别。(支持的值: none,error,warn,info,debug)infoStable

[1] 如果 OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED 设置为 true，则被 OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES 排除检测的进程将失败，而不是静默继续。

[2] 注意通过 dotnet MyApp.dll 启动的应用程序的进程名为 dotnet 或 dotnet.exe。

资源

资源是生成遥测数据的实体的不可变表示。

资源属性

环境变量描述默认值状态
OTEL_RESOURCE_ATTRIBUTES用作资源属性的键值对。Stable
OTEL_SERVICE_NAME设置service.name资源属性的值。如果在 OTEL_RESOURCE_ATTRIBUTES 中提供了 service.name，则 OTEL_SERVICE_NAME 的值优先。请参见配置方法部分下的服务名称自动检测。Stable

资源检测器

环境变量描述默认值状态
OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED启用所有资源检测器。trueExperimental
OTEL_DOTNET_AUTO_{0}_RESOURCE_DETECTOR_ENABLED启用特定资源检测器的配置模式,其中 {0} 是你想要启用的资源检测器的大写 ID。覆盖 OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED 的设置。trueExperimental

以下资源检测器默认包含并启用:

ID描述文档状态
AZUREAPPSERVICEAzure App Service 检测器Azure 资源检测器文档Experimental
CONTAINER容器检测器容器资源检测器文档 不支持 .NET FrameworkExperimental
HOST主机检测器主机资源检测器文档Experimental
OPERATINGSYSTEM操作系统检测器操作系统资源检测器文档Experimental
PROCESS进程检测器进程资源检测器文档Experimental
PROCESSRUNTIME进程运行时检测器进程运行时资源检测器文档Experimental

Propagators

Propagators 允许应用程序共享上下文。

环境变量描述默认值
OTEL_PROPAGATORS以逗号分隔的 propagator 列表。支持的选项: tracecontext, baggage, b3multi, b3。更多详细信息请参见 OpenTelemetry 规范。tracecontext,baggage

采样器

采样器让你可以通过选择要收集和导出的追踪来控制 OpenTelemetry 检测引入的潜在噪声和开销。更多详细信息请参见 OpenTelemetry 规范。

环境变量描述默认值状态
OTEL_TRACES_SAMPLER用于追踪的采样器 [1]parentbased_always_onStable
OTEL_TRACES_SAMPLER_ARG用作采样器参数的字符串值 [2]Stable

[1]: 支持的值包括:

  • always_on,
  • always_off,
  • traceidratio,
  • parentbased_always_on,
  • parentbased_always_off,
  • parentbased_traceidratio。

[2]: 对于 traceidratio 和 parentbased_traceidratio 采样器:采样概率是一个 [0..1] 范围内的数字,例如 "0.25"。默认值为 1.0。

Exporters

Exporters 用于输出遥测数据。

环境变量描述默认值状态
OTEL_TRACES_EXPORTER以逗号分隔的导出器列表。支持的选项: otlp, zipkin, console, none。otlpStable
OTEL_METRICS_EXPORTER以逗号分隔的导出器列表。支持的选项: otlp, prometheus, console, none。otlpStable
OTEL_LOGS_EXPORTER以逗号分隔的导出器列表。支持的选项: otlp, console, none。otlpStable

追踪导出器

环境变量描述默认值状态
OTEL_BSP_SCHEDULE_DELAY两次连续导出之间的延迟间隔(毫秒)。5000Stable
OTEL_BSP_EXPORT_TIMEOUT导出数据的最大允许时间(毫秒)。30000Stable
OTEL_BSP_MAX_QUEUE_SIZE最大队列大小。2048Stable
OTEL_BSP_MAX_EXPORT_BATCH_SIZE最大批量大小。必须小于或等于 OTEL_BSP_MAX_QUEUE_SIZE。512Stable

指标导出器

环境变量描述默认值状态
OTEL_METRIC_EXPORT_INTERVAL两次导出尝试开始之间的时间间隔(毫秒)。OTLP 导出器为60000，console 导出器为10000Stable
OTEL_METRIC_EXPORT_TIMEOUT导出数据的最大允许时间(毫秒)。OTLP 导出器为30000，console 导出器无默认值Stable

日志导出器

环境变量描述默认值状态
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE是否应设置格式化的日志消息。falseExperimental

OTLP

状态: Stable

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

重要的 OTLP 导出器的环境变量包括:

环境变量描述默认值状态
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 导出器的目标端点。http/protobuf: http://localhost:54318, grpc: http://localhost:54317Stable
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT等同于 OTEL_EXPORTER_OTLP_ENDPOINT，但仅适用于追踪。http/protobuf: http://localhost:54318/v1/traces, grpc: http://localhost:54317Stable
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT等同于 OTEL_EXPORTER_OTLP_ENDPOINT，但仅适用于指标。http/protobuf: http://localhost:54318/v1/metrics, grpc: http://localhost:54317Stable
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT等同于 OTEL_EXPORTER_OTLP_ENDPOINT，但仅适用于日志。http/protobuf: http://localhost:54318/v1/logs, grpc: http://localhost:54317Stable
OTEL_EXPORTER_OTLP_PROTOCOLOTLP 导出器传输协议。支持的值为 grpc, http/protobuf。[1]http/protobufStable
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL等同于 OTEL_EXPORTER_OTLP_PROTOCOL，但仅适用于追踪。http/protobufStable
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL等同于 OTEL_EXPORTER_OTLP_PROTOCOL，但仅适用于指标。http/protobufStable
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL等同于 OTEL_EXPORTER_OTLP_PROTOCOL，但仅适用于日志。http/protobufStable
OTEL_EXPORTER_OTLP_TIMEOUT后端处理每个批次的最大等待时间(毫秒)。10000 (10 秒)Stable
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT等同于 OTEL_EXPORTER_OTLP_TIMEOUT，但仅适用于追踪。10000 (10 秒)Stable
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT等同于 OTEL_EXPORTER_OTLP_TIMEOUT，但仅适用于指标。10000 (10 秒)Stable
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT等同于 OTEL_EXPORTER_OTLP_TIMEOUT，但仅适用于日志。10000 (10 秒)Stable
OTEL_EXPORTER_OTLP_HEADERS每次导出时发送的额外 HTTP 头的逗号分隔列表，例如：Authorization=secret,X-Key=Value。Stable
OTEL_EXPORTER_OTLP_TRACES_HEADERS等同于 OTEL_EXPORTER_OTLP_HEADERS，但仅适用于追踪。Stable
OTEL_EXPORTER_OTLP_METRICS_HEADERS等同于 OTEL_EXPORTER_OTLP_HEADERS，但仅适用于指标。Stable
OTEL_EXPORTER_OTLP_LOGS_HEADERS等同于 OTEL_EXPORTER_OTLP_HEADERS，但仅适用于日志。Stable
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT属性值的最大允许大小。无Stable
OTEL_ATTRIBUTE_COUNT_LIMIT最大允许的 span 属性数量。128Stable
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT属性值的最大允许大小。不适用于指标。无Stable
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT最大允许的 span 属性数量。不适用于指标。128Stable
OTEL_SPAN_EVENT_COUNT_LIMIT最大允许的 span 事件数量。128Stable
OTEL_SPAN_LINK_COUNT_LIMIT最大允许的 span 链接数量。128Stable
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT每个 span 事件允许的最大属性数量。128Stable
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT每个 span 链接允许的最大属性数量。128Stable
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE基于工具类型使用的聚合时效性。[2]cumulativeStable

[1]: 关于 OTEL_EXPORTER_OTLP_PROTOCOL 的注意事项:

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

[2]: OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE 支持的值(不区分大小写)有:

  • Cumulative: 为所有工具类型选择累积聚合时效性。
  • Delta: 为计数器、异步计数器和直方图工具类型选择增量聚合时效性，为上下计数器和异步上下计数器工具类型选择累积聚合。

其他设置

环境变量描述默认值状态
OTEL_DOTNET_AUTO_TRACES_ENABLED启用追踪。trueExperimental
OTEL_DOTNET_AUTO_OPENTRACING_ENABLED启用 OpenTracing 追踪器。falseExperimental
OTEL_DOTNET_AUTO_LOGS_ENABLED启用日志。trueExperimental
OTEL_DOTNET_AUTO_METRICS_ENABLED启用指标。trueExperimental
OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED在 .NET Framework 上启用自动检测所使用的程序集的自动重定向。trueExperimental
OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES启动时要添加到追踪器的额外 System.Diagnostics.ActivitySource 名称的逗号分隔列表。用于捕获手动检测的 spans。Experimental
OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_LEGACY_SOURCES启动时要添加到追踪器的额外旧版源名称的逗号分隔列表。用于捕获不使用 System.Diagnostics.ActivitySource API 创建的 System.Diagnostics.Activity 对象。Experimental
OTEL_DOTNET_AUTO_FLUSH_ON_UNHANDLEDEXCEPTION控制在引发 AppDomain.UnhandledException 事件时是否刷新遥测数据。当你怀疑遗漏遥测数据并且也遇到未处理的异常时,将其设置为 true。falseExperimental
OTEL_DOTNET_AUTO_METRICS_ADDITIONAL_SOURCES启动时要添加到计量器的额外 System.Diagnostics.Metrics.Meter 名称的逗号分隔列表。用于捕获手动检测的 spans。Experimental
OTEL_DOTNET_AUTO_PLUGINSOTel SDK 检测插件类型的冒号分隔列表,使用程序集限定名称指定。注意:此列表必须使用冒号分隔,因为类型名称可能包含逗号。 有关如何编写插件的更多信息,请参见 plugins.md。Experimental

规则引擎

规则引擎是一个用于验证 OpenTelemetry API、SDK、检测和导出器程序集是否存在不支持场景的功能,通过回退而不是崩溃来确保 OpenTelemetry 自动检测更加稳定。它适用于 .NET 6 及更高版本。

仅在应用程序首次运行时,或在部署发生变更或自动检测库升级时启用规则引擎。一旦验证完成,当应用程序重新启动时就不需要重新验证规则。

环境变量描述默认值状态
OTEL_DOTNET_AUTO_RULE_ENGINE_ENABLED启用规则引擎。trueExperimental

.NET CLR Profiler

CLR 使用以下环境变量来设置探查器。更多信息请参见 .NET Runtime Profiler Loading。

.NET Framework 环境变量.NET 环境变量描述必需值状态
COR_ENABLE_PROFILINGCORECLR_ENABLE_PROFILING启用探查器。1Experimental
COR_PROFILERCORECLR_PROFILER探查器的 CLSID。{918728DD-259F-4A6A-AC2B-B85E1B658318}Experimental
COR_PROFILER_PATHCORECLR_PROFILER_PATH探查器的路径。Linux glibc: $INSTALL_DIR/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so Linux musl: $INSTALL_DIR/linux-musl-x64/OpenTelemetry.AutoInstrumentation.Native.so macOS: $INSTALL_DIR/osx-x64/OpenTelemetry.AutoInstrumentation.Native.dylibExperimental
COR_PROFILER_PATH_32CORECLR_PROFILER_PATH_3232 位探查器的路径。位数特定的路径优先于通用路径。Windows: $INSTALL_DIR/win-x86/OpenTelemetry.AutoInstrumentation.Native.dllExperimental
COR_PROFILER_PATH_64CORECLR_PROFILER_PATH_6464 位探查器的路径。位数特定的路径优先于通用路径。Windows: $INSTALL_DIR/win-x64/OpenTelemetry.AutoInstrumentation.Native.dllExperimental

在 .NET Framework 中必须将 OpenTelemetry .NET 自动检测设置为 .NET CLR Profiler。

在 .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 中的程序集版本冲突。

环境变量必需值状态
DOTNET_STARTUP_HOOKS$INSTALL_DIR/net/OpenTelemetry.AutoInstrumentation.StartupHook.dllExperimental
DOTNET_ADDITIONAL_DEPS$INSTALL_DIR/AdditionalDepsExperimental
DOTNET_SHARED_STORE$INSTALL_DIR/storeExperimental

internal-logs (内部日志)

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

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

如果无法创建默认日志目录,检测将使用当前用户的临时文件夹路径代替。

环境变量描述默认值状态
OTEL_DOTNET_AUTO_LOG_DIRECTORY.NET 追踪器日志的目录。参见前面关于默认路径的说明Experimental
OTEL_LOG_LEVELSDK 日志级别。(支持的值: none,error,warn,info,debug)infoStable
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE是否应格式化日志状态。falseExperimental