配置

为了让 Elastic APM 探针适应您的需求，可以通过环境变量或框架特定的配置进行设置。

您可以通过设置环境变量来配置探针

ELASTIC_APM_SERVICE_NAME=foo python manage.py runserver
		

或者通过内联（inline）配置

apm_client = Client(service_name="foo")
		

或者使用框架特定的配置，例如在您的 Django settings.py 文件中

ELASTIC_APM = {
    "SERVICE_NAME": "foo",
}
		

优先级如下

• 集中配置（受支持的选项标记有 ）
• 环境变量
• 内联配置
• 框架特定配置
• 默认值

标记有 徽章的配置选项可以在运行时从受支持的源设置时更改。

Python 探针支持 集中配置，这允许您在 APM 应用中微调某些配置。此功能在探针中通过 central_config 默认启用。

要配置 Django，请在您的 settings.py 中添加一个 ELASTIC_APM 字典

ELASTIC_APM = {
    'SERVICE_NAME': 'my-app',
    'SECRET_TOKEN': 'changeme',
}
		

要配置 Flask，请在您的 app.config 中添加一个 ELASTIC_APM 字典

app.config['ELASTIC_APM'] = {
    'SERVICE_NAME': 'my-app',
    'SECRET_TOKEN': 'changeme',
}

apm = ElasticAPM(app)
		

您的服务名称。这用于将服务的所有错误和事务汇总在一起，是 Elastic APM 用户界面中的主要过滤器。

虽然提供了默认值，但必须使用在整个基础架构中更具描述性且唯一的名称来覆盖此默认值。

APM Server 的 URL。URL 必须是完全限定的，包括协议（http 或 https）和端口。注意：如果您在 AWS Lambda 函数中使用 APM，请勿设置此项。APM 探针被设计为通过 Lambda 扩展代理其到 APM Server 的调用。相反，请设置 ELASTIC_APM_LAMBDA_APM_SERVER。有关更多信息，请参阅 AWS Lambda。

启用或禁用探针。当设置为 false 时，探针将不会收集任何数据或启动任何后台线程。

启用或禁用事件记录。如果设置为 false，Python 探针不会向 Elastic APM Server 发送任何事件，且插桩开销被降至最低。探针将继续轮询服务器以获取配置更改。

elasticapm 记录器将记录的 logging.logLevel。可用选项包括

• "off"（将 logging.logLevel 设置为 1000）
• "critical" (严重)
• "error" (错误)
• "warning" (警告)
• "info" (信息)
• "debug" (调试)
• "trace"（将 logging.log_level 设置为 5）

选项不区分大小写

请注意，此选项不处理日志处理器 (handlers)。为了使任何日志可见，您必须配置处理器（logging.basicConfig 会为您完成此操作）或设置 log_file。这也会覆盖您的应用为 elasticapm 记录器设置的任何日志级别。

这使探针能够记录到文件。默认情况下禁用此项。探针将按照使用 log_level 配置的 logging.logLevel 进行记录。使用 log_file_size 配置日志文件的最大容量。此日志文件会自动轮转。

请注意，必须设置 log_level 才能使此设置生效。

如果安装了 ecs_logging，日志将自动格式化为兼容 ECS 的 JSON。

如果设置了 log_file，则表示日志文件的大小。

探针在轮转时始终保留一个备份文件，因此日志文件将消耗的最大空间是此设置值的两倍。

有效选项

• "off"
• "override" (覆盖)

如果安装了 ecs_logging，将其设置为 "override" 将使探针自动尝试启用 ECS 格式的日志记录。

对于标准库的基础 logging，探针将获取根记录器，找到任何附加的处理器，并将每个处理器的格式化程序设置为 ecs_logging.StdlibFormatter()。

如果安装了 structlog，探针将使用 ecs_logging.StructlogFormatter() 覆盖任何已配置的处理器。

请注意，这是一种非常强硬的手段，可能会产生意想不到的副作用。如果出现问题，请手动应用这些格式化程序并将此设置保留为 "off"。有关使用这些格式化程序的更多信息，请参阅 ecs_logging 文档。

另请注意，此设置并不有助于将日志发送到 Elasticsearch。我们建议使用 Filebeat 来实现该目的。

向 APM Server 发送事件时使用的传输类。

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

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

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

