配置 APM Server

Elastic Stack

如何配置 APM Server 取决于您的部署方法。

APM Server 二进制文件用户需要编辑 apm-server.yml 配置文件。该文件的位置因平台而异。要找到该文件，请参阅安装布局。
Fleet 管理用户直接在 Kibana 中配置 APM Server。每个配置页面都描述了具体的位置。
Elastic cloud 用户应参阅添加 APM 用户设置，了解如何配置 Elastic APM。

以下主题描述了如何配置 APM Server

编辑 APM 用户设置

通过提供您自己的用户设置来更改 Elastic APM 的运行方式。从 Elastic Stack 8.0 版本开始，您更改 APM 设置的方式以及可用的设置取决于您启动 Elastic APM 的方式。有两种模式

Fleet 管理的 APM 集成

在 Elastic Stack 8.0 及更高版本中创建的新部署将由 Fleet 管理。

查看 APM 配置参考，了解如何在此模式下配置 Elastic APM。

独立的 APM Server（旧版）

在 Elastic Stack 8.0 之前创建的部署处于旧版模式。升级到或超过 Elastic Stack 8.0 不会将您从旧版模式中移除。

查看编辑独立的 APM 设置（旧版）和支持的独立的 APM 设置（旧版），了解如何在此模式下配置 Elastic APM。

要了解有关这些模式之间差异的更多信息，或者要从独立的 APM Server（旧版）模式切换到 Fleet 管理的模式，请查看切换到 Elastic APM 集成。

编辑独立的 APM 设置（旧版）

用户设置会附加到您的实例的 apm-server.yml 配置文件中，并提供自定义配置选项。

要添加用户设置

登录到 Elastic Cloud 控制台。
在主页或 托管部署 页面上找到您的部署，然后选择管理以访问其设置菜单。

在 托管部署 页面上，您可以按名称、ID 缩小您的部署范围，或者从其他几个过滤器中选择。要自定义您的视图，请使用过滤器组合，或者将格式从网格更改为列表。
从您的部署菜单中，转到编辑页面。
在 APM 部分中，选择 编辑用户设置。（对于具有用户设置的现有部署，您可能需要展开 编辑 apm-server.yml 插入符号。）
更新用户设置。
选择 保存更改。

注意

如果 Elastic Cloud 不支持某个设置，当您尝试保存时，您将收到一条错误消息。

支持的独立的 APM 设置（旧版）

当以独立模式（旧版）运行 APM 时，Elastic Cloud 托管支持以下设置。

提示

如果设置不正确，某些设置可能会破坏您的集群，这些设置已列入阻止列表。以下设置在云环境中通常是安全的。有关 APM 设置的详细信息，请查看 APM 文档。

8.0+ 版本

此堆栈版本移除了对一些先前支持的设置的支持。以下是此版本的所有受支持设置

apm-server.agent.config.cache.expiration: 使用 APM agent 配置时，确定从 Kibana 获取的信息的缓存过期时间。默认为 30s。
apm-server.aggregation.transactions.*: 此功能是实验性的，可能会在未来的版本中更改或完全删除。启用后，APM Server 会生成事务直方图指标，这些指标用于驱动 APM 应用程序。将此责任从 APM 应用程序转移到 APM Server 可以提高查询性能，并消除存储未采样事务的需要。

可以配置以下 apm-server.auth.anonymous.* 设置来限制对指定 agent 和/或服务的匿名访问。这主要用于允许对不受信任的 agent 进行有限访问，例如真实用户监控。启用 RUM 后会自动启用匿名身份验证。否则，禁用匿名身份验证。启用匿名身份验证后，仅允许匹配 allow_agent 的 agent 和匹配 allow_service 的服务。有关这些默认值的详细信息，请参见下文。

