配置 Elasticsearch 输出
编辑配置 Elasticsearch 输出
编辑Elasticsearch 输出使用 Elasticsearch HTTP API 直接将事件发送到 Elasticsearch。
配置示例
当通过 elasticsearch
输出将数据发送到安全集群时,Heartbeat 可以使用以下任何一种身份验证方法:
- 基本身份验证凭据(用户名和密码)。
- 基于令牌(API 密钥)的身份验证。
- 公钥基础设施 (PKI) 证书。
基本身份验证
output.elasticsearch: hosts: ["https://myEShost:9200"] username: "heartbeat_writer" password: "YOUR_PASSWORD"
API 密钥身份验证
output.elasticsearch: hosts: ["https://myEShost:9200"] api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA"
PKI 证书身份验证
output.elasticsearch: hosts: ["https://myEShost:9200"] ssl.certificate: "/etc/pki/client/cert.pem" ssl.key: "/etc/pki/client/cert.key"
有关每种身份验证方法的详细信息,请参阅与 Elasticsearch 的安全通信。
兼容性
编辑此输出适用于所有兼容版本的 Elasticsearch。请参阅Elastic 支持矩阵。
或者,您可以将 Heartbeat 设置为仅连接到版本至少与 Beat 相同的实例。可以通过将 output.elasticsearch.allow_older_versions
设置为 false
来启用检查。将设置保留为其默认值 true
可以避免在 Heartbeat 升级到高于 Elastic Stack 的版本后无法连接到 Elasticsearch 的问题。
配置选项
编辑您可以在 heartbeat.yml
配置文件的 elasticsearch
部分中指定以下选项:
hosts
编辑要连接的 Elasticsearch 节点列表。事件以轮询顺序分发到这些节点。如果一个节点变得无法访问,则事件会自动发送到另一个节点。每个 Elasticsearch 节点都可以定义为 URL
或 IP:PORT
。例如:http://192.15.3.2
、https://es.found.io:9230
或 192.24.3.2:9300
。如果未指定端口,则使用 9200
。
output.elasticsearch: hosts: ["10.45.3.2:9220", "10.45.3.1:9230"] protocol: https path: /elasticsearch
在前面的示例中,Elasticsearch 节点在 https://10.45.3.2:9220/elasticsearch
和 https://10.45.3.1:9230/elasticsearch
可用。
compression_level
编辑gzip 压缩级别。将此值设置为 0
将禁用压缩。压缩级别必须在 1
(最佳速度)到 9
(最佳压缩)的范围内。
提高压缩级别将减少网络使用量,但会增加 CPU 使用量。
默认值为 1
。
worker
或 workers
编辑每个配置的主机将事件发布到 Elasticsearch 的 worker 数量。这最好与启用的负载均衡模式一起使用。示例:如果您有 2 个主机和 3 个 worker,则总共启动 6 个 worker(每个主机 3 个)。
默认值为 1
。
loadbalance
编辑当设置 loadbalance: true
时,Heartbeat 连接到所有配置的主机并通过所有连接并行发送数据。如果连接失败,则数据将发送到剩余的主机,直到可以重新建立连接。只要 Heartbeat 可以连接到至少一个配置的主机,就会继续发送数据。
当设置 loadbalance: false
时,Heartbeat 一次将数据发送到单个主机。目标主机从配置的主机列表中随机选择,所有数据都发送到该目标,直到连接失败,然后选择新的目标。只要 Heartbeat 可以连接到至少一个配置的主机,就会继续发送数据。
默认值为 true
。
output.elasticsearch: hosts: ["localhost:9200", "localhost:9201"] loadbalance: true
api_key
编辑您可以不使用用户名和密码,而是使用 API 密钥来保护与 Elasticsearch 的通信。该值必须是 API 密钥的 ID 和 API 密钥,以冒号连接:id:api_key
。
有关详细信息,请参阅使用 API 密钥授予访问权限。
password
编辑用于连接到 Elasticsearch 的基本身份验证密码。
parameters
编辑要在索引操作中通过 URL 传递的 HTTP 参数字典。
protocol
编辑Elasticsearch 可访问的协议名称。选项为:http
或 https
。默认值为 http
。但是,如果您为hosts
指定 URL,则 protocol
的值将被您在 URL 中指定的任何 scheme 覆盖。
path
编辑附加到 HTTP API 调用的 HTTP 路径前缀。这对于 Elasticsearch 在 HTTP 反向代理后面侦听的情况非常有用,该反向代理在自定义前缀下导出 API。
headers
编辑要添加到 Elasticsearch 输出创建的每个请求的自定义 HTTP 标头。示例
output.elasticsearch.headers: X-My-Header: Header contents
可以通过用逗号分隔同一标头名称的多个标头值。
proxy_disable
编辑如果设置为 true
,则所有代理设置(包括 HTTP_PROXY
和 HTTPS_PROXY
变量)都将被忽略。
proxy_url
编辑连接到 Elasticsearch 服务器时要使用的代理的 URL。该值必须是完整的 URL。如果未通过配置文件指定值,则使用代理环境变量。有关环境变量的更多信息,请参阅Go 文档。
proxy_headers
编辑在 CONNECT 请求期间要发送到代理的其他标头。
index
编辑写入事件的索引目标。可以指向索引、别名或数据流。使用每日索引时,这将是索引名称。默认值为 "heartbeat-%{[agent.version]}-%{+yyyy.MM.dd}"
,例如 "heartbeat-8.17.0-2024-12-13"
。如果您更改此设置,还需要配置 setup.template.name
和 setup.template.pattern
选项(请参阅Elasticsearch 索引模板)。
当索引生命周期管理 (ILM)启用时,默认 index
为 "heartbeat-%{[agent.version]}-%{+yyyy.MM.dd}-%{index_num}"
,例如 "heartbeat-8.17.0-2024-12-13-000001"
。启用 ILM 时,自定义 index
设置将被忽略。如果您将事件发送到支持索引生命周期管理的集群,请参阅索引生命周期管理 (ILM)以了解如何更改索引名称。
您可以通过使用格式字符串来访问任何事件字段来动态设置索引。例如,此配置使用自定义字段 fields.log_type
来设置索引:
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] index: "%{[fields.log_type]}-%{[agent.version]}-%{+yyyy.MM.dd}"
使用此配置,所有 log_type: normal
的事件都将发送到名为 normal-8.17.0-2024-12-13
的索引,而所有 log_type: critical
的事件都将发送到名为 critical-8.17.0-2024-12-13
的索引。
要了解如何将自定义字段添加到事件中,请参阅 fields
选项。
有关动态设置索引的其他方法,请参阅 indices
设置。
indices
编辑索引选择器规则的数组。每个规则指定用于匹配该规则的事件的索引。在发布期间,Heartbeat 使用数组中的第一个匹配规则。规则可以包含条件、基于格式字符串的字段和名称映射。如果缺少 indices
设置或没有规则匹配,则使用 index
设置。
与 index
类似,定义自定义的 indices
将禁用索引生命周期管理 (ILM)。
规则设置
-
index
- 要使用的索引格式字符串。如果此字符串包含字段引用,例如
%{[fields.name]}
,则这些字段必须存在,否则规则将失败。 -
mappings
- 一个字典,它接受
index
返回的值并将其映射到一个新名称。 -
default
- 如果
mappings
未找到匹配项,则要使用的默认字符串值。 -
when
- 必须成功才能执行当前规则的条件。处理器支持的所有条件也在此处支持。
以下示例根据 message
字段是否包含指定的字符串来设置索引
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] indices: - index: "warning-%{[agent.version]}-%{+yyyy.MM.dd}" when.contains: message: "WARN" - index: "error-%{[agent.version]}-%{+yyyy.MM.dd}" when.contains: message: "ERR"
此配置将生成名为 warning-8.17.0-2024-12-13
和 error-8.17.0-2024-12-13
的索引(如果未找到匹配项,则使用默认索引)。
以下示例通过获取 index
格式字符串返回的名称并将其映射到用于索引的新名称来设置索引
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] indices: - index: "%{[fields.log_type]}" mappings: critical: "sev1" normal: "sev2" default: "sev3"
此配置将生成名为 sev1
、 sev2
和 sev3
的索引。
mappings
设置简化了配置,但仅限于字符串值。您不能在映射对中指定格式字符串。
pipeline
编辑一个格式字符串值,指定要将事件写入的摄取管道。
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] pipeline: my_pipeline_id
有关更多信息,请参阅使用摄取管道解析数据。
您可以通过使用格式字符串访问任何事件字段来动态设置摄取管道。例如,此配置使用自定义字段 fields.log_type
来为每个事件设置管道
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] pipeline: "%{[fields.log_type]}_pipeline"
通过此配置,所有 log_type: normal
的事件都将发送到名为 normal_pipeline
的管道,所有 log_type: critical
的事件都将发送到名为 critical_pipeline
的管道。
要了解如何将自定义字段添加到事件中,请参阅 fields
选项。
有关动态设置摄取管道的其他方法,请参阅pipelines
设置。
pipelines
编辑管道选择器规则的数组。每个规则指定要用于与规则匹配的事件的摄取管道。在发布期间,Heartbeat 将使用数组中第一个匹配的规则。规则可以包含条件、基于格式字符串的字段和名称映射。如果缺少 pipelines
设置或没有规则匹配,则使用pipeline
设置。
规则设置
-
pipeline
- 要使用的管道格式字符串。如果此字符串包含字段引用,例如
%{[fields.name]}
,则这些字段必须存在,否则规则将失败。 -
mappings
- 一个字典,它接受
pipeline
返回的值并将其映射到一个新名称。 -
default
- 如果
mappings
未找到匹配项,则要使用的默认字符串值。 -
when
- 必须成功才能执行当前规则的条件。处理器支持的所有条件也在此处支持。
以下示例根据 message
字段是否包含指定的字符串将事件发送到特定的管道
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] pipelines: - pipeline: "warning_pipeline" when.contains: message: "WARN" - pipeline: "error_pipeline" when.contains: message: "ERR"
以下示例通过获取 pipeline
格式字符串返回的名称并将其映射到用于管道的新名称来设置管道
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] pipelines: - pipeline: "%{[fields.log_type]}" mappings: critical: "sev1_pipeline" normal: "sev2_pipeline" default: "sev3_pipeline"
通过此配置,所有 log_type: critical
的事件都将发送到 sev1_pipeline
,所有 log_type: normal
的事件都将发送到 sev2_pipeline
,所有其他事件都将发送到 sev3_pipeline
。
有关摄取管道的更多信息,请参阅使用摄取管道解析数据。
bulk_max_size
编辑单个 Elasticsearch 批量 API 索引请求中要批量处理的最大事件数。默认值为 1600。
事件可以收集到批次中。Heartbeat 将大于 bulk_max_size
的队列中读取的批次拆分为多个批次。
指定较大的批次大小可以通过降低发送事件的开销来提高性能。但是,较大的批次大小也可能会增加处理时间,这可能会导致 API 错误、连接中断、发布请求超时,并最终降低吞吐量。
将 bulk_max_size
设置为小于或等于 0 的值将禁用批次拆分。禁用拆分时,队列将决定批次中包含的事件数。
backoff.init
编辑在网络错误后尝试重新连接到 Elasticsearch 之前要等待的秒数。等待 backoff.init
秒后,Heartbeat 会尝试重新连接。如果尝试失败,则退避计时器会呈指数级增加,直到达到 backoff.max
。成功连接后,退避计时器将被重置。默认值为 1s
。
backoff.max
编辑在网络错误后尝试连接到 Elasticsearch 之前要等待的最大秒数。默认值为 60s
。
idle_connection_timeout
编辑空闲连接在关闭自身之前保持空闲的最大时长。零表示没有限制。格式为 Go 语言持续时间(例如,60s 为 60 秒)。默认值为 3s。
timeout
编辑Elasticsearch 请求的 http 请求超时时间,单位为秒。默认值为 90。
allow_older_versions
编辑默认情况下,Heartbeat 希望 Elasticsearch 实例的版本相同或更新,以提供最佳体验。我们建议您连接到相同的版本,以确保 Heartbeat 使用的所有功能在您的 Elasticsearch 实例中都可用。
您可以在更新 Elastic Stack 时禁用此检查,以便可以继续收集数据。
ssl
编辑用于 HTTPS 连接的 SSL 参数(例如要使用的证书颁发机构)的配置选项。如果缺少 ssl
部分,则主机 CA 将用于与 Elasticsearch 的 HTTPS 连接。
有关更多信息,请参阅保护与 Elasticsearch 的通信指南或SSL 配置参考。
non_indexable_policy
编辑指定当 elasticsearch 集群显式拒绝文档(例如,在映射冲突时)时的行为。
drop
编辑默认行为,当事件被 elasticsearch 显式拒绝时,将丢弃该事件。
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] non_indexable_policy.drop: ~
dead_letter_index
编辑此功能为 Beta 版,可能会发生更改。设计和代码不如官方 GA 功能成熟,并按原样提供,不提供任何保证。Beta 版功能不受官方 GA 功能的支持 SLA 的约束。
在显式拒绝时,此策略将在下一批次中重试该事件。但是,目标索引将更改为指定的索引。此外,事件的结构将更改为以下字段
- message
- 包含原始事件的转义 json。
- error.type
- 包含状态代码
- error.message
- 包含 elasticsearch 返回的状态,描述原因
-
index
- 将拒绝的事件发送到的索引。
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] non_indexable_policy.dead_letter_index: index: "my-dead-letter-index"
preset
编辑要应用于输出配置的性能预设。
output.elasticsearch: hosts: ["https://127.0.0.1:9200"] preset: balanced
性能预设根据所需的性能目标应用一组配置覆盖。如果设置了性能预设,则该预设将覆盖其他配置标志,以匹配该预设的推荐设置。有效选项为:* balanced
:通用效率的良好起点 * throughput
:适用于高数据量,可能会增加 CPU 和内存需求 * scale
:在大型低吞吐量部署中减少环境资源使用 * latency
:尽量减少新数据在 Elasticsearch 中可见的时间 * custom
:直接应用用户配置,不进行任何覆盖
如果未指定,则默认值为 custom
。
预设表示基于预期目标的当前建议;它们的效果可能会在版本之间更改,以更好地满足这些目标。目前,预设有以下效果
preset | balanced | throughput | scale | latency |
---|---|---|---|---|
1600 |
1600 |
1600 |
50 |
|
1 |
4 |
1 |
1 |
|
3200 |
12800 |
3200 |
4100 |
|
1600 |
1600 |
1600 |
2050 |
|
|
|
|
|
|
1 |
1 |
1 |
1 |
|
|
|
|
|
Elasticsearch API
编辑Heartbeat 将使用 Elasticsearch 中的 _bulk
API,事件将按其到达发布管道的顺序发送,单个 _bulk
请求可能包含来自不同输入/模块的事件。临时失败会重试。
将检查每个事件的状态代码并按如下方式处理
-
< 300
:该事件计为events.acked
-
409
(冲突):该事件计为events.duplicates
-
429
(请求过多):该事件计为events.toomany
-
> 399
和< 500
:应用non_indexable_policy
。