核心配置选项

`Recording（记录）` ([1.7.0])

一个布尔值，指定代理是否应该进行记录。当处于记录状态时，代理会捕获 HTTP 请求、跟踪错误，并收集和发送指标。不处于记录状态时，代理作为 noop 工作，不收集数据或与 APM server 通信，除了轮询中心配置端点。这是一个可逆开关，因此停用时不会杀死代理线程，但在这种状态下它们将基本处于空闲，因此开销可以忽略不计。

使用此设置可以在运行时动态禁用 Elastic APM。

警告

将 Recording 设置为 false 会影响 Public API 的行为。当代理不活动时，它不会跟踪事务、span 以及任何相关属性。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_RECORDING`	`ElasticApm:Recording`

默认	类型
`true`	布尔

`Enabled（启用）` ([1.7.0])

将其设置为 false 将完全禁用代理，包括 instrumentation 和远程配置轮询。如果您想动态改变代理的状态，请改用 recording。

警告

将 Enabled 设置为 false 会影响 Public API 的行为。当代理不活动时，它不会跟踪事务、span 以及任何相关属性。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_ENABLED`	`ElasticApm:Enabled`

默认	类型
`true`	布尔

`ServiceName（服务名称）`

这用于将服务的所有错误和事务聚合在一起，并且是 Elastic APM 用户界面中的主要过滤器。

注意

服务名称必须符合此正则表达式：^[a-zA-Z0-9 _-]+$。换句话说，您的服务名称只能包含 ASCII 字母、数字、破折号、下划线和空格。服务名称中与正则表达式不匹配的字符将被替换为 _ 符号。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_SERVICE_NAME`	`ElasticApm:ServiceName`

默认	类型
入口程序集的名称	字符串

`ServiceNodeName（服务节点名称）` ([1.3])

这是一个可选名称，用于区分服务中的节点。如果未设置，数据聚合将基于容器 ID（如果有效）或基于报告的主机名（自动发现）。

注意

此功能需要 APM Server 版本 >= 7.5

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_SERVICE_NODE_NAME`	`ElasticApm:ServiceNodeName`

默认	类型
`<无>`	字符串

`ServiceVersion（服务版本）`

服务当前部署版本的版本字符串。如果您不对部署进行版本控制，此字段的推荐值是部署修订的提交标识符，例如 git rev-parse HEAD 的输出。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_SERVICE_VERSION`	`ElasticApm:ServiceVersion`

默认	类型
入口程序集的信息版本	字符串

`HostName（主机名）` ([1.7])

这允许手动指定报告的主机名。如果未设置，将查找主机名。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_HOSTNAME`	`ElasticApm:HostName`

默认	类型
`<无>`	字符串

`Environment（环境）` ([1.1])

此服务部署所在环境的名称，例如“production”或“staging”。

通过环境，您可以在 APM 应用中轻松地在全球范围内过滤数据。在不同代理之间命名环境时保持一致性非常重要。有关更多信息，请参阅 Kibana UI 中的环境选择器。

注意