apm-server.auth.anonymous.allow_agent: 仅允许对指定 agent 进行匿名访问。
apm-server.auth.anonymous.allow_service: 仅允许对指定服务名称进行匿名访问。默认情况下，允许所有服务名称。这取代了以前可用于 7.x 部署的配置选项 apm-server.rum.allow_service_names。
apm-server.auth.anonymous.rate_limit.event_limit: 速率限制是根据每个唯一客户端 IP 地址定义的，适用于有限数量的 IP 地址。具有许多并发客户端的站点应考虑增加此限制。默认为 1000。这取代了以前可用于 7.x 部署的配置选项 apm-server.rum.event_rate.limit。
apm-server.auth.anonymous.rate_limit.ip_limit: 定义每个 IP 每秒允许的最大事件数量。默认为 300。匿名访问的总体最大事件吞吐量为 (event_limit * ip_limit)。这取代了以前可用于 7.x 部署的配置选项 apm-server.rum.event_rate.lru_size。
apm-server.auth.api_key.enabled: 启用使用 Elasticsearch API 密钥的 agent 授权。这取代了以前可用于 7.x 部署的配置选项 apm-server.api_key.enabled。
apm-server.auth.api_key.limit: 限制每分钟允许的唯一 API 密钥数量。应至少设置为在受监控服务中配置的不同 API 密钥数量。每个唯一的 API 密钥都会触发对 Elasticsearch 的一个请求。这取代了以前可用于 7.x 部署的配置选项 apm-server.api_key.limit。
apm-server.capture_personal_data: 设置为 true 时，服务器会捕获检测服务的 IP 及其用户代理。默认情况下已启用。
apm-server.default_service_environment: 如果指定，APM Server 会将此值记录在没有定义服务环境的事件中，并在没有在来自 agent 的请求中指定时，将其添加到 Kibana 的 agent 配置查询中。
apm-server.max_event_size: 指定服务器处理事件允许的最大大小（以字节为单位）。默认为 307200。
apm-server.rum.allow_headers: 除了 "Content-Type"、"Content-Encoding" 和 "Accept" 之外，允许 RUM 请求的 Access-Control-Allow-Headers 列表。
apm-server.rum.allow_origins: 允许进行真实用户监控的源列表。用户代理将发送一个源标头，该标头将根据此列表进行验证。源由协议方案、主机和端口组成，没有 URL 路径。此设置中允许的源可以使用通配符 * 来匹配任何内容（例如：http://*.example.com）。如果列表中的某个项目是单个 *，则将允许所有源。
apm-server.rum.enabled: 启用真实用户监控 (RUM) 支持。默认情况下，RUM 已启用。RUM 不支持基于令牌的授权。已启用的 RUM 端点不需要为其他端点配置任何授权。
apm-server.rum.exclude_from_grouping: 要与堆栈跟踪帧的 file_name 匹配的正则表达式。如果正则表达式匹配，则该堆栈跟踪帧不用于计算错误组。默认模式排除文件名以 /webpack 开头的堆栈跟踪帧
apm-server.rum.library_pattern: 要与堆栈跟踪帧的 file_name 和 abs_path 属性匹配的正则表达式。如果正则表达式匹配，则该堆栈跟踪帧被认为是库帧。
apm-server.rum.source_mapping.enabled: 如果之前已上传源映射，则源映射会自动应用于发送到 RUM 端点的所有错误和事务文档。启用 RUM 后，默认启用源映射。
apm-server.rum.source_mapping.cache.expiration: cache.expiration 确定源映射应在内存中缓存多长时间。请注意，没有时间单位配置的值将被解释为秒。
apm-server.sampling.tail.enabled: 设置为 true 以启用基于尾部的抽样。默认情况下禁用。
apm-server.sampling.tail.policies: 用于将根事务匹配到采样率的标准。
apm-server.sampling.tail.interval: 多个 APM Server 的同步间隔。应在几十秒或几分钟的量级。
logging.level: 设置最小日志级别。默认日志级别为 error。可用的日志级别有：error、warning、info 或 debug。
logging.selectors: 为选定的组件启用调试输出。要启用所有选择器，请使用 ["*"]。其他可用的选择器有 "beat"、"publish" 或 "service"。可以链接多个选择器。
logging.metrics.enabled: 如果启用，apm-server 会定期记录其在过去一段时间内已更改的内部指标。对于每个已更改的指标，将记录该期间开始时该值与当前值的差值。此外，所有非零内部指标的总值将在关闭时记录。默认为 false。
logging.metrics.period: 记录内部指标的时间间隔。默认为 30 秒。
max_procs: 设置可以同时执行的最大 CPU 数量。默认为系统中可用的逻辑 CPU 数量。
output.elasticsearch.flush_interval: 在刷新到 Elasticsearch 之前，为批量请求累积事件的最长时间。该值必须具有持续时间后缀。默认为 1 秒。
output.elasticsearch.flush_bytes: 刷新到 Elasticsearch 之前的批量请求大小阈值（以字节为单位）。该值必须具有后缀。默认为 5MB。

7.17+ 版本

此堆栈版本包含来自 7.16 的所有设置以及以下内容

仅允许指定的代理和/或服务进行匿名访问。这主要用于允许不受信任的代理（如真实用户监控）进行有限访问。启用 RUM 时，会自动启用匿名身份验证。否则，将禁用匿名身份验证。启用匿名身份验证后，只允许匹配 allow_agent 的代理和服务匹配 allow_service 的服务。有关这些默认值的详细信息，请参见下文。

