核心配置选项

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

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

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

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

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

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

以下是服务名称自动检测的工作方式

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

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 字母表中的字符、数字、破折号、下划线和空格。

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

当前部署的服务版本的版本字符串。如果您不为部署版本化，则此字段的建议值是已部署修订的提交标识符，例如 git rev-parse HEAD 的输出。

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

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

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

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

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

值将四舍五入到 4 个有效数字，例如，值 0.55555 将四舍五入为 0.5556

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

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

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

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

以下事务、span 和错误字段在发送到 APM 服务器之前，将在此 Unicode 字符数处被截断

请注意，上游 APM 服务器的追踪数据限制为 max_event_size，默认值为 300kB。如果将 long_field_max_length 配置得过大，可能会导致事务、span 或错误被 APM 服务器拒绝。

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

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

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

一个应该选择性启用的检测列表。有效选项为 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 中添加。 ) 禁用，否则将启用默认启用的所有检测。

一个应该被禁用的检测列表。有效选项为 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 中添加。 ) 启用实验性检测。

是否应用实验性检测。

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

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

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

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

示例

对于由 HTTP 请求触发的事务，Java 代理可以选择捕获请求体（例如 POST 变量）。 对于由从消息代理接收消息触发的事务，代理可以捕获文本消息体。

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

此选项不区分大小写。

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

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

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

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

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

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

一个方法列表，用于为其创建事务或 span。

如果要监视大量方法，请改用profiling_inferred_spans_enabled。

它的工作原理是检测每个匹配的方法以包含为该方法创建 span 的代码。虽然创建 span 在性能方面非常便宜，但检测整个代码库或在紧密循环中执行的方法会导致显著的开销。

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

语法为 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 配置选项，则提供一个阈值来限制基于持续时间的 span。当设置为大于 0 的值时，默认情况下，将丢弃基于 trace_methods 跟踪的方法的 span。如果满足以下条件之一，则将跟踪和报告此类方法

设置为 0 以禁用。

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

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

禁用分解指标的收集 (span.self_time)

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

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

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

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

当此设置设置为 true 时，代理还会添加标头 elastic-apm-traceparent，以便向后兼容旧版本的 Elastic APM 代理。

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

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

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

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

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

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

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

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

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

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

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

有效值是：

从 Elastic Observability 8.2 开始，跨度链接在跟踪视图中可见。

此选项不区分大小写。

有效选项：continue、restart、restart_external

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