配置

要使 Elastic APM 代理适应您的需求，请使用环境变量或特定于框架的配置对其进行配置。

您可以通过设置环境变量来配置代理

ELASTIC_APM_SERVICE_NAME=foo python manage.py runserver

或使用内联配置

apm_client = Client(service_name="foo")

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

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

优先级如下

动态配置编辑

如果从受支持的来源设置，则标记有 标记的配置选项可以在运行时更改。

Python 代理支持 集中配置，允许您从 APM 应用程序中微调某些配置。默认情况下，代理中通过 central_config 启用此功能。

Django编辑

要配置 Django，请将 ELASTIC_APM 字典添加到您的 settings.py 中

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

Flask编辑

要配置 Flask，请将 ELASTIC_APM 字典添加到您的 app.config 中

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

apm = ElasticAPM(app)

核心选项编辑

service_name编辑

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

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

server_url编辑

您的 APM 服务器的 URL。URL 必须是完全限定的，包括协议（http 或 https）和端口。注意：如果您在 AWS lambda 函数中使用 APM，请不要设置此项。APM 代理旨在通过 lambda 扩展将其调用代理到 APM 服务器。而是设置 ELASTIC_APM_LAMBDA_APM_SERVER。有关更多信息，请参阅 AWS Lambda。

enabled编辑

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

recording编辑

启用或禁用事件记录。如果设置为 false，则 Python 代理不会向 Elastic APM 服务器发送任何事件，并且仪器开销最小化。代理将继续轮询服务器以获取配置更改。

日志记录选项编辑

log_level编辑

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

选项不区分大小写

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

log_file编辑

这使代理能够记录到文件。默认情况下禁用此功能。代理将记录在使用 log_level 配置的 logging.logLevel 处。使用 log_file_size 配置日志文件的最大大小。此日志文件将自动轮换。

请注意，设置 log_level 是此设置执行任何操作所必需的。

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

log_file_size编辑

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

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

log_ecs_reformatting编辑

有效选项

如果安装了 ecs_logging，则将其设置为 "override" 将导致代理自动尝试启用 ecs 格式的日志记录。

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

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

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

另请注意，此设置不 facilitar 将日志发送到 Elasticsearch。为此，我们建议使用 Filebeat。

其他选项编辑

transport_class编辑

向 APM 服务器发送事件时要使用的传输类。

service_node_name编辑

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

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

environment编辑

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

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

cloud_provider编辑

此配置值允许您指定应假定哪个云提供商用于元数据收集。默认情况下，代理将尝试检测云提供商，如果失败，将使用试错法来收集元数据。

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

secret_token编辑

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

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

api_key编辑

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

service_version编辑

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

framework_name编辑

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

framework_version编辑

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

filter_exception_types编辑

要过滤的异常类型列表。这些类型的异常不会发送到 APM 服务器。

transaction_ignore_urls编辑

代理不应捕获任何事务数据的 URL 列表。

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

transactions_ignore_patterns编辑

正则表达式列表。名称与任何已配置模式匹配的事务将被忽略，并且不会发送到 APM 服务器。

server_timeout编辑

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

hostname编辑

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

auto_log_stacks编辑

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

可以通过设置 extra 键 stack 来分别覆盖此设置

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

collect_local_variables编辑

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

Elastic APM Python 代理可以收集堆栈帧的局部变量。默认情况下，这仅针对错误执行。

local_var_max_length编辑

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

local_var_list_max_length编辑

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

local_var_dict_max_length编辑

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

source_lines_error_app_frames编辑

source_lines_error_library_frames编辑

source_lines_span_app_frames编辑

source_lines_span_library_frames编辑

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

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

capture_body编辑

对于作为 HTTP 请求的事务，Python 代理可以选择捕获请求正文（例如 POST 变量）。

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

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

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

capture_headers编辑

对于由于 HTTP 请求而发生的事务和错误，Python 代理可以选择捕获请求和响应标头。

可能的值：true、false

transaction_max_spans编辑

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

stack_trace_limit编辑

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

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

span_stack_trace_min_duration编辑

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

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

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

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

span_frames_min_duration编辑

span_compression_enabled编辑

启用/禁用 span 压缩。

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

span_compression_exact_match_max_duration编辑

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

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

span_compression_same_kind_max_duration编辑

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

如果以下属性相同，则认为两个 span 属于同一类型：* span 类型 * span 子类型 * 目标资源（例如数据库名称）

exit_span_min_duration编辑

