›

配置

配置编辑

有几种方法可以配置 Elastic APM 的行为。我们建议使用 config/elastic_apm.yml 文件

server_url: 'https://127.0.0.1:8200'
secret_token: <%= ENV["VERY_SECRET_TOKEN"] %>

一些选项可以通过 ENV 变量设置。使用此方法时，字符串将以逗号分隔，例如，ELASTIC_APM_SANITIZE_FIELD_NAMES="a,b" # => [/a/, /b/]。

配置优先级编辑

选项按以下顺序应用（最后一个优先）：

默认值
传递给 ElasticAPM.start / Config.new 的参数
配置文件，例如 config/elastic_apm.yml
环境变量
集中式配置（支持的选项用标记）

动态配置编辑

用 dynamic config 徽章标记的配置选项可以在运行时从支持的来源设置时更改。

代理支持集中式配置，允许您通过 APM 应用程序微调某些配置。此功能在代理中默认启用，使用 central_config。

Ruby on Rails编辑

使用 Rails 时，可以在 config/application.rb 中指定选项

# config/application.rb
config.elastic_apm.service_name = 'MyApp'

Sinatra 和 Rack编辑

使用 Sinatra 和 Rack 时，您可以在启动代理时进行配置

# config.ru or similar
ElasticAPM.start(
  app: MyApp,
  service_name: 'SomeOtherName'
)

或者，使用 ElasticAPM::Sinatra.start API

# config.ru or similar
ElasticAPM::Sinatra.start(
  MyApp,
  service_name: 'SomeOtherName'
)

请参阅 Rack 入门。

Grape 和 Rack编辑

使用 Grape 和 Rack（不使用 Rails）时，在启动代理时进行配置

# config.ru or similar
ElasticAPM::Grape.start(
  MyApp,
  service_name: 'SomeOtherName'
)

请参阅 Rack 入门。

选项编辑

`config_file`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CONFIG_FILE`	`config_file`	`config/elastic_apm.yml`

配置 YAML 文件的路径。如果文件存在，Elastic APM 将从该文件加载配置选项。该文件将被评估为 ERB，因此您可以像在 database.yml 中一样包含 ENV 变量，例如

secret_token: <%= ENV['VERY_SECRET_TOKEN'] %>

`server_url`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_SERVER_URL`	`server_url`	`'https://127.0.0.1:8200'`

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

`secret_token`编辑

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SECRET_TOKEN`	`secret_token`	`nil`	随机字符串

此字符串用于确保只有您的代理可以向您的 APM 服务器发送数据。代理和 APM 服务器都必须配置为使用相同的密钥。以下是一个生成安全密钥的示例

ruby -r securerandom -e 'print SecureRandom.uuid'

只有当您的 APM 服务器使用 TLS 时，密钥才能提供真正的安全性。

`api_key`编辑

环境	`Config` 键	默认值	示例
`ELASTIC_APM_API_KEY`	`api_key`	`nil`	一个 base64 编码的字符串

此 base64 编码的字符串用于确保只有您的代理可以向您的 APM 服务器发送数据。API 密钥必须使用 APM 服务器命令行工具创建。

只有当您的 APM 服务器使用 TLS 时，API 密钥才能提供真正的安全性。

`api_buffer_size`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_API_BUFFER_SIZE`	`api_buffer_size`	`256`

在发送到 APM 服务器之前，队列中保留的最大对象数量。

如果达到限制，请考虑增加代理的工作池大小。如果没有，代理可能无法连接到 APM 服务器。日志应该会告诉你出了什么问题。

`api_request_size`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_API_REQUEST_SIZE`	`api_request_size`	`"750kb"`

发送到 APM 服务器的单个请求的最大字节数。当达到此限制时，代理将打开一个新的请求。

这必须以 大小格式 提供。

`api_request_time`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_API_REQUEST_TIME`	`api_request_time`	`"10s"`

向 APM 服务器发送单个流式请求的最大持续时间，在打开新的请求之前。

APM 服务器有自己的 30 秒限制，在此之后它将关闭请求。这必须以 持续时间格式 提供。

