核心配置选项

recording ( [1.15.0] 在 1.15.0 中添加。 )编辑

一个布尔值，用于指定代理是否应该记录。当记录时，代理会检测传入的 HTTP 请求，跟踪错误并收集和发送指标。当不记录时，代理将作为 noop 工作，不收集数据，也不与 APM 服务器通信，除了轮询中央配置端点。请注意，当禁用记录时，跟踪上下文传播、行李和日志关联也将被禁用。由于这是一个可逆开关，代理线程在停用时不会被杀死，但它们在此状态下将大部分时间处于空闲状态，因此开销应该可以忽略不计。

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

enabled ( [1.18.0] 在 1.18.0 中添加。 )编辑

设置为 false 将完全禁用代理，包括检测和远程配置轮询。如果要动态更改代理的状态，请改用 recording。

instrument ( [1.0.0] 在 1.0.0 中添加。自版本 1.15.0 起，可以在运行时更改此值 )编辑

一个布尔值，用于指定代理是否应该检测应用程序以收集应用程序的跟踪信息。当设置为 false 时，大多数内置检测插件都将被禁用，这将最大限度地减少对应用程序的影响。但是，代理仍然会应用与手动跟踪选项相关的检测，并且仍然会收集指标并将其发送到 APM 服务器。

service_name编辑

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

您可以选择依赖代理的服务名称自动检测机制，而不是手动配置服务名称。如果显式设置了 service_name，则所有自动检测机制都将被禁用。

服务名称自动检测的工作原理如下

通常，建议依赖于基于 META-INF/MANIFEST.MF 的服务名称检测。Spring Boot 会自动添加相关的清单条目。对于使用 Maven 构建的其他应用程序，以下是添加清单条目的方法

pom.xml。

    <build>
        <plugins>
            <plugin>
                <!-- replace with 'maven-war-plugin' if you're building a war -->
                <artifactId>maven-jar-plugin</artifactId>
                <configuration>
                    <archive>
                        <!-- Adds
                        Implementation-Title based on ${project.name} and
                        Implementation-Version based on ${project.version}
                        -->
                        <manifest>
                            <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
                        </manifest>
                        <!-- To customize the Implementation-* entries, remove addDefaultImplementationEntries and add them manually
                        <manifestEntries>
                            <Implementation-Title>foo</Implementation-Title>
                            <Implementation-Version>4.2.0</Implementation-Version>
                        </manifestEntries>
                        -->
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>

服务名称必须符合以下正则表达式：^[a-zA-Z0-9 _-]+$。用不太专业的术语来说：您的服务名称只能包含 ASCII 字母表中的字符、数字、破折号、下划线和空格。

service_node_name ( [1.11.0] 在 1.11.0 中添加。 )编辑

如果设置，此名称用于区分服务的不同节点，因此它对于服务中的每个 JVM 应该是唯一的。如果未设置，数据聚合将基于容器 ID（如果有效）或报告的主机名（通过 hostname 自动发现或手动配置）完成。

service_version编辑

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

与 service_name 的自动检测类似，代理可以根据 META-INF/MANIFEST.MF 中的 Implementation-Title 属性自动检测服务版本。有关如何设置此属性，请参阅 service_name。

hostname ( [1.10.0] 在 1.10.0 中添加。 )编辑

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

environment编辑

部署此服务的环环境名称，例如“生产”或“暂存”。

环境允许您在 APM 应用程序中轻松地在全局级别过滤数据。在跨代理命名环境时保持一致非常重要。有关更多信息，请参阅 APM 应用程序中的 环境选择器。

transaction_sample_rate（性能）编辑

默认情况下，代理会对每个事务（例如，对服务的请求）进行采样。为了减少开销和存储需求，您可以将采样率设置为 0.0 到 1.0 之间的值。（对于 8.0 之前的服务器，代理仍然会记录并发送未采样事务的总时间和结果，但不会发送上下文信息、标签或跨度。当连接到 8.0+ 服务器时，根本不会发送未采样的请求）。

值将舍入到 4 位有效数字，例如，值 *0.55555* 将舍入到 0.5556

transaction_max_spans（性能）编辑

限制每个事务记录的跨度数量。