退出 span 是表示对外部服务（如数据库）的调用的 span。如果此类调用非常短，则它们通常无关紧要，可以忽略。

默认情况下，此功能处于禁用状态。

api_request_size编辑

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

如果遇到流量突然激增，此设置可用于限制内存消耗。必须以 大小格式 提供。

api_request_time编辑

在将请求发送到 APM 服务器之前，请求缓冲区的最大队列时间。较低的值会增加 APM 服务器上的负载，而较高的值会增加应用程序的内存压力。较高的值还会影响数据在 Elasticsearch 中建立索引和可搜索的时间。

如果遇到流量突然激增，此设置可用于限制内存消耗。必须以 持续时间格式 提供。

processors编辑

用于处理事务和错误的处理器列表。有关更多信息，请参阅清理数据。

sanitize_field_names编辑

使用处理器时要匹配和屏蔽的 glob 匹配字段名称列表。有关更多信息，请参阅清理数据。

transaction_sample_rate编辑

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

include_paths编辑

一组路径，可以选择使用 shell 通配符（有关语法说明，请参阅 fnmatch）。这些路径与每个帧的绝对文件名匹配，如果模式匹配，则该帧被视为“应用内帧”。

include_paths 优先于 exclude_paths。

exclude_paths编辑

一组路径，可以选择使用 shell 通配符（有关语法说明，请参阅 fnmatch）。这些路径与每个帧的绝对文件名匹配，如果模式匹配，则该帧被视为“库帧”。

include_paths 优先于 exclude_paths。

默认值因 Python 版本和实现而异，例如

debug编辑

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

disable_send编辑

如果设置为 True，则代理不会向 APM 服务器发送任何事件，无论任何调试状态如何。

instrument编辑

如果设置为 False，则代理不会检测任何代码。这将禁用大多数跟踪功能，但对于调试可能的检测问题很有用。

verify_server_cert编辑

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

server_cert编辑

如果您已使用自签名 TLS 证书配置 APM 服务器，或者您只想固定服务器证书，则可以通过 ELASTIC_APM_SERVER_CERT 配置指定 PEM 编码证书的路径。

server_ca_cert_file编辑

默认情况下，代理将使用 Mozilla 精选并由 certifi 包提供的众所周知的 CA 来验证 APM 服务器的 TLS/SSL 证书。

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

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

use_certifi编辑

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

metrics_interval编辑

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

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

disable_metrics编辑

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

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

breakdown_metrics编辑

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

prometheus_metrics (测试版)编辑

启用/禁用从 prometheus_client 跟踪和收集指标。

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

prometheus_metrics_prefix (测试版)编辑

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

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

metrics_sets编辑

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

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

central_config编辑

启用后，代理将定期向 APM 服务器发出请求以获取更新的配置。

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

global_labels编辑

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

disable_log_record_factory编辑

默认情况下，在 Python 3 中，代理会安装一个 LogRecord 工厂，它会自动将跟踪字段添加到您的日志记录中。通过将其设置为 True 来禁用此行为。

use_elastic_traceparent_header编辑

为了启用 分布式跟踪，代理会为使用 已检测的 HTTP 库 发出的传出请求设置多个 HTTP 标头。这些标头（traceparent 和 tracestate）在 W3C 跟踪上下文 规范中定义。

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

trace_continuation_strategy编辑

此选项允许对 APM 代理如何处理传入请求上的 W3C 跟踪上下文标头进行一些控制。默认情况下，traceparent 和 tracestate 标头根据 W3C 规范用于分布式跟踪。但是，在某些情况下，不 使用传入的 traceparent 标头可能会有所帮助。一些用例示例

有效值为

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

use_elastic_excepthook编辑

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

include_process_args编辑

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

Django 特定配置编辑

django_transaction_name_from_route编辑

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

django_autoinsert_middleware编辑

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

通用环境变量编辑

一些并非特定于 APM 代理的环境变量可用于配置代理。

HTTP_PROXY 和 HTTPS_PROXY编辑

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

NO_PROXY编辑

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

如果 HTTP_PROXY / HTTPS_PROXY 是出于代理/APM 服务器通信以外的其他原因设置的，这将很有用。

SSL_CERT_FILE 和 SSL_CERT_DIR编辑

要指示代理使用不同的 SSL 证书，可以使用这些环境变量。另请参阅 OpenSSL 文档。

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

配置格式编辑

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

持续时间格式编辑

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

示例：5ms

支持的单位

大小格式编辑

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

示例：10kb

支持的单位: