配置

使用以下方法之一来自定义 Elastic APM Go Agent 的行为—这些方法按优先级降序排列。

1. 通过 Kibana 进行 APM Agent 配置（支持的选项会以 标记）
2. 在代码中使用 Tracer Config API
3. 环境变量

通过 Kibana 配置的设置将优先于在代码中配置的相同设置，而代码中配置的设置又优先于环境变量。如果通过 Kibana 配置的设置后来被移除，Agent 将恢复到通过 Tracer Config API 或环境变量在本地配置的设置。

为了简化开发和测试，Agent 默认将数据发送到 Elastic APM Server，地址为 https://:8200。要将数据发送到其他位置，您必须配置 ELASTIC_APM_SERVER_URL。根据您的服务器配置，您可能还需要设置 ELASTIC_APM_API_KEY、ELASTIC_APM_SECRET_TOKEN 和 ELASTIC_APM_VERIFY_SERVER_CERT。所有其他变量都具有可用的默认值。

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

Go Agent 支持 集中式配置，该功能允许您通过 APM 应用微调某些配置。此功能在 Agent 中默认启用，通过 ELASTIC_APM_CENTRAL_CONFIG 进行控制。

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

持续时间格式用于超时等选项。单位作为后缀直接跟在数字后面，中间没有任何空格。

示例： 5ms

支持的单位：

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

大小格式用于最大缓冲区大小等选项。单位作为后缀直接跟在数字后面，中间没有任何空格。

示例： 10KB

支持的单位：

• B (字节)
• KB (千字节)
• MB (兆字节)
• GB (千兆字节)

您的 Elastic APM 服务器的 URL。服务器支持 HTTP 和 HTTPS。如果您使用 HTTPS，则可能需要配置客户端计算机，以便可以验证服务器证书。您可以使用 ELASTIC_APM_VERIFY_SERVER_CERT 禁用证书验证。

发往您的 Elastic APM 服务器的请求的超时时间。当设置为零或负值时，超时将被禁用。

此字符串用于确保只有您的 Agent 才能将数据发送到您的 APM 服务器。Agent 和 APM 服务器都必须配置相同的 secret token。

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

您的服务或应用程序的名称。它用于将服务的所有错误和事务聚合在一起，并且是 Elastic APM 用户界面中的主要过滤器。

如果您不指定 ELASTIC_APM_SERVICE_NAME，Go Agent 将使用可执行文件的名称。例如，如果您的可执行文件名为 "my-app.exe"，则您的服务将被识别为 "my-app"。

当前已部署服务版本的版本字符串。如果您不为部署版本号，则此字段推荐值是已部署修订版的提交标识符，例如 git rev-parse HEAD 的输出。

用于区分服务中节点的可选名称。必须是唯一的，否则来自多个节点的数据将被聚合在一起。

如果您不指定 ELASTIC_APM_SERVICE_NODE_NAME，服务节点将使用容器 ID（如果可用）来识别，否则使用主机名。

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

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

启用或禁用 Agent。如果设置为 false，则 Go Agent 不会向 Elastic APM 服务器发送任何数据，并且会最大程度地减少仪器开销。

启用或禁用事件记录。如果设置为 false，则 Go Agent 不会向 Elastic APM 服务器发送任何事件，并且会最大程度地减少仪器开销，但 Agent 会继续轮询服务器以获取配置更改。

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

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

要忽略的 HTTP 请求的模式列表。请求行与任何模式匹配的传入 HTTP 请求将不会被报告为事务。

此选项支持通配符 *，它匹配零个或多个字符。示例：/foo/*/bar/*/baz*、*foo*。默认情况下，匹配不区分大小写。在模式前加上 (?-i) 会使匹配区分大小写。

要进行脱敏处理的 HTTP 标头、Cookie 和 POST 表单字段名称的模式列表。

此选项支持通配符 *，它匹配零个或多个字符。示例：/foo/*/bar/*/baz*、*foo*。默认情况下，匹配不区分大小写。在模式前加上 (?-i) 会使匹配区分大小写。

对于 HTTP 请求事务，Go Agent 可以选择性地捕获请求和响应标头。

可能的值：true，false。

捕获的标头会根据 ELASTIC_APM_SANITIZE_FIELD_NAMES 进行清理。

对于 HTTP 请求事务，Go Agent 可以选择性地捕获请求体。

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

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

在结束对 Elastic APM 服务器的请求之前等待的时间。当您报告事务、跨度和错误时，Agent 将发起一个请求，并在有足够数据发送时将其发送到服务器；该请求将保持打开状态，直到超过此时间，或者直到达到 最大请求大小。

发送到 Elastic APM 服务器的请求体的最大大小。Agent 将维护一个内存中的压缩数据缓冲区，用于流式传输到 APM 服务器。

在 Agent 忙碌时，用于存储未压缩、已编码事件的最大字节数。当 Agent 能够时，它会将缓冲数据传输到请求缓冲区，并开始将其流式传输到服务器。如果缓冲区已满，新事件将开始替换旧事件。

限制每个事务记录的跨度数量。

这在事务创建大量跨度（例如，成千上万个 SQL 查询）的情况下很有帮助。设置上限可以防止此类极端情况将 Agent 和 APM 服务器置于过载状态。

