配置

要使 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，请将 ELASTIC_APM 字典添加到您的 settings.py

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

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

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 服务器发送任何事件，并且仪器开销将最小化。代理将继续轮询服务器以获取配置更改。

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

选项不区分大小写

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

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

请注意，必须设置 log_level 才能使此设置起作用。

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

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

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

有效选项

如果安装了 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（如果需要）。

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

此服务部署所在环境的名称，例如“生产”或“暂存”。

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

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

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

此字符串用于确保只有您的代理才能将数据发送到您的 APM Server。代理和 APM Server 都必须配置相同的密钥令牌。生成安全密钥令牌的一个示例是

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

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

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

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

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

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

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

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

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

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

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

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

可以通过设置 extra 键 stack 来单独覆盖此设置

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

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

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

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

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

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

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

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

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

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

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

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

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

可能的值：true、false

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

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

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

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

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

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

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

启用/禁用 span 压缩。

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

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

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

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

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

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

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

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

如果您遇到突然的流量高峰，此设置有助于限制内存消耗。它必须以大小格式提供。

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

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

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

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

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

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

include_paths 优先于 exclude_paths。

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

include_paths 优先于 exclude_paths。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

一个前缀，用于添加到 Prometheus 指标名称的前面。

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

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

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

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

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

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

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

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

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

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

有效值为：

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

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

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

默认情况下，我们使用视图的函数或类名作为事务名称。从 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 服务器。如果两者都设置，则 HTTPS_PROXY 优先。

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

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

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

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

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

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

示例：5ms

支持的单位

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

示例：10kb

支持的单位: