配置 Logstash 输出

Logstash 允许对 APM 事件进行额外的处理和路由。Logstash 输出使用 lumberjack 协议（通过 TCP 运行）将事件直接发送到 Logstash。

要将事件发送到 Logstash，您必须

要在 APM Server 中启用 Logstash 输出，请编辑 apm-server.yml 文件以

最后，您必须创建一个 Logstash 配置管道，该管道监听传入的 APM Server 连接并将接收到的事件索引到 Elasticsearch 中。

当我们将所有内容组合在一起时，您的基本 Logstash 配置文件将如下所示

input {
  elastic_agent {
    port => 5044
  }
}

output {
  elasticsearch {
    data_stream => "true"
    cloud_id => "YOUR_CLOUD_ID_HERE"
    cloud_auth => "YOUR_CLOUD_AUTH_HERE"
  }
}

发送到 Logstash 的每个事件都包含一个名为 @metadata 的特殊字段，您可以在 Logstash 中将其用于条件、过滤、索引等。APM Server 将以下 @metadata 发送到 Logstash

{
    ...
    "@metadata": {
      "beat": "apm-server", 
      "version": "8.16.0" 
    }
}

除了 @metadata 之外，APM Server 还提供了其他可能很有用的字段，例如 data_stream 字段，该字段可用于有条件地对 事件类型、命名空间或数据集进行操作。

例如，您可能希望使用 Logstash 将所有 metrics 事件路由到同一个自定义指标数据流，而不是路由到特定于服务的某个数据流。

但是，如果您组合所有 metrics 事件时，有些事件的 data_stream.dataset 字段设置为不同的值，则索引将失败，并显示一条消息，指出该字段不接受任何其他值。例如，错误可能显示类似 failed to parse field [data_stream.dataset] of type [constant_keyword] 或 [constant_keyword] field [data_stream.dataset] only accepts values that are equal to the value defined in the mappings 的内容。这是因为 data_stream.dataset 字段的映射设置为 constant_keyword，它期望索引中所有字段的值都相同。

为了防止因索引失败而导致数据丢失，请添加一个 Logstash mutate 过滤器 来更新 data_stream.dataset 的值。然后，您可以将所有指标事件发送到一个自定义指标数据流

filter {
  if [@metadata][beat] == "apm-server" { 
    if [data_stream][type] == "metrics" { 
      mutate {
        update => { "[data_stream][dataset]" => "custom" } 
      }
    }
  }
}
output {
  elasticsearch {
    data_stream => "true"
    cloud_id => "${CLOUD_ID}" 
    cloud_auth => "${CLOUD_AUTH}" 
  }
}

此输出适用于所有兼容版本的 Logstash。请参阅 Elastic 支持矩阵。

您可以在 apm-server.yml 配置文件的 logstash 部分中指定以下选项

enabled 配置是一个布尔设置，用于启用或禁用输出。如果设置为 false，则输出被禁用。

默认值为 false。

要连接到的已知 Logstash 服务器列表。如果负载均衡被禁用，但配置了多个主机，则随机选择一个主机（没有优先级）。如果一个主机变得不可访问，则会随机选择另一个主机。

此列表中的所有条目都可以包含端口号。如果未给出数字，则将使用默认端口号 5044。

gzip 压缩级别。将此值设置为 0 将禁用压缩。压缩级别必须在 1（最快速度）到 9（最佳压缩）的范围内。

提高压缩级别将减少网络使用量，但会增加 CPU 使用量。

默认值为 3。

配置字符串中 HTML 的转义。设置为 true 以启用转义。

默认值为 false。

每个配置的主机发布事件到 Logstash 的工作进程数。这最适合在启用负载均衡模式时使用。例如：如果您有 2 个主机和 3 个工作进程，则总共启动 6 个工作进程（每个主机 3 个）。

如果设置为 true 并且配置了多个 Logstash 主机，则输出插件会将发布的事件负载均衡到所有 Logstash 主机上。如果设置为 false，则输出插件会将所有事件仅发送到一个主机（随机确定），如果选定的主机无响应，则会切换到另一个主机。默认值为 false。

output.logstash:
  hosts: ["localhost:5044", "localhost:5045"]
  loadbalance: true
  index: apm-server

与 Logstash 的连接的生存时间，在此时间之后连接将重新建立。在 Logstash 主机表示负载均衡器时很有用。由于与 Logstash 主机的连接是粘性的，因此在负载均衡器后面操作会导致实例之间负载分布不均。在连接上指定 TTL 允许在实例之间实现均衡的连接分布。将 TTL 指定为 0 将禁用此功能。

默认值为 0。

配置异步发送到 Logstash 的批次数量，同时等待来自 Logstash 的 ACK。只有在写入指定数量的 pipelining 批次后，输出才会变为阻塞。如果配置的值为 0，则禁用流水线。默认值为 2。

