›

配置参考

`api_key`

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_API_KEY`	`elastic_apm.api_key`

默认值	类型
无	字符串

此字符串用于确保只有您的 Agent 可以将数据发送到您的 APM Server。您必须使用 APM Server 命令行工具创建 API 密钥。

api_key 是 secret_token 的替代方案。如果同时配置了 secret_token 和 api_key，则 api_key 优先，secret_token 将被忽略。

APM Server 版本 >= 7.6 完全支持此功能。

api_key 值以纯文本形式在每个请求中发送到服务器，因此您还应该使用 HTTPS 保护您的通信。否则，您的 API 密钥可能会被攻击者观察到。

`breakdown_metrics`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_BREAKDOWN_METRICS`	`elastic_apm.breakdown_metrics`

默认值	类型
true	布尔值

如果此配置选项设置为 true，则 Agent 将收集并报告用于“按 Span 类型花费的时间”图表的分解指标 (span.self_time)。将其设置为 false 以禁用分解指标的收集和报告，这可以减少 Agent 的开销。

此功能需要 APM Server 和 Kibana >= 7.3。

`capture_errors`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_CAPTURE_ERRORS`	`elastic_apm.capture_errors`

默认值	类型
true	布尔值

如果此配置选项设置为 true，则 Agent 将收集并报告错误事件。将其设置为 false 以禁用 APM 错误事件的收集和报告，这可以减少 Agent 的开销。

另请参阅将 PHP 错误作为 APM 错误事件。

`disable_instrumentations`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_DISABLE_INSTRUMENTATIONS`	`elastic_apm.disable_instrumentations`

默认值	类型
空列表	字符串列表

以逗号分隔的通配符表达式列表，用于匹配应禁用的检测名称。禁用检测后，将不会为该检测创建 Span。每个检测都有一个名称和任意数量的关键字。如果检测的名称或其任何关键字与此配置选项匹配，则禁用该检测。

有关如何使用通配符表达式的更多详细信息，请参阅通配符。

支持的检测

名称	关键字
`curl`	`HTTP-client`
`PDO`	`DB`
`MySQLi`	`DB`

示例

db 禁用 PDO 和 MySQLi 检测
*HTTP* 禁用 curl 检测

`disable_send`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_DISABLE_SEND`	`elastic_apm.disable_send`

默认值	类型
false	布尔值

如果设置为 true，则 Agent 将像往常一样工作，除了任何需要与 APM 服务器通信的任务。事件将被丢弃，Agent 将无法接收中心配置，这意味着在这种状态下，任何其他配置都无法在不重启服务的情况下进行更改。此设置的示例用途包括：通过日志关联功能保持创建跟踪和记录跟踪/事务/Span ID 的能力，以及通过 W3C HTTP 标头获取自动分布式跟踪。

`enabled`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_ENABLED`	`elastic_apm.enabled`

默认值	类型
true	布尔值

设置为 false 将完全禁用 Agent。

`environment`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_ENVIRONMENT`	`elastic_apm.environment`

默认值	类型
无	字符串

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

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

Kibana 版本 >= 7.2 的 APM 应用程序完全支持此功能。您必须在 7.2 之前的版本中使用查询栏来筛选特定环境。

`global_labels`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_GLOBAL_LABELS`	`elastic_apm.global_labels`

默认值	类型
空映射	字符串到字符串映射

来自此配置的标签将添加到 Agent 生成的所有实体。

格式为 key=value[,key=value[,...]]。例如 dept=engineering,rack=number8。

在 .ini 文件中设置此配置选项时，需要将值括在引号中（因为该值包含等号）。例如 elastic_apm.global_labels = "dept=engineering,rack=number8"

应用程序通过 Agent 的公共 API 设置的任何标签都将覆盖具有相同键的全局标签。

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

`hostname`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_HOSTNAME`	`elastic_apm.hostname`

默认值	类型
本地计算机的主机名	字符串

此选项允许配置报告的主机名。如果未设置此选项，则使用本地计算机的主机名。

`log_level`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_LOG_LEVEL`	`elastic_apm.log_level`

默认值	类型
无	日志级别

用于控制 Agent 日志级别的回退配置设置。仅当未明确设置特定于接收器的选项时才使用。有关详细信息，请参阅日志。