这在事务创建大量跨度（例如，数千个 SQL 查询）的情况下很有用。

设置上限将防止代理和 APM 服务器因此类边缘情况而超载。

当超过最大跨度数时，将记录一条消息，但每 5 分钟仅记录一次，以确保性能不受影响。

long_field_max_length（性能 [1.37.0] 在 1.37.0 中添加。 )编辑

以下事务、跨度和错误字段在发送到 APM 服务器之前将被截断为此数量的 unicode 字符

请注意，上游 APM 服务器上的跟踪数据受限于 max_event_size，默认为 300kB。如果将 long_field_max_length 配置得过大，则可能导致 APM 服务器拒绝事务、跨度或错误。

sanitize_field_names（安全）编辑

有时需要清理发送到 Elastic APM 的数据，例如删除敏感数据。

配置应清理的字段名称的通配符模式列表。这些模式适用于例如 HTTP 标头和 application/x-www-form-urlencoded 数据。

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

enable_instrumentations ( [1.28.0] 在 1.28.0 中添加。 )编辑

应选择性启用的检测列表。有效选项包括 annotations、annotations-capture-span、annotations-capture-transaction、annotations-traced、apache-commons-exec、apache-httpclient、asynchttpclient、aws-lambda、aws-sdk、cassandra、concurrent、dubbo、elasticsearch-restclient、exception-handler、executor、executor-collection、experimental、finagle-httpclient、fork-join、grails、grpc、hibernate-search、http-client、jakarta-websocket、java-ldap、javalin、javax-websocket、jax-rs、jax-ws、jdbc、jdk-httpclient、jdk-httpserver、jedis、jms、jsf、kafka、lettuce、log-correlation、log-error、log-reformatting、logging、micrometer、mongodb、mongodb-client、okhttp、opentelemetry、opentelemetry-annotations、opentelemetry-metrics、opentracing、process、public-api、quartz、rabbitmq、reactor、redis、redisson、render、scala-future、scheduled、servlet-api、servlet-api-async、servlet-api-dispatch、servlet-input-stream、servlet-service-name、servlet-version、sparkjava、spring-amqp、spring-mvc、spring-resttemplate、spring-service-name、spring-view-render、spring-webclient、spring-webflux、ssl-context、struts、timer-task、urlconnection、vertx、vertx-web、vertx-webclient、websocket。当设置为非空值时，如果未通过 disable_instrumentations ( [1.0.0] 在 1.0.0 中添加。自 1.15.0 版起，可以在运行时更改此值 ) 或 enable_experimental_instrumentations ( [1.25.0] 在 1.25.0 中添加。 ) 禁用，则仅启用列出的检测。当未设置或为空（默认值）时，将启用默认情况下启用的所有检测，除非通过 disable_instrumentations ( [1.0.0] 在 1.0.0 中添加。自 1.15.0 版起，可以在运行时更改此值 ) 或 enable_experimental_instrumentations ( [1.25.0] 在 1.25.0 中添加。 ) 禁用它们。

disable_instrumentations ( [1.0.0] 在 1.0.0 中添加。自 1.15.0 版起，可以在运行时更改此值 )编辑

应禁用的检测列表。有效选项包括 annotations、annotations-capture-span、annotations-capture-transaction、annotations-traced、apache-commons-exec、apache-httpclient、asynchttpclient、aws-lambda、aws-sdk、cassandra、concurrent、dubbo、elasticsearch-restclient、exception-handler、executor、executor-collection、experimental、finagle-httpclient、fork-join、grails、grpc、hibernate-search、http-client、jakarta-websocket、java-ldap、javalin、javax-websocket、jax-rs、jax-ws、jdbc、jdk-httpclient、jdk-httpserver、jedis、jms、jsf、kafka、lettuce、log-correlation、log-error、log-reformatting、logging、micrometer、mongodb、mongodb-client、okhttp、opentelemetry、opentelemetry-annotations、opentelemetry-metrics、opentracing、process、public-api、quartz、rabbitmq、reactor、redis、redisson、render、scala-future、scheduled、servlet-api、servlet-api-async、servlet-api-dispatch、servlet-input-stream、servlet-service-name、servlet-version、sparkjava、spring-amqp、spring-mvc、spring-resttemplate、spring-service-name、spring-view-render、spring-webclient、spring-webflux、ssl-context、struts、timer-task、urlconnection、vertx、vertx-web、vertx-webclient、websocket。对于 1.25.0 及更高版本，请使用 enable_experimental_instrumentations ( [1.25.0] 在 1.25.0 中添加。 ) 启用实验性检测。

