配置 Logstash 输出

Elastic Stack

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

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

1. 在 APM Server 中启用 Logstash 输出
2. 在 Logstash 中创建 Logstash 配置管道

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

1. 通过注释掉来禁用 Elasticsearch 输出，并且

2. 通过取消注释 Logstash 部分并将 enabled 设置为 true 来启用 Logstash 输出

   output.logstash:
     enabled: true
     hosts: ["localhost:5044"]
   

   1. hosts 选项指定 Logstash 服务器和端口 (5044)，Logstash 配置为在该端口上侦听传入的 APM Server 连接。

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

1. 使用 Elastic Agent 输入插件配置 Logstash 以接收来自 APM Server 的事件。一个最小的 input 配置可能如下所示

   input {
     elastic_agent {
       port => 5044
     }
   }
   

2. 使用 Elasticsearch 输出插件将事件发送到 Elasticsearch 以进行索引。一个最小的 output 配置可能如下所示

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

   1. 启用索引到 Elasticsearch 数据流中。
   2. 此示例假定您正在将数据发送到 Elastic Cloud。如果您使用的是自托管版本的 Elasticsearch，请改用 hosts。有关更多信息，请参见 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": "9.0.0"
    }
}

1. 要更改默认的 apm-server 值，请在 APM Server 配置文件中设置 index 选项。
2. APM Server 的当前版本。

除了 @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}"
  }
}

1. 仅当数据从 APM Server 发送时才应用此输出。
2. 确定事件类型是否为 metrics。
3. 添加一个 Logstash mutate 过滤器来更新 data_stream.dataset 的值。
4. 在此示例中，cloud_id 和 cloud_auth 存储为 环境变量。

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

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

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

默认值为 false。

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

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

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

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

默认值为 3。

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

默认值为 false。

每个配置的主机上将事件发布到 Logstash 的 worker 数量。这最好与启用的负载平衡模式一起使用。示例：如果您有 2 个主机和 3 个 worker，则总共启动 6 个 worker（每个主机 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-]VERSION-YYYY.MM.DD" 索引（例如，"apm-9.0.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 相互身份验证

1. 创建一个证书颁发机构 (CA)，并使用它来签署您计划用于 APM Server 和 Logstash 的证书。 创建正确的 SSL/TLS 基础设施不在此文档的范围内。 有很多在线资源可以描述如何创建证书。

   提示

   如果您正在使用安全功能，则可以使用 elasticsearch-certutil 工具 来生成证书。

2. 配置 APM Server 以使用 SSL。 在 apm-server.yml 配置文件中，在 ssl 下指定以下设置

   • certificate_authorities：配置 APM Server 以信任由指定 CA 签署的任何证书。 如果 certificate_authorities 为空或未设置，则使用主机系统的受信任证书颁发机构。

   • certificate 和 key：指定 APM Server 用于向 Logstash 进行身份验证的证书和密钥。

     例如

     output.logstash:
       hosts: ["logs.mycompany.com:5044"]
       ssl.certificate_authorities: ["/etc/ca.crt"]
       ssl.certificate: "/etc/client.crt"
       ssl.key: "/etc/client.key"
     

     有关这些配置选项的更多信息，请参阅 SSL/TLS 输出设置。

3. 配置 Logstash 以使用 SSL。 在 Logstash 配置文件中，为 Logstash 的 Beats 输入插件 指定以下设置

   • ssl：设置为 true 时，使 Logstash 能够使用 SSL/TLS。

   • ssl_certificate_authorities：配置 Logstash 以信任由指定 CA 签署的任何证书。

   • ssl_certificate 和 ssl_key：指定 Logstash 用于向客户端进行身份验证的证书和密钥。

   • ssl_verify_mode：指定 Logstash 服务器是否针对 CA 验证客户端证书。 您需要指定 peer 或 force_peer 以使服务器请求证书并对其进行验证。 如果您指定 force_peer，并且 APM Server 没有提供证书，则 Logstash 连接将被关闭。 如果您选择不使用 certutil，则您获得的证书必须允许 clientAuth 和 serverAuth（如果存在扩展密钥用法扩展）。

     例如

     input {
       beats {
         port => 5044
         ssl => true
         ssl_certificate_authorities => ["/etc/ca.crt"]
         ssl_certificate => "/etc/server.crt"
         ssl_key => "/etc/server.key"
         ssl_verify_mode => "force_peer"
       }
     }
     

     有关这些选项的更多信息，请参阅 Beats 输入插件的文档。

在运行 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

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