`log_level_stderr`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_LOG_LEVEL_STDERR`	`elastic_apm.log_level_stderr`

默认值	类型
`CRITICAL`	日志级别

stderr 日志接收器的日志级别。有关详细信息，请参阅日志。

`log_level_syslog`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_LOG_LEVEL_SYSLOG`	`elastic_apm.log_level_syslog`

默认值	类型
`INFO`	日志级别

syslog 日志接收器的日志级别。有关详细信息，请参阅日志。

`profiling_inferred_spans_enabled`

编辑

此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能的支持 SLA 的约束。

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_PROFILING_INFERRED_SPANS_ENABLED`	`elastic_apm.profiling_inferred_spans_enabled`

默认值	类型
`false`	布尔值

如果此选项设置为 true，则 Agent 会根据采样（又名统计分析器）为方法执行创建 Span。

由于采样分析器的工作方式的性质，推断 Span 的持续时间不精确，而只是估计值。请参阅 profiling_inferred_spans_sampling_interval 以微调准确性和开销之间的权衡。

`profiling_inferred_spans_min_duration`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_PROFILING_INFERRED_SPANS_MIN_DURATION`	`elastic_apm.profiling_inferred_spans_min_duration`

默认值	类型
`0ms`	持续时间

推断 Span 的最小持续时间。

请注意，有效最小持续时间也受采样间隔的影响，因此它是 max(profiling_inferred_spans_min_duration, profiling_inferred_spans_sampling_interval)

此配置选项支持持续时间后缀：ms、s 和 m。例如：100ms。

`profiling_inferred_spans_sampling_interval`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_PROFILING_INFERRED_SPANS_SAMPLING_INTERVAL`	`elastic_apm.profiling_inferred_spans_sampling_interval`

默认值	类型
`50ms`	持续时间

为了构建推断 Span 而收集堆栈跟踪的频率。此设置越低，推断 Span 的持续时间就越准确。另一方面，更高的准确性以更高的开销和更多潜在不相关操作的推断 Span 为代价（请参阅 profiling_inferred_spans_min_duration）。

此配置选项支持以下持续时间后缀：ms、s 和 m。例如：50ms。

`secret_token`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SECRET_TOKEN`	`elastic_apm.secret_token`

默认值	类型
无	字符串

此字符串用于确保只有您的代理才能将数据发送到您的 APM 服务器。代理和 APM 服务器都必须配置相同的密钥令牌。

有关如何配置 APM 服务器的密钥令牌，请参阅相关的 APM 服务器文档。

如果 APM 服务器需要令牌，例如在 Elasticsearch Service 中，请使用此设置。

secret_token 是 api_key 的替代方案。如果同时配置了 secret_token 和 api_key，则 api_key 优先，并且 secret_token 将被忽略。

secret_token 在发送到服务器的每个请求中都以明文形式发送，因此您还应该使用 HTTPS 来保护您的通信。否则，您的密钥令牌可能会被攻击者观察到。

`server_timeout`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SERVER_TIMEOUT`	`elastic_apm.server_timeout`

默认值	类型
`30s`	持续时间

如果将事件发送到 APM 服务器的请求花费的时间超过了配置的超时时间，则请求将被取消，并且事件将被丢弃。

该值必须以持续时间格式提供。

此选项的默认单位是 s（秒）。

如果该值为 0（或 0ms、0s 等），则禁用将事件发送到 APM 服务器的超时。

负值无效，将导致使用默认值。

`server_url`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SERVER_URL`	`elastic_apm.server_url`

默认值	类型
`https://127.0.0.1:8200`	字符串

您的 APM 服务器的 URL。URL 必须是完全限定的，包括协议（http 或 https）和端口。

`service_name`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SERVICE_NAME`	`elastic_apm.service_name`

默认值	类型
`unknown-php-service`	字符串

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

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

`service_node_name`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SERVICE_NODE_NAME`	`elastic_apm.service_node_name`

默认值	类型
无	字符串

如果设置了此名称，则此名称用于区分服务的不同节点。如果未设置，则数据聚合将基于容器 ID 进行（如果受监视的应用程序在容器中运行）。否则，数据聚合将基于报告的主机名进行（自动发现或使用 hostname 手动配置）。

`service_version`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SERVICE_VERSION`	`elastic_apm.service_version`

默认值	类型
无	字符串

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

`span_compression_enabled`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SPAN_COMPRESSION_ENABLED`	`elastic_apm.span_compression_enabled`

默认值	类型
true	布尔值

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