`breakdown-metrics`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_BREAKDOWN_METRICS`	`breakdown_metrics`	`true`

启用或禁用细分指标的跟踪和收集。将其设置为 False 将禁用细分指标的跟踪，这可以减少代理的开销。

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

`capture_body`编辑

环境	`Config` 键	默认值	示例
`ELASTIC_APM_CAPTURE_BODY`	`capture_body`	`"off"`	`"all"`

Ruby 代理可以选择捕获作为 HTTP 请求的事务的请求主体（例如 POST 变量或 JSON 数据）。

可能的值："errors"、"transactions"、"all"、"off"。

如果请求有主体并且此设置被禁用，则主体将显示为 [SKIPPED]。

请求主体通常包含敏感值，如密码和信用卡号。我们尝试从表单主体中删除看起来敏感的数据，但不会触碰 JSON 等文本主体。如果您的服务处理此类数据，我们建议您谨慎启用此功能。

`capture_headers`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CAPTURE_HEADERS`	`capture_headers`	`true`

这表示是否将请求标头附加到事务和错误。

`capture_elasticsearch_queries`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CAPTURE_ELASTICSEARCH_QUERIES`	`capture_elasticsearch_queries`	`false`

这表示是否捕获 Elasticsearch 中请求的正文。

`capture_env`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CAPTURE_ENV`	`capture_env`	`true`

这表示是否将 ENV 从 Rack 附加到事务和错误。

`central_config`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CENTRAL_CONFIG`	`central_config`	`true`

这将启用通过 Kibana 进行 APM 代理配置。如果设置为 true，客户端将定期轮询 APM 服务器以获取新的代理配置。

通常 APM 服务器决定轮询频率，但如果没有，则默认间隔为 5 分钟。

此功能需要 APM Server v7.3 或更高版本，并且 APM Server 必须配置为 kibana.enabled: true。

`cloud_provider`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_CLOUD_PROVIDER`	`cloud_provider`	`"auto"`

指定用于元数据收集的云提供商。这默认为 "auto"，这意味着代理使用试错法从所有支持的云提供商收集元数据。

有效选项为 "auto"、"aws"、"gcp"、"azure" 和 "none"。如果设置为 "none"，则不会收集任何云元数据。如果设置为 "aws"、"gcp" 或 "azure" 中的任何一个，则只会尝试从所选提供商收集元数据。

`disable_metrics`编辑

环境	`Config` 键	默认值	示例
`ELASTIC_APM_DISABLE_METRICS`	`disable_metrics`	[]	`".cpu.,system.memory.total"`

一个以逗号分隔的点分隔指标名称列表，这些名称不应发送到 APM 服务器。可以使用 * 来匹配多个指标。匹配不区分大小写。

`disable_send`编辑

环境	`Config` 键	默认值
`ELASTIC_APM_DISABLE_SEND`	`disable_send`	`false`

禁用将有效负载发送到 APM 服务器。

`disable_start_message`edit

环境	`Config` 键	默认值
`ELASTIC_APM_DISABLE_START_MESSAGE`	`disable_start_message`	`false`

禁用代理启动消息，该消息会宣布代理本身。

`disable_instrumentations`edit

环境	`Config` 键	默认值
`ELASTIC_APM_DISABLE_INSTRUMENTATIONS`	`disable_instrumentations`	`['json']`

Elastic APM 会自动检测选定的第三方库。使用此选项禁用任何这些库。

使用 ElasticAPM.agent.config.enabled_instrumentations 获取已启用检测的数组。

`enabled`edit

环境	`Config` 键	默认值
`ELASTIC_APM_ENABLED`	`enabled`	`true`

指示是否启动代理。如果 enabled 为 false，则 ElasticAPM.start 不会执行任何操作，并且对根 API 的所有调用都将返回 nil。

`environment`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_ENVIRONMENT`	`environment`	来自 `ENV`	`"production"`

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

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

默认为 ENV['RAILS_ENV'] || ENV['RACK_ENV']。

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

`filter_exception_types`edit

环境	`Config` 键	默认值	示例
N/A	`filter_exception_types`	`[]`	`[MyApp::Errors::IgnoredError]`

使用此选项过滤特定错误常量的错误跟踪。

`framework_name`edit

环境	`Config` 键	默认值
`ELASTIC_APM_FRAMEWORK_NAME`	`framework_name`	取决于框架

所用框架的名称。对于 Rails 或 Sinatra，这默认为 Ruby on Rails 和 Sinatra，否则默认为 nil。

`framework_version`edit

环境	`Config` 键	默认值
`ELASTIC_APM_FRAMEWORK_VERSION`	`framework_version`	取决于框架

所用框架的版本号。对于 Ruby on Rails 和 Sinatra，这默认为所用框架的版本，否则，默认为 nil。

`global_labels`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_GLOBAL_LABELS`	`global_labels`	`nil`	`dept=engineering,rack=number8`