apm-server.auth.anonymous.allow_agent: 仅允许对指定 agent 进行匿名访问。
apm-server.auth.anonymous.allow_service: 仅允许指定的服务名称进行匿名访问。默认情况下，允许所有服务名称。这将替换 8.0 后的配置选项 apm-server.rum.allow_service_names。
apm-server.auth.anonymous.rate_limit.event_limit: 速率限制是根据每个唯一的客户端 IP 地址定义的，适用于有限数量的 IP 地址。具有大量并发客户端的站点应考虑增加此限制。默认为 1000。这将替换 8.0 后的配置选项 apm-server.rum.event_rate.limit。
apm-server.auth.anonymous.rate_limit.ip_limit: 定义每个 IP 每秒允许的最大事件数量。默认为 300。匿名访问的总体最大事件吞吐量为（event_limit * ip_limit）。这将替换 8.0 后的配置选项 apm-server.rum.event_rate.lru_size。
apm-server.auth.api_key.enabled: 使用 Elasticsearch API 密钥启用代理授权。这将替换 8.0 后的配置选项 apm-server.api_key.enabled。
apm-server.auth.api_key.limit: 限制每分钟允许的唯一 API 密钥数量。应设置为至少与您监控的服务中配置的不同 API 密钥数量相同。每个唯一的 API 密钥都会触发一个 Elasticsearch 请求。这将替换 8.0 后的配置选项 apm-server.api_key.limit。

8.x 之前的支持版本

apm-server.aggregation.transactions.*

此功能是实验性的，可能会在未来的版本中更改或完全删除。启用后，APM Server 会生成事务直方图指标，这些指标用于驱动 APM 应用程序。将此责任从 APM 应用程序转移到 APM Server 可以提高查询性能，并消除存储未采样事务的需要。

apm-server.default_service_environment

如果指定，APM Server 会将此值记录在没有定义服务环境的事件中，并在没有在来自 agent 的请求中指定时，将其添加到 Kibana 的 agent 配置查询中。

apm-server.rum.allow_service_names

允许的服务名称列表，用于限制为未经身份验证的 RUM 事件创建的服务特定索引和数据流。如果列表为空，则允许任何服务名称。

apm-server.ilm.setup.mapping

ILM 策略现在支持可配置的索引后缀。您可以根据 event_type 将 policy_name 附加一个 index_suffix，event_type 可以是 span、transaction、error 或 metric 之一。

apm-server.rum.allow_headers

除了 "Content-Type"、"Content-Encoding" 和 "Accept" 之外，还允许 RUM 请求的 Access-Control-Allow-Headers 列表。

setup.template.append_fields

要添加到 Elasticsearch 模板和 Kibana 数据视图（以前称为 *索引模式*）的字段列表。

apm-server.api_key.enabled

默认启用。对于 APM Server 接受授权标头中的 secret_token 的任何请求，它现在也可以选择接受 API 密钥。

apm-server.api_key.limit

配置每分钟允许的唯一 API 密钥数量。应设置为至少与监控服务中使用的不同 API 密钥数量相同。默认值为 100。

apm-server.ilm.setup.enabled

启用后，APM Server 将创建别名、事件类型特定设置和 ILM 策略。如果禁用，则需要手动管理事件类型特定模板。

apm-server.ilm.setup.overwrite

设置为 true 以应用自定义策略，并在使用 ILM 和不使用 ILM 之间切换时正确覆盖模板。

apm-server.ilm.setup.require_policy

当策略在 APM Server 外部设置但在本配置中引用时，设置为 false。

apm-server.ilm.setup.policies

ILM 策略数组。每个条目都有一个 name 和一个 policy。

apm-server.ilm.setup.mapping

ILM 策略到事件类型的映射数组。每个条目都有一个 policy_name 和一个 event_type，event_type 可以是 span、transaction、error 或 metric 之一。

apm-server.rum.source_mapping.enabled

当使用 RUM 代理监控事件时，APM Server 默认尝试应用源代码映射。此配置选项允许您在堆栈跟踪上禁用源代码映射。

apm-server.rum.source_mapping.cache.expiration

设置在从 Elasticsearch 重新获取源代码映射之前应缓存源代码映射的时间。默认值为 5m。

output.elasticsearch.pipeline

APM 附带默认的管道定义。这允许覆盖它。要禁用，您可以设置 pipeline: _none

apm-server.agent.config.cache.expiration

使用 APM agent 配置时，确定从 Kibana 获取的信息的缓存过期时间。默认为 30s。

apm-server.ilm.enabled

为 APM Server 创建的索引启用索引生命周期管理 (ILM)。默认为 false。如果您正在更新现有的 APM Server，您还必须设置 setup.template.overwrite: true。如果不这样做，索引模板将不会被覆盖，并且 ILM 更改将不会生效。

apm-server.max_event_size

指定服务器处理事件允许的最大大小（以字节为单位）。默认为 307200。

output.elasticsearch.pipelines

添加一个管道选择器配置数组，该数组支持条件、基于格式字符串的字段访问和名称映射，用于使用提取节点管道分析数据。

