›

配置

有几种方法可以配置 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
环境变量
中央配置（支持的选项标有）

动态配置

编辑

当从支持的源设置时，标有动态配置徽章的配置选项可以在运行时更改。

Agent 支持中央配置，允许您通过 APM 应用程序微调某些配置。默认情况下，此功能在 Agent 中启用，使用 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 服务器。必须使用 APM 服务器命令行工具创建 API 密钥。

仅当您的 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`

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

`central_config`

编辑

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

这将通过 Kibana 启用 APM Agent 配置。如果设置为 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`

编辑

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

这将禁用代理的启动消息，该消息会宣布自身。

`disable_instrumentations`

编辑

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

Elastic APM 会自动检测选择的第三方库。使用此选项可以禁用其中任何一个。

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

`enabled`

编辑

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

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

`environment`

编辑

环境	`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`

编辑

环境	`Config` 键	默认值	示例
不适用	`filter_exception_types`	`[]`	`[MyApp::Errors::IgnoredError]`

使用此选项可以筛选特定错误常量的错误跟踪。

`framework_name`

编辑

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

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

`framework_version`

编辑

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

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

`global_labels`

编辑

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

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

此选项需要 APM Server 7.2 或更高版本，并且在使用旧版本服务器时无效。

`hostname`

编辑

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

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

`ignore_url_patterns`

编辑

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

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

此处的忽略指的是不要将其包装在事务中。错误仍会报告。

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

`instrument`

编辑

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

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

`instrumented_rake_tasks`

编辑

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

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

`log_ecs_reformatting`

编辑

环境	`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`

编辑

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

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

`log_path`

编辑

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

日志文件的路径。

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

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

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

`logger`

编辑

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

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

使用此项可以提供其他记录器。此项应具有与 Ruby 内置 Logger 相同的 API。

`metrics_interval`

编辑

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

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

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

`pool_size`

编辑

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

Elastic APM 使用线程池将其数据发送到 APM 服务器。

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

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

`proxy_address`

编辑

环境	`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`

编辑

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

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

`sanitize_field_names`

编辑

环境	`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`

编辑

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

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

如果您使用的是 Ruby on Rails，则此项默认为您的应用名称。如果您使用的是 Sinatra，则此项默认为您的应用类的名称。

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

`service_node_name`

编辑

[options="header"]

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

给定服务节点的名称。这是可选的，如果省略，则 APM Server 将回退到 system.container.id （如果可用），并在必要时回退到 host.name。

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

`service_version`

编辑

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

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

环境	`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`

编辑

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

使用此项可禁用持续时间短于或等于给定毫秒数的跨度的堆栈跟踪框架收集。

默认值为 "5ms"。

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

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

`server_ca_cert_file`

编辑

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

用于连接到 APM 服务器的自定义 CA 证书的路径。

`stack_trace_limit`

编辑

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

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

`transaction_max_spans`

编辑

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

限制每个事务记录的跨度数量。这在事务创建大量跨度（例如，数千个 SQL 查询）的情况下很有帮助。设置上限将防止代理和 APM 服务器因针对此类极端情况的过多工作而过载。

`transaction_sample_rate`

编辑

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

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

`verify_server_cert`

编辑

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

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

配置格式

编辑

某些选项需要单位，即持续时间或大小。这些需要以特定格式提供。

持续时间格式

编辑

持续时间格式用于超时等选项。单位以后缀形式直接提供在数字之后，且不通过任何空格分隔。

示例: "5ms"

支持的单位

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

大小格式

编辑

大小格式用于最大缓冲区大小等选项。单位以后缀形式直接提供在数字之后，且不通过任何空格分隔。

示例: 10kb

支持的单位:

b （字节）
kb (千字节)
mb (兆字节)
gb (吉字节)

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

特殊配置

编辑

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_message

disable_instrumentations

enabled

environment

filter_exception_types

framework_name

framework_version

global_labels

hostname

ignore_url_patterns

instrument

instrumented_rake_tasks

log_ecs_reformatting

log_level

log_path

logger

metrics_interval

pool_size

proxy_address

recording

sanitize_field_names

service_name

service_node_name

service_version

source_lines_error_app_frames

source_lines_error_library_frames

source_lines_span_app_frames

source_lines_span_library_frames

span_frames_min_duration

server_ca_cert_file

stack_trace_limit

transaction_max_spans

transaction_sample_rate

verify_server_cert

配置格式

持续时间格式

大小格式

特殊配置

`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`

`disable_instrumentations`

`enabled`

`environment`

`filter_exception_types`

`framework_name`

`framework_version`

`global_labels`

`hostname`

`ignore_url_patterns`

`instrument`

`instrumented_rake_tasks`

`log_ecs_reformatting`

`log_level`

`log_path`

`logger`

`metrics_interval`

`pool_size`

`proxy_address`

`recording`

`sanitize_field_names`

`service_name`

`service_node_name`

`service_version`

`source_lines_error_app_frames`

`source_lines_error_library_frames`

`source_lines_span_app_frames`

`source_lines_span_library_frames`

`span_frames_min_duration`

`server_ca_cert_file`

`stack_trace_limit`

`transaction_max_spans`

`transaction_sample_rate`

`verify_server_cert`