添加到所有事件的标签，格式为 key=value[,key=value[,…]]。

此选项需要 APM Server 7.2 或更高版本，在使用旧版服务器版本时将不起作用。

`hostname`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_HOSTNAME`	`hostname`	`hostname`	`app-server01.example.com`

将错误和事务数据发送到 APM 服务器时要使用的主机名。

`ignore_url_patterns`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_IGNORE_URL_PATTERNS`	`ignore_url_patterns`	`[]`	`['^/ping', %r{^/admin}]`

使用此选项忽略某些 URL 模式，例如运行状况检查或管理部分。

在此上下文中，“忽略”意味着“不要包装在事务中”。仍然会报告错误。

通过 ENV 设置此选项时，请使用逗号分隔的字符串。例如 ELASTIC_APM_IGNORE_URL_PATTERNS="a,b" # => [/a/, /b/]

`instrument`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_INSTRUMENT`	`instrument`	`true`	`0`

使用此选项忽略某些 URL 模式，例如运行状况检查或管理部分。

`instrumented_rake_tasks`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_INSTRUMENTED_RAKE_TASKS`	`instrumented_rake_tasks`	`[]`	`['my_task']`

Elastic APM 可以检测您的 Rake 任务。这是一个选择性字段，因为它们用于多种用途。

`log_ecs_reformatting`edit

环境	`Config` 键	默认值
`ELASTIC_APM_LOG_ECS_REFORMATTING`	`log_ecs_reformatting`	`off`

这是一个实验性选项，它配置代理以使用 ecs-logging gem 中的记录器。两个有效选项是 off 和 override。

将此选项设置为 override 将将代理记录器设置为 EcsLogging::Logger 实例，并且所有记录的输出都将以与 ECS 兼容的 json 格式。

必须在启动代理之前安装 ecs-logging gem。如果 log_ecs_reformatting 设置为 override，代理将尝试需要该 gem，如果无法加载，它将回退到使用标准 Ruby ::Logger 并记录加载错误。

请注意，如果您使用的是 Rails，代理将忽略此选项并使用 Rails 记录器。如果您想在使用 Rails 时使用 EcsLogging::Logger，请将代理的记录器配置选项显式设置为 EcsLogging::Logger 实例。

`log_level`edit

环境	`Config` 键	默认值
`ELASTIC_APM_LOG_LEVEL`	`log_level`	`Logger::INFO # => 1`

默认情况下，Elastic APM 记录到 stdout 或在与 Rails 一起使用时使用 Rails.log。

`log_path`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_LOG_PATH`	`log_path`	`nil`	`log/elastic_apm.log`

日志文件的路径。

默认情况下，Elastic APM 记录到 stdout 或在与 Rails 一起使用时使用 Rails.log。

如果指定了 log_path，这将覆盖 Rails.log 以指向该路径。

这应该支持绝对路径和相对路径。请确保目录存在。

`logger`edit

环境	`Config` 键	默认值	示例
N/A	`logger`	取决于	`Logger.new('path/to_file.log')`

默认情况下，Elastic APM 记录到 stdout 或在与 Rails 一起使用时使用 Rails.log。

使用此选项提供另一个记录器。这应该与 Ruby 的内置 Logger 具有相同的 API。

`metrics_interval`edit

环境	`Config` 键	默认值
`ELASTIC_APM_METRICS_INTERVAL`	`metrics_interval`	`'30s'`

指定向 APM Server 报告指标的间隔。间隔应以秒为单位，或包含时间后缀。

要禁用指标报告，请将间隔设置为 0。

`pool_size`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_POOL_SIZE`	`pool_size`	`1`	`2`

Elastic APM 使用线程池将数据发送到 APM Server。

这确保代理不会比必要时更多地阻塞主线程。

如果您负载很高并且收到有关缓冲区已满的警告，增加工作线程池大小可能会有所帮助。