enable_experimental_instrumentations ( [1.25.0] 在 1.25.0 中添加。 )编辑

是否应用实验性检测。

unnest_exceptions编辑

报告异常时，取消嵌套与通配符模式匹配的异常。例如，这对于 Spring 的 org.springframework.web.util.NestedServletException 非常方便。

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

ignore_exceptions ( [1.11.0] 在 1.11.0 中添加。 )编辑

应忽略且不报告为错误的异常列表。这允许忽略在常规控制流中抛出的异常，这些异常不是实际错误

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

示例

capture_body（性能）编辑

对于作为 HTTP 请求的事务，Java 代理可以选择捕获请求正文（例如 POST 变量）。对于通过接收来自消息代理的消息而启动的事务，代理可以捕获文本消息正文。

如果 HTTP 请求或消息具有正文并且此设置被禁用，则正文将显示为 [已编辑]。

此选项不区分大小写。

有效选项：off、errors、transactions、all

capture_headers（性能）编辑

如果设置为 true，则代理将捕获 HTTP 请求和响应标头（包括 Cookie），以及使用 Kafka 或 JMS 等消息传递框架时的消息标头/属性。

global_labels ( [1.7.0] 在 1.7.0 中添加。需要 APM 服务器 7.2+ )编辑

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

instrument_ancient_bytecode ( [1.35.0] 在 1.35.0 中添加。 )编辑

一个布尔值，指定代理是否应该检测 Java-1.4 之前的字节码。

context_propagation_only ( [1.44.0] 在 1.44.0 中添加。 )编辑

设置为 true 时，将禁用日志发送、指标和跟踪收集。跟踪上下文传播和日志关联将保持活动状态。请注意，与 disable_send 相反，代理仍将连接到 APM 服务器以获取配置更新和运行状况检查。

classes_excluded_from_instrumentation编辑

用于从检测中排除特定类。要排除整个包，请使用通配符，如：com.project.exclude.* 此选项支持通配符 *，它匹配零个或多个字符。示例：/foo/*/bar/*/baz*、*foo*。默认情况下，匹配不区分大小写。在元素前面加上 (?-i) 使匹配区分大小写。

trace_methods ( [1.0.0] 在 1.0.0 中添加。自版本 1.15.0 起，可以在运行时更改此值 )编辑

要为其创建事务或跨度的方列表。

如果您想监控大量方法，请改用 profiling_inferred_spans_enabled。

这是通过检测每个匹配方法来实现的，以包含为该方法创建跨度的代码。虽然在性能方面创建跨度的成本很低，但检测整个代码库或在紧密循环中执行的方法会导致巨大的开销。

使用类似切入点的语法，您可以根据以下内容进行匹配

语法为 modifier @fully.qualified.AnnotationName fully.qualified.ClassName#methodName(fully.qualified.ParameterType)。

一些例子

常用配置

跟踪 CDI 注释 bean 中的所有公共方法

public @@javax.enterprise.context.NormalScope your.application.package.*
public @@jakarta.enterprise.context.NormalScope your.application.package.*
public @@javax.inject.Scope your.application.package.*

trace_methods_duration_threshold ( [1.7.0] 在 1.7.0 中添加。 )编辑

如果设置了 trace_methods 配置选项，则提供一个阈值以根据持续时间限制跨度。当设置为大于 0 的值时，默认情况下将丢弃表示基于 trace_methods 跟踪的方法的跨度。如果满足以下任一条件，则将跟踪和报告此类方法

设置为 0 以禁用。

支持持续时间后缀 ms、s 和 m。示例：0ms。

central_config ( [1.8.0] 在 1.8.0 中添加。 )编辑

启用后，代理将定期向 APM 服务器发出请求以获取更新的配置。