此功能在 Kibana 版本 >= 7.2 的 APM 应用中得到完全支持。在 7.2 之前的版本中，您必须使用查询栏过滤特定环境。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_ENVIRONMENT`	`ElasticApm:Environment`

默认	类型
请参阅下面的注释	字符串

注意

在 ASP.NET Core 应用程序中，代理默认使用 IHostingEnvironment 中的 EnvironmentName 作为默认环境名称。

`TransactionSampleRate（事务采样率）`

默认情况下，代理会对每个事务（例如对您服务的请求）进行采样。为了减少开销和存储需求，将采样率设置为介于 0.0 和 1.0 之间的值。代理仍会记录未采样事务的总时间和结果，但不会记录上下文信息、标签或 span。

注意

在解析此选项的值时，代理不考虑当前文化。它还期望使用句点（.）来分隔浮点数的整数部分和小数部分。

此设置可在代理启动后更改。

环境变量名称	IConfiguration 或 Web.config 键
`ELASTIC_APM_TRANSACTION_SAMPLE_RATE`	`ElasticApm:TransactionSampleRate`

默认	类型
1.0	Double（双精度浮点数）

`TransactionMaxSpans`（事务最大 span 数）（性能）([1.1.1])

这限制了每个事务记录的 span 数量。当一个事务创建大量 span（例如，数千个 SQL 查询）时，这会很有帮助。设置上限有助于防止在这些极端情况下代理和 APM server 过载。

注意

值为 0 表示永远不会收集 span。设置 -1 表示永远不会丢弃 span。如果值设置低于 -1，代理将恢复为默认值。

此设置可在代理启动后更改。

环境变量名称	IConfiguration 键
`ELASTIC_APM_TRANSACTION_MAX_SPANS`	`ElasticApm:TransactionMaxSpans`

默认	类型
`500`	Integer（整数）

`CentralConfig（中心配置）` ([1.1])

如果设置为 true，代理会定期向 APM Server 发出请求以获取最新的APM Agent 配置。

环境变量名称	IConfiguration 键
`ELASTIC_APM_CENTRAL_CONFIG`	`ElasticApm:CentralConfig`

默认	类型
true	布尔

`SanitizeFieldNames（清理字段名称）` ([1.2])

有时，有必要对发送到 Elastic APM 的敏感数据进行清理（即编辑）。此配置接受一个逗号分隔的通配符模式列表，用于指定应清理的字段名称。这些模式适用于请求和响应的 HTTP 头部、cookie 和 application/x-www-form-urlencoded 数据。

重要

此设置仅适用于代理自动捕获的值。如果您使用公共 API 手动捕获请求正文，此配置不适用，并且代理不会清理正文。

通配符 * 匹配零个或多个字符，默认情况下匹配不区分大小写。在元素前加上 (?-i) 会使匹配区分大小写。示例：/foo/*/bar/*/baz*, *foo*。

请仔细检查 Elastic APM 捕获的数据，确保它不包含敏感信息。如果您在 Elasticsearch 索引中发现敏感数据，请在此列表中添加额外的条目。在此处设置值将**覆盖**默认值，因此请确保同时包含默认条目。

注意

敏感信息不应在查询字符串中发送。查询字符串中的数据被视为非敏感数据。有关更多信息，请参阅 owasp.org。

Cookie 头部清理

对于传入的 HTTP 请求事务，Cookie 头部会自动被编辑。cookie 列表中的每个名称-值对都会被代理解析，并根据 SanitizeFieldNames 配置进行清理。值中包含敏感数据的 cookie 可以通过将 cookie 名称添加到逗号分隔的列表中来编辑。

环境变量名称	IConfiguration 键
`ELASTIC_APM_SANITIZE_FIELD_NAMES`	`ElasticApm:SanitizeFieldNames`

默认	类型
`password, passwd, pwd, secret, key, token, session, credit, card, auth, set-cookie, principal*`	逗号分隔字符串

`GlobalLabels（全局标签）` ([1.2])

标签以 key=value[,key=value[,...]] 的格式添加到所有事件中。应用程序通过代理的公共 API 设置的任何标签都将覆盖具有相同键的全局标签。

环境变量名称	IConfiguration 键
`ELASTIC_APM_GLOBAL_LABELS`	`ElasticApm:GlobalLabels`

默认	类型
<空 map>	字符串到字符串的 Map

注意

此选项需要 APM Server 7.2 或更高版本。在旧版本上无效。

`SpanCompressionEnabled（启用 Span 压缩）` ([1.14])

将此选项设置为 true 将启用 span 压缩功能。Span 压缩减少了收集、处理和存储开销，并消除了 UI 中的混乱。权衡是不会收集所有压缩 span 的一些信息，例如数据库语句。

环境变量名称	IConfiguration 键
`ELASTIC_APM_SPAN_COMPRESSION_ENABLED`	`ElasticApm:SpanCompressionEnabled`

默认	类型
`true`	布尔

`SpanCompressionExactMatchMaxDuration（Span 压缩完全匹配最大持续时间）` ([1.14])

连续的完全匹配且在此阈值以下的 span 将被压缩成一个复合 span。此选项不适用于复合 span。这减少了收集、处理和存储开销，并消除了 UI 中的混乱。权衡是不会收集所有压缩 span 的数据库语句。

环境变量名称	IConfiguration 键
`ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION`	`ElasticApm:SpanCompressionExactMatchMaxDuration`

默认	类型
`50ms`	TimeDuration（时间持续时间）

`SpanCompressionSameKindMaxDuration（Span 压缩同类最大持续时间）` ([1.14])

连续的对同一目标的 span 且在此阈值以下的 span 将被压缩成一个复合 span。此选项不适用于复合 span。这减少了收集、处理和存储开销，并消除了 UI 中的混乱。权衡是不会收集所有压缩 span 的数据库语句。

环境变量名称	IConfiguration 键
`ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION`	`ElasticApm:SpanCompressionSameKindMaxDuration`

默认	类型
`0ms`	TimeDuration（时间持续时间）

`ExitSpanMinDuration（出口 Span 最小持续时间）` ([1.14])

设置出口 span 的最小持续时间。持续时间小于此阈值的出口 span 会尝试被丢弃。如果出口 span 等于或大于阈值，则应保留。在某些情况下，出口 span 无法被丢弃。例如，将跟踪上下文传播到下游服务的 span，如传出 HTTP 请求，无法被丢弃。然而，不传播上下文的外部调用，如对数据库的调用，可以使用此阈值进行丢弃。此外，导致错误的 span 也无法被丢弃。

环境变量名称	IConfiguration 键
`ELASTIC_APM_EXIT_SPAN_MIN_DURATION`	`ElasticApm:ExitSpanMinDuration`

默认	类型
`0ms`	TimeDuration（时间持续时间）

`OpentelemetryBridgeEnabled（启用 OpenTelemetry Bridge）` ([1.13])

将此选项设置为 false 将禁用 OpenTelemetry Bridge。这将禁用使用供应商中立的 OpenTelemetry Tracing API（.NET 中的 Activity API）手动 instrumentation 代码，并让 Elastic .NET APM 代理处理这些 API 调用。

环境变量名称	IConfiguration 键
`ELASTIC_APM_OPENTELEMETRY_BRIDGE_ENABLED`	`ElasticApm:OpentelemetryBridgeEnabled`

默认	类型
`true`	布尔