`proxy_address`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_PROXY_ADDRESS`	`proxy_address`	`nil`	`"example.com"`

用作 HTTP 客户端代理的地址。

可用的选项是

proxy_address
proxy_headers
proxy_password
proxy_port
proxy_username

还有 ENV 版本，它们遵循相同的模式，在前面添加 ELASTIC_APM_。

请参阅 Http.rb 的文档。

`recording`edit

环境	`Config` 键	默认值
`ELASTIC_APM_RECORDING`	`recording`	`true`

启用或禁用事件的记录。如果设置为 false，则代理不会创建或发送任何事件到 Elastic APM 服务器，并且检测开销将降至最低。当此选项为 false 时，代理将继续轮询服务器以获取配置更改。

`sanitize_field_names`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SANITIZE_FIELD_NAMES`	`sanitize_field_names`	`"password,passwd,pwd,secret,key,token,session,credit,card,auth*,set-cookie"`	`Authtion,abc,*xyz`

有时需要对发送到 Elastic APM 的数据进行清理，以删除敏感值。

配置要清理的字段名称的通配符模式列表。这些模式适用于 HTTP 标头和正文（如果它们正在被捕获）。

支持通配符 *，它匹配零个或多个字符。示例：/foo/*/bar/*/baz*、*foo*。匹配不区分大小写。

`service_name`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SERVICE_NAME`	`service_name`	应用程序的名称	`MyApp`

您服务的名称。这用于对您服务的错误和事务进行分组，并且是 Elastic APM 用户界面中的主要过滤器。

如果您使用的是 Ruby on Rails，这将默认为您的应用程序的名称。如果您使用的是 Sinatra，这将默认为您的应用程序类的名称。

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

`service_node_name`edit

[options="header"]

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SERVICE_NODE_NAME`	`service_node_name`	`nil`	`"my-app-1"`

指定的服务节点名称。此选项可选，如果省略，APM Server 将回退到 system.container.id（如果可用）和 host.name（如果需要）。

此选项允许您手动设置节点名称，以确保其唯一且有意义。