环境允许您在 APM 应用的全域级别轻松过滤数据。跨 Agent 命名环境时保持一致非常重要。有关更多信息，请参阅 APM 应用中的环境选择器。

此配置值允许您指定在收集元数据时应假设哪家云服务提供商。默认情况下，探针将尝试检测云提供商，如果检测失败，将通过反复试验来收集元数据。

有效选项为 "auto"、"aws"、"gcp" 和 "azure"。如果此配置值设置为 "none"，则不会收集云元数据。

此字符串用于确保只有您的探针可以向 APM Server 发送数据。探针和 APM Server 都必须配置相同的秘密令牌。生成安全秘密令牌的一个示例如下

python -c "import secrets; print(secrets.token_urlsafe(32))"
		

此 base64 编码的字符串用于确保只有您的探针可以向 APM Server 发送数据。API 密钥可以在 应用程序 UI 中创建。

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

所用框架的名称。对于 Django 和 Flask，默认为 django 和 flask，否则默认为 None。

所用框架的版本号。对于 Django 和 Flask，默认为框架的使用版本，否则默认为 None。

要过滤的异常类型列表。这些类型的异常将不会发送到 APM Server。

探针不应为其捕获任何事务数据的 URL 列表。

可选地，可以使用 * 一次匹配多个 URL。

正则表达式列表。事务名称如果匹配配置的任何模式，将被忽略且不会发送到 APM Server。

APM Server 请求的超时时间。该设置必须以 持续时间格式 提供。如果对 APM Server 的请求时长超过配置的超时时间，则取消该请求并丢弃事件（异常或事务）。设置为 None 可禁用超时。

向 APM Server 发送错误和事务数据时使用的主机名。

如果设置为 True（默认值），探针将向每个日志事件添加堆栈跟踪，指示日志消息发出的位置。

通过设置 extra 键中的 stack，可以单独覆盖此设置。

logger.info('something happened', extra={'stack': False})
		

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

Elastic APM Python 探针可以为堆栈帧收集局部变量。默认情况下，仅对错误执行此操作。

收集局部变量时，它们将被转换为字符串。此设置允许您限制生成的字符串长度。

此设置允许您限制局部变量中列表的长度。

此设置允许您限制局部变量中字典 (dict) 的长度。

默认情况下，APM 探针会收集错误的源代码片段。此设置允许您修改正在收集的源代码行数。

我们区分错误和跨度 (spans)，以及库帧 (library frames) 和应用帧 (app frames)。

对于属于 HTTP 请求的事务，Python 探针可以选择捕获请求体（例如 POST 变量）。

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

如果请求有正文且禁用了此设置，正文将显示为 [REDACTED]。

对于内容类型为 multipart/form-data 的请求，任何上传的文件都将在一个特殊的 _files 键中引用。它包含字段名称和上传文件的名称（如果提供了）。

对于因 HTTP 请求而发生的事务和错误，Python 探针可以选择捕获请求和响应头。

可能的值：true、false

这限制了每个事务记录的跨度数量。这在事务创建极大量跨度（例如数千条 SQL 查询）的情况下很有帮助。设置上限将防止边缘情况使探针和 APM Server 过载。

这限制了每个堆栈跟踪捕获的帧数。

将限制设置为 0 将禁用堆栈跟踪收集，而任何正整数值将用作收集的最大帧数。要禁用限制并始终捕获所有帧，请将值设置为 -1。

默认情况下，APM 探针会为每个持续时间等于或长于此配置阈值的记录跨度收集堆栈跟踪。虽然堆栈跟踪对于查找代码中产生跨度的确切位置非常有帮助，但收集堆栈跟踪确实会产生一些开销。调整此阈值以确保仅为可能存在问题的跨度收集堆栈跟踪。

要为所有跨度收集跟踪，无论其长度如何，请将值设置为 0。

要完全禁用跨度的堆栈跟踪收集，请将值设置为 -1。

除了特殊值 -1 和 0 外，该设置应以 持续时间格式 提供。

启用/禁用跨度压缩。

如果启用，探针会将非常短的重复跨度压缩为单个跨度，这有利于存储和处理。在此过程中会丢失一些信息，例如每个压缩跨度的确切持续时间。

完全匹配且低于此阈值的连续跨度将被压缩为单个复合跨度。这减少了收集、处理和存储开销，并消除了 UI 的杂乱。权衡是不会收集所有被压缩跨度的数据库语句。