breakdown_metrics ( [1.8.0] 在 1.8.0 中添加。 )编辑

禁用故障指标的收集（span.self_time）

config_file ( [1.8.0] 在 1.8.0 中添加。 )编辑

设置代理配置文件的路径。特殊值 _AGENT_HOME_ 是 elastic-apm-agent.jar 所在文件夹的占位符。该文件必须在文件系统上。您不能引用类路径位置。

plugins_dir（实验性）编辑

包含外部代理插件的文件夹。

使用 apm-agent-plugin-sdk 和 apm-agent-api 工件创建一个 jar 并将其放入 plugins 文件夹。代理将加载在 META-INF/services/co.elastic.apm.agent.sdk.ElasticApmInstrumentation 服务描述符中声明的所有检测。有关示例插件，请参阅 integration-tests/external-plugin-test。

use_elastic_traceparent_header ( [1.14.0] 添加于 1.14.0 版本。 )编辑

为了启用分布式追踪，代理会将追踪上下文标头添加到传出请求（如 HTTP 请求、Kafka 记录、gRPC 请求等）。这些标头（traceparent 和 tracestate）在 W3C 追踪上下文 规范中定义。

如果此设置是 true，则代理还将添加标头 elastic-apm-traceparent 以向后兼容旧版本的 Elastic APM 代理。

disable_outgoing_tracecontext_headers ( [1.37.0] 添加于 1.37.0 版本。 )编辑

使用此选项可禁用向任何传出通信注入 tracecontext 标头。

span_min_duration ( [1.16.0] 添加于 1.16.0 版本。 )编辑

设置 span 的最短持续时间。将尝试丢弃执行速度快于此阈值的 span。

如果它们导致无法丢弃的 span，则尝试失败。传播追踪上下文到下游服务的 span（例如传出 HTTP 请求）无法丢弃。此外，导致错误或可能是异步操作的父级的 span 也无法丢弃。

但是，可以使用此阈值丢弃不传播上下文的外部调用，例如对数据库的调用。

支持持续时间后缀 ms、s 和 m。示例：0ms。

cloud_provider ( [1.21.0] 添加于 1.21.0 版本。 )编辑

此配置值允许您指定应假定哪个云提供商用于元数据收集。默认情况下，代理将尝试检测云提供商，或者如果失败，将使用试错法来收集元数据。

有效选项：AUTO、AWS、GCP、AZURE、NONE

enable_public_api_annotation_inheritance (性能)编辑

一个布尔值，指定代理是否应在类层次结构中搜索公共 API 注释（@CaptureTransaction、@CaptureSpan、@Traced 以及从 1.45.0 版本开始的 @WithSpan）。设置为 false 时，如果方法使用公共 API 注释进行注释，则对其进行检测。设置为 true 时，也将对覆盖注释方法的方法进行检测。无论哪种方式，只有当方法包含在配置的 application_packages 中时，才会对其进行检测。

transaction_name_groups ( [1.33.0] 添加于 1.33.0 版本。 )编辑

使用此选项，您可以使用通配符表达式对包含动态部分的事务名称进行分组。例如，模式 GET /user/*/cart 会将事务（例如 GET /users/42/cart 和 GET /users/73/cart）合并为一个事务名称 GET /users/*/cart，从而减少事务名称的基数。

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

trace_continuation_strategy ( [1.34.0] 添加于 1.34.0 版本。 )编辑

此选项允许对 APM 代理如何处理传入请求上的 W3C 追踪上下文标头进行一些控制。默认情况下，traceparent 和 tracestate 标头按 W3C 规范用于分布式追踪。但是，在某些情况下，不使用传入的 traceparent 标头可能会有所帮助。一些用例示例

有效值为

从 Elastic Observability 8.2 开始，span 链接在追踪视图中可见。

此选项不区分大小写。

有效选项：continue、restart、restart_external

baggage_to_attach ( [1.43.0] 添加于 1.43.0 版本。 )编辑

如果任何 baggage 键与通过此配置选项提供的任何模式匹配，则相应的 baggage 键和值将自动存储在相应的事务、span 和错误上。baggage 键在存储时将以“baggage.”为前缀。