连接到 Logstash 服务器时要使用的 SOCKS5 代理的 URL。该值必须是方案为 socks5:// 的 URL。用于与 Logstash 通信的协议不是基于 HTTP 的，因此不能使用 Web 代理。

如果 SOCKS5 代理服务器需要客户端身份验证，则可以在 URL 中嵌入用户名和密码，如示例所示。

使用代理时，主机名在代理服务器上解析，而不是在客户端上解析。您可以通过设置 proxy_use_local_resolver 选项来更改此行为。

output.logstash:
  hosts: ["remote-host:5044"]
  proxy_url: socks5://user:password@socks5-proxy:2233

proxy_use_local_resolver 选项确定在使用代理时是否在本地解析 Logstash 主机名。默认值为 false，这意味着当使用代理时，名称解析发生在代理服务器上。

要将事件写入的索引根名称。默认为 apm-server。例如 "apm" 生成 "[apm-]8.16.0-YYYY.MM.DD" 索引（例如，"apm-8.16.0-2017.04.26"）。

SSL 参数的配置选项，例如 Logstash 连接的根 CA。有关更多信息，请参阅 SSL/TLS 输出设置。要使用 SSL，您还必须将 Logstash 的 Beats 输入插件 配置为使用 SSL/TLS。

在超时之前等待 Logstash 服务器响应的秒数。默认为 30（秒）。

发布失败后重试发布事件的次数。在指定的重试次数后，事件通常会被丢弃。

将 max_retries 设置为小于 0 的值，以重试直到所有事件都发布。

默认为 3。

在一个 Logstash 请求中批量发送的事件的最大数量。默认为 2048。

如果 Beat 发送单个事件，则将事件收集到批次中。如果 Beat 发布大量事件（大于 bulk_max_size 指定的值），则会拆分该批次。

指定更大的批次大小可以通过降低发送事件的开销来提高性能。但是，较大的批次大小也会增加处理时间，这可能会导致 API 错误、连接终止、发布请求超时，并最终导致吞吐量降低。

将 bulk_max_size 设置为小于或等于 0 的值将禁用批次的拆分。当禁用拆分时，队列将决定每个批次包含的事件数量。

如果启用，则每次事务仅传输一批事件中的一个子集。如果未遇到错误，则要发送的事件数量将增加到 bulk_max_size。发生错误时，每次事务的事件数量将再次减少。

默认值为 false。

网络错误后，在尝试重新连接到 Logstash 之前等待的秒数。等待 backoff.init 秒后，APM Server 会尝试重新连接。如果尝试失败，则退避计时器将指数级增加，直到达到 backoff.max。连接成功后，退避计时器将重置。默认值为 1s。

网络错误后，在尝试连接到 Logstash 之前等待的最大秒数。默认值为 60s。

您可以使用 SSL 互认证来保护 APM Server 和 Logstash 之间的连接。这确保 APM Server 仅将加密数据发送到受信任的 Logstash 服务器，并且 Logstash 服务器仅接收来自受信任的 APM Server 客户端的数据。

要使用 SSL 互认证

在运行 APM Server 之前，您应该验证 Logstash 服务器的证书。即使用于与 Logstash 通信的协议不是基于 HTTP，您也可以使用 curl 来验证证书。例如

curl -v --cacert ca.crt https://logs.mycompany.com:5044

如果测试成功，您将收到一个空的响应错误

* Rebuilt URL to: https://logs.mycompany.com:5044/
*   Trying 192.168.99.100...
* Connected to logs.mycompany.com (192.168.99.100) port 5044 (#0)
* TLS 1.2 connection using TLS_DHE_RSA_WITH_AES_256_CBC_SHA
* Server certificate: logs.mycompany.com
* Server certificate: mycompany.com
> GET / HTTP/1.1
> Host: logs.mycompany.com:5044
> User-Agent: curl/7.43.0
> Accept: */*
>
* Empty reply from server
* Connection #0 to host logs.mycompany.com left intact
curl: (52) Empty reply from server

以下示例使用 IP 地址而不是主机名来验证证书

curl -v --cacert ca.crt https://192.168.99.100:5044

此测试的验证失败，因为证书对于指定的 IP 地址无效。它仅对 logs.mycompany.com 有效，即证书的“主体”字段中显示的主机名。

* Rebuilt URL to: https://192.168.99.100:5044/
*   Trying 192.168.99.100...
* Connected to 192.168.99.100 (192.168.99.100) port 5044 (#0)
* WARNING: using IP address, SNI is being disabled by the OS.
* SSL: certificate verification failed (result: 5)
* Closing connection 0
curl: (51) SSL: certificate verification failed (result: 5)

有关解决此问题的更多信息，请参阅 故障排除文档。

如果 APM Server 作为服务运行，请先停止该服务。然后，通过在前景中运行 APM Server 来测试您的设置，以便您可以快速查看发生的任何错误

apm-server -c apm-server.yml -e -v

任何错误都将打印到控制台。有关解决常见错误的信息，请参阅 故障排除文档。