apm-server.register.ingest.pipeline.enabled

在 APM Server 启动时将管道定义加载到 Elasticsearch。默认为 false。

apm-server.register.ingest.pipeline.overwrite

覆盖 Elasticsearch 中现有的管道定义。默认为 true。

apm-server.rum.event_rate.lru_size

定义可以在 LRU 缓存中跟踪的唯一 IP 地址的数量，该缓存为每个最近看到的 IP 地址保留速率限制。默认为 1000。

apm-server.rum.event_rate.limit

设置发送到 APM Server v2 RUM 端点的每个 IP 地址每秒的事件速率限制。默认为 300。

apm-server.rum.enabled

启用/禁用真实用户监控 (RUM) 支持。默认为 true（启用）。

apm-server.rum.allow_origins

指定来自用户代理的允许来源列表。默认为 *，表示允许所有来源。

apm-server.rum.library_pattern

区分库框架和特定属性。请参阅可观察性指南中的“配置真实用户监控 (RUM)”以了解更多信息。默认值为 "node_modules|bower_components|~"。

apm-server.rum.exclude_from_grouping

配置与堆栈跟踪框架的 file_name 匹配的 RegExp。

apm-server.rum.rate_limit

设置发送到 RUM 端点的每个 IP 地址每秒的请求速率限制。默认为 10。

apm-server.capture_personal_data

设置为 true 时，服务器会捕获检测服务的 IP 及其用户代理。默认情况下已启用。

setup.template.settings.index.number_of_shards

指定 Elasticsearch 模板的分片数。

setup.template.settings.index.number_of_replicas

指定 Elasticsearch 模板的副本数。

apm-server.frontend.enabled

启用/禁用前端支持。

apm-server.frontend.allow_origins

指定来自用户代理的允许来源的逗号分隔列表。默认为 *，表示允许所有来源。

apm-server.frontend.library_pattern

区分库框架和特定属性。默认值为 "node_modules|bower_components|~"。

apm-server.frontend.exclude_from_grouping

配置与堆栈跟踪框架的 file_name 匹配的 RegExp。

apm-server.frontend.rate_limit

设置发送到前端端点的每个 IP 地址每秒的请求速率限制。默认为 10。

apm-server.capture_personal_data

设置为 true 时，服务器会捕获检测服务的 IP 地址及其用户代理。默认情况下启用。

max_procs

同时使用的最大 CPU 数量。默认为可用的逻辑 CPU 数量。

setup.template.enabled

设置为 false 可禁用加载用于 APM 索引的 Elasticsearch 模板。如果设置为 false，您必须手动加载模板。

setup.template.name

模板名称。默认为 apm-server。

setup.template.pattern

应用于默认索引设置的模板模式。默认为 apm-*

setup.template.settings.index.number_of_shards

指定 Elasticsearch 模板的分片数。

setup.template.settings.index.number_of_replicas

指定 Elasticsearch 模板的副本数。

output.elasticsearch.bulk_max_size

单个 Elasticsearch 批量 API 请求中要批量处理的最大事件数。默认情况下，此数字根据实例的大小而变化

实例大小	默认最大事件数
512MB	267
1GB	381
2GB	533
4GB	762
8GB	1067

output.elasticsearch.indices

支持条件和格式化字符串的索引选择器规则数组。

output.elasticsearch.index

要将事件写入的索引。如果更改，则必须相应地更改 setup.template.name 和 setup.template.pattern。

output.elasticsearch.worker

将事件发布到 Elasticsearch 的最大并发工作线程数。默认情况下，此数字根据实例的大小而变化

实例大小	默认最大并发工作线程数
512MB	5
1GB	7
2GB	10
4GB	14
8GB	20

queue.mem.events

在内部队列中并发存储的最大事件数。默认情况下，此数字根据实例的大小而变化

实例大小	默认最大事件数
512MB	2000
1GB	4000
2GB	8000
4GB	16000
8GB	32000

queue.mem.flush.min_events

在将事件推送到 Elasticsearch 之前必须拥有的最小事件数。默认情况下，此数字根据实例的大小而变化。

queue.mem.flush.timeout

如果未超过 min_events，则将事件发送到输出之前的最大持续时间。

日志设置

logging.level: 指定最小日志级别。可以是 *debug*、*info*、*warning* 或 *error* 之一。默认为 *info*。
logging.selectors: 不同 APM Server 组件使用的仅用于调试的选择器标记列表。使用 * 来启用所有组件的调试输出。例如，添加 *publish* 以显示与事件发布相关的所有调试消息。
logging.metrics.enabled: 如果启用，APM Server 会定期记录其在过去一段时间内已更改的内部指标。默认为 *true*。
logging.metrics.period: 记录内部指标的周期。默认为 *30s*。

注意

要更改日志记录设置，您必须首先启用部署日志记录。