`span_compression_exact_match_max_duration`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SPAN_COMPRESSION_EXACT_MATCH_MAX_DURATION`	`elastic_apm.span_compression_exact_match_max_duration`

默认值	类型
`50ms`	持续时间

如果连续的 span 完全匹配并且低于此阈值，则它们将被压缩为单个复合 span。此选项不适用于复合 span。这减少了收集、处理和存储开销，并消除了 UI 中的混乱。其缺点是，不会收集所有压缩 span 的数据库语句。

由于它是最大持续时间阈值设置，因此将此配置选项设置为 0 实际上会禁用此压缩策略，因为只有持续时间为 0 的 span 才会被视为符合此策略的压缩条件。

此配置选项支持以下持续时间后缀：ms、s 和 m。例如：10ms。此选项的默认单位是 ms，因此 5 将被解释为 5ms。

`span_compression_same_kind_max_duration`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SPAN_COMPRESSION_SAME_KIND_MAX_DURATION`	`elastic_apm.span_compression_same_kind_max_duration`

默认值	类型
`0ms`	持续时间

如果连续的 span 指向同一目标并且低于此阈值，则它们将被压缩为单个复合 span。此选项不适用于复合 span。这减少了收集、处理和存储开销，并消除了 UI 中的混乱。其缺点是，不会收集所有压缩 span 的数据库语句。

此配置选项支持以下持续时间后缀：ms、s 和 m。例如：10ms。此选项的默认单位是 ms，因此 5 将被解释为 5ms。

`span_stack_trace_min_duration`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION`	`elastic_apm.span_stack_trace_min_duration`

默认值	类型
`5ms`	持续时间

虽然将堆栈跟踪附加到 span 可能非常有用，但收集堆栈跟踪确实会产生一些开销。此配置控制收集堆栈跟踪的最小 span 持续时间。值越高意味着开销越低，因为会跳过快速 span 的堆栈跟踪收集。

将此配置设置为

任何正值（例如 5ms） - 将堆栈跟踪收集限制为持续时间等于或大于给定值的 span（例如，5 毫秒）
0（或带有任何持续时间单位的 0，例如 0ms） - 收集任何持续时间的 span 的堆栈跟踪
任何负值（例如 -1ms） - 完全禁用 span 的堆栈跟踪收集

此配置选项支持以下持续时间后缀：ms、s 和 m。例如：10ms。此选项的默认单位是 ms，因此 5 将被解释为 5ms。

`stack_trace_limit`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_STACK_TRACE_LIMIT`	`elastic_apm.stack_trace_limit`

默认值	类型
`50`	整数

此选项控制代理捕获的堆栈跟踪中包含的帧数。

将此配置设置为

任何正整数 - 定义堆栈跟踪中包含的最大帧数
0 - 禁用堆栈跟踪捕获
任何负整数 - 捕获所有帧

`transaction_ignore_urls`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_TRANSACTION_IGNORE_URLS`	`elastic_apm.transaction_ignore_urls`

默认值	类型
空列表	通配符表达式列表

此选项指示代理通过不为这些请求创建事务来忽略具有某些 URL 的请求。它只会影响代理自动创建事务，但用户仍然可以使用代理的公共 API手动创建事务。

有关如何使用通配符表达式的更多详细信息，请参阅通配符部分。

`transaction_max_spans`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_TRANSACTION_MAX_SPANS`	`elastic_apm.transaction_max_spans`

默认值	类型
500	整数

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

如果值为 0，则不会收集任何 span。

负值无效，将导致使用默认值。

`transaction_sample_rate`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_TRANSACTION_SAMPLE_RATE`	`elastic_apm.transaction_sample_rate`

默认值	类型
1.0	浮点数

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

`verify_server_cert`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_VERIFY_SERVER_CERT`	`elastic_apm.verify_server_cert`

默认值	类型
`true`	布尔值

默认情况下，如果您使用与 APM 服务器的 HTTPS 连接，则代理会验证 SSL 证书。可以通过将此设置更改为 false 来禁用验证。

`url_groups`

编辑

环境变量名称	`php.ini` 中的选项名称
`ELASTIC_APM_URL_GROUPS`	`elastic_apm.url_groups`

默认值	类型
空列表	通配符表达式列表

使用此选项，您可以使用通配符表达式（如 /user/*）将多个 URL 路径分组在一起 - 这样 /user/Alice 和 /user/Bob 将映射到事务名称 /user/*。

有关如何使用通配符表达式的更多详细信息，请参阅通配符部分。

« 配置公共 API »