`service_version`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SERVICE_VERSION`	`service_version`	`git` sha	指示已部署服务的版本的字符串

已部署服务的版本。默认值为 git rev-parse --verify HEAD。

`source_lines_error_app_frames`edit

`source_lines_error_library_frames`edit

`source_lines_span_app_frames`edit

`source_lines_span_library_frames`edit

环境	`Config` 键	默认值
`ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES`	`source_lines_error_app_frames`	`5`
`ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES`	`source_lines_error_library_frames`	`5`
`ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES`	`source_lines_span_app_frames`	`0`
`ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES`	`source_lines_span_library_frames`	`0`

默认情况下，APM 代理会收集错误的源代码片段。使用以上设置修改收集的源代码行数。

我们区分错误和跨度，以及库帧和应用程序帧。

特别是对于跨度，收集源代码会对 Elasticsearch 集群中的存储使用量产生重大影响。

`span_frames_min_duration`edit

环境	`Config` 键	默认值
`ELASTIC_APM_SPAN_FRAMES_MIN_DURATION`	`span_frames_min_duration`	`"5ms"`

使用此选项禁用对持续时间小于或等于给定毫秒数的跨度的堆栈跟踪帧收集。

默认值为 "5ms"。

将其设置为 -1 以收集所有跨度的堆栈跟踪。将其设置为 0 以禁用所有跨度的堆栈跟踪收集。

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

`server_ca_cert_file`edit

环境	`Config` 键	默认值	示例
`ELASTIC_APM_SERVER_CA_CERT_FILE`	`server_ca_cert_file`	`nil`	`'/path/to/ca.pem'`

连接到 APM Server 的自定义 CA 证书的路径。

`stack_trace_limit`edit

环境	`Config` 键	默认值
`ELASTIC_APM_STACK_TRACE_LIMIT`	`stack_trace_limit`	`999999`

每个跨度/错误的堆栈跟踪行数的最大值。

`transaction_max_spans`edit

环境	`Config` 键	默认值
`ELASTIC_APM_TRANSACTION_MAX_SPANS`	`transaction_max_spans`	`500`

限制每个事务记录的跨度数量。这在事务创建大量跨度（例如数千个 SQL 查询）的情况下很有用。设置上限将防止代理和 APM 服务器因此类边缘情况而超载。

`transaction_sample_rate`edit

环境	`Config` 键	默认值
`ELASTIC_APM_TRANSACTION_SAMPLE_RATE`	`transaction_sample_rate`	`1.0`

默认情况下，代理将对每个事务（例如对您服务的请求）进行采样。为了减少开销和存储需求，您可以将采样率设置为 0.0 和 1.0 之间的值。我们仍然会记录未采样事务的总时间和结果，但不会记录任何上下文信息、标签或跨度。采样率将四舍五入到小数点后 4 位。

`verify_server_cert`edit

环境	`Config` 键	默认值
`ELASTIC_APM_VERIFY_SERVER_CERT`	`verify_server_cert`	`true`

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

配置格式edit

某些选项需要一个单位，无论是持续时间还是大小。这些需要以特定格式提供。

持续时间格式edit

持续时间格式用于超时等选项。单位作为后缀直接在数字之后提供，没有任何空格分隔。

示例: "5ms"

支持的单位

ms（毫秒）
s（秒）
m（分钟）

大小格式edit

大小格式用于最大缓冲区大小等选项。单位作为后缀直接在数字之后提供，没有任何空格分隔。

示例: 10kb

支持的单位:

b（字节）
kb（千字节）
mb（兆字节）
gb（千兆字节）

我们使用 2 的幂大小约定，例如 1 千字节 == 1024 字节。

特殊配置edit

Elastic APM 修补了 Kernel#require 以自动检测和检测支持的第三方库。它以最大的谨慎执行此操作，但在极少数情况下，它可能会与某些库发生冲突。

要绕过此修补程序，请将环境变量 ELASTIC_APM_SKIP_REQUIRE_PATCH 设置为 "1"。

代理可能需要一些额外的调整才能确保拾取和检测第三方库。确保您在要求其他依赖项之后要求代理。

« 支持的技术高级主题 »

配置

配置编辑

配置优先级编辑

动态配置编辑

Ruby on Rails编辑

Sinatra 和 Rack编辑

Grape 和 Rack编辑

选项编辑

config_file编辑

server_url编辑

secret_token编辑

api_key编辑

api_buffer_size编辑

api_request_size编辑

api_request_time编辑

breakdown-metrics编辑

capture_body编辑

capture_headers编辑

capture_elasticsearch_queries编辑

capture_env编辑

central_config编辑

cloud_provider编辑

disable_metrics编辑

disable_send编辑

disable_start_messageedit

disable_instrumentationsedit

enablededit

environmentedit

filter_exception_typesedit

framework_nameedit

framework_versionedit

global_labelsedit

hostnameedit

ignore_url_patternsedit

instrumentedit

instrumented_rake_tasksedit

log_ecs_reformattingedit

log_leveledit

log_pathedit

loggeredit

metrics_intervaledit

pool_sizeedit

proxy_addressedit

recordingedit

sanitize_field_namesedit

service_nameedit

service_node_nameedit

service_versionedit

source_lines_error_app_framesedit

source_lines_error_library_framesedit

source_lines_span_app_framesedit

source_lines_span_library_framesedit

span_frames_min_durationedit

server_ca_cert_fileedit

stack_trace_limitedit

transaction_max_spansedit

transaction_sample_rateedit

verify_server_certedit

配置格式edit

持续时间格式edit

大小格式edit

特殊配置edit

`config_file`编辑

`server_url`编辑

`secret_token`编辑

`api_key`编辑

`api_buffer_size`编辑

`api_request_size`编辑

`api_request_time`编辑

`breakdown-metrics`编辑

`capture_body`编辑

`capture_headers`编辑

`capture_elasticsearch_queries`编辑

`capture_env`编辑

`central_config`编辑

`cloud_provider`编辑

`disable_metrics`编辑

`disable_send`编辑

`disable_start_message`edit

`disable_instrumentations`edit

`enabled`edit

`environment`edit

`filter_exception_types`edit

`framework_name`edit

`framework_version`edit

`global_labels`edit

`hostname`edit

`ignore_url_patterns`edit

`instrument`edit

`instrumented_rake_tasks`edit

`log_ecs_reformatting`edit

`log_level`edit

`log_path`edit

`logger`edit

`metrics_interval`edit

`pool_size`edit

`proxy_address`edit

`recording`edit

`sanitize_field_names`edit

`service_name`edit

`service_node_name`edit

`service_version`edit

`source_lines_error_app_frames`edit

`source_lines_error_library_frames`edit

`source_lines_span_app_frames`edit

`source_lines_span_library_frames`edit

`span_frames_min_duration`edit

`server_ca_cert_file`edit

`stack_trace_limit`edit

`transaction_max_spans`edit

`transaction_sample_rate`edit

`verify_server_cert`edit