如果以下属性相同，则两个跨度被视为完全匹配：* 跨度名称 * 跨度类型 * 跨度子类型 * 目标资源（例如数据库名称）

前往相同目标且低于此阈值的连续跨度将被压缩为单个复合跨度。这减少了收集、处理和存储开销，并消除了 UI 的杂乱。权衡是不会收集元数据（如所有被压缩跨度的数据库语句）。

如果以下属性相同，则两个跨度被视为同一种类：* 跨度类型 * 跨度子类型 * 目标资源（例如数据库名称）

出口跨度 (Exit spans) 是表示调用外部服务（如数据库）的跨度。如果此类调用非常短，通常无关紧要，可以忽略。

此功能默认禁用。

发送请求到 APM Server 前请求缓冲区的最大队列长度。较低的值会增加 APM Server 的负载，而较高的值会增加应用的内存压力。较高的值还会影响数据在 Elasticsearch 中被索引和可搜索的时间。

此设置对于限制流量突然激增时的内存消耗非常有用。必须以 大小格式 提供。

向 APM Server 发送请求前请求缓冲区的最大队列时间。较低的值会增加 APM Server 的负载，而较高的值会增加应用的内存压力。较高的值还会影响数据在 Elasticsearch 中被索引和可搜索的时间。

此设置对于限制流量突然激增时的内存消耗非常有用。必须以 持续时间格式 提供。

用于处理事务和错误的处理器列表。有关更多信息，请参阅 数据脱敏 (Sanitizing Data)。

使用处理器时，要匹配和掩盖的 glob 模式字段名称列表。有关更多信息，请参阅 数据脱敏 (Sanitizing Data)。

默认情况下，探针会采样每个事务（例如，向您的服务发送的请求）。为了减少开销和存储需求，请将采样率设置为 0.0 到 1.0 之间的值。我们仍然会记录未采样事务的总时间和结果，但不会记录上下文信息、标签或跨度。

一组路径，可选地使用 shell glob（语法描述见 fnmatch）。这些将与每个帧的绝对文件名进行匹配，如果模式匹配，则该帧被认为是“应用内帧”。

include_paths 优先于 exclude_paths。

一组路径，可选地使用 shell glob（语法描述见 fnmatch）。这些将与每个帧的绝对文件名进行匹配，如果模式匹配，则该帧被认为是“库帧”。

include_paths 优先于 exclude_paths。

默认值取决于您的 Python 版本和实现，例如

• PyPy3：['\*/lib-python/3/*', '\*/site-packages/*']
• CPython 2.7：['\*/lib/python2.7/*', '\*/lib64/python2.7/*']

如果您的应用处于调试模式（例如在 Django 中 settings.DEBUG = True 或在 Flask 中 app.debug = True），探针将不会向 APM Server 发送任何数据。您可以通过将此设置更改为 True 来覆盖它。

如果设置为 True，探针将不会向 APM Server 发送任何事件，无论调试状态如何。

如果设置为 False，探针将不会对任何代码进行插桩。这会禁用大部分跟踪功能，但对于调试可能的插桩问题很有用。

默认情况下，如果使用 HTTPS 连接到 APM Server，探针会验证 SSL 证书。可以通过将此设置更改为 False 来禁用验证。当设置了 server_cert 时，此设置会被忽略。

如果您为 APM Server 配置了自签名 TLS 证书，或者您只是希望锁定 (pin) 服务器证书，则可以通过 ELASTIC_APM_SERVER_CERT 配置指定 PEM 编码证书的路径。

默认情况下，探针将使用由 Mozilla 策划并由 certifi 包提供的知名 CA 验证 APM Server 的 TLS/SSL 证书。

您可以将此选项设置为包含将替代使用的 CA 证书文件的路径。

使用自签名证书时必须指定此选项，除非禁用了服务器证书验证。

默认情况下，Python 探针使用 certifi 证书库。要使用 Python 的默认证书查找机制，请将此选项设置为 False。

探针收集指标的时间间隔。较短的间隔会增加指标的粒度，但也会增加探针的开销以及存储需求。

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

不应发送到 APM Server 的点分指标名称的逗号分隔列表。您可以使用 * 匹配多个指标；例如，要禁用所有与 CPU 相关的指标以及“系统总内存”指标，请将 disable_metrics 设置为

"*.cpu.*,system.memory.total"
		

