配置 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.17.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 的 ACK 时异步发送到 Logstash 的批次数量。只有在写入了 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.17.0-YYYY.MM.DD" 索引（例如，"apm-8.17.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 服务器的证书。您可以使用 curl 来验证证书，即使用于与 Logstash 通信的协议不是基于 HTTP 的。例如

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 有效，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

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