设置要报告的退出跨度的最小持续时间。持续时间小于或等于此阈值的跨度将被 Agent 丢弃，并在跨度的事务中作为统计信息报告，前提是事务在跨度报告之前尚未结束。

当启用跨度压缩时（ELASTIC_APM_SPAN_COMPRESSION_ENABLED），将考虑压缩跨度复合体的总和。

此设置的最小持续时间为 1 微秒 (us)。

APM Agent 将为持续时间超过此配置值的每个记录的跨度收集堆栈跟踪。虽然这对于查找代码中导致跨度发生的精确位置非常有用，但收集此堆栈跟踪确实会产生一些处理和存储开销。

APM Agent 将为持续时间超过此配置值的每个记录的跨度收集堆栈跟踪。虽然这对于查找代码中导致跨度发生的精确位置非常有用，但收集此堆栈跟踪确实会产生一些处理和存储开销。

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

将限制设置为 0 将禁用堆栈跟踪收集，而任何正整数值将用作要收集的最大帧数。设置负值（如 -1）表示将收集所有帧。

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

APM Agent 收集和报告指标的间隔。设置为 0s 以禁用。

禁用某些指标的收集。如果指标的名称与任何通配符表达式匹配，则不会收集它。

此选项支持通配符 *，它匹配零个或多个字符。示例：/foo/*/bar/*/baz*、*foo*。默认情况下，匹配不区分大小写。在模式前加上 (?-i) 会使匹配区分大小写。

捕获细分指标。设置为 false 以禁用。

如果您已为 APM Server 配置了自签名 TLS 证书，或者您想固定服务器证书，请通过 ELASTIC_APM_SERVER_CERT 配置指定 PEM 编码证书的路径。

用于验证服务器 TLS 证书链的 PEM 编码的 TLS 证书颁发机构证书的路径。

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

ELASTIC_APM_LOG_FILE 指定 Agent 的默认内部日志记录器的输出文件。在进程启动时，该文件将被创建，如果已存在则会被截断。默认情况下，日志记录是禁用的。您必须指定 ELASTIC_APM_LOG_FILE 来启用它。如果日志记录器是程序化配置的，则将忽略此环境变量。

Agent 识别两个特殊文件名：stdout 和 stderr。这些将配置日志记录器写入标准输出和标准错误。

ELASTIC_APM_LOG_LEVEL 指定 Agent 的默认内部日志记录器的日志级别。日志记录器使用的唯一两个级别是 "error" 和 "debug"。默认情况下，日志记录是禁用的。您必须指定 ELASTIC_APM_LOG_FILE 来启用它。

如果日志记录器是程序化配置的，则将忽略此环境变量。

通过 Kibana 激活 APM Agent 集中式配置。默认情况下，Agent 将轮询服务器以获取 Agent 配置更改。通过将其设置为 false 可以禁用此功能。有关更多信息，请参阅 APM Agent 集中式配置。

为了启用 分布式跟踪，Agent 会将跟踪上下文标头添加到使用 module/apmhttp 发出的 HTTP 请求中。这些标头 (traceparent 和 tracestate) 在 W3C 跟踪上下文规范中定义。

当此设置设置为 true 时，Agent 还会添加 elastic-apm-traceparent 标头，以实现与旧版本 Elastic APM Agent 的向后兼容。

此配置值允许您指定要假定的云提供商，用于元数据收集。默认情况下，Agent 将尝试通过试错法自动收集云元数据。

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

启用后，Agent 会尝试压缩共享相同父级的短退出跨度，将它们合并成一个复合跨度。短跨度的确切持续时间取决于所使用的压缩策略（same_kind 或 exact_match）。

为了使跨度可压缩，需要满足以下条件：

• 跨度是退出跨度。

• 跨度是同级（共享同一个父级）。

• 跨度未将其上下文传播到下游。

• 每个跨度的持续时间等于或低于压缩策略的最大持续时间。

• 当以下属性相同时，使用 same_kind 策略压缩跨度：

  • span.type.
  • span.subtype.
  • span.context.destination.service.resource

• 当满足所有先前条件且 span.name 相同时，使用 exact_match 策略压缩跨度。

压缩短退出跨度可以为创建大量连续短退出跨度（例如，到数据库或缓存服务）的服务节省一些存储空间，当查看跟踪时，这些跨度通常不那么有趣。

用于压缩同级退出跨度的最大持续时间，这些跨度是精确匹配以进行压缩的。

用于压缩同级退出跨度的最大持续时间，这些跨度是相同类型的以进行压缩的。

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

• 已进行 Elastic 监控的服务正在接收来自未监控服务的带有 traceparent 标头的请求。
• 由 Elastic 监控的服务是公开暴露的，并且不希望跟踪数据（跟踪 ID、采样决策）可能被用户请求欺骗。

有效选项包括 continue、restart 和 restart_external。

continue

默认行为。使用传入的 traceparent 值来继续跟踪并确定采样决策。

restart

始终忽略传入请求的 traceparent 标头。将生成新的 trace-id，并且将根据 transaction_sample_rate 进行采样决策。将创建一个 span 链接到传入的 traceparent。

restart_external

如果传入请求在 tracestate 中包含 es vendor 标志，则任何 traceparent 都将被视为内部，并将按上述 continue 的描述进行处理。否则，任何 traceparent 都将被视为外部，并将按上述 restart 的描述进行处理。

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