启用或禁用细分指标 (breakdown metrics) 的跟踪和收集。将其设置为 False 会禁用细分指标的跟踪，从而减少探针开销。

启用/禁用来自 prometheus_client 的指标跟踪和收集。

有关更多信息，请参阅 Prometheus 指标集（测试版）。

添加到 Prometheus 指标名称前面的前缀。

有关更多信息，请参阅 Prometheus 指标集（测试版）。

用于收集指标的 MetricSets 的导入路径列表。

有关更多信息，请参阅 自定义指标。

启用后，探针将定期向 APM Server 发送请求以获取更新的配置。

有关更多信息，请参阅 动态配置。

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

在 Python 3 中，探针默认安装一个 LogRecord factory，它会自动将跟踪字段添加到您的日志记录中。通过将此项设置为 True 来禁用此行为。

为了启用 分布式跟踪，探针对使用 插桩的 HTTP 库 发出的传出请求设置了一些 HTTP 头。这些头（traceparent 和 tracestate）在 W3C Trace Context 规范中定义。

此外，当此设置设为 True 时，探针将设置 elasticapm-traceparent 以实现向后兼容。

此选项允许控制 APM 探针如何处理传入请求中的 W3C trace-context 标头。默认情况下，按照 W3C 规范使用 traceparent 和 tracestate 标头进行分布式追踪。但在某些情况下，不使用传入的 traceparent 标头会有所帮助。一些示例用例

• 一个受 Elastic 监控的服务收到来自未监控服务的带有 traceparent 标头的请求。
• 受 Elastic 监控的服务公开在公网上，并且不希望追踪数据（trace-id、采样决定）可能被用户请求伪造。

有效值为：

• 'continue'：默认行为。使用传入的 traceparent 值来继续追踪并确定采样决策。
• 'restart'：始终忽略传入请求的 traceparent 标头。将生成一个新的 trace-id，并根据 transaction_sample_rate 做出采样决策。将创建一个跨度链接 (span link) 指向传入的 traceparent。
• 'restart_external'：如果传入请求在 tracestate 中包含 es 供应商标志，则任何 traceparent 都将被视为内部并按上述 'continue' 处理。否则，任何 'traceparent' 都被视为外部并按上述 'restart' 处理。

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

如果设置为 True，探针将拦截默认的 sys.excepthook，这允许探针收集所有未捕获的异常。

每个事务是否应附加进程参数。默认禁用以节省磁盘空间。

是否应跳过服务器信息检查，以便在 AWS Lambda 等受限环境中减少一些延迟。默认禁用。

默认情况下，我们使用视图的函数或类名作为事务名称。从 Django 2.2 开始，Django 在 request.resolver_match 对象上提供路由（例如 users/<int:user_id>/）。如果您想使用路由而不是视图名称作为事务名称，请将此配置选项设置为 true。

为了追踪 Django 请求，探针使用了一个中间件 elasticapm.contrib.django.middleware.TracingMiddleware。默认情况下，此中间件自动插入为 settings.MIDDLEWARES 中的第一项。要禁用中间件的自动插入，请将此设置更改为 False。

一些非 APM 探针特有的环境变量也可以用于配置探针。

通过使用 HTTP_PROXY 和 HTTPS_PROXY，可以指示探针使用代理连接到 APM Server。如果两者都设置了，HTTPS_PROXY 优先。

要指示探针不使用代理，可以使用 NO_PROXY 环境变量。您可以将其设置为不应使用代理的主机逗号分隔列表（例如 localhost,example.com），或使用 * 匹配任何主机。

如果 HTTP_PROXY / HTTPS_PROXY 是出于探针/APM Server 通信以外的其他原因而设置的，则此操作非常有用。

要告诉探针使用不同的 SSL 证书，可以使用这些环境变量。另见 OpenSSL 文档。

请注意，这些变量可能会应用于您服务中的其他 SSL/TLS 通信，而不仅仅是与 APM 探针相关的通信。

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

持续时间格式用于超时等选项。单位作为后缀紧跟在数字后面——不带任何空格分隔。

示例: 5ms

支持的单位

• us (微秒)
• ms (毫秒)
• s (秒)
• m (分钟)

大小格式用于最大缓冲区大小等选项。单位作为后缀紧跟在数字后面，不带任何空格分隔。

示例: 10kb

支持的单位:

• b (字节)
• kb (千字节)
• mb (兆字节)
• gb (吉字节)