› › › ›

配置 Logstash 输出

编辑

配置 Logstash 输出编辑

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

将事件发送到 Logstash编辑

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

Logstash 输出配置编辑

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

通过注释掉来禁用 Elasticsearch 输出，以及
通过取消注释 Logstash 部分并将 enabled 设置为 true 来启用 Logstash 输出
```
output.logstash:
  enabled: true
  hosts: ["localhost:5044"] 
```
hosts 选项指定 Logstash 服务器和 Logstash 配置为侦听传入 APM Server 连接的端口 (5044)。

Kibana 端点配置编辑

APM Server 使用 APM 集成来设置和管理 APM 模板、策略和管道。为了确认集成已安装，APM Server 在启动时会轮询 Elasticsearch 或 Kibana。当使用非 Elasticsearch 输出时，APM Server 需要通过 Kibana 端点访问 Kibana。

示例配置

apm-server:
  kibana:
    enabled: true
    host: "https://..."
    username: "elastic"
    password: "xxx"

Logstash 配置管道编辑

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

使用 Elastic Agent 输入插件配置 Logstash 以接收来自 APM Server 的事件。一个最小的 input 配置可能如下所示
```
input {
  elastic_agent {
    port => 5044
  }
}
```

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

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

	启用索引到 Elasticsearch 数据流。
	此示例假设您将数据发送到 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"
  }
}

访问 @metadata 字段编辑

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

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

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

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

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

output {
  if [@metadata][beat] == "apm-server" { 
    if [data_stream][type] == "metrics" { 
      elasticsearch {
        index => "%{[data_stream][type]}-custom-%{[data_stream][namespace]}" 
        action => "create" 
        cloud_id => "${CLOUD_ID}" 
        cloud_auth => "${CLOUD_AUTH}" 
      }
    } else {
      elasticsearch {
        data_stream => "true" 
        cloud_id => "${CLOUD_ID}"
        cloud_auth => "${CLOUD_AUTH}"
      }
    }
  }
}

	仅当数据从 APM Server 发送时才应用此输出
	确定事件类型是否为 `metric`
	如果事件类型为 `metric`，则输出到自定义数据流：`metrics-custom-<YOUR_NAMESPACE>`
	当使用 Logstash 将索引输出到数据流时，您必须显式地将 `action` 设置为 `create`
	在此示例中，`cloud_id` 和 `cloud_auth` 存储为环境变量
	对于所有其他事件类型，将数据直接索引到预定义的 APM 数据流中

兼容性编辑

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

配置选项编辑

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

`enabled`编辑

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

默认值为 false。

`hosts`编辑

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

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

`compression_level`编辑

gzip 压缩级别。将此值设置为 0 将禁用压缩。压缩级别必须在 1（最佳速度）到 9（最佳压缩）之间。

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

默认值为 3。

`escape_html`编辑

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

默认值为 false。

`worker`编辑

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

`loadbalance`编辑

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

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

`ttl`编辑

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

默认值为 0。

"ttl" 选项在异步 Logstash 客户端（具有 "pipelining" 选项设置的客户端）上尚不支持。

`pipelining`编辑

配置异步发送到 Logstash 的批次数量，同时等待来自 Logstash 的 ACK。一旦写入 pipelining 批次数量，输出就会变为阻塞。如果配置的值为 0，则禁用管道。默认值为 2。

`proxy_url`编辑

连接到 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`编辑

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

`index`edit

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

此参数的值将被分配给 metadata.beat 字段。然后可以在 Logstash 的输出部分以 %{[@metadata][beat]} 的形式访问它。

`ssl`edit

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

`timeout`edit

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

`max_retries`edit

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

将 max_retries 设置为小于 0 的值，表示在所有事件发布之前一直重试。

默认值为 3。

`bulk_max_size`edit

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

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

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

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

`slow_start`edit

如果启用，则每次事务只传输一批事件中的部分事件。如果未遇到错误，则每事务发送的事件数量会增加到 bulk_max_size。如果发生错误，则每事务的事件数量会再次减少。

默认值为 false。

`backoff.init`edit

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

`backoff.max`edit

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

与 Logstash 的安全通信edit

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

要使用 SSL 互认证

创建一个证书颁发机构 (CA)，并使用它来签署您计划用于 APM Server 和 Logstash 的证书。创建正确的 SSL/TLS 基础设施超出了本文档的范围。网上有很多资源描述了如何创建证书。

如果您使用安全功能，则可以使用 elasticsearch-certutil 工具生成证书。
配置 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 输出设置。
配置 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 输入插件的文档。

验证 Logstash 服务器的证书edit

在运行 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 到 Logstash 的连接edit

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

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

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

« 配置 Elasticsearch 输出配置 Kafka 输出 »

配置 Logstash 输出

配置 Logstash 输出编辑

将事件发送到 Logstash编辑

Logstash 输出配置编辑

Kibana 端点配置编辑

Logstash 配置管道编辑

访问 @metadata 字段编辑

兼容性编辑

配置选项编辑

enabled编辑

hosts编辑

compression_level编辑

escape_html编辑

worker编辑

loadbalance编辑

ttl编辑

pipelining编辑

proxy_url编辑

proxy_use_local_resolver编辑

indexedit

ssledit

timeoutedit

max_retriesedit

bulk_max_sizeedit

slow_startedit

backoff.initedit

backoff.maxedit

与 Logstash 的安全通信edit

验证 Logstash 服务器的证书edit

测试 APM Server 到 Logstash 的连接edit

`enabled`编辑

`hosts`编辑

`compression_level`编辑

`escape_html`编辑

`worker`编辑

`loadbalance`编辑

`ttl`编辑

`pipelining`编辑

`proxy_url`编辑

`proxy_use_local_resolver`编辑

`index`edit

`ssl`edit

`timeout`edit

`max_retries`edit

`bulk_max_size`edit

`slow_start`edit

`backoff.init`edit

`backoff.max`edit