> For the complete documentation index, see [llms.txt](https://ilogtail.gitbook.io/ilogtail-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ilogtail.gitbook.io/ilogtail-docs/pre-release/plugins/shu-chu-cha-jian/kuo-zhan-shu-chu-cha-jian/flusher-elasticsearch.md). # ElasticSearch ## 简介 `flusher_elasticsearch` `flusher`插件可以实现将采集到的数据，经过处理后，发送到 ElasticSearch，需要 ElasticSearch 版本至少为 `8`。 ## 事件能力 列含义见 [概览 · 事件能力列说明](https://ilogtail.gitbook.io/ilogtail-docs/pre-release/plugins/shu-chu-cha-jian/kuo-zhan-shu-chu-cha-jian/pages/V3l051tHPlzCBkmzOfvu#事件能力列说明)。 | v1 接口 | v2 接口 | Log | Metric | Span | | ----- | ----- | ------ | ------ | ---- | | ✓ | ✓ | v1\&v2 | 透传未知 | 透传未知 | ## 版本 [Alpha](/ilogtail-docs/pre-release/plugins/stability-level.md) ## 版本说明 * 推荐版本：iLogtail v2.0.0 及以上 ## 配置参数 | 参数 | 类型 | 是否必选 | 说明 | | --------------------------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | | Type | string | 是 | 插件类型，固定为`flusher_elasticsearch` | | Addresses | String数组 | 是 | ElasticSearch 地址 | | Convert | Struct | 否 | LoongCollector 数据转换协议配置 | | Convert.Protocol | string | 否 | LoongCollector 数据转换协议，elasticsearch flusher 可选值：`custom_single`,`custom_single_flatten`,`otlp_log_v1`。默认值：`custom_single` | | Convert.Encoding | string | 否 | LoongCollector Flusher 数据转换编码，可选值：`json`、`none`、`protobuf`，默认值：`json` | | Convert.TagFieldsRename | Map | 否 | 对日志中tags中的json字段重命名 | | Convert.ProtocolFieldsRename | Map | 否 | LoongCollector 日志协议字段重命名，可当前可重命名的字段：`contents`,`tags`和`time` | | Index | string | 是 | 插入数据目标索引 | | Authentication | Struct | 是 | ElasticSearch 连接访问认证配置 | | Authentication.PlainText.Username | string | 是 | ElasticSearch 用户名 | | Authentication.PlainText.Password | string | 是 | ElasticSearch 密码 | | Authentication.TLS.Enabled | bool | 否 | 是否启用 TLS 安全连接, | | Authentication.TLS.CAFile | string | 否 | TLS CA 根证书文件路径 | | Authentication.TLS.CertFile | string | 否 | TLS 连接证书文件路径 | | Authentication.TLS.KeyFile | string | 否 | TLS 连接私钥文件路径 | | Authentication.TLS.MinVersion | string | 否 | TLS 支持协议最小版本，可选配置：`1.0, 1.1, 1.2, 1.3`,默认：`1.2` | | Authentication.TLS.MaxVersion | string | 否 | TLS 支持协议最大版本,可选配置：`1.0, 1.1, 1.2, 1.3`,默认采用：`crypto/tls`支持的版本，当前`1.3` | | HTTPConfig.MaxIdleConnsPerHost | int | 否 | 每个host的连接池最大空闲连接数 | | HTTPConfig.ResponseHeaderTimeout | string | 否 | 读取头部的时间限制，可选配置`Nanosecond`，`Microsecond`，`Millisecond`，`Second`，`Minute`，`Hour` | ## Elasticsearch动态索引格式化 开发插件往`Elasticsearch`写入数据时。用户往往存在一些动态索引的需求，动态索引和kafka的动态topic稍微有些区别。 动态索引常见的使用场景如下： * 按照业务字段标识动态创建索引，和`Kafka`的动态`topic`一样。 * 基于时间的索引创建，按天、按周、按月等。在`ELK`社区例常见的案例：`%{+yyyy.MM.dd}`基于天创建，`%{+yyyy.ww}`基于周创建 结合两种需求，动态索引的创建规则如下： * `%{content.fieldname}`。`content`代表从`contents`中取指定字段值 * `%{tag.fieldname}`,`tag`表示从`tags`中取指定字段值，例如：`%{tag.k8s.namespace.name}` * `${env_name}`, 使用`$`符直接从环境变量中获取，从`1.5.0`版本支持 * `%{+yyyy.MM.dd}`,按天创建，注意表达式前面时间格式前面的`+`符号不能缺少。 * `%{+yyyy.ww}`，按周创建，还有其他时间格式就不一一举例。由于`golang`时间格式看起来不是非常人性化， 表达式使用上直接参考`ELK`社区的格式。 格式化动态索引的函数如下： ```go func FormatIndex(targetValues map[string]string, indexPattern string, indexTimestamp uint32) (*string, error) ``` * `targetValues`使用Convert协议转换处理后需要替换的键值对。可参考`flusher_kafka_v2`中的对`ToByteStreamWithSelectedFields`的使用。 * `indexPattern`动态索引表达式。 * `indexTimestamp`和`Log`这个pb中的time字段类型一致方便可以使用日志中的时间来格式化动态索引。 ## 样例 ### 常规索引 采集`/home/test-log/`路径下的所有文件名匹配`*.log`规则的文件，并将采集结果发送到 ElasticSearch。 ```yaml enable: true inputs: - Type: input_file FilePaths: - /home/test-log/*.log flushers: - Type: flusher_elasticsearch Addresses: - http://192.XX.XX.1:9092 - http://192.XX.XX.2:9092 Index: default Authentication: PlainText: Username: user Password: 123456 HTTPConfig: MaxIdleConnsPerHost: 10 ResponseHeaderTimeout: Second ``` ### 动态索引 采集结果支持写入`ElasticSearch`动态索引，例如，数据写入到一个名字包含当前日期的索引，可以这样写（只提供`flushers`）。 ```yaml flushers: - Type: flusher_elasticsearch Addresses: - http://192.XX.XX.1:9092 - http://192.XX.XX.2:9092 Index: log_%{+yyyyMMdd} Authentication: PlainText: Username: user Password: 123456 ``` ### 数据平铺写入 自 **1.8.0** 起（同仓历史版本号，旧文档常写作 iLogtail）新增数据平铺协议 `custom_single_flatten`，对 `contents`、`tags` 和 `time` 三个 `convert` 层协议字段中的数据做一级打平。 当前`convert`协议在单条数据处理仅支持`json`编码，因此`custom_single_flatten`需要配合`json`编码一起使用。 ```yaml enable: true inputs: - Type: input_file FilePaths: - /home/test-log/*.log flushers: - Type: flusher_elasticsearch Addresses: - http://192.XX.XX.1:9092 - http://192.XX.XX.2:9092 Convert: Protocol: custom_single_flatten Encoding: json Index: default ``` 非平铺前写入`ElasticSearch`的数据格式 ```json { "contents": { "class": "org.springframework.web.servlet.DispatcherServlet@initServletBean:547", "application": "springboot-docker", "level": "ERROR", "message": "Completed initialization in 9 ms", "thread": "http-nio-8080-exec-10", "@time": "2022-07-20 16:55:05.415" }, "tags": { "k8s.namespace.name":"java_app", "host.ip": "192.168.6.128", "host.name": "master", "log.file.path": "/data/test.log" }, "time": 1664435098 } ``` 使用平铺协议后`custom_single_flatten`，`json`全部被一级平铺。 ```json { "class": "org.springframework.web.servlet.DispatcherServlet@initServletBean:547", "application": "springboot-docker", "level": "ERROR", "message": "Completed initialization in 9 ms", "thread": "http-nio-8080-exec-10", "@time": "2022-07-20 16:55:05.415", "k8s.namespace.name":"java_app", "host.ip": "192.168.6.128", "host.name": "master", "log.file.path": "/data/test.log", "time": 1664435098 } ```