Table of Contents

1. 关于

2. 什么是iLogtail   1.1

3. 发展历史   1.2

4. 产品优势   1.3

5. 开源协议   1.4

6. 社区版和企业版的对比说明   1.5

8. 社区活动

9. 开源之夏 2024   2.1

1. iLogtail 社区项目介绍   2.1.1

1. iLogtail 数据吞吐性能优化   2.1.1.1

2. ConfigServer 能力升级 + 体验优化（全栈）   2.1.1.2

11. 安装

12. 快速开始   3.1

13. Docker使用   3.2

14. Kubernetes使用   3.3

15. 守护进程   3.4

16. 发布记录   3.5

17. 发布记录(1.x版本)   3.6

18. 支持的操作系统   3.7

19. 源代码   3.8

1. 下载   3.8.1

2. 编译   3.8.2

3. Docker镜像   3.8.3

4. 编译依赖   3.8.4

20. 镜像站   3.9

22. 概念

23. 关键概念   4.1

25. 配置

26. 采集配置   5.1

27. 系统参数   5.2

28. 日志   5.3

30. 插件

31. 概览   6.1

32. 版本管理   6.2

33. 输入   6.3

1. 文本日志   6.3.1

2. 容器标准输出（原生插件）   6.3.2

3. 脚本执行数据   6.3.3

4. 容器标准输出   6.3.4

5. 文本日志（debug）   6.3.5

6. MetricInput示例插件   6.3.6

7. 主机Meta数据   6.3.7

8. Mock数据-Metric   6.3.8

9. eBPF网络调用数据   6.3.9

10. 主机监控数据   6.3.10

11. MySQL Binlog   6.3.11

12. GO Profile   6.3.12

13. GPU数据   6.3.13

14. HTTP数据   6.3.14

15. ServiceInput示例插件   6.3.15

16. Journal数据   6.3.16

17. Kafka   6.3.17

18. Mock数据-Service   6.3.18

19. SqlServer 查询数据   6.3.19

20. OTLP数据   6.3.20

21. PostgreSQL 查询数据   6.3.21

22. Syslog数据   6.3.22

23. eBPF文件安全数据   6.3.23

24. eBPF网络可观测数据   6.3.24

25. eBPF网络安全数据   6.3.25

26. eBPF进程安全数据   6.3.26

34. 处理   6.4

1. 原生插件   6.4.1

1. 正则解析   6.4.1.1

2. 分隔符解析   6.4.1.2

3. Json解析   6.4.1.3

4. 时间解析   6.4.1.4

5. 过滤   6.4.1.5

6. 脱敏   6.4.1.6

2. 扩展插件   6.4.2

1. 添加字段   6.4.2.1

2. 添加云资产信息   6.4.2.2

3. 原始数据   6.4.2.3

4. 数据脱敏   6.4.2.4

5. 丢弃字段   6.4.2.5

6. 字段加密   6.4.2.6

7. 条件字段处理   6.4.2.7

8. 日志过滤   6.4.2.8

9. Go时间格式解析   6.4.2.9

10. Grok   6.4.2.10

11. Json   6.4.2.11

12. 日志转SLS Metric   6.4.2.12

13. 正则   6.4.2.13

14. 重命名字段   6.4.2.14

15. 分隔符   6.4.2.15

16. 键值对   6.4.2.16

17. 多行切分   6.4.2.17

18. 字符串替换   6.4.2.18

35. 聚合   6.5

1. 基础   6.5.1

2. 上下文   6.5.2

3. 按Key分组   6.5.3

4. 按GroupMetadata分组   6.5.4

36. 输出   6.6

1. Kafka（Deprecated）   6.6.1

2. kafkaV2   6.6.2

3. ClickHouse   6.6.3

4. ElasticSearch   6.6.4

5. SLS   6.6.5

6. 标准输出/文件   6.6.6

7. OTLP日志   6.6.7

8. Pulsar   6.6.8

9. HTTP   6.6.9

10. Loki   6.6.10

37. 扩展   6.7

1. BasicAuth鉴权   6.7.1

2. 协议解码/反序列化   6.7.2

3. 协议编码/序列化   6.7.3

4. 数据筛选   6.7.4

5. 请求熔断   6.7.5

39. 工作原理

40. 文件发现   7.1

41. 插件系统   7.2

43. 可观测性

44. 日志   8.1

46. 开发者指南

47. 开发环境   9.1

48. 日志协议   9.2

1. 协议转换   9.2.1

2. 增加新的日志协议   9.2.2

3. [协议]   9.2.3

1. sls协议   9.2.3.1

2. 单条协议   9.2.3.2

49. 代码风格   9.3

50. 数据模型   9.4

51. 插件开发   9.5

1. 开源插件开发引导   9.5.1

2. Checkpoint接口   9.5.2

3. Logger接口   9.5.3

4. 自监控指标接口   9.5.4

5. 如何开发Input插件   9.5.5

6. 如何开发Processor插件   9.5.6

7. 如何开发Aggregator插件   9.5.7

8. 如何开发Flusher插件   9.5.8

9. 如何生成插件文档   9.5.9

10. 插件文档规范   9.5.10

11. 纯插件模式启动   9.5.11

52. 测试   9.6

1. 单元测试   9.6.1

2. E2E测试   9.6.2

53. 代码检查   9.7

1. 检查代码规范   9.7.1

2. 检查文件许可证   9.7.2

3. 检查依赖包许可证   9.7.3

55. 贡献指南

56. 贡献指南   10.1

57. 开发者   10.2

58. 成就   10.3

60. 性能测试

61. 容器场景iLogtail与Filebeat性能对比测试   11.1

63. 管控工具

64. 使用介绍   12.1

65. 通信协议   12.2

66. 开发指南   12.3

68. Awesome iLogtail

69. 走近iLogtail社区版   13.1

70. iLogtail社区版使用入门   13.2

71. iLogtail社区版开发者指南   13.3

72. iLogtail社区版使用案例   13.4

什么是iLogtail

iLogtail 为可观测场景而生，拥有的轻量级、高性能、自动化配置等诸多生产级别特性，在阿里巴巴以及外部数万家阿里云客户内部广泛应用。你可以将它部署于物理机，虚拟机，Kubernetes等多种环境中来采集遥测数据，例如logs、traces和metrics。

核心优势

- 支持多种Logs、Traces、Metrics数据采集，尤其对容器、Kubernetes环境支持非常友好

- 数据采集资源消耗极低，相比同类遥测数据采集的Agent性能好5-20倍

- 高稳定性，在阿里巴巴以及数万阿里云客户生产中使用验证，部署量近千万，每天采集数十PB可观测数据

- 支持插件化扩展，可任意扩充数据采集、处理、聚合、发送模块

- 支持配置远程管理，支持以图形化、SDK、K8s Operator等方式进行配置管理，可轻松管理百万台机器的数据采集

- 支持自监控、流量控制、资源控制、主动告警、采集统计等多种高级特性

功能

iLogtail 支持收集多种遥测数据并将其传输到多种不同的后端，例如 SLS可观测平台 。 支持采集的数据主要如下:

- Logs

- 收集静态日志文件

- 在容器化环境中运行时动态收集文件

- 在容器化环境中运行时动态收集 Stdout

- Traces

- OpenTelemetry 协议

- Skywalking V2 协议

- Skywalking V3 协议

- ...

- Metrics

- Node指标

- Process指标

- GPU 指标

- Nginx 指标

- 支持获取Prometheus指标

- 支持收集Telegraf指标

- ...

快速开始

由于C++编译环境较为复杂，iLogtail的编译依赖docker。如果想从源码编译iLogtail，可以执行下面的命令：

make

cp example/quick_start/* output

cd output

./ilogtail

# 现在ilogtail已经开始采集output/simple.log文件并输出到标准输出了

如果你对细节感兴趣，请参见文档编译。

RoadMap

iLogtail 发展规划：RoadMap

贡献

- 贡献指南

- 开发者

- 成就

我们的用户

目前来自阿里云、石墨文档、同程旅行、小红书、字节跳动、哔哩哔哩、嘀嗒出行的多位同学在参与 iLogtail 社区的共建。

Licence

Apache 2.0 许可证

联系我们

您可以通过Github Issues 或 Github Discussions 报告bug、提出建议或参与讨论。也可以通过以下方式联系我们：

- 微信公众号：日志服务

- 哔哩哔哩：阿里云SLS

- 知乎：iLogtail社区

- 交流群请扫描

发展历史

秉承着阿里人简单的特点，iLogtail的命名也非常简单，我们最开始期望的就是能够有一个统一去Tail日志的工具，所以就叫做Logtail，添加上“i”的原因主要当时使用了inotify的技术，能够让日志采集的延迟控制在毫秒级，因此最后叫做iLogtail。从2013年开始研发，iLogtail整个发展历程概括起来大致可以分为四个阶段，分别是飞天5K阶段、阿里集团阶段、云原生阶段和开源共建阶段。

飞天5K阶段

作为中国云计算领域的里程碑，2013年8月15日，阿里巴巴集团正式运营服务器规模达到5000（5K）的“飞天”集群，成为中国第一个独立研发拥有大规模通用计算平台的公司，也是世界上第一个对外提供5K云计算服务能力的公司。飞天5K项目从2009年开始，从最开始的30台逐渐发展到5000，不断解决系统核心的问题，比如说规模、稳定性、运维、容灾等等。而iLogtail在这一阶段诞生，最开始就是要解决5000台机器的监控、问题分析、定位的工作（如今的词语叫做“可观测性”）。从30到5000的跃升中，对于可观测问题有着诸多的挑战，包括单机瓶颈、问题复杂度、排查便捷性、管理复杂度等。

在5K阶段，iLogtail本质上解决的是从单机、小规模集群到大规模的运维监控挑战，这一阶段iLogtail主要的特点有：

- 功能：实时日志、监控采集，日志抓取延迟毫秒级

- 性能：单核处理能力10M/s，5000台集群平均资源占用0.5%CPU核

- 可靠性：自动监听新文件、新文件夹，支持文件轮转，处理网络中断

- 管理：远程Web管理，配置文件自动下发

- 运维：加入集团yum源，运行状态监控，异常自动上报

- 规模：3W+部署规模，上千采集配置项，日10TB数据

阿里集团阶段

iLogtail在阿里云飞天5K项目中的应用解决了日志、监控统一收集的问题，而当时阿里巴巴集团、蚂蚁等还缺少一套统一、可靠的日志采集系统，因此我们开始推动iLogtail作为集团、蚂蚁的日志采集基础设施。从5K这种相对独立的项目到全集团应用，不是简单复制的问题，而我们要面对的是更多的部署量、更高的要求以及更多的部门：

1. 百万规模运维问题：此时整个阿里、蚂蚁的物理机、虚拟机超过百万台，我们希望只用1/3的人力就可以运维管理百万规模的Logtail

2. 更高的稳定性：iLogtail最开始采集的数据主要用于问题排查，集团广泛的应用场景对于日志可靠性要求越来越高，例如计费计量数据、交易数据，而且还需要满足双十一、双十二等超大数据流量的压力考验。

3. 多部门、团队：从服务5K团队到近千个团队，会有不同的团队使用不同的iLogtail，而一个iLogtail也会被多个不同的团队使用，在租户隔离上对iLogtail是一个新的挑战。

经过几年时间和阿里集团、蚂蚁同学的合作打磨，iLogtail在多租户、稳定性等方面取得了非常大的进步，这一阶段iLogtail主要的特点有：

- 功能：支持更多的日志格式，例如正则、分隔符、JSON等，支持多种日志编码方式，支持数据过滤、脱敏等高级处理

- 性能：极简模式下提升到单核100M/s，正则、分隔符、JSON等方式20M/s+

- 可靠性：采集可靠性支持Polling、轮转队列顺序保证、日志清理保护、CheckPoint增强；进程可靠性增加Critical自恢复、Crash自动上报、多级守护

- 多租户：支持全流程多租户隔离、多级高低水位队列、采集优先级、配置级/进程级流量控制、临时降级机制

- 运维：基于集团StarAgent自动安装与守护，异常主动通知，提供多种问题自查工具

- 规模：百万+部署规模，千级别内部租户，10万+采集配置，日采集PB级数据

云原生阶段

随着阿里所有IT基础设施全面云化，以及iLogtail所属产品SLS（日志服务）正式在阿里云上商业化，iLogtail开始全面拥抱云原生。从阿里内部商业化并对外部各行各业的公司提供服务，对于iLogtail的挑战的重心已经不是性能和可靠性，而是如何适应云原生（容器化、K8s，适应云上环境）、如何兼容开源协议、如何去处理碎片化需求。这一阶段是iLogtail发展最快的时期，经历了非常多重要的变革：

- 统一版本：iLogtail最开始的版本还是基于GCC4.1.2编译，代码还依赖飞天基座，为了能适用更多的环境，iLogtail进行了全版本的重构，基于一套代码实现Windows/Linux、X86/Arm、服务器/嵌入式等多种环境的编译发版

- 全面支持容器化、K8s：除了支持容器、K8s环境的日志、监控采集外，对于配置管理也进行了升级，支持通过Operator的方式进行扩展，只需要配置一个AliyunLogConfig的K8s自定义资源就可以实现日志、监控的采集

- 插件化扩展：iLogtail增加插件系统，可自由扩展Input、Processor、Aggregator、Flusher插件用以实现各类自定义的功能

- 规模：千万部署规模，数万内外部客户，百万+采集配置项，日采集数十PB数据

开源共建阶段

闭源自建的软件永远无法紧跟时代潮流，尤其在当今云原生的时代，我们坚信开源才是iLogtail最优的发展策略，也是释放其最大价值的方法。iLogtail作为可观测领域最基础的软件，我们将之开源，也希望能够和开源社区一起共建，持续优化，争取成为世界一流的可观测数据采集器。对于未来iLogail的发展，我们期待：

1. iLogtail在性能和资源占用上相比其他开源采集软件具备一定优势，相比开源软件，在千万部署规模、日数十PB数据的规模性下为我们减少了100TB的内存和每年1亿的CPU核小时数。我们也希望这款采集软件可以为更多的企业带来资源效率的提升，实现可观测数据采集的“共同富裕”。

2. 目前iLogtail还只是在阿里内部以及很小一部分云上企业在使用，面对的场景相对还较少，我们希望有更多不同行业、不同特色的公司可以使用iLogtail并对其提出更多的数据源、处理、输出目标的需求，丰富iLogtail支持的上下游生态。

3. 性能、稳定性是iLogtail的最基本追求，我们也希望能够通过开源社区，吸引更多优秀的开发者，一起共建iLogtail，持续提升这款可观测数据采集器的性能和稳定性。

产品优势

对于可观测数据的采集，有很多开源的采集器，例如Logstash、Fluentd、Filebeats等。这些采集器的功能非常丰富，但在性能、稳定性、管控能力等关键特性方面iLogtail因其独特设计而具备优势。

分类

对比项

iLogtail社区版

某开源选择1

某开源选择2

采集方式

宿主机文件

支持

支持

支持

container文件

支持自动发现

静态采集

静态采集

container stdout

支持自动发现

插件扩展

Docker driver

数据处理

处理方式

插件扩展及C++加速插件

插件扩展

插件扩展

自动打标

支持

不支持k8s

不支持k8s

过滤

插件扩展及C++加速插件

插件扩展

插件扩展

性能

采集性能

极简单核160M/s、正则20M/s

单核2M/s左右

单核3-5M/s

资源消耗

平均CPU 2%、内存40M

10倍以上性能消耗

10倍以上性能消耗

可靠性

数据保存

支持

插件支持

插件支持

采集点位保存

所有均支持

只支持文件

插件支持

监控

本地监控

支持

支持

支持

服务端监控

后续支持

支持简单功能

辅助监控软件扩展

开源协议

iLogtail，包括内核、插件和工具均遵循Apache License v2.0分发：

Apache License

Version 2.0, January 2004

http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,

and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by

the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all

other entities that control, are controlled by, or are under common

control with that entity. For the purposes of this definition,

"control" means (i) the power, direct or indirect, to cause the

direction or management of such entity, whether by contract or

otherwise, or (ii) ownership of fifty percent (50%) or more of the

outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity

exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,

including but not limited to software source code, documentation

source, and configuration files.

"Object" form shall mean any form resulting from mechanical

transformation or translation of a Source form, including but

not limited to compiled object code, generated documentation,

and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or

Object form, made available under the License, as indicated by a

copyright notice that is included in or attached to the work

(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object

form, that is based on (or derived from) the Work and for which the

editorial revisions, annotations, elaborations, or other modifications

represent, as a whole, an original work of authorship. For the purposes

of this License, Derivative Works shall not include works that remain

separable from, or merely link (or bind by name) to the interfaces of,

the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including

the original version of the Work and any modifications or additions

to that Work or Derivative Works thereof, that is intentionally

submitted to Licensor for inclusion in the Work by the copyright owner

or by an individual or Legal Entity authorized to submit on behalf of

the copyright owner. For the purposes of this definition, "submitted"

means any form of electronic, verbal, or written communication sent

to the Licensor or its representatives, including but not limited to

communication on electronic mailing lists, source code control systems,

and issue tracking systems that are managed by, or on behalf of, the

Licensor for the purpose of discussing and improving the Work, but

excluding communication that is conspicuously marked or otherwise

designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity

on behalf of whom a Contribution has been received by Licensor and

subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of

this License, each Contributor hereby grants to You a perpetual,

worldwide, non-exclusive, no-charge, royalty-free, irrevocable

copyright license to reproduce, prepare Derivative Works of,

publicly display, publicly perform, sublicense, and distribute the

Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of

this License, each Contributor hereby grants to You a perpetual,

worldwide, non-exclusive, no-charge, royalty-free, irrevocable

(except as stated in this section) patent license to make, have made,

use, offer to sell, sell, import, and otherwise transfer the Work,

where such license applies only to those patent claims licensable

by such Contributor that are necessarily infringed by their

Contribution(s) alone or by combination of their Contribution(s)

with the Work to which such Contribution(s) was submitted. If You

institute patent litigation against any entity (including a

cross-claim or counterclaim in a lawsuit) alleging that the Work

or a Contribution incorporated within the Work constitutes direct

or contributory patent infringement, then any patent licenses

granted to You under this License for that Work shall terminate

as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the

Work or Derivative Works thereof in any medium, with or without

modifications, and in Source or Object form, provided that You

meet the following conditions:

(a) You must give any other recipients of the Work or

Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices

stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works

that You distribute, all copyright, patent, trademark, and

attribution notices from the Source form of the Work,

excluding those notices that do not pertain to any part of

the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its

distribution, then any Derivative Works that You distribute must

include a readable copy of the attribution notices contained

within such NOTICE file, excluding those notices that do not

pertain to any part of the Derivative Works, in at least one

of the following places: within a NOTICE text file distributed

as part of the Derivative Works; within the Source form or

documentation, if provided along with the Derivative Works; or,

within a display generated by the Derivative Works, if and

wherever such third-party notices normally appear. The contents

of the NOTICE file are for informational purposes only and

do not modify the License. You may add Your own attribution

notices within Derivative Works that You distribute, alongside

or as an addendum to the NOTICE text from the Work, provided

that such additional attribution notices cannot be construed

as modifying the License.

You may add Your own copyright statement to Your modifications and

may provide additional or different license terms and conditions

for use, reproduction, or distribution of Your modifications, or

for any such Derivative Works as a whole, provided Your use,

reproduction, and distribution of the Work otherwise complies with

the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,

any Contribution intentionally submitted for inclusion in the Work

by You to the Licensor shall be under the terms and conditions of

this License, without any additional terms or conditions.

Notwithstanding the above, nothing herein shall supersede or modify

the terms of any separate license agreement you may have executed

with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade

names, trademarks, service marks, or product names of the Licensor,

except as required for reasonable and customary use in describing the

origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or

agreed to in writing, Licensor provides the Work (and each

Contributor provides its Contributions) on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or

implied, including, without limitation, any warranties or conditions

of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A

PARTICULAR PURPOSE. You are solely responsible for determining the

appropriateness of using or redistributing the Work and assume any

risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,

whether in tort (including negligence), contract, or otherwise,

unless required by applicable law (such as deliberate and grossly

negligent acts) or agreed to in writing, shall any Contributor be

liable to You for damages, including any direct, indirect, special,

incidental, or consequential damages of any character arising as a

result of this License or out of the use or inability to use the

Work (including but not limited to damages for loss of goodwill,

work stoppage, computer failure or malfunction, or any and all

other commercial damages or losses), even if such Contributor

has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing

the Work or Derivative Works thereof, You may choose to offer,

and charge a fee for, acceptance of support, warranty, indemnity,

or other liability obligations and/or rights consistent with this

License. However, in accepting such obligations, You may act only

on Your own behalf and on Your sole responsibility, not on behalf

of any other Contributor, and only if You agree to indemnify,

defend, and hold each Contributor harmless for any liability

incurred by, or claims asserted against, such Contributor by reason

of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

社区版和企业版的对比说明

分类

比较项

社区版

商业版

部署方式

Linux

支持

支持

Windows

暂不支持

支持

Kubernetes DaemonSet

支持

支持

Kubernetes Sidecar

支持

支持

Kubernetes Operator

暂不支持

支持

采集能力

Log

支持

支持

Trace

支持

支持

Metrics

支持

支持

数据处理

支持

支持

采集性能

单核采集性能

极简100M/s，正则20M/s

极简100M/s，正则20M/s

支持配置数

2000+

2000+

安装部署

自动化程度

单机部署或第三方工具

阿里云自动化原生支持

第三方Agent集成

仅支持数据对接

支持自动安装第三方Agent

配置管理

配置UI

暂不支持

支持

本地配置管理

支持

支持

中心化配置管理

暂不支持

支持

SDK/API管理

不支持

支持

采集可靠性

自监控

支持

CloudLens for SLS

CheckPoint

支持

支持

日志上下文

不支持

支持

Exactly Once写入

不支持

支持（需手动打开）

高级管控能力

历史数据导入

支持

支持

多租户隔离

支持

支持

采集降级/恢复

支持

支持

自动安装/升级

不支持

支持

自身可观测

运行状态监控

本地日志

服务端可视化查看

采集数据统计

本地日志

服务端可视化查看

报错信息

本地日志

服务端可视化查看

机器组心跳监控

不支持

支持

自定义告警

不支持

支持

服务与支持

文档

基本的使用介绍

SLS官方提供企业应用场景下最全最及时的文档/最佳实践支持

服务

社区推动

及时的专家服务（工单、群支持）与需求承接。大规模/复杂场景专业化支持：比如K8s短job，单节点大流量日志、千级别日志目录

开源之夏 2024

活动介绍

开源之夏是由中国科学院软件研究所“开源软件供应链点亮计划”发起并长期支持的一项暑期开源活动，旨在鼓励在校学生积极参与开源软件的开发维护，培养和发掘更多优秀的开发者，促进优秀开源软件社区的蓬勃发展，助力开源软件供应链建设。活动联合各大开源社区，针对重要开源软件的开发与维护提供项目开发任务，并向全球高校学生开放报名。

开源之夏活动中的 iLogtail 社区主页。

如何参与

欢迎 iLogtail 社区学生成员报名参加活动。

学生可自主选择感兴趣的项目进行申请，中选后在项目开发者（社区导师）的指导下进行开发。根据项目的难易程度和完成情况，结项者将获取开源之夏活动奖金和结项证书。

关于报名、项目选择的说明和建议，参见学生指南与项目申请建议。

下面是活动的部分日程安排，请有意愿参加的同学关注：

- 04/30-06/04 学生报名、挑选项目、与导师沟通并准备项目申请材料、提交申请

- 06/05-06/25 项目申请审核

- 06/26 中选公示

- 06/26-06/30 项目预热

- 07/01-09/30 项目开发

- 10/01-10/31 导师结项审核-PR/MR 合并阶段

- 11/01-11/08 组委会结项审核-成果审核阶段

- 11/09 结项项目公示

- 11月 年度优秀学生评选

iLogtail 社区项目介绍

iLogtail 为本次开源之夏贡献了两个项目。宣传视频：iLogtail 社区开源之夏宣讲介绍

- iLogtail 数据吞吐性能优化

- ConfigServer 能力升级 + 体验优化（全栈）

iLogtail 数据吞吐性能优化

项目链接

https://summer-ospp.ac.cn/org/prodetail/246eb0231?lang=zh&list=pro

项目描述

iLogtail介绍

iLogtail 为可观测场景而生，拥有轻量级、高性能、自动化配置等诸多生产级别特性，在阿里巴巴以及外部数万家阿里云客户内部广泛应用。你可以将它部署于物理机，虚拟机，Kubernetes等多种环境中来采集可观测数据，例如logs、traces和metrics。目前来自阿里云、石墨文档、同程旅行、小红书、字节跳动、哔哩哔哩、嘀嗒出行的多位同学在参与 iLogtail 社区的共建。iLogtail 代码库：https://github.com/alibaba/ilogtail

iLogtail 数据接入介绍

iLogtail作为阿里云SLS提供的可观测数据采集器，可以运行在服务器、容器、K8s、嵌入式等多种环境，支持采集数百种可观测数据（日志、监控、Trace、事件等），已经有千万级的安装量。为了能够更好地实现与开源生态的融合并满足用户不断丰富的接入需求，我们为 iLogtail 引入了 Golang 实现的数据接入系统，目前，我们已通过该系统支持了若干数据源，包括 Kafka、OTLP、HTTP、MySQL Query、MySQL Binlog 等。

项目具体要求

Golang 实现的数据接入、处理、发送能力，效率上还是与 C++ 有差距。在 iLogtail 2.0 中，我们实现了 C++ 版本的数据处理流水线，希望将一些高频的数据源输出、解析、输出模块，升级到 C++ 版本，来提升 iLogtail 在这些场景的输入输出速率。

本次项目，我们旨在实现 Syslog 输入、Nginx 解析、Kafka 输出等高频使用模块的更高性能的 C++ 版本，来提升 iLogtail 的数据吞吐能力。升级后的版本需要满足下面的条件：

- 性能更优：

- Syslog 输入、Kafka 输出，相较于升级前的 Golang 版本，支持更高的读取/发送速率

- Nginx 解析速率需要高于 C++ 正则解析

- 内存优化：相同处理速率时，内存开销小于升级前的 Golang 版本

- 数据Tag管理：iLogtail内部的tag与输入/输出源的tag格式不一致，需要能够管理好tag间的转换。

- 数据完整性：满足“at least once”原则，保证不丢失数据

项目导师

阿柄（bingchang.cbc@alibaba-inc.com）

项目难度

进阶

技术领域标签

Kafka,TCP/IP,DataOps

编程语言标签

C++,Go

项目产出要求

1. 实现 C++ 版本的 Syslog 输入、Nginx 解析、Kafka 输出模块

2. 为实现的功能模块提供完善的说明文档和使用案例

3. 为实现的功能模块添加完善的测试

4. 编写实现的功能模块与 Golang 版本的性能对比测试报告

项目技术要求

1. 掌握C++，了解Golang

2. 了解 Kafka 客户端 API 和集群架构

3. 了解 syslog 协议及相关库函数

4. 了解 Git、GitHub 相关操作

5. 有开发高性能网络服务/插件经验更优

参考资料

什么是iLogtail：https://ilogtail.gitbook.io/ilogtail-docs

你好，iLogtail 2.0！：https://developer.aliyun.com/article/1441630

ConfigServer 能力升级 + 体验优化（全栈）

项目链接

https://summer-ospp.ac.cn/org/prodetail/246eb0236?lang=zh&list=pro

项目描述

iLogtail介绍

iLogtail 为可观测场景而生，拥有轻量级、高性能、自动化配置等诸多生产级别特性，在阿里巴巴以及外部数万家阿里云客户内部广泛应用。你可以将它部署于物理机，虚拟机，Kubernetes等多种环境中来采集可观测数据，例如logs、traces和metrics。目前来自阿里云、石墨文档、同程旅行、小红书、字节跳动、哔哩哔哩、嘀嗒出行的多位同学在参与 iLogtail 社区的共建。iLogtail 代码库：https://github.com/alibaba/ilogtail

ConfigServer介绍

目前可观测采集 Agent，例如 iLogtail 开源版，主要提供了本地采集配置管理模式，当涉及实例数较多时，需要逐个实例进行配置变更，管理比较复杂。此外，多实例场景下 Agent 的版本信息、运行状态等也缺乏统一的监控。为了解决这个问题，我们有了 ConfigServer 项目。 ConfigServer 是一款用于管控可观测采集 Agent 的工具，目前支持的功能有：

- 采集 Agent 注册到 ConfigServer

- 以 Agent 组的形式对采集 Agent 进行统一管理

- 远程批量管理采集 Agent 的采集配置

- 监控采集 Agent 的运行状态

- 管控UI

项目具体要求

ConfigServer 当前的部署不够灵活、管控能力不够全面，需要优化使用体验。本项目需要进行全栈开发，实现以下需求：

- 管控能力升级：支持多 Agent 组管控；支持 Agent 上报告警。

- 部署能力升级：支持容器化部署、开箱即用；支持分布式部署。

- 管控体验优化：前端适配多Agent组等新功能；前端支持采集 Agent 监控与自监控。

项目导师

玄飏（yangzehua.yzh@alibaba-inc.com）

项目难度

进阶

技术领域标签

React,Mysql,Redis,Docker

编程语言标签

Go,JavaScript,C++

项目产出要求

1. 管控能力升级

1. ConfigServer 支持多 Agent 组管控。

2. ConfigServer 支持 Agent 上报告警信息。

2. 部署能力升级

1. 基于 ConfigServer 预留的数据存储层接口，实现分布式部署。

2. 支持 ConfigServer 容器化部署，做到开箱即用。

3. 体验优化

1. ConfigServer UI升级，支持多 Agent 组、Agent 告警查看等新增功能

2. ConfigServer 提供监控能力，包括监控 ConfigServer 自身状态、监控 Agent 状态，并在UI界面展示。

4. 编写 ConfigServer 使用与开发文档

项目技术要求

1. 掌握 Golang，熟悉 React 或其他前端开发框架，了解C++

2. 熟悉分布式应用开发

3. 熟悉容器化技术

4. 熟悉Git、GitHub相关操作

5. 有阿里云日志服务使用经验更优

参考资料

ConfigServer介绍：https://ilogtail.gitbook.io/ilogtail-docs/config-server/quick-start

快速开始

采集主机日志

1. 下载预编译的iLogtail包，解压后进入目录，该目录下文均称为部署目录。

wget https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/latest/ilogtail-latest.linux-amd64.tar.gz

tar -xzvf ilogtail-latest.linux-amd64.tar.gz

cd ilogtail-<version>

2. 对iLogtail进行配置

部署目录中 ilogtail_config.json 是iLogtail的系统参数配置文件， config/local 是iLogtail的本地采集配置目录。

这里我们在采集配置目录中创建 file_simple.yaml 文件，配置采集当前目录simple.log文件并输出到标准输出：

enable: true

inputs:

- Type: input_file          # 文件输入类型

FilePaths:

- ./simple.log

flushers:

- Type: flusher_stdout    # 标准输出流输出类型

OnlyStdout: true

您也可以直接从下面的地址下载示例配置。

cd ./config/local

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/quick_start/config/file_simple.yaml

cd -

3. 后台启动iLogtail

nohup ./ilogtail > stdout.log 2> stderr.log &

以上命令将标准输出重定向到stdout.log以便观察。

4. 构造示例日志

echo 'Hello, iLogtail!' >> simple.log

5. 查看采集到的文件日志

cat stdout.log

结果为

2022-07-15 00:20:29 {"__tag__:__path__":"./simple.log","content":"Hello, iLogtail!","__time__":"1657815627"}

更多采集配置

了解采集配置结构：采集配置

参考更多可组合的日志采集和处理配置样例：https://github.com/alibaba/ilogtail/blob/main/example_config

Docker使用

使用前提

已安装docker

采集Docker容器日志

1. 准备iLogtail配置目录

新建配置目录 config 目录，在目录中创建 file_simple.yaml 和 stdout_simple.yaml 。

在 file_simple.yaml 中配置采集容器中的simple.log到标准输出。

enable: true

inputs:

- Type: input_file          # 文件输入类型

FilePaths:

- ./simple.log

flushers:

- Type: flusher_stdout    # 标准输出流输出类型

OnlyStdout: true

在 stdout_simple.yaml 中配置采集容器标准输出并输出到simple.stdout文件。

enable: true

inputs:

- Type: service_docker_stdout # 容器标准输出流输入类型

Stderr: false               # 不采集标准错误流

Stdout: true                # 采集标准输出流

flushers:

- Type: flusher_stdout        # 标准输出流输出类型

FileName: simple.stdout     # 重定向文件名

您也可以直接从下面的地址下载示例配置。

mkdir config && cd config

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_docker/config/file_simple.yaml

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_docker/config/stdout_simple.yaml

cd -

2. 启动iLogtail容器，并挂载iLogtail配置目录

docker run -d --name docker_ilogtail \

-v /:/logtail_host:ro \

-v /var/run:/var/run \

-v /var/lib/docker_ilogtail/checkpoint:/usr/local/ilogtail/checkpoint \

-v `pwd`/config:/usr/local/ilogtail/config/local \

sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:latest

第1行-d参数表示后台启动iLogtail容器，--name指定容器名称以便引用。\ 第2行将主机/目录挂载到iLogtail容器中，iLogtail依赖 logtail_host 路径采集容器日志。\ 第3行将主机/var/run目录挂载到iLogtail容器中，iLogtail依赖/var/run目录与容器引擎通信。\ 第4行将主机目录挂载到容器中iLogtail的checkpoint目录，使采集状态在容器重启时可恢复。\ 第5行将配置目录挂载到iLogtail容器中。

3. 查看ilogtail_docker容器自身标准输出日志

docker logs docker_ilogtail

结果为

delay stop seconds:  0

ilogtail started. pid: 10

register fun v2 0xa34f3c 0xa34f86 0xa34fdc 0xa35576

2022/07/14 16:23:17 DEBUG Now using Go's stdlib log package (via loggers/mappers/stdlib).

load log config /usr/local/ilogtail/plugin_logger.xml

recover stderr

recover stdout

4. 进入iLogtail容器

docker exec -it docker_ilogtail bash

5. 查看采集到的标准输出

cat /usr/local/ilogtail/simple.stdout

结果为

2022-07-14 16:23:20 {"content":"delay stop seconds:  0","_time_":"2022-07-14T16:23:17.704235928Z","_source_":"stdout","_image_name_":"sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.1.0","_container_name_":"docker_ilogtail","_container_ip_":"172.17.0.2","__time__":"1657815797"}

2022-07-14 16:23:20 {"content":"ilogtail started. pid: 10","_time_":"2022-07-14T16:23:17.704404952Z","_source_":"stdout","_image_name_":"sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.1.0","_container_name_":"docker_ilogtail","_container_ip_":"172.17.0.2","__time__":"1657815797"}

2022-07-14 16:23:20 {"content":"recover stdout","_time_":"2022-07-14T16:23:17.847939016Z","_source_":"stdout","_image_name_":"sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.1.0","_container_name_":"docker_ilogtail","_container_ip_":"172.17.0.2","__time__":"1657815797"}

6. 构造示例日志

echo 'Hello, iLogtail!' >> /root/simple.log

7. 查看采集到的容器文件日志

跳出容器，在宿主机上执行

docker logs docker_ilogtail

结果相比第3步的结果，多了

2022-07-14 16:26:20 {"__tag__:__path__":"/root/simple.log","content":"Hello, iLogtail!","__time__":"1657815980"}

采集模版

了解采集配置结构：采集配置

参考更多可组合的日志采集和处理配置样例：https://github.com/alibaba/ilogtail/blob/main/example_config

Kubernetes使用

使用前提

已部署Kubernetes集群或minikube

具备访问Kubernetes集群的kubectl

采集Kubernetes容器日志

1. 创建部署iLogtail的命名空间

将下面内容保存为ilogtail-ns.yaml

```yaml {.line-numbers} apiVersion: v1 kind: Namespace metadata: name: ilogtail

您也可以直接从下面的地址下载示例配置。

```bash

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_k8s/ilogtail-ns.yaml

应用上述配置

kubectl apply -f ilogtail-ns.yaml

2. 创建配置iLogtail的ConfigMap和Secret

将下面内容保存为ilogtail-user-configmap.yaml。该ConfigMap后续将作为配置目录挂载到iLogtail容器中，因此可包含多个采集配置。

```yaml {.line-numbers} apiVersion: v1 kind: ConfigMap metadata: name: ilogtail-user-cm namespace: ilogtail data: nginx_stdout.yaml: |

enable: true

inputs:

- Type: service_docker_stdout

Stderr: false

Stdout: true                # only collect stdout

IncludeK8sLabel:

app: nginx                # choose containers with this label

processors:

- Type: processor_regex       # structure log

SourceKey: content

Regex: '([\d\.:]+) - (\S+) \[(\S+) \S+\] \"(\S+) (\S+) ([^\\"]+)\" (\d+) (\d+) \"([^\\"]*)\" \"([^\\"]*)\" \"([^\\"]*)\"'

Keys:

- remote_addr

- remote_user

- time_local

- method

- url

- protocol

- status

- body_bytes_sent

- http_referer

- http_user_agent

- http_x_forwarded_for

flushers:

- Type: flusher_stdout

OnlyStdout: true

将下面内容保存为ilogtail-secret.yaml。该Secret为可选，当需要将日志写入SLS时会用到。

```yaml {.line-numbers}

apiVersion: v1

kind: Secret

metadata:

name: ilogtail-secret

namespace: ilogtail

type: Opaque

data:

access_key_id:  # base64 accesskey id if you want to flush to SLS

access_key:     # base64 accesskey secret if you want to flush to SLS

您也可以直接从下面的地址下载示例配置。

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_k8s/ilogtail-user-configmap.yaml

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_k8s/ilogtail-secret.yaml

应用上述配置

kubectl apply -f ilogtail-user-configmap.yaml

kubectl apply -f ilogtail-secret.yaml

3. 创建iLogtail DaemonSet

将下面内容保存为ilogtail-daemonset.yaml。

```yaml {.line-numbers} apiVersion: apps/v1 kind: DaemonSet metadata: name: ilogtail-ds namespace: ilogtail labels:

k8s-app: logtail-ds

spec: selector:

matchLabels:

k8s-app: logtail-ds

template:

metadata:

labels:

k8s-app: logtail-ds

spec:

tolerations:

- operator: Exists                    # deploy on all nodes

containers:

- name: logtail

env:

- name: ALIYUN_LOG_ENV_TAGS       # add log tags from env

value: _node_name_|_node_ip_

- name: _node_name_

valueFrom:

fieldRef:

apiVersion: v1

fieldPath: spec.nodeName

- name: _node_ip_

valueFrom:

fieldRef:

apiVersion: v1

fieldPath: status.hostIP

- name: cpu_usage_limit           # iLogtail's self monitor cpu limit

value: "1"

- name: mem_usage_limit           # iLogtail's self monitor mem limit

value: "512"

- name: default_access_key_id     # accesskey id if you want to flush to SLS

valueFrom:

secretKeyRef:

name: ilogtail-secret

key: access_key_id

optional: true

- name: default_access_key        # accesskey secret if you want to flush to SLS

valueFrom:

secretKeyRef:

name: ilogtail-secret

key: access_key

optional: true

image: >-

sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:latest

imagePullPolicy: IfNotPresent

resources:

limits:

cpu: 1000m

memory: 1Gi

requests:

cpu: 400m

memory: 384Mi

volumeMounts:

- mountPath: /var/run                       # for container runtime socket

name: run

- mountPath: /logtail_host                  # for log access on the node

mountPropagation: HostToContainer

name: root

readOnly: true

- mountPath: /usr/local/ilogtail/checkpoint # for checkpoint between container restart

name: checkpoint

- mountPath: /usr/local/ilogtail/config/local # mount config dir

name: user-config

readOnly: true

dnsPolicy: ClusterFirstWithHostNet

hostNetwork: true

volumes:

- hostPath:

path: /var/run

type: Directory

name: run

- hostPath:

path: /

type: Directory

name: root

- hostPath:

path: /etc/ilogtail-ilogtail-ds/checkpoint

type: DirectoryOrCreate

name: checkpoint

- configMap:

defaultMode: 420

name: ilogtail-user-cm

name: user-config

您也可以直接从下面的地址下载示例配置。

```bash

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_k8s/ilogtail-daemonset.yaml

添加参数示例

- name: logtail

command:

- /usr/local/ilogtail/ilogtail_control.sh

args:

- "start_and_block"

- "-enable_containerd_upper_dir_detect=true"

- "-dirfile_check_interval_ms=5000"

- "-logtail_checkpoint_check_gc_interval_sec=120"

应用上述配置

kubectl apply -f ilogtail-daemonset.yaml

4. 部署用来测试的nginx

将下面内容保存为nginx-deployment.yaml。

```yaml {.line-numbers} apiVersion: apps/v1 kind: Deployment metadata: name: nginx namespace: default labels:

app: nginx

spec: replicas: 1 selector:

matchLabels:

app: nginx

template:

metadata:

labels:

app: nginx

spec:

containers:

- image: 'nginx:latest'

name: nginx

ports:

- containerPort: 80

name: http

protocol: TCP

resources:

requests:

cpu: 100m

memory: 100Mi

您也可以直接从下面的地址下载示例配置。

```bash

wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/start_with_k8s/nginx-deployment.yaml

应用上述配置

kubectl apply -f nginx-deployment.yaml

5. 发送请求构造示例日志

kubectl exec nginx-<pod-id> -- curl localhost/hello/ilogtail

6. 查看采集到的测试容器标准输出日志

kubectl logs ilogtail-ds-<pod-id> -n ilogtail

结果为

2022-07-14 16:36:50 {"_time_":"2022-07-15T00:36:48.489153485+08:00","_source_":"stdout","_image_name_":"docker.io/library/nginx:latest","_container_name_":"nginx","_pod_name_":"nginx-76d49876c7-r892w","_namespace_":"default","_pod_uid_":"07f75a79-da69-40ac-ae2b-77a632929cc6","_container_ip_":"10.223.0.154","remote_addr":"::1","remote_user":"-","time_local":"14/Jul/2022:16:36:48","method":"GET","url":"/hello/ilogtail","protocol":"HTTP/1.1","status":"404","body_bytes_sent":"153","http_referer":"-","http_user_agent":"curl/7.74.0","http_x_forwarded_for":"-","__time__":"1657816609"}

采集模版

了解采集配置结构：采集配置

查看更多K8s采集日志模版（从容器中采集文件日等）：https://github.com/alibaba/ilogtail/blob/main/k8s_templates

参考更多可组合的日志采集和处理配置样例：https://github.com/alibaba/ilogtail/blob/main/example_config

ilogtail守护进程

当ilogtail因为各种原因异常退出，需要有一个守护来保证ilogtail进程的可用性。

安装ilogtail

参考快速开始，下载并安装ilogtail： 快速开始

linux环境

1. 执行生成systemd文件

其中ExecStart中路径根据ilogtail安装路径自行修改。

cat>/etc/systemd/system/ilogtaild.service<<EOF

[Unit]

Description=ilogtail

[Service]

Type=simple

User=root

Restart=always

RestartSec=60

ExecStart=/usr/local/ilogtail/ilogtail

[Install]

WantedBy=multi-user.target

EOF

2. 注册服务

systemctl daemon-reload

3. 启动服务

systemctl restart ilogtaild

4. 查看服务状态

systemctl status ilogtaild

在服务启动后，可以在ilogtail-目录下查看ilogtail.LOG。

5. 停止服务

systemctl stop ilogtaild

发布历史

2.0.0

发布记录

发版日期：2024 年 1 月 12 日

iLogtail 2.0是一个架构全新升级的版本，与1.x版本的采集配置不是完全兼容的，升级指南请参考变更说明#1294

2.0版本的配置方式完美支持了C++原生插件之间的级联和C++原生插件和Go插件之间的级联，同时引入了更加高效的数据处理语言SLS Processing Language (SPL)，端上数据处理更加游刃有余。

新功能

- 支持全新设计的V2采集配置 #1185

- 支持SPL数据处理语言处理数据 #1278

- 新增原生Input和Flusher插件接口，并定义完整原生流水线 #1184

- 即使使用Go插件Tag也将被置于Log的Meta中而非内容中，除非选项UsingOldContentTag为true #1169

- 输出支持jsonline协议 #1265

- Env方式控制配置创建升级使用2.0配置管理接口 #1282

优化

- flusher_http插件新增队列缓存和异步拦截器设置 #1203

- goprofile插件上报数据中使用机器的IP地址 #1281

- 增强vscode开发环境体验 #1219

- kafka输出插件新增MaxOpenRequests选项 #1224

- 插件自监控指标新增labels支持 #1240

- loki flusher支持只输出内容 #1256

问题修复

- 修复K8s集群Pod网络为HostNetwork时获取到的容器IP有时为空的问题 #1280

- 修复使用libcurl因没有设置CURLOPT_NOSIGNAL导致偶尔崩溃的问题 #1283

- 修复原生分隔符解析插件解析行首有空格的日志时字段错乱的问题 #1289

- 修复原生插件丢弃超时日志时区处理错误的问题 #1293

- 修复解析任意含有content key的json后，原生JSON插件总是错误保留原始content字段的问题 #1296

- 修复原生分隔符插件的内存泄露问题 #1300

- 修复因检查点转储早于目录注册导致的日志重复问题 #1291

- 修复飞天日志无法解析带逗号时间格式的兼容性问题 #1285

- 如果原生解析失败并选择保留原始日志，原始日志将仅保留在raw_log而不再保留在content字段以避免数据重复 #1304

- 解决了原生飞天解析插件多线程工作时解析错误的问题 #1305

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-2.0.0.linux-amd64.tar.gz

Linux

x86-64

0bcd191bc82f1e33d0d4a032ff2c9ea9e75de1dee04f11418107dde9d05b4185

ilogtail-2.0.0.linux-arm64.tar.gz

Linux

arm64

fc825b4879fd1c00bcba94ed19a4484555ced1f9b778f78786bc3e2bfc9ebad8

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:2.0.0

1.x版本

发布记录(1.x版本)

发布历史(1.x版本)

1.8.4

发布记录

发版日期：2024 年 1 月 2 日

优化

- goprofile插件上报数据中使用机器的IP地址 #1281

问题修复

- 修复正则配置time_key没有默认设置为time的兼容性问题 #1272

- 修复使用libcurl因没有设置CURLOPT_NOSIGNAL导致偶尔崩溃的问题 #1286

- 修复原生分隔符解析插件解析行首有空格的日志时字段错乱的问题 #1288

- 修复原生插件丢弃超时日志时区处理错误的问题 #1293

- 修复解析任意含有content key的json后，原生JSON插件总是错误保留原始content字段的问题 #1295

- 修复原生分隔符插件的内存泄露问题 #1299

- 修复因检查点转储早于目录注册导致的日志重复问题 #1301

- 修复飞天日志无法解析带逗号时间格式的兼容性问题 #1302

- 如果原生解析失败并选择保留原始日志，原始日志将仅保留在raw_log而不再保留在content字段以避免数据重复 #1304

- 修复K8s集群Pod网络为HostNetwork时获取到的容器IP有时为空的问题 #1280

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.8.4.linux-amd64.tar.gz

Linux

x86-64

c4b079d01b8dd840f49d4d4387df24c268b4736995c2065a740edd9f2d727356

ilogtail-1.8.4.linux-arm64.tar.gz

Linux

arm64

c4c7bb1ccec34cf19424c70f3447121a2dd0285c428bc78308e76ca10348c025

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.8.4

1.8.3

发布记录

发版日期：2023 年 12 月 7 日

问题修复

- 修复因#1216引入的日志重复采集问题 #1232

- 修复container info含nil字段导致的插件崩溃 #1247

- 修复ProcessorParseDelimiterNative解析携带下一行数据的问题 #1250

- 修复在反压情况下可能出现的文件无法读完的问题 #1251

- 修复plugin_export panic导致插件崩溃的问题 #1252

- 修复解析Apsara格式日志导致的崩溃问题 #1253

- 修复解析Apsara格式日志解析数据黏连问题 #1255

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.8.3.linux-amd64.tar.gz

Linux

x86-64

1cd352dec783247c4500074f77d8cfb88b607e28f6c95039c8f3da2a7b5880e3

ilogtail-1.8.3.linux-arm64.tar.gz

Linux

arm64

6d77b86ed4b38605ed9e87b3d3ec049da5497b8c48e2cb9ec5334324ef26f0aa

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.8.3

1.8.1

发布记录

发版日期：2023 年 11 月 8 日

问题修复

- 修复因字符串内存重用导致Promethus插件发送错误数据 #1201

- 修复采集多个SkyWalking实例时丢失JVM指标的问题 #1163

- 修复ElasticSearch Flusher TLS鉴权问题 #1157

- 修复Profiling在相同Java/Go堆栈下类型错误问题 #1187

- 修复从1.3之前的版本升级时本地send buffer丢失的问题 #1199

- 修复strptime_ns解析%c与原有striptime存在差异的问题 #1204

- 修复topic提取命名不支持带下划线的问题 #1205

- 修复存在多个jmxfetch配置时jmxfetch状态异常 #1210

- 修复被采集容器内存WSS增长的问题 #1216

- 修复采集路径黑名单配置错误没有日志提示的问题 #1218

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.8.1.linux-amd64.tar.gz

Linux

x86-64

b659e711b1960db995787b306c9d87c615345df562affdaa1a090dad7cb453f4

ilogtail-1.8.1.linux-arm64.tar.gz

Linux

arm64

a44ef5a4affcbff27dd551c57224c8e8447be37ad6c36292b63790673bba0b7c

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.8.1

1.8.0

发布记录

发版日期：2023 年 10 月 10 日

新功能

- C++流水线重构，处理流程插件化 #995

- 多行切分新增continue/end模式，支持多个模式组合 #978

- 支持超时切分行 #1067

- SLS Flusher 支持纳秒级日志时间#1097

- 新增全局主机路径黑名单 #1073

- 新增trace解析插件 processor_otel_metric  #1130

- 环境变量方式创建采集配置时添加资源标签 #1147

优化

- 编译镜像GCC升级到9.3.1 #1108

- Kafka V2插件支持写数据时增加header #1065

- 缓存未构成完整行的日志，减少读文件系统调用 #1142

- 支持使用环境变量控制日志打印级别 #959

- 支持flusher输出时使用扁平格式 #1112

- skywalking插件支持捕获 db.connection_string 标签 #1131

- 统一对metrics V1模型的格式化处理 #1060

- 校验网卡IP以获取更精确地主机IP #1019

问题修复

- 解决采集有挂载卷的statefulset漂移到不同节点时数据重复采集的问题 #1081

- 修复json processor支持array解析后的兼容性问题 #1088

- 修复空文件inode复用后导致采集到的日志文件名错误的问题 #1102

- 修复因checkpoint重新打开文件导致容器无法退出的问题 #1109

- 修复stdout文件路径为软链时无法采集容器stdout的问题 #1037

- 修复飞天日志时间无法调整时区的问题 #1123

- 修复json模式日志最后没有回车可能解析不正确的问题 #1126

- 修复读取到的数据开头含有非法jon时json解析异常的问题 #1161

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.8.0.linux-amd64.tar.gz

Linux

x86-64

90f60c372379311880d78a30609e76924f07d1fc8fdbcb944a78c01cc94de891

ilogtail-1.8.0.linux-arm64.tar.gz

Linux

arm64

6737c2f59f4a462d98e46fe5dca8d471a6634531e2cd8a2feb4a6beaaff22d20

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.8.0

1.7.1

发布记录

发版日期：2023 年 8 月 20 日

新功能

- 新增命令执行结果采集插件 input_command #925

- 新增log转sls metric插件 processor_log_to_sls_metric #955

- 新增log转sls trace插件 processor_otel_trace #1028

- Elasticsearch flusher支持动态索引 #979

- HTTP Server支持接受原始文本 #976

- Json processor支持解析数组 #972

优化

- Service_prometheus支持K8s中自动伸缩 #932

- containerd容器采集支持自定义rootfs路径和自动发现路径 #985

- 纳秒级高精度时间性能优化和windows支持 #1026

- 避免文件30天无更新后写入导致的重复采集问题 #1039

- 添加C++ Core UT流水线 #951

问题修复

- 修复 service_go_profile可能panic的问题 #1036

- 修复zstd批量发送问题 #1006

- 修复service_otlp插件无法退出的问题 #1040

- 修复env创建配置时ttl值非法与空行为不一致的问题 #1045

- 修复当只有容器删除事件时容器因fd所得无法退出的问题 #986

- 为system_v2插件采集disk metrics增加超时避免卡死 #933

- 修复profile中相同的容器内文件路径数据互相覆盖的问题 #1034

- 修复apsara_log_conf.json文件存在时不创建snapshot目录的问题 #944

- 修复otlp flusher时间戳总为1970-01-01的问题 #1031

- 修复config更新后config server下发为删除的问题 #1023

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.7.1.linux-amd64.tar.gz

Linux

x86-64

13029900e0bdd4f6db858d97b31d30f1659145fc40bfceb97f7946f35c94c232

ilogtail-1.7.1.linux-arm64.tar.gz

Linux

arm64

fe5e2e2b69cb664ed0fc0578d1fdec95e94ab00711b547c7b90591f0a07853e1

ilogtail-1.7.1.windows-amd64.zip

Windows

x86-64

593f734035f4c808654b638492f1e0d79205b2080a8975305f7f86b988841166

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.7.1

1.7.0

发布记录

发版日期：2023 年 7 月 2 日

新功能

- 写入SLS支持纳秒级高精度时间 #952

优化

- Go版本升级到1.19 #936

- 为metric_system_v2收集磁盘指标添加超时，避免影响其他指标采集 #933

- 增加日志超长切分失败告警 #915

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.7.0.linux-amd64.tar.gz

Linux

x86-64

d64061f9b5dc33e40f385c5514000157cc530c5b1f325afb3552267231334cd8

ilogtail-1.7.0.linux-arm64.tar.gz

Linux

arm64

27f9a34df79869bffb1c1be639c3602f1bd021c068e97fc3e287ef9cbabb3834

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.7.0

1.6.0

发布记录

发版日期：2023 年 6 月 8 日

新功能

- 新增OpenTelemetry指标格式转换SLS指标格式，支持将service_otlp和service_http_server插件采集的OpenTelemetry指标数据写入SLS时序库 #577

- 新增InfluxDB格式DecodeV2解码方法 #846

- 纯Go运行模式支持文件输入到文件文件输出测试 #869

- metric_meta_kubernetes 插件支持采集kruise CRD元数据 #878

- ConfigServer UI支持和协议使用POST方式替代GET方式传递数据 #894

- service-otlp-input 插件支持gzip解压缩 #875

- 支持Prometheus更多服务发现 #890

优化

- 优化 flusher_pulsar 、 flusher_kafka_v2 在静态topic下场景性能 #824

- 升级Kafka客户端sarama版本到1.38.1，并对Kafka相关插件进行匹配改造 #600

- 优化Prometheus协议解析性能约20% #866

- 优化 processor_desensitize 性能 20-80% #981

- SLS监控统计日志中增加ConfigName和Tag，以区分不同配置和容器 #905 #840

问题修复

- 修复网络异常时，异常高频访问ECS Meta的问题 851

- 修复 metric_system_v2 插件在多分区情况下采集磁盘容量重复计算的问题 #835

- 修复会应用已退出容器env采集配置的问题 #825

- 修复Converter将日志转为JSON时，误将字符HTML转义的问题 #857

- 修复ConfigServer Bug #876

- 修复多个容器文件采集配置指向同一个目录时，容器无法退出的问题 #872

- 修复 processor_gotime 插件无法表达0时区的问题 #829

- 修复env采集配置缓存无法过期的问题 #845

- 修复多行正则加速模式下，读取到的起始行无法匹配时被抛弃的问题 #902

- 修复多行正则模式下，行尾多余回车的问题 #896

- 修复通过文件获取容器信息时，文件更新导致容器Label丢失的问题 #906

- 修复 processor_string_replace 正则不匹配时字段丢失问题 #892

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.6.0.linux-amd64.tar.gz

Linux

x86-64

392766fc6b2f96df2da4bbd1ffcfc48e2027fc4613138236c7df72dde84d077f

ilogtail-1.6.0.linux-arm64.tar.gz

Linux

arm64

50993809b1b741aad4779be7cce3798adb12c1aa8b455538129c15607e186642

ilogtail-1.6.0.windows-amd64.zip

Windows

x86-64

f0da617f09ed1db2cd41135a581fddff64c0572a708fba0ae1b1fc27540b817f

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.6.0

1.5.0

发布记录

发版日期：2023 年 5 月 1 日

新功能

- 新增插件Extension机制 #648

- flusher_http插件通过Extension机制支持自定义鉴权、过滤、熔断 #648

- 新增Fusher插件: flusher_loki #259

- 新增Processor插件: processor_string_replace #757

- 支持在C++加速模式下通过文件为数据自动添加Tag #812

- 为SLS Data Server Endpoint添加受控的切换策略 #802

- 支持iLogtail通过网络代理管控和发送数据 #806

- 添加Windows编译脚本支持编译x86和x86-64版本 #327

- Profiling功能支持goprofile拉取模式 #730

- V2流水线完整支持OTLP Log模型 #779

优化

- 默认打开enable_env_ref_in_config选项以支持配置中环境变量替换 #744

- processor_split_key_value插件性能优化并增加多字符引用符 #762

问题修复

- 修复使用flusher_kafka_v2/flusher_pulsar插件时，TagFieldsRename选项中部分Tag字段无法被重命名的问题 #744

- 修复创建query模式的logstore时，无法自动创建索引的问题 #798

- 修复processor_filter_key有多个key时即使匹配也过滤日志的问题 #816

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.5.0.linux-amd64.tar.gz

Linux

x86-64

ccb7e637bc7edc4e9fe22ab3ac79cedee63d80678711e0efc77122387ec73882

ilogtail-1.5.0.linux-arm64.tar.gz

Linux

arm64

f1d7940e08ee51f2c66d963d91c16903658ab1e0fc856002351248c94d0e6b0a

ilogtail-1.5.0.windows-amd64.zip

Windows

x86-64

7b3ccbfcca18e1ffeb2e5db06b32fbcac3e8b7ecf8113a7006891bbe3c1a5a84

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.5.0

1.4.0

发布记录

发版日期：2023 年 3 月 21 日

新功能

- 新增Pulsar输出插件flusher_pulsar #540

- 新增ClickHouse输出插件flusher_clickhouse #112

- 新增Elasticsearch输出插件flusher_elasticsearch #202

- 新增Open Telemetry输入插件service_otlp #637

- 新增使用plugins.yml裁剪插件和external_plugins.yml引入外部插件库 #625

- 新增云主机实例元信息处理插件processor_cloud_meta #692

- 更新Open Telemetry输出插件新增Metric/Trace支持，同时重命名为flusher_otlp #646

- 更新HTTP输入服务新增Pyroscope协议支持 #653

优化

- 更新Kafka V2 flusher支持TLS和Kerberos认证 #601

- 更新HTTP输出支持添加动态Header #643

- 更新通过ENV配置SLS Config新增冷存等Logstore参数支持 #687

问题修复

- 修复时区相关问题，使用系统时间和解析日志时间失败时忽略时区调整选项 #550

- 修复因inode复用导致的日志重复采集或文件名错乱问题 #597

- 修复Prometheus输入插件自动切换到streaming模式卡死的问题 #684

- 修复Grok插件解析中文会可能卡死的问题 #644

- 修复1.2.1版本中引入的容器发现内存使用过高的问题 #661

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.4.0.linux-amd64.tar.gz

Linux

x86-64

d48fc6e8c76f117651487a33648ab6de0e2d8dd24ae399d9a7f534b81d639a61

ilogtail-1.4.0.linux-arm64.tar.gz

Linux

arm64

1d488d0905e0fb89678e256c980e491e9c1c0d3ef579ecbbc18360afdcc1a853

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.4.0

1.3.1

发布记录

发版日期：2022 年 12 月 13 日

新功能

优化

问题修复

- 获取IP可能失败并引发崩溃的问题 #576

- ARM版本无法在Ubuntu 20.04上运行的问题 #570

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.3.1.linux-amd64.tar.gz

Linux

x86-64

d74e2e8683fa9c01fcaa155e65953936c18611bcd068bcbeced84a1d7f170bd1

ilogtail-1.3.1.linux-arm64.tar.gz

Linux

arm64

d9a72b2ed836438b9d103d939d11cf1b0a73814e6bb3d0349dc0b6728b981eaf

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.3.1

1.3.0

发布记录

发版日期：2022 年 11 月 30 日

新功能

- 新增Kafka新版本输出插件，支持自定义输出格式 #218

- 支持通过grpc输出Open Telemetry协议日志 #418

- 支持通过HTTP接入Open Telemetry协议日志 #421

- 新增脱敏插件processor_desensitize #525

- 支持写入SLS时使用zstd压缩编码 #526

优化

- 减小发布二进制包大小 #433

- 使用ENV方式创建SLS资源时支持使用HTTPS协议 #505

- 支持创建SLS Logstore时选择query mode #502

- 使用插件处理时也支持输出内容在文件内偏移量 #395

- 默认支持采集容器标准输出时上下文保持连续 #522

- Prometheus数据接入内存优化 #524

问题修复

- 修复Docker环境下潜在的FD泄露和事件遗漏问题 #529

- 修复配置更新时文件句柄泄露的问题 #420

- IP在特殊主机名下解析错误 #517

- 修复多个配置路径存在父子目录关系时文件重复采集的问题 #533

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.3.0.linux-amd64.tar.gz

Linux

x86-64

5ef5672a226089aa98dfb71dc48b01254b9b77c714466ecc1b6c4d9c0df60a50

ilogtail-1.3.0.linux-arm64.tar.gz

Linux

arm64

73d33d4cac90543ea5c2481928e090955643c6dc6839535f53bfa54b6101704d

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.3.0

1.2.1

发布记录

发版日期：2022 年 9 月 28 日

新功能

- 新增PostgreSQL采集插件。

- 新增SqlServer采集插件。

- 新增Grok处理插件。

- 支持JMX性能指标采集。

- 新增日志上下文聚合插件，可支持插件处理后的上下文浏览和日志topic提取。

优化

- 支持采集秒退容器的标准输出采集。

- 缩短已退出容器句柄释放时间。

问题修复

- 飞天日志格式微妙时间戳解析。

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.2.1.linux-amd64.tar.gz

Linux

x86-64

8a5925f1bc265fd5f55614fcb7cebd571507c2c640814c308f62c498b021fe8f

ilogtail-1.2.1.linux-arm64.tar.gz

Linux

arm64

04be03f03eb722a3c9ba1b45b32c9be8c92cecabbe32bdc4672d229189e80c2f

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.2.1

1.1.1

发布记录

发版日期：2022 年 8 月 22 日

新功能

- 新增Logtail CSV处理插件。

- 支持通过eBPF进行四层、七层网络流量分析，支持HTTP、MySQL、PgSQL、Redis、DNS协议。

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.1.1.linux-amd64.tar.gz

Linux

x86-64

2330692006d151f4b83e4b8be0bfa6b68dc8d9a574c276c1beb6637c4a2939ec

Docker 镜像

Docker Pull 命令

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.1.1

1.1.0

发布记录

发版日期：2022 年 6 月 29 日

新功能

- 开源C++核心模块代码

- netping插件支持httping和DNS解析耗时。

详情和源代码

下载

文件名

系统

架构

SHA256 校验码

ilogtail-1.1.0.linux-amd64.tar.gz

Linux

x86-64

2f4eadd92debe17aded998d09b6631db595f5f5aec9c8ed6001270b1932cad7d

Docker 镜像

Docker Pull 命令

tag为1.1.0的镜像缺少必要环境变量，无法支持容器内文件采集和checkpoint，请使用1.1.0-k8s-patch或重新拉取latest

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail:1.1.0-k8s-patch

支持的操作系统

iLogtail支持以下操作系统和架构。

操作系统

发行版

架构

Linux

Aliyun Linux 2

x86_64

RedHat Enterprise 6、7、8

x86_64

CentOS 6、7、8

x86_64

CentOS Stream 8

x86_64

Debian 8、9、10、11

x86_64

Ubuntu 14.04、16.04、18.04、20.04

x86_64

SUSE Linux Enterprise Server 11、12、15

x86_64

OpenSUSE 15.1、15.2、42.3

x86_64

其他基于glibc 2.5及以上版本的Linux操作系统

x86_64

源代码

下载

稳定版本

生成环境，请从稳定版本源代码进行编译。稳定版本源代码的tar包或zip包下载链接地址服从如下规则：

https://github.com/alibaba/ilogtail/archive/refs/tags/v\.tar.gz

https://github.com/alibaba/ilogtail/archive/refs/tags/v\.zip

开发版本

对于有兴趣测试最新版本或者乐于贡献代码到开发者，获取最新开发代码GIT仓库的命令为：

git clone https://github.com/alibaba/ilogtail

注意，main分支是iLogtail的开发分支。因此，存在无法编译或者运行时出错的可能。

我们欢迎更多开发者参与测试或者开发，您的贡献将使iLogtail更加出色。

编译

Linux版本编译

编译前准备

下载源代码

安装docker

编译目标

Makefile描述了整个项目的所有编译目标，主要的包括：

目标

描述

core

仅编译C++核心

plugin

仅编译Go插件

all

编译完整iLogtail

dist

打包发行

docker

制作iLogtail镜像

plugin_local

本地编译Go插件

使用 make <target> 命令编译所选目标，如果需要指定生成的版本号则在编译命令前加上VERSION环境变量，如：

VERSION=1.8.3 make dist

如果发生编译错误，如

/src/core/common/CompressTools.cpp:18:23: fatal error: zstd/zstd.h: No such file or directory

#include <zstd/zstd.h>

^

compilation terminated.

请确保本地编译镜像为最新版本。可使用以下命令更新：

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux

使用镜像编译完整iLogtail

编译完整iLogtail的命令是 make all ，由于all是默认的编译目标，因此也可以直接 make 。该命令首先清理 output 目录，然后调用 ./scripts/gen_build_scripts.sh 脚本生成编译用的脚本和镜像描述保存到 ./gen 目录，调用 docker 制作镜像，制作的过程即镜像内的编译过程，最后将镜像内的编译结果复制到 output 目录。

以下命令可以快速编译出iLogtail的可执行程序和插件。

1. 进入源代码顶层目录。

2. 执行命令 make 。

3. 查看 output 目录结果。

./output

├── ilogtail （主程序）

├── libPluginAdapter.so（插件接口）

├── libPluginBase.h

└── libPluginBase.so （插件lib）

开发环境增量编译的方法请参考开发环境。

Go插件本地编译

Go插件可以在主机上进行直接编译，编译前，需要安装基础的 Go 1.16+ 语言开发环境，如何安装可以参见官方文档。 在安装完成后，为了方便后续地开发，请遵照此文档正确地设置你的开发目录以及 GOPATH 等环境变量。。

go mod tidy       # 若需要更新插件依赖库

make plugin_local # 每次更新插件代码后从这里开始

如果未对只是对插件依赖库进行修改，则只需要执行最后一行命令即可。

Windows版本编译

编译前准备

- 装备一台windows机器

- 安装Visual Studio Community Edition，推荐2017版本

- 安装golang

- 安装MinGW(根据windows机器位数选择对应版本)

- 下载相应位数的C++ boost库，安装

- boost_1_68_0-msvc-14.1-64.exe

- boost_1_68_0-msvc-14.1-32.exe

- 下载相应位数的ilogtail-deps编译依赖，解压

- 64位依赖

- 32位依赖

修改编译脚本

将ilogtail/scripts/windows64_build.bat(windows32_build.bat)脚本中的的BOOST_ROOT、ILOGTAIL_DEPS_PATH、CMAKE_BIN、DEVENV_BIN、MINGW_PATH五个环境变量值替换成编译机器上实际的路径

set ILOGTAIL_PLUGIN_SRC_PATH=%P1Path%

REM Change to where boost_1_68_0 locates

set BOOST_ROOT=C:\workspace\boost_1_68_0

REM Change to where ilogtail-deps.windows-x64 locates, path seperator must be /

set ILOGTAIL_DEPS_PATH=C:/workspace/ilogtail-deps.windows-x64

REM Change to where cmake locates

set CMAKE_BIN=C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake

REM Change to where devenv locates

set DEVENV_BIN=C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\devenv.com

REM Change to where mingw locates

set MINGW_PATH=C:\workspace\mingw64\bin

执行编译脚本

cd 到ilogtail/scripts目录下，执行windows64_build.bat(windows32_build.bat)脚本，等待约6分钟，完成编译。 编译产物列表：

- ilogtail.exe (主程序)

- PluginAdapter.dll (插件接口)

- PluginBase.dll (插件lib)

- PluginBase.h

Docker镜像

制作前准备

下载源代码

安装docker

镜像制作

制作镜像分为2步：

1. 代码库根目录准备ilogtail-.tar.gz 若使用已发布版本，可以从iLogtail发布记录下载压缩包。 若要使用本地最新代码构建，则执行如下命令 make dist 。

2. 将iLogtail发行版的tar包安装到base镜像中。 执行命令 make docker 。

制作的镜像默认名称为aliyun/ilogtail，可以DOCKER_REPOSITORY环境变量覆盖，Tag则必须与iLogtail包的版本相同，可以通过环境变量VERSION指定，例如：

$ VERSION=1.8.3 make dist

$ VERSION=1.8.3 make docker

$ docker image list

REPOSITORY        TAG     IMAGE ID       CREATED         SIZE

aliyun/ilogtail   1.8.3   c7977eb7dcc1   2 minutes ago   764MB

编译依赖

序号

名称 (版本)

用于……

1

boost (1.68.0  )

2

cityhash (8af9b8c2b889d80c22d6bc26ba0df1afb79a30db  )

3

curl (7.61.1  )

日志传输请求

4

gflags (2.2.1  )

设置系统参数

5

gperftools (2.7  )

6

gtest (1.8.1  )

单元测试

7

jsoncpp (1.8.4  )

解析JSON配置

8

libunwind (1.2.1  )

Linux上崩溃诊断

9

lz4 (1.8.3  )

日志传输压缩

10

openssl (1.0.2p  )

数据签名和加密

11

protobuf (3.6.1  )

日志传输序列化

12

rapidjson (c0ca05f6ddb690c943a7fc59efab9ca9cfc39736  )

日志JSON解析

13

re2 (2018-09-01  )

日志正则解析

14

spdlog (1.1.0  )

打印日志

15

zlib (1.2.11  )

16

breakpad (66571f4838b2306161f072555cb199049bc68142  )

Windows上崩溃诊断

17

leveldb (1.22  )

18

yaml-cpp (0.7.0  )

解析YAML配置

19

zstd (1.5.2  )

zstd压缩发送数据

镜像站

代码仓库

主站GitHub：https://github.com/alibaba/ilogtail

镜像站Gitee：https://gitee.com/mirrors/iLogtail

内容下载链接替换示例

主站GitHub： wget https://raw.githubusercontent.com/alibaba/ilogtail/main/example_config/quick_start/config/file_simple.yaml

镜像站Gitee： wget https://gitee.com/mirrors/iLogtail/raw/main/example_config/quick_start/config/file_simple.yaml

关键概念

采集配置

iLogtail 流水线是通过采集配置文件来定义的，每一个采集配置文件对应一条流水线。

格式

采集配置文件支持json和yaml文件格式，每个采集配置的一级字段如下：

参数

类型

是否必填

默认值

说明

enable

bool

否

true

是否使用当前配置。

global

object

否

空

全局配置。

global.EnableTimestampNanosecond

bool

否

false

否启用纳秒级时间戳，提高时间精度。

inputs

[object]

是

/

输入插件列表。目前只允许使用1个输入插件。

processors

[object]

否

空

处理插件列表。

aggregators

[object]

否

空

聚合插件列表。目前最多只能包含1个聚合插件，所有输出插件共享。

flushers

[object]

是

/

输出插件列表。至少需要包含1个输出插件。

extenstions

[object]

否

空

扩展插件列表。

其中，inputs、processors、aggregators、flushers和extenstions中可包含任意数量的插件。

组织形式

本地的采集配置文件默认均存放在 ./config/local 目录下，每个采集配置一个文件，文件名即为采集配置的名称。

热加载

采集配置文件支持热加载，当您在 ./config/local 目录下新增或修改已有配置文件，iLogtail将自动感知并重新加载配置。生效等待时间最长默认为10秒，可通过启动参数 config_scan_interval 进行调整。

示例

一个典型的采集配置如下所示：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_parse_regex_native

SourceKey: content

Regex: (\d*-\d*-\d*)\s(.*)

Keys:

- time

- msg

flushers:

- Type: flusher_stdout

OnlyStdout: true

其它常见的采集配置可参考example_config目录.

系统参数

在 iLogtail 启动时，会加载 ilogtail_config.json 配置文件，该配置文件指定了 iLogtail 正常运行的一些基本配置项。

参数列表

参数

类型

说明

cpu_usage_limit

double

CPU使用阈值，以单核计算。取值范围：0.1~当前机器的CPU核心数

警告 `cpu_usage_limit`为软限制，实际`iLogtail`占用的CPU可能超过限制值，超限5分钟后将触发熔断保护，`iLogtail`自动重启。

例如设置为0.4，表示日志服务将尽可能限制 `iLogtail` 的CPU使用为CPU单核的40%，超出后 `iLogtail` 自动重启。

mem_usage_limit

Int

内存使用阈值。

警告 `mem_usage_limit`为软限制，实际`iLogtail`占用的内存可能超过限制值，超限5分钟后将触发熔断保护，Logtail自动重启。

default_access_key_id

String

写入  SLS  的  access_id   ，需要具备写入权限。

default_access_key

String

写入  SLS  的  access_key   ，需要具备写入权限。

config_scan_interval

Int

本地配置热加载的更新间隔，单位为秒。

data_server_port

Int

用于控制 `flusher_sls` 往 `SLS` 发送的协议类型。

取值范围：443（默认），表示使用 `HTTPS` 协议发送；80表示使用 `HTTP` 协议发送。

如果使用`SLS`内网域名写入，建议使用`HTTP`协议发送，提高传输性能。

send_running_status

Bool

为了更好的了解  iLogtail  的使用情况，以便做出更有针对性的发展规划， iLogtail    会上报一些脱敏后的运行统计信息。您也可以手动关闭此开关。

host_path_blacklist

String

全局主机路径黑名单，黑名单为子串匹配，Linux下多个子串以:分隔，Windows下以;分隔。比如禁止采集NAS挂载，可以配置为 /volumes/kubernetes.io~csi/nas-   。

metrics_report_method

String

自身指标输出方式。默认为空，即不输出指标。

当前支持的值：

`file`：每分钟将指标输出到`ilogtail`运行目录下的`self_metrics`目录，文件格式为`self-metrics-&{time}.json`，最多保留60个指标文件（即1小时的数据）。该方式适合本地调试使用。

ebpf.receive_event_chan_cap

Int

用于接收内核事件的队列大小，默认为 4096

ebpf.admin_config.debug_mode

Bool

是否开启 ebpf debug 模式，默认为 false

ebpf.admin_config.log_level

String

ebpf 相关的日志级别，包括 info warn 和 debug，默认为 warn

典型配置

{

"default_access_key_id": "",

"default_access_key": "",

"cpu_usage_limit" : 0.4,

"mem_usage_limit" : 384

}

{

"ebpf": {

"receive_event_chan_cap": 4096,

"admin_config": {

"debug_mode": false,

"log_level": "warn"

}

}

}

环境变量

containerd runtime相关环境变量配置

参数

类型

说明

USE_CONTAINERD

Bool

是否使用containerd runtime，非必选。ilogtail会自动通过接口探测。

CONTAINERD_SOCK_PATH

String

自定义containerd sock路径，非必选。默认为/run/containerd/containerd.sock。自定义取值可以通过查看/etc/containerd/config.toml grpc.address字段获取。

CONTAINERD_STATE_DIR

String

自定义containerd 数据目录，非必选。自定义取值可以通过查看/etc/containerd/config.toml state字段获取。

LOGTAIL_LOG_LEVEL

String

用于控制/apsara/sls/ilogtail和golang插件的日志等级，支持通用日志等级，如trace, debug，info，warning，error，fatal

因为k8s本身自带资源限制的功能，所以如果你要将ilogtail部署到k8s中，可以通过将 cpu_usage_limit  和  mem_usage_limit  设置为一个很大的值（比如99999999），以此来达到“关闭”ilogtail自身熔断功能的目的。

日志

完整的iLogtail由 C++ 开发的主程序及 Golang 开发的插件组成，因此iLogtail的运行日志也有两部分组成。

iLogtail主程序日志

日志控制文件： apsara_log_conf.json， 该文件 iLogtail 首次运行时会自动生成。

日志级别： TRACE 、 DEBUG 、 INFO 、 WARNING 、 ERROR 、 FATAL

日志类型

- 运行日志：

- 日志文件： ilogtail.LOG

- 日志级别配置项： Loggers:/apsara/sls/ilogtail:AsyncFileSink

- profile 日志：

- 日志文件： snapshot/ilogtail_profile.LOG

- 日志级别配置项: 不需要修改。

- status 日志

- 日志文件： snapshot/ilogtail_status.LOG

- 日志级别配置项: 不需要修改。

完整配置项：

{

"Loggers" :

{

"/" :

{

"AsyncFileSink" : "WARNING"

},

"/apsara/sls/ilogtail" :

{

"AsyncFileSink" : "INFO"

},

"/apsara/sls/ilogtail/profile" :

{

"AsyncFileSinkProfile" : "INFO"

},

"/apsara/sls/ilogtail/status" :

{

"AsyncFileSinkStatus" : "INFO"

}

},

"Sinks" :

{

"AsyncFileSink" :

{

"Compress" : "Gzip",

"LogFilePath" : "${ilogtail运行路径}/ilogtail.LOG",

"MaxDaysFromModify" : 300,

"MaxLogFileNum" : 10,

"MaxLogFileSize" : 20000000,

"Type" : "AsyncFile"

},

"AsyncFileSinkProfile" :

{

"Compress" : "",

"LogFilePath" : "${ilogtail运行路径}/snapshot/ilogtail_profile.LOG",

"MaxDaysFromModify" : 1,

"MaxLogFileNum" : 61,

"MaxLogFileSize" : 1,

"Type" : "AsyncFile"

},

"AsyncFileSinkStatus" :

{

"Compress" : "",

"LogFilePath" : "${ilogtail运行路径}/snapshot/ilogtail_status.LOG",

"MaxDaysFromModify" : 1,

"MaxLogFileNum" : 61,

"MaxLogFileSize" : 1,

"Type" : "AsyncFile"

}

}

}

iLogtail插件日志

日志文件： logtail_plugin.LOG

日志控制文件： plugin_logger.xml

日志级别： trace 、 debug 、 info 、 warn 、 error 、 critical

日志级别配置项：修改 minlevel 字段取值即可

完整配置文件：

<seelog type="asynctimer" asyncinterval="500000" minlevel="info" >

<outputs formatid="common">

<rollingfile type="size" filename="${ilogtail运行路径}/logtail_plugin.LOG" maxsize="2097152" maxrolls="10"/>

</outputs>

<formats>

<format id="common" format="%Date %Time [%LEV] [%File:%Line] [%FuncShort] %Msg%n" />

</formats>

</seelog>

概览

输入

名称

提供方

简介

input_file

文本日志

SLS官方

文本采集。

input_container_stdio

容器标准输出（原生插件）

SLS官方

从容器标准输出/标准错误流中采集日志。

input_observer_network

eBPF网络调用数据

SLS官方

支持从网络系统调用中收集四层网络调用，并借助网络解析模块，可以观测七层网络调用细节。

input_command

脚本执行数据

社区

didachuxing

采集脚本执行数据。

input_docker_stdout

容器标准输出

SLS官方

从容器标准输出/标准错误流中采集日志。

metric_debug_file

文本日志（debug）

SLS官方

用于调试的读取文件内容的插件。

metric_input_example

MetricInput示例插件

SLS官方

MetricInput示例插件。

metric_meta_host

主机Meta数据

SLS官方

主机Meta数据。

metric_mock

Mock数据-Metric

SLS官方

生成metric模拟数据的插件。

metric_system_v2

主机监控数据

SLS官方

主机监控数据。

service_canal

MySQL Binlog

SLS官方

将MySQL Binlog输入到iLogtail。

service_go_profile

GO Profile

SLS官方

采集Golang pprof 性能数据。

service_gpu_metric

GPU数据

SLS官方

支持收集英伟达GPU指标。

service_http_server

HTTP数据

SLS官方

接收来自unix socket、http/https、tcp的请求，并支持sls协议、otlp等多种协议。

service_input_example

ServiceInput示例插件

SLS官方

ServiceInput示例插件。

service_journal

Journal数据

SLS官方

从原始的二进制文件中采集Linux系统的Journal（systemd）日志。

service_kafka

Kafka

SLS官方

将Kafka数据输入到iLogtail。

service_mock

Mock数据-Service

SLS官方

生成service模拟数据的插件。

service_mssql

SqlServer查询数据

SLS官方

将Sql Server数据输入到iLogtail。

service_otlp

OTLP数据

社区

Zhu Shunjia

通过http/grpc协议，接收OTLP数据。

service_pgsql

PostgreSQL查询数据

SLS官方

将PostgresSQL数据输入到iLogtail。

service_syslog

Syslog数据

SLS官方

采集syslog数据。

input_ebpf_file_security

eBPF文件安全数据

SLS官方

eBPF文件安全数据采集。

input_ebpf_network_observer

eBPF网络可观测数据

SLS官方

eBPF网络可观测数据采集。

input_ebpf_network_security

eBPF网络安全数据

SLS官方

eBPF网络安全数据采集。

input_ebpf_process_security

eBPF进程安全数据

SLS官方

eBPF进程安全数据采集。

处理

原生插件

名称

提供方

简介

processor_parse_regex_native

正则解析原生处理插件

SLS官方

通过正则匹配解析事件指定字段内容并提取新字段。

processor_parse_json_native

Json解析原生处理插件

SLS官方

解析事件中 Json   格式字段内容并提取新字段。

processor_parse_delimiter_native

分隔符解析原生处理插件

SLS官方

解析事件中分隔符格式字段内容并提取新字段。

processor_parse_timestamp_native

时间解析原生处理插件

SLS官方

解析事件中记录时间的字段，并将结果置为事件的time  字段。

processor_filter_regex_native

过滤原生处理插件

SLS官方

根据事件字段内容来过滤事件。

processor_desensitize_native

脱敏原生处理插件

SLS官方

对事件指定字段内容进行脱敏。

拓展插件

名称

提供方

简介

processor_add_fields

添加字段

SLS官方

添加字段。

processor_cloud_meta

添加云资产信息

SLS官方

为日志增加云平台元数据信息。

processor_default

原始数据

SLS官方

不对数据任何操作，只是简单的数据透传。

processor_desensitize

数据脱敏

SLS官方

Takuka0311

对敏感数据进行脱敏处理。

processor_drop

丢弃字段

SLS官方

丢弃字段。

processor_encrypt

字段加密

SLS官方

加密字段

processor_fields_with_conditions

条件字段处理

社区

pj1987111

根据日志部分字段的取值，动态进行字段扩展或删除。

processor_filter_regex

日志过滤

SLS官方

通过正则匹配过滤日志。

processor_gotime

Gotime

SLS官方

以 Go 语言时间格式解析原始日志中的时间字段。

processor_grok

Grok

SLS官方

Takuka0311

通过 Grok 语法对数据进行处理

processor_json

Json

SLS官方

实现对Json格式日志的解析。

processor_log_to_sls_metric

日志转sls metric

SLS官方

将日志转sls metric

processor_regex

正则

SLS官方

通过正则匹配的模式实现文本日志的字段提取。

processor_rename

重命名字段

SLS官方

重命名字段。

processor_split_char

分隔符

SLS官方

通过单字符的分隔符提取字段。

processor_split_string

分隔符

SLS官方

通过多字符的分隔符提取字段。

processor_split_key_value

键值对

SLS官方

通过切分键值对的方式提取字段。

processor_split_log_regex

多行切分

SLS官方

实现多行日志（例如Java程序日志）的采集。

processor_string_replace

字符串替换

SLS官方

pj1987111

通过全文匹配、正则匹配、去转义字符等方式对文本日志进行内容替换。

聚合

名称

提供方

简介

aggregator_content_value_group

社区

snakorse

按照指定的Key对采集到的数据进行分组聚合

aggregator_metadata_group

社区

urnotsally

按照指定的Metadata Keys对采集到的数据进行重新分组聚合

输出

名称

提供方

简介

flusher_kafka

Kafka

社区

将采集到的数据输出到Kafka。推荐使用下面的flusher_kafka_v2

flusher_kafka_v2

Kafka

社区

shalousun

将采集到的数据输出到Kafka。

flusher_sls

SLS

SLS官方

将采集到的数据输出到SLS。

flusher_stdout

标准输出/文件

SLS官方

将采集到的数据输出到标准输出或文件。

flusher_otlp_log

OTLP日志

社区

liuhaoyang

将采集到的数据支持 Opentelemetry log protocol   的后端。

flusher_http

HTTP

社区

snakorse

将采集到的数据以http方式输出到指定的后端。

flusher_pulsar

Kafka

社区

shalousun

将采集到的数据输出到Pulsar。

flusher_clickhouse

ClickHouse

社区

kl7sn

将采集到的数据输出到ClickHouse。

flusher_elasticsearch

ElasticSearch

社区

joeCarf

将采集到的数据输出到ElasticSearch。

flusher_loki

Loki

社区

abingcbc

将采集到的数据输出到Loki。

扩展

ClientAuthenticator

名称

提供方

简介

ext_basicauth

Basic认证

社区

snakorse

为 http_flusher 插件提供 basic 认证能力

FlushInterceptor

名称

提供方

简介

ext_groupinfo_filter

GroupInfo过滤

社区

snakorse

为 http_flusher 插件提供根据GroupInfo筛选最终提交数据的能力

RequestInterceptor

名称

提供方

简介

ext_request_breaker

请求熔断器

社区

snakorse

为 http_flusher 插件提供请求熔断能力

Decoder

名称

提供方

简介

ext_default_decoder

默认的decoder扩展

社区

snakorse

将内置支持的Format以Decoder扩展的形式封装

Encoder

名称

提供方

简介

ext_default_encoder

默认的encoder扩展

社区

yuanshuai.1900

将内置支持的Format以Encoder扩展的形式封装

版本管理

由于不同的iLogtail插件往往处于不同的开发进度，为了更好地区分这些插件的状态及可用性，我们将所有插件的状态分为4个阶段：Alpha、Beta、Stable和Deprecated，用户可以在各个插件的说明页上看到该插件的状态，从而方便用户更好地进行方案选择。

Alpha

任何初始PR提交的代码均处于该阶段。处于该阶段的插件已经初步具备使用条件，可在非关键场景中使用，但可能存在以下情况：

1. 插件的配置项仍可更改，且不保证后向兼容；

2. 插件可能存在功能错误和性能问题，用户可向社区反馈，但不一定得到立即响应。

Beta

当一个处于Alpha阶段的插件已经在部分非关键场景中稳定运行一段时间后，该插件进入Beta阶段。处于该阶段的插件已经基本达到稳定使用的条件，但仍然可能存在以下情况：

1. 插件的配置项仍可微调，但保证后向兼容；

2. 插件仍然可能存在微小的功能错误和性能问题，用户向社区反馈后，插件维护者将会尽快响应。

Stable

当处于Beta阶段的插件满足以下条件后，该插件正式进入稳定状态：

1. 该插件已被一定数量的社区用户在生产环境中使用，且运行稳定，无异常报告；

2. 该插件的功能已经完善，社区无新增相关issue，无未解决bug；

Deprecated

当一个插件被标注为Deprecated后，该插件将在不久的版本中被移除，社区中与之相关的新增issue将不再响应，具体信息可以参见插件的文档说明。

输入

文本日志

简介

input_file 插件可以实现从文本文件中采集日志。采集的日志内容将会保存在事件的 content 字段中。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_file。

FilePaths

[string]

是

/

待采集的日志文件路径列表（目前仅限1个路径）。路径中支持使用*和**通配符，其中**通配符仅能出现一次且仅限用于文件名前。

MaxDirSearchDepth

int

否

0

文件路径中**通配符匹配的最大目录深度。仅当日志路径中存在**通配符时有效，取值范围为0～1000。

ExcludeFilePaths

[string]

否

空

文件路径黑名单。路径必须为绝对路径，支持使用*通配符。

ExcludeFiles

[string]

否

空

文件名黑名单。支持使用*通配符。

ExcludeDirs

[string]

否

空

目录黑名单。路径必须为绝对路径，支持使用*通配符

FileEncoding

string

否

utf8

文件编码格式。可选值包括utf8和gbk。

TailSizeKB

uint

否

1024

配置首次生效时，匹配文件的起始采集位置距离文件结尾的大小。如果文件大小小于该值，则从头开始采集，取值范围为0～10485760KB。

Multiline

object

否

空

多行聚合选项。详见表1。

EnableContainerDiscovery

bool

否

false

是否启用容器发现功能。仅当Logtail以Daemonset模式运行，且采集文件路径为容器内路径时有效。

ContainerFilters

object

否

空

容器过滤选项。多个选项之间为“且”的关系，仅当EnableContainerDiscovery取值为true时有效，详见表2。

ExternalK8sLabelTag

map

否

空

对于部署于K8s环境的容器，需要在日志中额外添加的与Pod标签相关的tag。map中的key为Pod标签名，value为对应的tag名。 例如：在map中添加 app: k8s_label_app ，则若pod中包含 app=serviceA 的标签时，会将该信息以tag的形式添加到日志中，即添加字段__tag__:k8s_label_app: serviceA；若不包含 app   标签，则会添加空字段__tag__:k8s_label_app:

ExternalEnvTag

map

否

空

对于部署于K8s环境的容器，需要在日志中额外添加的与容器环境变量相关的tag。map中的key为环境变量名，value为对应的tag名。 例如：在map中添加 VERSION: env_version ，则当容器中包含环境变量 VERSION=v1.0.0 时，会将该信息以tag的形式添加到日志中，即添加字段__tag__:env_version: v1.0.0；若不包含 VERSION   环境变量，则会添加空字段__tag__:env_version:

AppendingLogPositionMeta

bool

否

false

是否在日志中添加该条日志所属文件的元信息，包括__tag__:__inode__字段和__file_offset__字段。

FlushTimeoutSecs

uint

否

5

当文件超过指定时间未出现新的完整日志时，将当前读取缓存中的内容作为一条日志输出。

AllowingIncludedByMultiConfigs

bool

否

false

是否允许当前配置采集其它配置已匹配的文件。

- 表1：多行聚合选项

参数

类型

是否必填

默认值

说明

Mode

string

否

custom

多行聚合模式。可选值包括custom和JSON。

StartPattern

string

当Multiline.Mode取值为custom时，至少1个必填

空

行首正则表达式。

ContinuePattern

string

空

行继续正则表达式。

EndPattern

string

空

行尾正则表达式。

UnmatchedContentTreatment

string

否

single_line

对于无法匹配的日志段的处理方式，可选值如下：

- discard：丢弃

- single_line：将不匹配日志段的每一行各自存放在一个单独的事件中

- 表2：容器过滤选项

参数

类型

是否必填

默认值

说明

K8sNamespaceRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器所在Pod所属的命名空间条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

K8sPodRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器所在Pod的名称条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

IncludeK8sLabel

map

否

空

对于部署于K8s环境的容器，指定待采集容器所在pod的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为Pod标签名，value为Pod标签的值，说明如下：

- 如果map中的value为空，则pod标签中包含以key为键的pod都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当pod标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的pod会被匹配；

- 其他情况下，当pod标签中存在以key为标签名且以value为标签值的情况时，相应的pod会被匹配。

</ul>

ExcludeK8sLabel

map

否

空

对于部署于K8s环境的容器，指定需要排除采集容器所在pod的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为pod标签名，value为pod标签的值，说明如下：

- 如果map中的value为空，则pod标签中包含以key为键的pod都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当pod标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的pod会被匹配；

- 其他情况下，当pod标签中存在以key为标签名且以value为标签值的情况时，相应的pod会被匹配。

</ul>

K8sContainerRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器的名称条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

IncludeEnv

map

否

空

指定待采集容器的环境变量条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为环境变量名，value为环境变量的值，说明如下：

- 如果map中的value为空，则容器环境变量中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时，相应的容器会被匹配。

</ul>

ExcludeEnv

map

否

空

指定需要排除采集容器的环境变量条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为环境变量名，value为环境变量的值，说明如下：

- 如果map中的value为空，则容器环境变量中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时，相应的容器会被匹配。

</ul>

IncludeContainerLabel

map

否

空

指定待采集容器的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则默认为空，表示采集所有容器。支持正则匹配。 map中的key为容器标签名，value为容器标签的值，说明如下：

- 如果map中的value为空，则容器标签中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器标签中存在以key为标签名且以value为标签值的情况时，相应的容器会被匹配。

</ul>

ExcludeContainerLabel

map

否

空

指定需要排除采集容器的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则默认为空，表示采集所有容器。支持正则匹配。 map中的key为容器标签名，value为容器标签的值，说明如下：

- 如果map中的value为空，则容器标签中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器标签中存在以key为标签名且以value为标签值的情况时，相应的容器会被匹配。

</ul>

样例

采集指定目录下的文件

采集 /home/test-log 路径下的所有文件名匹配 *.log 规则的文件，并将结果输出至stdout。

- 输入

{"key1": 123456, "key2": "abcd"}

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

{

"__tag__:__path__": "/home/test-log/json.log",

"content": "{\"key1\": 123456, \"key2\": \"abcd\"}",

"__time__": "1657354763"

}

注意： __tag__  字段的输出会由于ilogtail版本的不同而存在差别。为了在标准输出中能够准确地观察到  __tag__ ，建议仔细检查以下几点：

- flusher_stdout 的配置中，设置了  Tags: true

- 如果使用了较新版本的ilogtail，在观察标准输出时， __tag__ 可能会被拆分为一行单独的信息，先于日志的内容输出（这与文档中的示例输出会有差别），请注意不要观察遗漏。

此注意事项适用于后文所有观察  __tag__  字段输出的地方。

采集指定目录下的所有文件

采集 /home/test-log 路径下的所有文件名匹配 *.log 规则的文件（含递归），并将结果输出至stdout。

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/**/*.log

MaxDirSearchDepth: 10

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

采集K8s容器文件（仅限iLogtail以Daemonset的方式部署）

采集K8s命名空间 default 中以 deploy 为Pod名前缀、Pod标签包含 version: 1.0 且容器环境变量不为 ID=123 的所有容器中， /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将结果输出至stdout。

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

EnableContainerDiscovery: true

ContainerFilters:

K8sNamespaceRegex: default

K8sPodRegex: ^(deploy.*)$

IncludeK8sLabel:

version: v1.0

ExcludeEnv:

ID: 123

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

采集简单多行日志

采集文件 /home/test-log/regMulti.log ，文件内容通过行首正则表达式切分日志，然后通过正则表达式解析日志内容并提取字段，并将结果输出到stdout。

- 输入

[2022-07-07T10:43:27.360266763] [INFO] java.lang.Exception: exception happened

at com.aliyun.sls.devops.logGenerator.type.RegexMultiLog.f2(RegexMultiLog.java:108)

at java.base/java.lang.Thread.run(Thread.java:833)

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/regMulti.log

Multiline:

StartPattern: \[\d+-\d+-\w+:\d+:\d+.\d+]\s\[\w+]\s.*

processors:

- Type: processor_parse_regex_native

SourceKey: content

Keys:

- time

- level

- msg

Regex: \[(\S+)]\s\[(\S+)]\s(.*)

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

{

"__tag__:__path__": "/home/test-log/regMulti.log",

"time": "2022-07-07T10:43:27.360266763",

"level": "INFO",

"msg": "java.lang.Exception: exception happened

at com.aliyun.sls.devops.logGenerator.type.RegexMultiLog.f2(RegexMultiLog.java:108)

at java.base/java.lang.Thread.run(Thread.java:833)",

"__time__": "1657161807"

}

采集复杂多行日志

采集文件 /home/test-log/regMulti.log ，文件内容通过行首和行尾正则表达式切分日志，然后通过正则表达式解析日志内容并提取字段，并将结果输出到stdout。

- 输入

[2022-07-07T10:43:27.360266763] [ERROR] java.lang.Exception: exception happened

[2022-07-07T10:43:27.360266763]    at com.aliyun.sls.devops.logGenerator.type.RegexMultiLog.f2(RegexMultiLog.java:108)

[2022-07-07T10:43:27.360266763]    at java.base/java.lang.Thread.run(Thread.java:833)

[2022-07-07T10:43:27.360266763]    ... 23 more

[2022-07-07T10:43:27.360266763] Some user custom log

[2022-07-07T10:43:27.360266763] Some user custom log

[2022-07-07T10:43:27.360266763] [ERROR] java.lang.Exception: exception happened

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/regMulti.log

Multiline:

StartPattern: \[\d+-\d+-\w+:\d+:\d+.\d+].*Exception.*

EndPattern: .*\.\.\. \d+ more

processors:

- Type: processor_parse_regex_native

SourceKey: content

Keys:

- msg

- time

Regex: (\[(\S+)].*)

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

{

"__tag__:__path__": "/home/test-log/regMulti.log",

"time": "2022-07-07T10:43:27.360266763",

"msg": "[2022-07-07T10:43:27.360266763] [ERROR] java.lang.Exception: exception happened\n[2022-07-07T10:43:27.360266763]    at com.aliyun.sls.devops.logGenerator.type.RegexMultiLog.f2(RegexMultiLog.java:108)\n[2022-07-07T10:43:27.360266763]    at java.base/java.lang.Thread.run(Thread.java:833)\n[2022-07-07T10:43:27.360266763]    ... 23 more"

}

{

"__tag__:__path__": "/home/test-log/regMulti.log",

"time": "2022-07-07T10:43:27.360266763",

"msg": "[2022-07-07T10:43:27.360266763] Some user custom log"

}

{

"__tag__:__path__": "/home/test-log/regMulti.log",

"time": "2022-07-07T10:43:27.360266763",

"msg": "[2022-07-07T10:43:27.360266763] Some user custom log"

}

容器标准输出（原生插件）

简介

input_container_stdio   input 插件可以实现从容器标准输出/标准错误流中采集日志，采集的日志内容将会保存在 content 字段中。支持通过容器元信息筛选待采集容器，并支持多行文本切分、添加容器Meta信息等数据处理操作，仅支持 iLogtail 2.1 及以后版本。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_container_log。

IgnoringStdout

Boolean

否

false

是否忽略标准输出stdout。

IgnoringStderr

Boolean

否

false

是否忽略标准出错信息stderr。

TailSizeKB

uint

否

1024

配置首次生效时，标准输出文件的起始采集位置距离文件结尾的大小。如果文件大小小于该值，则从头开始采集，取值范围为0～10485760KB。

Multiline

object

否

空

多行聚合选项，详见表1。

ContainerFilters

object

否

空

容器过滤选项。多个选项之间为“且”的关系，详见表2。

ExternalK8sLabelTag

map

否

空

对于部署于K8s环境的容器，需要在日志中额外添加的与Pod标签相关的tag。map中的key为Pod标签名，value为对应的tag名。 例如：在map中添加 app: k8s_label_app ，则若pod中包含 app=serviceA 的标签时，会将该信息以tag的形式添加到日志中，即添加字段__tag__:k8s_label_app: serviceA；若不包含 app   标签，则会添加空字段__tag__:k8s_label_app:

ExternalEnvTag

map

否

空

对于部署于K8s环境的容器，需要在日志中额外添加的与容器环境变量相关的tag。map中的key为环境变量名，value为对应的tag名。 例如：在map中添加 VERSION: env_version ，则当容器中包含环境变量 VERSION=v1.0.0 时，会将该信息以tag的形式添加到日志中，即添加字段__tag__:env_version: v1.0.0；若不包含 VERSION   环境变量，则会添加空字段__tag__:env_version:

FlushTimeoutSecs

uint

否

5

当文件超过指定时间未出现新的完整日志时，将当前读取缓存中的内容作为一条日志输出。

AllowingIncludedByMultiConfigs

bool

否

false

是否允许当前配置采集其它配置已匹配的容器的标准输出日志。

- 表1：多行聚合选项

参数

类型

是否必填

默认值

说明

Mode

string

否

custom

多行聚合模式。仅支持custom。

StartPattern

string

当Multiline.Mode取值为custom时，至少1个必填

空

行首正则表达式。

ContinuePattern

string

空

行继续正则表达式。

EndPattern

string

空

行尾正则表达式。

UnmatchedContentTreatment

string

否

single_line

对于无法匹配的日志段的处理方式，可选值如下：

- discard：丢弃

- single_line：将不匹配日志段的每一行各自存放在一个单独的事件中

- 表2：容器过滤选项

参数

类型

是否必填

默认值

说明

K8sNamespaceRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器所在Pod所属的命名空间条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

K8sPodRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器所在Pod的名称条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

IncludeK8sLabel

map

否

空

对于部署于K8s环境的容器，指定待采集容器所在pod的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为Pod标签名，value为Pod标签的值，说明如下：

- 如果map中的value为空，则pod标签中包含以key为键的pod都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当pod标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的pod会被匹配；

- 其他情况下，当pod标签中存在以key为标签名且以value为标签值的情况时，相应的pod会被匹配。

</ul>

ExcludeK8sLabel

map

否

空

对于部署于K8s环境的容器，指定需要排除采集容器所在pod的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为pod标签名，value为pod标签的值，说明如下：

- 如果map中的value为空，则pod标签中包含以key为键的pod都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当pod标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的pod会被匹配；

- 其他情况下，当pod标签中存在以key为标签名且以value为标签值的情况时，相应的pod会被匹配。

</ul>

K8sContainerRegex

string

否

空

对于部署于K8s环境的容器，指定待采集容器的名称条件。如果未添加该参数，则表示采集所有容器。支持正则匹配。

IncludeEnv

map

否

空

指定待采集容器的环境变量条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为环境变量名，value为环境变量的值，说明如下：

- 如果map中的value为空，则容器环境变量中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时，相应的容器会被匹配。

</ul>

ExcludeEnv

map

否

空

指定需要排除采集容器的环境变量条件。多个条件之间为“或”的关系，如果未添加该参数，则表示采集所有容器。支持正则匹配。 map中的key为环境变量名，value为环境变量的值，说明如下：

- 如果map中的value为空，则容器环境变量中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器环境变量中存在以key为环境变量名且对应环境变量值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器环境变量中存在以key为环境变量名且以value为环境变量值的情况时，相应的容器会被匹配。

</ul>

IncludeContainerLabel

map

否

空

指定待采集容器的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则默认为空，表示采集所有容器。支持正则匹配。 map中的key为容器标签名，value为容器标签的值，说明如下：

- 如果map中的value为空，则容器标签中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器标签中存在以key为标签名且以value为标签值的情况时，相应的容器会被匹配。

</ul>

ExcludeContainerLabel

map

否

空

指定需要排除采集容器的标签条件。多个条件之间为“或”的关系，如果未添加该参数，则默认为空，表示采集所有容器。支持正则匹配。 map中的key为容器标签名，value为容器标签的值，说明如下：

- 如果map中的value为空，则容器标签中包含以key为键的容器都会被匹配；

- 如果map中的value不为空，则：

- 若value以`^`开头并且以`$`结尾，则当容器标签中存在以key为标签名且对应标签值能正则匹配value的情况时，相应的容器会被匹配；

- 其他情况下，当容器标签中存在以key为标签名且以value为标签值的情况时，相应的容器会被匹配。

</ul>

默认日志字段

所有使用本插件上报的日志均额外携带下列字段。目前暂不支持更改。

字段名称

说明

_time_

日志采集时间，例如 2021-02-02T02:18:41.979147844Z   。

_source_

日志源类型，stdout或stderr。

默认Tag字段

所有使用本插件上报的日志Tag均额外携带下列字段。目前暂不支持更改。

字段名称

说明

_image_name_

镜像名

_container_name_

容器名

_pod_name_

Pod名

_namespace_

Pod所在的命名空间

_pod_uid_

Pod的唯一标识

样例

示例1：通过容器环境变量黑白名单过滤容器

采集环境变量含 NGINX_SERVICE_PORT=80 且不含 POD_NAMESPACE=kube-system 的容器的标准输出。

1. 获取环境变量。

您可以登录容器所在的宿主机查看容器的环境变量。具体操作，请参见获取容器环境变量。

命令提示：

docker inspect

crictl inspect

ctr -n k8s.io containers info

"Env": [

...

"NGINX_SERVICE_PORT=80",

2. 创建iLogtail采集配置。

iLogtail采集配置示例如下所示。

inputs:

- Type: input_container_stdio

IgnoringStdout: false

IgnoringStderr: true

ContainerFilters:

IncludeEnv:

NGINX_SERVICE_PORT: "80"

ExcludeEnv:

POD_NAMESPACE: "kube-system"

示例2：通过容器Label黑白名单过滤容器

采集容器Label含 io.kubernetes.container.name:nginx 且不含 io.kubernetes.pod.namespace:kube-system 容器的标准输出。

1. 获取容器Label。

您可以登录容器所在的宿主机查看容器的Label。具体操作，请参见获取容器Label。

"Labels": {

...

"io.kubernetes.container.name": "nginx",

2. 创建Logtail采集配置。

Logtail采集配置示例如下所示。

inputs:

- Type: input_container_stdio

IgnoringStdout: false

IgnoringStderr: true

ContainerFilters:

IncludeContainerLabel:

io.kubernetes.container.name: "nginx"

IncludeContainerLabel:

io.kubernetes.pod.namespace": "kube-system"

示例3：通过Kubernetes Namespace名称、Pod名称和容器名称过滤容器

采集default命名空间下以nginx-开头的Pod中的nginx容器的标准输出。

1. 获取Kubernetes层级的信息。

命令提示：

kubectl describe

Name:         nginx-76d49876c7-r892w

Namespace:    default

...

Containers:

nginx:

Container ID:...

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: input_container_stdio

IgnoringStdout: false

IgnoringStderr: true

ContainerFilters:

K8sNamespaceRegex: "^(default)$"

K8sPodRegex: "^(nginx-.*)$"

K8sContainerRegex: "^(nginx)$"

示例4：通过Kubernetes Label过滤容器

采集Kubernetes Label含app=nginx且不含env=test开头的所有容器的标准输出。

1. 获取Kubernetes层级的信息。

Name:         nginx-76d49876c7-r892w

Namespace:    default

...

Labels:       app=nginx

...

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: input_container_stdio

IgnoringStdout: false

IgnoringStderr: true

ContainerFilters:

IncludeK8sLabel:

app: "nginx"

ExcludeK8sLabel:

env: "^(test.*)$"

示例5：多行日志的iLogtail采集配置

采集输出在标准错误流的Java异常堆栈（多行日志）。

1. 获取日志样例。

2021-02-03 14:18:41.969 ERROR [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : java.lang.NullPointerException

at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)

at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)

...

根据有区分度的行首编写正则。

行首： 2021-02-03 ...

正则： \d+-\d+-\d+.*

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: input_container_stdio

IgnoringStdout: false

IgnoringStderr: true

Multiline:

StartPattern: \d+-\d+-\d+.*

input_command 插件

简介

input_command 插件可以通过配置脚本内容，在agent机器上生成可执行的脚本，并通过指定的 cmdpath  执行该脚本，插件会从脚本执行后 stdout 获得内容进行解析，从而获取脚本内容执行后的信息。

注意：如果需要使用该插件，iLogtail需要在root用户下使用。配置的脚本内容请自查风险。

版本

Alpha

配置参数

基础参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 input_command

ScriptType

String

是

指定脚本内容的类型，目前支持:bash、shell、python2、python3

User

String

是

运行命令使用的用户名，只支持非Root用户(建议配置最小权限，只给需要关注的目录/文件rwx权限)

ScriptContent

String

是

脚本内容, 支持PlainText和base64加密的内容, 跟ContentEncoding的字段对应, ScriptContent长度不能超过512*1024

ContentEncoding

String

否

脚本内容的文本格式

支持PlainText(纯文本，不编码)\

Base64编码 默认:PlainText

LineSplitSep

String

否

脚本输出内容的分隔符，为空时不进行分割，全部作为一条数据返回

CmdPath

String

否

执行脚本命令的路径，如果为空，则使用默认路径。bash、shell、python2、python3对应的默认路径如下：

- bash: /usr/bin/bash

- shell: /usr/bin/sh

- python2: /usr/bin/python2

- python3: /usr/bin/python3

TimeoutMilliSeconds

int

否

执行脚本的超时时间，单位为毫秒，默认为3000ms

IntervalMs

int

否

采集触发频率，也是脚本执行的频率，单位为毫秒，默认为5000ms

Environments

[]string

否

环境变量，默认为os.Environ()的值，如果设置了Environments，则在os.Environ()的基础上追加设置的环境变量

IgnoreError

Bool

否

插件执行出错时是否输出Error日志。如果未添加该参数，则默认使用false，表示不忽略

生成参数

参数

类型

说明

content

String

表示脚本的输出内容

script_md5

String

用于表示 ScriptContent（脚本内容）的 MD5，有助于确定生成日志的脚本内容来源

- 采集配置1

enable: true

inputs:

- Type: input_command

User: test

ScriptType: shell

ScriptContent:

echo -e "test metric commond"

Environments:

- "DEBUG=true"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"content":"test metric commond",

"script_md5":"b3ebc535c2e6cead6e2e13b383907245",

"__time__":"1689677617"

}

- 采集配置2

enable: true

inputs:

- Type: input_command

User: test

ScriptType: python2

ScriptContent: |

print("test input_command 0")

print("test input_command 1")

print("test input_command 2")

print("test input_command 3")

print("test input_command 4")

print("test input_command 5")

print("test input_command 6")

print("test input_command 7")

print("test input_command 8")

print("test input_command 9")

CmdPath: /usr/bin/python

Environments:

- "DEBUG=true"

TimeoutMilliseconds: 1005

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"content":"test input_command 0\ntest input_command 1\ntest input_command 2\ntest input_command 3\ntest input_command 4\ntest input_command 5\ntest input_command 6\ntest input_command 7\ntest input_command 8\ntest input_command 9",

"script_md5":"5d049f5b2943d2d5e5737dddb065c39c",

"__time__":"1689677656"

}

- 采集配置3

enable: true

inputs:

- Type: input_command

User: test

ScriptType: python2

ScriptContent: |

import os

print os.environ

CmdPath: /usr/bin/python

Environments:

- "DEBUG=true"

TimeoutMilliseconds: 1005

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"content":"{'GOPATH': '/opt/go', 'GOROOT': '/usr/local/go',  'DEBUG': 'true', xxxxx(省略后面内容）}",

"script_md5":"1444286e16118f7d1bb778738a828273",

"__time__":"1689677681"

}

容器标准输出

简介

service_docker_stdout   input 插件可以实现从容器标准输出/标准错误流中采集日志，采集的日志内容将会保存在 content 字段中。支持通过容器元信息筛选待采集容器，并支持多行文本切分、添加容器Meta信息等数据处理操作，概览如下：

容器筛选，每项筛选条件之间为AND关系

- 支持通过容器Label白名单指定待采集的容器，多个白名单之间关系为OR。

- 支持通过容器Label黑名单排除不要采集的容器，多个黑名单之间关系为OR。

- 支持通过环境变量白名单指定待采集的容器，多个白名单之间关系为OR。

- 支持通过环境变量黑名单排除不要采集的容器，多个黑名单之间关系为OR。

- 支持通过Kubernetes Namespace名称指定待采集的容器。

- 支持通过Kubernetes Pod名称指定待采集的容器。

- 支持通过Kubernetes容器名称指定待采集的容器。

- 支持通过Kubernetes Label白名单指定待采集的容器，多个白名单之间关系为OR。

- 支持通过Kubernetes Label黑名单排除不要采集的容器，多个黑名单之间关系为OR。

数据处理

- 支持采集多行日志（例如Java Stack日志等）。

- 支持上报时自动关联Kubernetes Label信息。

- 支持上报时自动关联容器Meta信息（例如容器名、IP、镜像、Pod、Namespace、环境变量等）。

- 支持上报时自动关联宿主机Meta信息（例如宿主机名、IP、环境变量等）。

版本

Stable

配置参数

基本参数

参数

类型

是否必选

说明

Type

String

是

插件类型，固定为 service_docker_stdout

Stdout

Boolean

否

是否采集标准输出stdout。默认取值为 true   。</p>

Stderr

Boolean

否

是否采集标准出错信息stderr。默认取值为 true   。</p>

StartLogMaxOffset

Integer

否

首次采集时回溯历史数据长度，单位：字节。建议取值在[131072,1048576]之间。默认取值为128×1024字节。

筛选容器参数

参数

类型

是否必选

说明

IncludeLabel

Map，其中LabelKey和LabelValue为String类型

否

容器Label白名单，用于指定待采集的容器。默认为空，表示采集所有容器的标准输出。如果您要设置容器Label白名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则容器Label中包含LabelKey的容器都匹配。

- 如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才匹配。

LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 io.kubernetes.container.name ，设置LabelValue为`^(nginx\

cube)$`，表示可匹配名为nginx、cube的容器。</p></li></ul>
多个白名单之间为或关系，即只要容器Label满足任一白名单即可匹配。

ExcludeLabel

Map，其中LabelKey和LabelValue为String类型

否

容器Label黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置容器Label黑名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则容器Label中包含LabelKey的容器都将被排除。

- 如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才会被排除。

LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 io.kubernetes.container.name ，设置LabelValue为`^(nginx\

cube)$`，表示可匹配名为nginx、cube的容器。</p></li></ul>
多个黑名单之间为或关系，即只要容器Label满足任一黑名单对即可被排除。

IncludeEnv

Map，其中EnvKey和EnvValue为String类型

否

设环境变量白名单，用于指定待采集的容器。默认为空，表示采集所有容器的标准输出。如果您要设置环境变量白名单，那么EnvKey必填，EnvValue可选填。

- 如果EnvValue为空，则容器环境变量中包含EnvKey的容器都匹配。

- 如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才匹配。

EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配，例如设置EnvKey为 NGINX_SERVICE_PORT ，设置EnvValue为`^(80

6379)$`，表示可匹配服务端口为80、6379的容器。</p></li></ul>
多个白名单之间为或关系，即只要容器的环境变量满足任一键值对即可匹配。

ExcludeEnv

Map，其中EnvKey和EnvValue为String类型

否

环境变量黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置环境变量黑名单，那么EnvKey必填，EnvValue可选填。

- 如果EnvValue为空，则容器环境变量中包含EnvKey的容器的日志都将被排除。

- 如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才会被排除。

EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配，例如设置EnvKey为 NGINX_SERVICE_PORT ，设置EnvValue为`^(80\

6379)$`，表示可匹配服务端口为80、6379的容器。</p></li></ul>
多个黑名单之间为或关系，即只要容器的环境变量满足任一键值对即可被排除。

IncludeK8sLabel

Map，其中LabelKey和LabelValue为String类型

否

通过Kubernetes Label（定义在template.metadata中）白名单指定待采集的容器。如果您要设置Kubernetes Label白名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都匹配。

- 如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才匹配。

LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 app ，设置LabelValue为`^(test1\

test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。</p></li></ul>
多个白名单之间为或关系，即只要Kubernetes Label满足任一白名单即可匹配。

ExcludeK8sLabel

Map，其中LabelKey和LabelValue为String类型

否

通过Kubernetes Label（定义在template.metadata中）黑名单排除不采集的容器。如果您要设置Kubernetes Label黑名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都被排除。

- 如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才会被排除。

LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 app ，设置LabelValue为`^(test1\

test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。</p></li></ul>
多个黑名单之间为或关系，即只要Kubernetes Label满足任一黑名单对即可被排除。

K8sNamespaceRegex

String

否

通过Namespace名称指定采集的容器，支持正则匹配。例如设置为`^(default\

nginx)$`，表示匹配nginx命名空间、default命名空间下的所有容器。

K8sPodRegex

String

否

通过Pod名称指定待采集的容器，支持正则匹配。例如设置为 ^(nginx-log-demo.*)$   ，表示匹配以nginx-log-demo开头的Pod下的所有容器。

K8sContainerRegex

String

否

通过容器名称指定待采集的容器（Kubernetes容器名称是定义在spec.containers中），支持正则匹配。例如设置为 ^(container-test)$   ，表示匹配所有名为container-test的容器。

数据处理参数

参数

类型

是否必选

说明

BeginLineRegex

String

否

行首匹配的正则表达式。

该配置项为空，表示单行模式。

如果该表达式匹配某行的开头，则将该行作为一条新的日志，否则将此行拼接到上一条日志。

BeginLineCheckLength

Integer

否

行首匹配的长度，单位：字节。

默认取值为10×1024字节。

如果行首匹配的正则表达式在前N个字节即可体现，推荐设置此参数，提升行首匹配效率。

BeginLineTimeoutMs

Integer

否

行首匹配的超时时间，单位：毫秒。

默认取值为3000毫秒。

如果3000毫秒内没有出现新日志，则结束匹配，将最后一条日志上传到日志服务。

MaxLogSize

Integer

否

日志最大长度，默认取值为0，单位：字节。

默认取值为512×1024字节。

如果日志长度超过该值，则不再继续查找行首，直接上传。

ExternalK8sLabelTag

Map，其中LabelKey和LabelValue为String类型

否

设置Kubernetes Label（定义在template.metadata中）日志标签后，iLogtail将在日志中新增Kubernetes Label相关字段。

例如设置LabelKey为app，LabelValue为`k8s_label_app`，当Pod中包含Label `app=serviceA`时，会将该信息iLogtail添加到日志中，即添加字段k8s_label_app: serviceA；若不包含名为app的label时，添加空字段k8s_label_app: 。

ExternalEnvTag

Map，其中EnvKey和EnvValue为String类型

否

设置容器环境变量日志标签后，iLogtail将在日志中新增容器环境变量相关字段。

例如设置EnvKey为`VERSION`，EnvValue为`env_version`，当容器中包含环境变量`VERSION=v1.0.0`时，会将该信息以tag形式添加到日志中，即添加字段env_version: v1.0.0；若不包含名为VERSION的环境变量时，添加空字段env_version: 。

数据处理环境变量

环境变量

类型

是否必选

说明

ALIYUN_LOG_ENV_TAGS

String

否

设置全局环境变量日志标签后，iLogtail将在日志中新增iLogtail所在容器环境变量相关字段。多个环境变量名以`\

`分隔。</p>
例如设置为node_name\

node_ip，当iLogtail容器中暴露相关环境变量时，会将该信息以tag形式添加到日志中，即添加字段node_ip:172.16.0.1和node_name:worknode。</p>

默认日志字段

所有使用本插件上报的日志均额外携带下列字段。目前暂不支持更改。

字段名称

说明

_time_

日志采集时间，例如 2021-02-02T02:18:41.979147844Z   。

_source_

日志源类型，stdout或stderr。

_image_name_

镜像名

_container_name_

容器名

_pod_name_

Pod名

_namespace_

Pod所在的命名空间

_pod_uid_

Pod的唯一标识

样例

示例1：通过容器环境变量黑白名单过滤容器

采集环境变量含 NGINX_SERVICE_PORT=80 且不含 POD_NAMESPACE=kube-system 的容器的标准输出。

1. 获取环境变量。

您可以登录容器所在的宿主机查看容器的环境变量。具体操作，请参见获取容器环境变量。

命令提示：

docker inspect

crictl inspect

ctr -n k8s.io containers info

"Env": [

...

"NGINX_SERVICE_PORT=80",

2. 创建iLogtail采集配置。

iLogtail采集配置示例如下所示。

inputs:

- Type: service_docker_stdout

Stdout: true

Stderr: false

IncludeEnv:

NGINX_SERVICE_PORT: "80"

ExcludeEnv:

POD_NAMESPACE: "kube-system"

示例2：通过容器Label黑白名单过滤容器

采集容器Label含 io.kubernetes.container.name:nginx 且不含 io.kubernetes.pod.namespace:kube-system 容器的标准输出。

1. 获取容器Label。

您可以登录容器所在的宿主机查看容器的Label。具体操作，请参见获取容器Label。

"Labels": {

...

"io.kubernetes.container.name": "nginx",

2. 创建Logtail采集配置。

Logtail采集配置示例如下所示。

inputs:

- Type: service_docker_stdout

Stdout: true

Stderr: false

IncludeLabel:

io.kubernetes.container.name: "nginx"

IncludeLabel:

io.kubernetes.pod.namespace": "kube-system"

示例3：通过Kubernetes Namespace名称、Pod名称和容器名称过滤容器

采集default命名空间下以nginx-开头的Pod中的nginx容器的标准输出。

1. 获取Kubernetes层级的信息。

命令提示：

kubectl describe

Name:         nginx-76d49876c7-r892w

Namespace:    default

...

Containers:

nginx:

Container ID:...

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: service_docker_stdout

Stdout: true

Stderr: false

K8sNamespaceRegex: "^(default)$"

K8sPodRegex: "^(nginx-.*)$"

K8sContainerRegex: "^(nginx)$"

示例4：通过Kubernetes Label过滤容器

采集Kubernetes Label含app=nginx且不含env=test开头的所有容器的标准输出。

1. 获取Kubernetes层级的信息。

Name:         nginx-76d49876c7-r892w

Namespace:    default

...

Labels:       app=nginx

...

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: service_docker_stdout

Stdout: true

Stderr: false

IncludeK8sLabel:

app: "nginx"

ExcludeK8sLabel:

env: "^(test.*)$"

示例5：多行日志的iLogtail采集配置

采集输出在标准错误流的Java异常堆栈（多行日志）。

1. 获取日志样例。

2021-02-03 14:18:41.969 ERROR [spring-cloud-monitor] [nio-8080-exec-4] c.g.s.web.controller.DemoController : java.lang.NullPointerException

at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)

at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)

...

根据有区分度的行首编写正则。

行首： 2021-02-03 ...

正则： \d+-\d+-\d+.*

2. 创建Logtail采集配置。 Logtail采集配置示例如下所示。

inputs:

- Type: service_docker_stdout

Stdout: false

Stderr: true

BeginLineCheckLength: 10

BeginLineRegex: "\\d+-\\d+-\\d+.*"

文本日志（debug）

简介

metric_debug_file  插件是一个用于调试的插件，它可以逐行读取指定文件的内容，并将其与指定的名称绑定在一起成为一个字段，用于模拟文件输入。源代码

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，固定为 metric_debug_file   。

InputFilePath

String

是

要读入的文件路径。

FieldName

String

否

生成的字段的字段名。默认取值为 content   。

LineLimit

Integer

否

读取文件的前n行。默认取值为1000行。

样例

- 输入

echo "2022/07/26/14:25:47 hello world" >> /home/test-log/debug_file.log

echo "2023/05/23/19:37:47 hello world" >> /home/test-log/debug_file.log

- 采集配置

enable: true

inputs:

- Type: metric_debug_file

InputFilePath: /home/test-log/debug_file.log

FieldName: HelloWorld

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"HelloWorld": "2022/07/26/14:25:47 hello world",

"__time__":"1658814799"

}

{

"HelloWorld": "2023/05/23/19:37:47 hello world",

"__time__":"1658814799"

}

MetricInput示例插件

简介

metric_input_example  可作为编写 MetricInput 类插件的参考示例样例，该插件会定时生成模拟的指标数据。源代码

版本

Stable

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 metric_input_example   。

样例

- 采集配置

enable: true

inputs:

- Type: metric_input_example

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__name__":"example_counter",

"__labels__":"hostname#$#************************|ip#$#172.***.***.***",

"__time_nano__":"1658491078378371632",

"__value__":"101",

"__time__":"1658491078"

}

主机Meta数据

简介

metric_meta_host   input 插件用于采集主机的Meta信息（例如CPU型号、内存大小、进程等）。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

CPU

Boolean

否

是否开启主机CPU采集。

默认取值：true。

Memory

Boolean

否

是否开启主机Memory采集。

默认取值：true。

Net

Boolean

否

是否开启主机Net采集。

默认取值：false。

Disk

Boolean

否

是否开启主机Disk采集。

默认取值：false。

Process

Boolean

否

是否开启主机Process采集。

默认取值：false。
件。

ProcessNamesRegex

String数组

否

进程名过滤规则，支持正则匹配。件。

Labels

String字典

否

自定义Labels。件。

ProcessIntervalRound

Integer

否

Process采集间隔。

默认取值：5s。

样例

采集主机上CPU、Memory、Net、Disk、Process等Meta信息。

采集配置

enable: true

inputs:

- Type: metric_meta_host

CPU: true

Memory: true

Net: true

Disk: true

Process: true

ProcessIntervalRound: 60

ProcessNamesRegex:

- ilogtail

Labels:

cluster: ilogtail-test-cluster

flushers:

- Type: flusher_stdout

OnlyStdout: true

输出

- 主机Meta信息

{

"__time__": 1658364854,

"type": "HOST",

"labels": "{\"platform_family\":\"\",\"ip\":\"172.16.2.0\",\"os\":\"linux\",\"virtualization_role\":\"guest\",\"boot_time\":\"1640524878\",\"platform_version\":\"3\",\"cluster\":\"ilogtail-test-cluster\",\"hostname\":\"iZj6cilksm3spb8xfv2t888\",\"platform\":\"alibaba\",\"kernel_version\":\"5.10.60-9.al8.x86_64\",\"kernel_arch\":\"x86_64\",\"virtualization_system\":\"\",\"host_id\":\"591c4a11-6b13-4735-a4ee-c46d11bf164e\"}",

"attributes": "{\"MEM\":

{\"mem_total\":16221536256,\"swap_total\":0,\"vsz_total\":35184372087808},\"CPU\":{\"cache_size\":49152,\"core_count\":2,\"family\":\"6\",\"mhz\":2699.998,\"model\":\"106\",\"model_name\":\"Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz\",\"processor_count\":4,\"vendor_id\":\"GenuineIntel\"},\"NET\":

[{\"addrs\":[{\"addr\":\"127.0.0.1/8\"},{\"addr\":\"::1/128\"}],\"flags\":[\"up\",\"loopback\"],\"hardware_address\":\"\",\"index\":1,\"mtu\":65536,\"name\":\"lo\"},{\"addrs\":[{\"addr\":\"172.16.2.0/24\"},{\"addr\":\"fe80::216:3eff:fe01:4786/64\"}],\"flags\":[\"up\",\"broadcast\",\"multicast\"],\"hardware_address\":\"00:16:3e:02:47:86\",\"index\":2,\"mtu\":1500,\"name\":\"eth0\"},{\"addrs\":[{\"addr\":\"172.17.0.1/16\"},{\"addr\":\"fe80::42:cfff:fe44:79dd/64\"}],\"flags\":[\"up\",\"broadcast\",\"multicast\"],\"hardware_address\":\"02:42:cc:41:79:dd\",\"index\":3,\"mtu\":1500,\"name\":\"docker0\"}],\"DISK\":[{\"device\":\"/dev/vda1\",\"fstype\":\"ext4\",\"mount_point\":\"/\",\"opts\":\"rw,relatime\"},{\"device\":\"/dev/vdb1\",\"fstype\":\"ext4\",\"mount_point\":\"/mnt\",\"opts\":\"rw,relatime\"}]}",

"id": "591c4a11-6b13-4735-a4ee-c46d11bf164e_172.16.2.0",

"parents": "[]"

}

- 进程Meta信息

{

"__time__": 1658364348,

"type": "PROCESS",

"labels": "{\"cluster\":\"ilogtail-test-cluster\",\"hostname\":\"iZj6cilksm3spb8xfv2t888\",\"ip\":\"172.16.2.0\"}",

"attributes": "{\"command\":\"./ilogtail\",\"exe\":\"/mnt/bin/ilogtail-1.1.0/ilogtail\",\"name\":\"ilogtail\",\"ppid\":3403955,\"pid\":3404557}",

"id": "iZj6cilksm3spb8xfv2t888_172.16.2.0_PROCESS_3404557_1783946933",

"parents": "[\"HOST:591c4a11-6b13-4735-a4ee-c46d11bf164e_172.16.2.0:iZj6cilksm3spb8xfv2t888\"]"

}

Mock数据-Metric

简介

metric_mock  插件是用于模拟采集Metric类型输入数据的插件，可以通过调整参数获取不同的模拟输入。源代码

版本

Stable

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 metric_mock   。

Tags

Map，其中tagKey和tagValue为String类型， {}

可以按需求给mock数据添加tag。

Fields

Map，其中fieldKey和fieldValue为String类型， {}

可以按需求给mock数据添加字段。

Index

Long， 0

生成的mock数据的开始编号（从下一个编号开始）。

OpenPrometheusPattern

Boolean， false

是否生成Prometheus样式的mock数据。

样例

- 采集配置1

enable: true

inputs:

- Type: metric_mock

Fields:

field1: field1

field2: field2

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出1

{

"field2":"field2",

"Index":"1",

"field1":"field1",

"__time__":"1658807050"

}

{

"field1":"field1",

"field2":"field2",

"Index":"2",

"__time__":"1658807051"

}

- 采集配置2

enable: true

inputs:

- Type: metric_mock

Index: 100

Tags:

tag1: tag1

tag2: tag2

Fields:

field1: field1

field2: field2

OpenPrometheusPattern: true

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出2

{

"__name__":"metrics_mock",

"__labels__":"field1#$#field1|field2#$#field2|tag1#$#tag1|tag2#$#tag2",

"__time_nano__":"1658806869597190887",

"__value__":"101",

"__time__":"1658806869"

}

{

"__name__":"metrics_mock",

"__labels__":"field1#$#field1|field2#$#field2|tag1#$#tag1|tag2#$#tag2",

"__time_nano__":"1658806870597391426",

"__value__":"102",

"__time__":"1658806870"

}

无侵入网络调用数据

简介

observer_ilogtail_network  插件支持从网络系统调用中收集四层网络调用，并借助网络解析模块，可以识别七层网络调用细节。此功能核心网络观测能力基于eBPF技术实现，具有高性能、无侵入等核心优势。

版本

Beta

前提

1. Linux 内核 4.19+

2. 下载libebpf.so 动态链接库放到iLogtail 的运行路径，此代码后续被CoolBpf 开源。

- wget https://logtail-release-us-west-1.oss-us-west-1.aliyuncs.com/kubernetes/libebpf.so

配置参数

基础参数

参数

类型

是否必选

说明

Type

String

否

插件类型，指定为 observer_ilogtail_network_v1   。

Common.FlushOutL4Interval

Number

否

聚合数据输出间隔时间，默认15s

Common.FlushOutL7Interval

Number

否

聚合数据输出间隔时间，默认60s

Common.FlushMetaInterval

Number

否

读取容器元信息间隔时间，默认30s，行为可类比我为docker ps

Common.FlushNetlinkInterval

Number

否

设置读取Socket元信息的时间间隔，默认10s

Common.Sampling

Number

否

设置网络数据的采样率，默认100

Common.ProtocolProcess

bool

否

开启后Logtail将解析应用层的网络协议数据，例如HTTP、MySQL、Redis等，默认开启。

Common.DropUnixSocket

Number

否

开启后将丢弃Unix域网络请求。Unix域常用于本地网络交互，默认开启。

Common.DropLocalConnections

Number

否

开启后丢弃对端地址为本地的INET域网络请求，默认开启。

Common.DropUnknownSocket

Number

否

开启后将丢弃非INET域或Unix域的网络请求，默认开启。

Common.IncludeProtocols

[]string

否

进行7层网络协议识别的协议类别，默认为全部，目前支持HTTP、Redis、MySQL、PgSQL、DNS 5种协议。

Common.Tags

map[string]string

否

tagb标签，会被附带上传

EBPF.Enabled

map[string]string

是

开启Ebpf 功能

高级参数

参数

类型

是否必选

说明

Common.IncludeContainerLabels

map[string]string

否

用于指定待采集的容器。多个白名单之间为或关系，即只要容器Label满足任一白名单即可被匹配。注意： 此变量为容器Label而非Kubernetes Label

Common.ExcludeContainerLabels

map[string]string

否

用于排除待采集的容器。多个黑名单之间为或关系，即只要容器Label满足任一黑名单即可被匹配。注意： 此变量为容器Label而非Kubernetes Label

Common.IncludeK8sLabels

map[string]string

否

用于指定待采集的容器。设置LabelKey为具体名称，LabelValue为正则表达式。例如设置LabelKey为io.kubernetes.container.name，设置LabelValue为^(nginx

Common.ExcludeK8sLabels

map[string]string

否

用于排除不需要采集的容器。设置LabelKey为具体名称，LabelValue为正则表达式。例如设置LabelKey为io.kubernetes.container.name，设置LabelValue为^(nginx

Common.IncludeEnvs

map[string]string

否

用于指定待采集的容器。设置EnvKey为具体名称，EnvValue为正则表达式。例如设置EnvKey为NGINX_SERVICE_PORT，设置EnvValue为^(80

Common.ExcludeEnvs

map[string]string

否

用于排除不需要采集的容器。设置EnvKey为具体名称，EnvValue为正则表达式。例如设置EnvKey为NGINX_SERVICE_PORT，设置EnvValue为^(80

Common.IncludeCmdRegex

string

否

设置命令行正则表达式，用于指定需要监控的进程。例如设置为^mockclient$，表示仅监控/proc/{pid}/cmdline下名为mockclient的进程。

Common.ExcludeCmdRegex

string

否

设置命令行正则表达式，用于排除不需要监控的进程。例如设置为^mockclient$，表示不监控/proc/{pid}/cmdline下名为mockclient的进程。

Common.IncludeContainerNameRegex

string

否

输入匹配Contianer名称的正则表达式，用于指定待采集的 Contianer。

Common.ExcludeContainerNameRegex

string

否

输入匹配Contianer名称的正则表达式，用于排除不需要采集的 Contianer。

Common.IncludePodNameRegex

string

否

输入匹配Pod名称的正则表达式，用于指定待采集的Pod。

Common.ExcludePodNameRegex

string

否

输入匹配Pod名称的正则表达式，用于排除不需要采集的Pod。

Common.IncludeNamespaceNameRegex

string

否

输入匹配Namespace名称的正则表达式，用于指定待采集的命名空间。

Common.ExcludeNamespaceNameRegex

string

否

输入匹配Namespace名称的正则表达式，用于排除不需要采集的命名空间。

EBPF.Pid

map[string]string

否

指定唯一的进程ID 用于采集范围确定

样例：收集HTTP 请求调用

采集配置

observer_ilogtail_network_v1 程序运行与C++ 核心部分，需要增加processor_default 插件，才可以选取社区多种输出插件，如Kafka

enable: true

inputs:

- Type: observer_ilogtail_network_v1

Common:

FlushOutL4Interval: 5

FlushOutL7Interval: 5

EBPF:

Enabled: true

processors:

- Type: processor_default

flushers:

- Type: flusher_stdout

输出

2022-08-25 16:44:01 [INF] [flusher_stdout.go:119] [Flush] [config#/root/workspace/ilogtail/output/./config/local/demo.yaml,] {"type":"protocols","_process_pid_":"605","_process_cmd_":"/usr/sbin/nscd","_running_mode_":"host","protocol":"dns","query_record":"ilogtail-community-edition.cn-shanghai.log.aliyuncs.com","query_type":"A","success":"1","role":"client","remote_info":"{\"remote_ip\":\"100.100.2.136\",\"remote_port\":\"53\",\"remote_type\":\"dns\"}\n","total_count":"1","total_latency_ns":"387138","total_req_bytes":"73","total_resp_bytes":"272","__time__":"1661417038"}:

2022-08-25 16:44:01 [INF] [flusher_stdout.go:119] [Flush] [config#/root/workspace/ilogtail/output/./config/local/demo.yaml,] {"type":"protocols","_process_pid_":"1945","_process_cmd_":"/usr/local/cloudmonitor/bin/argusagent","_running_mode_":"host","protocol":"http","version":"1","host":"metrichub-cn-beijing.aliyun.com","method":"POST","url":"/agent/metrics/putLines","resp_code":"200","role":"client","remote_info":"{\"remote_ip\":\"100.100.105.70\",\"remote_port\":\"80\",\"remote_type\":\"server\"}\n","total_count":"1","total_latency_ns":"3492453","total_req_bytes":"13661","total_resp_bytes":"165","__time__":"1661417038"}:

2022-08-25 16:44:01 [INF] [flusher_stdout.go:119] [Flush] [config#/root/workspace/ilogtail/output/./config/local/demo.yaml,] {"type":"statistics","_process_pid_":"1945","_process_cmd_":"/usr/local/cloudmonitor/bin/argusagent","_running_mode_":"host","remote_info":"{\"remote_ip\":\"100.100.105.70\",\"remote_port\":\"80\",\"remote_type\":\"server\"}\n","socket_type":"inet_socket","role":"client","send_bytes":"13661","recv_bytes":"165","send_packets":"1","recv_packets":"1","send_total_latency":"0","recv_total_latency":"0","__time__":"1661417038"}:

2022-08-25 16:44:01 [INF] [flusher_stdout.go:119] [Flush] [config#/root/workspace/ilogtail/output/./config/local/demo.yaml,] {"type":"statistics","_process_pid_":"605","_process_cmd_":"/usr/sbin/nscd","_running_mode_":"host","remote_info":"{\"remote_ip\":\"100.100.2.136\",\"remote_port\":\"53\",\"remote_type\":\"dns\"}\n","socket_type":"inet_socket","role":"client","send_bytes":"73","recv_bytes":"272","send_packets":"1","recv_packets":"1","send_total_latency":"0","recv_total_latency":"0","__time__":"1661417038"}:

主机监控数据

简介

metric_system_v2   input 插件用于采集主机的监控数据（例如CPU、内存、负载、磁盘、网络等）。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

CPU

Boolean

否

是否开启主机CPU指标采集。

默认取值：true。

Mem

Boolean

否

是否开启主机Memory指标采集。

默认取值：true。

Disk

Boolean

否

是否开启主机Disk指标采集。

默认取值：true。

Net

Boolean

否

是否开启主机Net指标采集。

默认取值：true。

Protocol

Boolean

否

是否开启主机Protocol指标采集。

默认取值：true。
件。

TCP

Boolean

否

是否开启主机Net采集。

默认取值：false。

OpenFd

Boolean

否

是否开启主机Net采集。

默认取值：true。

CPUPercent

Boolean

否

是否开启主机CPU使用率指标采集。

默认取值：true。

Labels

String字典

否

自定义Labels。件。

样例

采集主机上CPU、Memory、Net、Disk、Process等监控数据。

采集配置

enable: true

inputs:

- Type: metric_system_v2

CPU: true

Mem: true

Disk: true

Disk: true

Net: true

Protocol: true

TCP: true

OpenFd: true

CPUPercent: true

Labels:

cluster: ilogtail-test-cluster

flushers:

- Type: flusher_stdout

FileName: /tmp/124.log

OnlyStdout: false

输出

- 主机指标信息

{

"__name__":"net_out_pkt",

"__labels__":"cluster#$#ilogtail-test-cluster|hostname#$#master-1-1.c-ca9717110efa1b40|hostname#$#test-1|interface#$#eth0|ip#$#10.1.37.31",

"__time_nano__":"1680079323040664058",

"__value__":"32.764761658490045",

"__time__":"1680079323"

}

Canal

简介

service_canal   input 插件可以采集MySQL Binlog。

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，指定为 service_canal   。

Host

String， 127.0.0.1

数据库主机。

Port

Interger， 3306

数据库端口。

User

String， root

数据库用户名。

Password

String，默认值为空

数据库密码。

ServerID

Interger，125

Logtail模拟Mysql Slave的ID。

IncludeTables

Array， 无默认值（必填）

包含的表名称（包括db，例如：test_db.test_table），可配置为正则表达式。如果某个表不符合IncludeTables中的任一条件则该表不会被采集。如果您希望采集所有表，请将此参数设置为 .*\\..*   。如果需要完全匹配，请在前面加上^，后面加上$，例如：^test_db\.test_table$。

ExcludeTables

Array， 无默认值（必填）

忽略的表名称（包括db，例如：test_db.test_table），可配置为正则表达式。如果某个表符合ExcludeTables中的任一条件则该表不会被采集。不设置时默认收集所有表。

StartBinName

String， ""

首次采集的Binlog文件名。不设置时，默认从当前时间点开始采集。如果想从指定位置开始采集，可以查看当前的Binlog文件以及文件大小偏移量，并将StartBinName、StartBinlogPos设置成对应的值。

StartBinlogPos

Interger， true

是否附加全局事务ID。不设置时，默认为true。设置为false时，表示上传的数据不附加全局事务ID。

EnableGTID

Boolean， true

是否附加全局事务ID。不设置时，默认为true。设置为false时，表示上传的数据不附加全局事务ID。

EnableInsert

Boolean， true

是否采集insert事件的数据。不设置时，默认为true。设置为false时，表示将不采集insert事件数据。

EnableUpdate

Boolean， true

是否采集update事件的数据。不设置时，默认为true。设置为false时，表示不采集update事件数据。

EnableDelete

Boolean， true

是否采集delete事件的数据。不设置时，默认为true。设置为false时，表示不采集delete事件数据。

EnableDDL

Boolean， false

是否采集DDL（data definition language）事件数据。不设置时， 默认为false，表示不收集DDL事件数据。该选项不支持IncludeTables和ExcludeTables过滤。

Charset

String， utf-8

编码方式。不设置时，默认为utf-8。

TextToString

Boolean， false

是否将text类型的数据转换成字符串。不设置时，默认为false，表示不转换。

PackValues

Boolean， false

是否将事件数据打包成JSON格式。默认为false，表示不打包。如果设置为true，Logtail会将事件数据以JSON格式集中打包到data和old_data两个字段中，其中old_data仅在row_update事件中有意义。 示例：假设数据表有三列数据c1，c2，c3，设置为false，row_insert事件数据中会有c1，c2，c3三个字段，而设置为true时，c1，c2，c3会被统一打包为data字段，值为 {"c1":"...", "c2": "...", "c3": "..."}   。

EnableEventMeta

Boolean， false

是否采集事件的元数据，默认为false，表示不采集。 Binlog事件的元数据包括event_time、event_log_position、event_size和event_server_id。

UseDecimal

Boolean， false

Binlog解析DECIMAL类型时，是否保持原格式输出，而不是使用科学计数法。如果未设置，系统默认为false，即默认使用科学计数法。

样例

对user_info数据库下的SpecialAlarm表分别执行INSERT、UPDATE、DELETE操作，数据库表结构、数据库操作及日志样例如下所示。

- 表结构

CREATE TABLE `titles` (

`emp_no` int(11) NOT NULL,

`title` varchar(50) NOT NULL,

`from_date` date NOT NULL,

`to_date` date DEFAULT NULL,

PRIMARY KEY (`emp_no`,`title`,`from_date`),

) ENGINE=InnoDB DEFAULT CHARSET=utf8;

- 表内容，其中一行

emp_no title from_date to_date

10006 Senior Engineer 1990-08-05 9999-01-01

- 执行三条语句

update titles set title = 'test-update' where emp_no = 10006

delete from titles where emp_no = 10006

INSERT INTO `titles` (`emp_no`, `title`, `from_date`, `to_date`)

VALUES

(10006, 'Senior Engineer', '1990-08-05', '9999-01-01');

- 采集配置

enable: true

inputs:

- Type: service_canal

Host: 127.0.0.1

Port: 3306

ServerID: 123456

Password: xxxxx

EnableDDL: true

TextToString: true

flushers:

- Type: flusher_kafka

Brokers:

- localhost:9092

Topic: access-log

- 输出

{"Time":1657890330,"Contents":[{"Key":"_table_","Value":"titles"},{"Key":"_offset_","Value":"4308"},{"Key":"_old_emp_no","Value":"10006"},{"Key":"from_date","Value":"1990-08-05"},{"Key":"_host_","Value":"127.0.0.1"},{"Key":"_event_","Value":"row_update"},{"Key":"_id_","Value":"12"},{"Key":"_old_from_date","Value":"1990-08-05"},{"Key":"_gtid_","Value":"00000000-0000-0000-0000-000000000000:0"},{"Key":"_db_","Value":"employees"},{"Key":"_filename_","Value":"mysql-bin.000001"},{"Key":"_old_title","Value":"Senior Engineer"},{"Key":"_old_to_date","Value":"9999-01-01"},{"Key":"emp_no","Value":"10006"},{"Key":"title","Value":"test-update"},{"Key":"to_date","Value":"9999-01-01"}]}

{"Time":1657890333,"Contents":[{"Key":"_id_","Value":"13"},{"Key":"_filename_","Value":"mysql-bin.000001"},{"Key":"emp_no","Value":"10006"},{"Key":"title","Value":"test-update"},{"Key":"_db_","Value":"employees"},{"Key":"_table_","Value":"titles"},{"Key":"_event_","Value":"row_delete"},{"Key":"from_date","Value":"1990-08-05"},{"Key":"to_date","Value":"9999-01-01"},{"Key":"_host_","Value":"127.0.0.1"},{"Key":"_gtid_","Value":"00000000-0000-0000-0000-000000000000:0"},{"Key":"_offset_","Value":"4660"}]}

{"Time":1657890335,"Contents":[{"Key":"_offset_","Value":"4975"},{"Key":"emp_no","Value":"10006"},{"Key":"title","Value":"Senior Engineer"},{"Key":"from_date","Value":"1990-08-05"},{"Key":"_gtid_","Value":"00000000-0000-0000-0000-000000000000:0"},{"Key":"_filename_","Value":"mysql-bin.000001"},{"Key":"_table_","Value":"titles"},{"Key":"_event_","Value":"row_insert"},{"Key":"_id_","Value":"14"},{"Key":"to_date","Value":"9999-01-01"},{"Key":"_host_","Value":"127.0.0.1"},{"Key":"_db_","Value":"employees"}]}

GO Profile

简介

service_go_profile   input 插件可以采集Golang pprof 性能数据。

配置参数

全局参数

参数

类型，默认值

说明

Mode

string，无默认值（必填）

工作类型，目前支持 host 与 kubernets    2种环境工作。

Config

object，无默认值（必填）

详见不同工作模式子配置。

Interval

int， 10

抓取性能数据间隔，单位秒

Timeout

int， 15

抓取性能数据超时时间，单位秒

BodyLimitSize

int， 10240

抓取性能数据Body最大上限，单位KB

EnabledProfiles

[]string， ["cpu", "mem", "goroutines", "mutex", "block"]

抓取性能数据类型。

Labels

map[string]string， {}

性能数据全局追加标签。

host模式子配置

对于静态host模式，需要指定service标签标明归属服务。

1. 子配置

参数

类型，默认值

说明

Addresses

[]Address，无默认值（必填）

Address Object 数组

1. Address 配置

参数

类型，默认值

说明

Host

string，无默认值（必填）

实例地址

Port

int，无默认值（必填）

实例端口

InstanceLabels

map[string]string， {}

具体实例性能数据追加标签

kubernetes模式子配置

待采集容器需要先声明ILOGTAIL_PROFILE_PORT={PORT} 环境变量，其后通过下述配置二次过滤。

参数

类型

是否必选

说明

IncludeContainerLabel

Map，其中LabelKey和LabelValue为String类型

否

容器Label白名单，用于指定待采集的容器。默认为空，表示采集所有容器。如果您要设置容器Label白名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则容器Label中包含LabelKey的容器都匹配。

- 如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才匹配。

LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 io.kubernetes.container.name ，设置LabelValue为`^(nginx\

cube)$`，表示可匹配名为nginx、cube的容器。</p></li></ul>
多个白名单之间为或关系，即只要容器Label满足任一白名单即可匹配。

ExcludeContainerLabel

Map，其中LabelKey和LabelValue为String类型

否

容器Label黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置容器Label黑名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则容器Label中包含LabelKey的容器都将被排除。

- 如果LabelValue不为空，则容器Label中包含LabelKey=LabelValue的容器才会被排除。

LabelValue默认为字符串匹配，即只有LabelValue和容器Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 io.kubernetes.container.name ，设置LabelValue为`^(nginx\

cube)$`，表示可匹配名为nginx、cube的容器。</p></li></ul>
多个黑名单之间为或关系，即只要容器Label满足任一黑名单对即可被排除。

IncludeEnv

Map，其中EnvKey和EnvValue为String类型

否

设环境变量白名单，用于指定待采集的容器。默认为空，表示采集所有容器。如果您要设置环境变量白名单，那么EnvKey必填，EnvValue可选填。

- 如果EnvValue为空，则容器环境变量中包含EnvKey的容器都匹配。

- 如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才匹配。

EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配，例如设置EnvKey为 NGINX_SERVICE_PORT ，设置EnvValue为`^(80

6379)$`，表示可匹配服务端口为80、6379的容器。</p></li></ul>
多个白名单之间为或关系，即只要容器的环境变量满足任一键值对即可匹配。

ExcludeEnv

Map，其中EnvKey和EnvValue为String类型

否

环境变量黑名单，用于排除不采集的容器。默认为空，表示不排除任何容器。如果您要设置环境变量黑名单，那么EnvKey必填，EnvValue可选填。

- 如果EnvValue为空，则容器环境变量中包含EnvKey的容器的日志都将被排除。

- 如果EnvValue不为空，则容器环境变量中包含EnvKey=EnvValue的容器才会被排除。

EnvValue默认为字符串匹配，即只有EnvValue和环境变量的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配，例如设置EnvKey为 NGINX_SERVICE_PORT ，设置EnvValue为`^(80\

6379)$`，表示可匹配服务端口为80、6379的容器。</p></li></ul>
多个黑名单之间为或关系，即只要容器的环境变量满足任一键值对即可被排除。

IncludeK8sLabel

Map，其中LabelKey和LabelValue为String类型

否

通过Kubernetes Label（定义在template.metadata中）白名单指定待采集的容器。如果您要设置Kubernetes Label白名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都匹配。

- 如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才匹配。

LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 app ，设置LabelValue为`^(test1\

test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。</p></li></ul>
多个白名单之间为或关系，即只要Kubernetes Label满足任一白名单即可匹配。

ExcludeK8sLabel

Map，其中LabelKey和LabelValue为String类型

否

通过Kubernetes Label（定义在template.metadata中）黑名单排除不采集的容器。如果您要设置Kubernetes Label黑名单，那么LabelKey必填，LabelValue可选填。

- 如果LabelValue为空，则Kubernetes Label中包含LabelKey的容器都被排除。

- 如果LabelValue不为空，则Kubernetes Label中包含LabelKey=LabelValue的容器才会被排除。

LabelValue默认为字符串匹配，即只有LabelValue和Kubernetes Label的值完全相同才会匹配。如果该值以 ^ 开头并且以 $ 结尾，则为正则匹配。例如设置LabelKey为 app ，设置LabelValue为`^(test1\

test2)$`，表示匹配Kubernetes Label中包含app:test1、app:test2的容器。</p></li></ul>
多个黑名单之间为或关系，即只要Kubernetes Label满足任一黑名单对即可被排除。

K8sNamespaceRegex

String

否

通过Namespace名称指定采集的容器，支持正则匹配。例如设置为`^(default\

nginx)$`，表示匹配nginx命名空间、default命名空间下的所有容器。

K8sPodRegex

String

否

通过Pod名称指定待采集的容器，支持正则匹配。例如设置为 ^(nginx-log-demo.*)$   ，表示匹配以nginx-log-demo开头的Pod下的所有容器。

K8sContainerRegex

String

否

通过容器名称指定待采集的容器（Kubernetes容器名称是定义在spec.containers中），支持正则匹配。例如设置为 ^(container-test)$   ，表示匹配所有名为container-test的容器。

ExternalK8sLabelTag

Map，其中LabelKey和LabelValue为String类型

否

设置Kubernetes Label（定义在template.metadata中）标签后，iLogtail将在性能数据中新增Kubernetes Label相关字段。

例如设置LabelKey为app，LabelValue为`k8s_label_app`，当Pod中包含Label `app=serviceA`时，会将该信息iLogtail添加到性能数据中，即添加字段k8s_label_app: serviceA；若不包含名为app的label时，添加空字段k8s_label_app: 。

ExternalEnvTag

Map，其中EnvKey和EnvValue为String类型

否

设置容器环境变量性能数据标签后，iLogtail将在性能数据中新增容器环境变量相关字段。

例如设置EnvKey为`VERSION`，EnvValue为`env_version`，当容器中包含环境变量`VERSION=v1.0.0`时，会将该信息以tag形式添加到性能数据中，即添加字段env_version: v1.0.0；若不包含名为VERSION的环境变量时，添加空字段env_version: 。

样例

采集host模式性能数据

1. 配置样例

inputs:

- Type: service_go_profile

Mode: host

Labels:

global: outer

service: service

Config:

Addresses:

- Host: "127.0.0.1"

Port: 18689

InstanceLabels:

service: inner

1. 采集结果

2023-04-03 14:04:52 [INF] [flusher_stdout.go:120] [Flush] [1.0#PluginProject_0##Config0,PluginLogstore_0]       {"name":"github.com/denisenkom/go-mssqldb/internal/cp.init /Users/evan/go/pkg/mod/github.com/denisenkom/go-mssqldb@v0.12.2/internal/cp/cp950.go","stack":"runtime.doInit /usr/local/go/src/runtime/proc.go\nruntime.doInit /usr/local/go/src/runtime/proc.go\nruntime.doInit /usr/local/go/src/runtime/proc.go\nruntime.doInit /usr/local/go/src/runtime/proc.go\nruntime.doInit /usr/local/go/src/runtime/proc.go\nruntime.main /usr/local/go/src/runtime/proc.go","stackID":"c4bbfc9dff64151d","language":"go","type":"profile_mem","dataType":"CallStack","durationNs":"0","profileID":"f6a443c0-cca0-45ac-b50a-b1e25a48fb74","labels":"{\"__name__\":\"service\",\"global\":\"outer\",\"instance\":\"inner\",\"job\":\"1_0_pluginproject_0__config0\"}","units":"bytes","valueTypes":"inuse_space","aggTypes":"sum","val":"1615794.00","__time__":"1680501892"}:

采集kubernets模式性能数据

inputs:

- Type: service_go_profile

Mode: kubernetes

Config:

IncludeK8sLabel:

app: golang-pull

Labels:

global: outer

1. 采集结果

2023-04-03 06:07:13 [INF] [flusher_stdout.go:120] [Flush] [1.0#PluginProject_0##Config0,PluginLogstore_0]       {"name":"runtime.memclrNoHeapPointers /usr/local/go/src/runtime/memclr_amd64.s","stack":"runtime.mallocgc /usr/local/go/src/runtime/malloc.go\nruntime.makeslice /usr/local/go/src/runtime/slice.go\nmain.memNormal /output/main.go\nmain.main.func1 /output/main.go","stackID":"36108813ff189cc4","language":"go","type":"profile_cpu","dataType":"CallStack","durationNs":"10000045532","profileID":"7bb6291c-b358-43fa-888a-dec7676552e4","labels":"{\"__name__\":\"golang-pull\",\"container\":\"golang-pull\",\"instance\":\"10.175.2.230:8080\",\"job\":\"1_0_pluginproject_0__config0\",\"label\":\"outer\",\"namespace\":\"profile\",\"pod\":\"golang-pull-6b946f8f6c-vhv9t\"}","units":"nanoseconds","valueTypes":"cpu","aggTypes":"sum","val":"20000000.00","__time__":"1680502023"}:

GPU 指标

简介

service_gpu_metric   input 插件可以采集 英伟达 GPU 相关指标（如未安装英伟达驱动，此插件无法正常工作）。

版本

Stable

配置参数

参数

类型，默认值

说明

CollectIntervalMs

int(1000)

插件类型，指定为 service_gpu_metric   。

样例

- 采集配置

enable: true

inputs:

- Type: service_gpu_metric

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"metric_type":"gpu",

"device":"0",

"gpu_power_usage":"7",

"gpu_temperature":"36",

"gpu_util":"0",

"gpu_total_memory":"7611",

"gpu_free_memory":"7611",

"gpu_memory_util":"0",

"gpu_used_memory":"0",

"__time__":"1663034534"

}

采集指标含义

名称

说明

gpu_power_usage

此 GPU 及其相关电路的电源使用情况(以毫瓦为单位)。

gpu_temperature

此 GPU 的温度（以摄氏度为单位）。

gpu_util

GPU 使用率。

gpu_memory_util

GPU 内存使用率。

gpu_used_memory

GPU 使用内存(MB)。

gpu_total_memory

GPU 总内存(MB)。

gpu_free_memory

GPU 剩余内存(MB)。

ServiceInput示例插件

简介

service_http_server   input 插件可以接收来自unix socket、http/https、tcp的请求，并支持sls协议、otlp等多种协议。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，固定为 service_http_server

Format

String

否

数据格式。

支持格式：`sls`、`prometheus`、`influxdb`、`otlp_logv1`、 `otlp_metricv1`、`pyroscope`、`statsd`

v2版本支持格式:`raw`、`prometheus`、`otlp_logv1`、`otlp_metricv1`、`otlp_tracev1`

说明：`raw`格式以原始请求字节流传输数据

Address

String

否

监听地址。

Path

String

否

接收端点, 如Format 为 `otlp_logv1` 时, 默认端点为`/v1/logs` 。

ReadTimeoutSec

String

否

读取超时时间。

默认取值为:`10s`。

ShutdownTimeoutSec

String

否

关闭超时时间。

默认取值为:`5s`。

MaxBodySize

String

否

最大传输 body 大小。

默认取值为:`64k`。

UnlinkUnixSock

String

否

启动前如果监听地址为unix socket，是否进行强制释放。

默认取值为:`true`。

FieldsExtend

Boolean

否

是否支持非integer以外的数据类型(如String)

目前仅针对有 String、Bool 等额外类型的 influxdb Format 有效

QueryParams

[]String

否

需要解析到Group.Metadata中的请求参数。
解析结果会以KeyValue放入Metadata。默认取值为`[]`，即不解析。

仅v2版本有效

QueryParamPrefix

String

否

解析请求参数时需要添加的key前缀，如 _query_param_ 。
前缀会直接拼接在每个QueryParam前，无额外连接符，默认取值为空，即不增加前缀。

仅v2版本有效

HeaderParams

[]String

否

需要解析到Group.Metadata中的header参数。
解析结果会以KeyValue放入Metadata。默认取值为`[]`，即不解析。

仅v2版本有效

HeaderParamPrefix

String

否

解析Header参数时需要添加的key前缀，如 _header_param_ 。
前缀会直接拼接在每个HeaderParam前，无额外连接符，默认取值为空，即不增加前缀。

仅v2版本有效

DisableUncompress

Boolean

否

禁用对于请求数据的解压缩, 默认取值为: false
目前仅针对Raw Format有效

仅v2版本有效

Tags

map[String]String

否

输出数据默认携带标签
仅v1版本有效

DumpData

Boolean

否

[开发使用] 将接收的请求存储于本地文件, 默认取值为: false

DumpDataKeepFiles

Int

否

[开发使用] Dump文件保留文件数目, 文件按小时滚动, 此参数默认值为5, 表示保留5小时Dump 参数

AllowUnsafeMode

Boolean

否

是否允许unsafe模式的Decode，启用该模式，Decoder将可能利用go unsafe技术来加速解码，目前仅当Format=prometheus时有效(注：暂不支持Exemplar、Histogram)

样例

接收 OTLP 日志

- 采集配置

enable: true

inputs:

- Type: service_http_server

Format: "otlp_logv1"

Address: "http://127.0.0.1:12345"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输入

使用 opentelemetry-java-sdk构造数据，基于ExampleConfiguration.java、OtlpExporterExample.java 进行如下代码改造。

ExampleConfiguration  进行  OTLP SDK  初始化。

static OpenTelemetrySdk initHTTPOpenTelemetry() {

// Include required service.name resource attribute on all spans and metrics

Resource resource =

Resource.getDefault()

.merge(Resource.builder().put(SERVICE_NAME, "OtlpExporterExample").build());

OpenTelemetrySdk openTelemetrySdk =

OpenTelemetrySdk.builder()

.setLogEmitterProvider(

SdkLogEmitterProvider.builder()

.setResource(resource)

.addLogProcessor(SimpleLogProcessor

.create(OtlpHttpLogExporter

.builder()

.setEndpoint("http://127.0.0.1:12345/v1/logs")

.build()))

.build())

.buildAndRegisterGlobal();

Runtime.getRuntime()

.addShutdownHook(new Thread(openTelemetrySdk.getSdkLogEmitterProvider()::shutdown));

return openTelemetrySdk;

}

OtlpExporterExample  构造数据。

OpenTelemetrySdk openTelemetry = ExampleConfiguration.initHTTPOpenTelemetry();

LogEmitter logger = openTelemetry.getSdkLogEmitterProvider().get("io.opentelemetry.example");

logger

.logRecordBuilder()

.setBody("log body1")

.setAllAttributes(

Attributes.builder()

.put("k1", "v1")

.put("k2", "v2").build())

.setSeverity(Severity.INFO)

.setSeverityText("INFO")

.setEpoch(Instant.now())

.setContext(Context.current())

.emit();

- 输出

{

"time_unix_nano": "1663913736115000000",

"severity_number": "9",

"severity_text": "INFO",

"content": "log body1",

"attributes": "{\"k1\":\"v1\",\"k2\":\"v2\"}",

"resources": "{\"service.name\":\"OtlpExporterExample\",\"telemetry.sdk.language\":\"java\",\"telemetry.sdk.name\":\"opentelemetry\",\"telemetry.sdk.version\":\"1.18.0\"}",

"__time__": "1663913736"

}

接收 OTLP Logs/Metrics/Traces (v2)

注意：目前v2 pipeline尚不支持otlp logs请求，会丢弃数据。

- 采集配置

enable: true

version: v2

inputs:

- Type: service_http_server

Format: "otlp_logv1"

Address: "http://127.0.0.1:12344"

- Type: service_http_server

Format: "otlp_metricv1"

Address: "http://127.0.0.1:12345"

- Type: service_http_server

Format: "otlp_tracev1"

Address: "http://127.0.0.1:12346"

flushers:

- Type: flusher_stdout

OnlyStdout: true

接收字节流数据

- 采集配置

enable: true

version: v2

inputs:

- Type: service_http_server

Format: "raw"

Address: "http://127.0.0.1:12345"

QueryParams:

- "QueryKey"

QueryParamPrefix: "_param_prefix_"

HeaderParams:

- "HeaderKey"

HeaderParamPrefix: "_header_prefix_"

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输入

手动构造请求

curl --location --request POST 'http://127.0.0.1:12345?QueryKey=queryValue' --header 'HeaderKey: headerValue' --header 'Content-Type: text/plain' --data 'test_measurement,host=server01,region=cn value=0.5'

- 输出

[Event] event 1, metadata map[_header_prefix_HeaderKey:headerValue _param_prefix_QueryKey:queryValue], tags map[__hostname__:579ce1e01dea]

{

"eventType":"byteArray",

"name":"",

"timestamp":0,

"observedTimestamp":0,

"tags":{

},

"byteArray":"test_measurement,host=server01,region=cn value=0.5"

}

接收Pyroscope Agent 数据

- Agent 兼容性说明

Agent

协议

是否兼容

pyroscopde/nodjs

pprof

是

pyroscopde/.net

pprof

是

pyroscopde/.net-new

pprof

是

pyroscopde/java

JFR

是

pyroscopde/go

pprof

是

pyroscopde/php

raw tire

是

pyroscopde/ebpf

raw tire

是

pyroscopde/rust

raw groups

是

pyroscopde/ruby

raw groups

是

pyroscopde/python

raw groups

是

- 采集配置 使用v1 版本表述使用protocol.Log 传递数据

enable: true

version: v1

inputs:

- Type: service_http_server

Format: "pyroscope"

Address: "http://:4040"

Endpoint: "/ingest"

Cluster: "sls-mall"

TagsInGroup: false

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输入

- 进入Pyroscope Golang Example

- 编译 Pyroscope Golang Example

go build -o main .

- 启动Pyroscope Golang Example

./main

- 输出

2023-02-21 14:15:20 {"name":"runtime.malg /Users/evan/sdk/go1.19.4/src/runtime/proc.go","stack":"runtime.newproc1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.newproc.func1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.systemstack /Users/evan/sdk/go1.19.4/src/runtime/asm_amd64.s","stackID":"afb4871c4cb30267","language":"go","type":"profile_mem","dataType":"CallStack","durationNs":"0","profileID":"e3620581-930d-4c51-8e52-cb752e75f1be","labels":"{\"__name__\":\"simple.golang.app\",\"_sample_rate_\":\"100\",\"cluster\":\"s=s-mall\"}","units":"count","valueTypes":"alloc_objects","aggTypes":"sum","val":"1260.00","__time__":"1676960120"}

2023-02-21 14:15:20 {"name":"runtime.malg /Users/evan/sdk/go1.19.4/src/runtime/proc.go","stack":"runtime.newproc1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.newproc.func1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.systemstack /Users/evan/sdk/go1.19.4/src/runtime/asm_amd64.s","stackID":"afb4871c4cb30267","language":"go","type":"profile_mem","dataType":"CallStack","durationNs":"0","profileID":"e3620581-930d-4c51-8e52-cb752e75f1be","labels":"{\"__name__\":\"simple.golang.app\",\"_sample_rate_\":\"100\",\"cluster\":\"s=s-mall\"}","units":"bytes","valueTypes":"alloc_space","aggTypes":"sum","val":"524496.00","__time__":"1676960120"}

2023-02-21 14:15:20 {"name":"runtime.malg /Users/evan/sdk/go1.19.4/src/runtime/proc.go","stack":"runtime.newproc1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.newproc.func1 /Users/evan/sdk/go1.19.4/src/runtime/proc.go\nruntime.systemstack /Users/evan/sdk/go1.19.4/src/runtime/asm_amd64.s","stackID":"afb4871c4cb30267","language":"go","type":"profile_mem","dataType":"CallStack","durationNs":"0","profileID":"e3620581-930d-4c51-8e52-cb752e75f1be","labels":"{\"__name__\":\"simple.golang.app\",\"_sample_rate_\":\"100\",\"cluster\":\"s=s-mall\"}","units":"count","valueTypes":"inuse_objects","aggTypes":"sum","val":"1260.00","__time__":"1676960120"}

2023-02-21 14:15:20 {"name":"compress/flate.(*compressor).init /Users/evan/sdk/go1.19.4/src/compress/flate/deflate.go","stack":"compress/flate.NewWriter /Users/evan/sdk/go1.19.4/src/compress/flate/deflate.go\ncompress/gzip.(*Writer).Write /Users/evan/sdk/go1.19.4/src/compress/gzip/gzip.go\nruntime/pprof.(*profileBuilder).flush /Users/evan/sdk/go1.19.4/src/runtime/pprof/proto.go\nruntime/pprof.(*profileBuilder).pbSample /Users/evan/sdk/go1.19.4/src/runtime/pprof/proto.go\nruntime/pprof.(*profileBuilder).build /Users/evan/sdk/go1.19.4/src/runtime/pprof/proto.go\nruntime/pprof.profileWriter /Users/evan/sdk/go1.19.4/src/runtime/pprof/pprof.go","stackID":"d4e9448662480cdb","language":"go","type":"profile_mem","dataType":"CallStack","durationNs":"0","profileID":"e3620581-930d-4c51-8e52-cb752e75f1be","labels":"{\"__name__\":\"simple.golang.app\",\"_sample_rate_\":\"100\",\"cluster\":\"s=s-mall\"}","units":"count","valueTypes":"alloc_objects","aggTypes":"sum","val":"177.00","__time__":"1676960120"}

ServiceInput示例插件

简介

service_input_example  可作为编写 ServiceInput 类插件的参考示例样例，可以在指定端口接收模拟HTTP请求。源代码

版本

Stable

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 service_input_example   。

Address

String， ：19000

接收端口。

样例

- 采集配置

enable: true

inputs:

- Type: service_input_example

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输入

curl --header "test:val123" http://127.0.0.1:19000/data

- 输出

{

"test":"val123",

"__time__":"1658495321"

}

Journal数据

简介

service_journal  插件支持从原始的二进制文件中采集Linux系统的Journal（systemd）日志。systemd是专用于 Linux 操作系统的系统与服务管理器。当作为启动进程(PID=1)运行时，它将作为初始化系统运行，启动并维护各种用户空间的服务。 systemd统一管理所有Unit的日志（包括内核和应用日志），配置文件一般在 /etc/systemd/journald.conf 中。源代码

版本

Stable

功能

- 支持设置初始同步位置，后续采集会自动保存checkpoint，不需关心应用重启。

- 支持过滤指定的Unit。

- 支持采集内核日志。

- 支持自动解析日志等级。

- 支持以容器方式采集宿主机上的Journal日志，适用于Docker/Kubernetes场景。

相关限制

- Logtail支持版本为0.16.18及以上。

- 运行的操作系统需支持Journal日志格式。

适用场景

1. 监听内核事件，出现异常时自动告警。

2. 采集所有系统日志，用于长期存储，减少磁盘空间占用。

3. 采集软件（Unit）的输出日志，用于分析或告警。

4. 采集所有Journal日志，可以从所有日志中快速检索关键词或日志，相比Journalctl查询大幅提升。

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 service_journal

JournalPaths

Array，其中value为String，无默认值（必填）

Journal日志路径，建议直接填写Journal日志所在文件夹，例如 /var/log/journal   。

SeekPosition

String， tail

首次采集方式，为head则采集所有数据，为tail则只采集配置应用后新的数据。

Kernel

Boolean， true

为false时则不采集内核日志。

Units

Array，其中value为String， []

指定采集的Unit列表，为空时则全部采集。

ParseSyslogFacility

Boolean， false

是否解析syslog日志的facility字段。

ParsePriority

Boolean， false

是否解析Priority字段。

UseJournalEventTime

Boolean， false

是否使用Journal日志中的字段作为日志时间，即使用采集时间作为日志时间（实时日志采集一般相差3秒以内）。

CursorFlushPeriodMs

Integer， 5000

日志读取检查点的刷新时间。

CursorSeekFallback

String， SeekPositionTail

日志读取检查点回退的位置。

Identifiers

Array，其中value为String， []

syslog标识符，可以添加到监视器。

MatchPatterns

Array，其中value为String， []

匹配规则，可以添加到监视器。

ParsePriority映射关系表如下：

"0": "emergency"

"1": "alert"

"2": "critical"

"3": "error"

"4": "warning"

"5": "notice"

"6": "informational"

"7": "debug"

样例

样例1

从默认的 /var/log/journal 路径采集journal日志。

- 采集配置1

enable: true

inputs:

- Type: service_journal

JournalPaths:

- "/var/log/journal"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出1

{

"PRIORITY":"6",

"_GID":"0",

"_TRANSPORT":"syslog",

"_SYSTEMD_OWNER_UID":"0",

"_BOOT_ID":"bab**************54b",

"_PID":"21848",

"_MACHINE_ID":"************************",

"_CAP_EFFECTIVE":"3fffffffff",

"_COMM":"crond",

"_HOSTNAME":"iZj*****************1hZ",

"_SYSTEMD_SLICE":"user-0.slice",

"MESSAGE":"(root) CMD (/usr/lib64/sa/sa1 1 1)",

"_CMDLINE":"/usr/sbin/CROND -n",

"SYSLOG_FACILITY":"9",

"SYSLOG_IDENTIFIER":"CROND",

"_AUDIT_LOGINUID":"0",

"_SYSTEMD_SESSION":"3319",

"_UID":"0",

"_EXE":"/usr/sbin/crond",

"SYSLOG_PID":"21848",

"_AUDIT_SESSION":"3319",

"_SYSTEMD_CGROUP":"/user.slice/user-0.slice/session-3319.scope",

"_SYSTEMD_UNIT":"session-3319.scope",

"_SOURCE_REALTIME_TIMESTAMP":"1658823001526225",

"_realtime_timestamp_":"1658823001526482",

"_monotonic_timestamp_":"1637927744052",

"__time__":"1658823031"

}

样例2

Kubernetes场景下，使用Logtail的DaemonSet模式采集宿主机的系统日志，由于日志中有很多并不重要的字段，使用处理插件只挑选较为重要的日志字段。

- 采集配置2

enable: true

inputs:

- Type: service_journal

ParsePriority: true

ParseSyslogFacility: true

JournalPaths:

- "/logtail_host/var/log/journal"

processors:

- Type: processor_filter_regex

Exclude:

UNIT: "^libcontainer.*test"

- Type: processor_pick_key

Include:

- MESSAGE

- PRIORITY

- _EXE

- _PID

- _SYSTEMD_UNIT

- _realtime_timestamp_

- _HOSTNAME

- UNIT

- SYSLOG_FACILITY

- SYSLOG_IDENTIFIER

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出2

{

"MESSAGE":  "ejected connection from \"192.168.0.251:48914\" (error \"EOF\", ServerName "")",

"PRIORITY":  "informational",

"SYSLOG_IDENTIFIER":  "etcd",

"_EXE": "/opt/etcd-v3.3.8/etcd",

"_HOSTNAME":  "iZb*****************ueZ",

"_PID":  "10590",

"_SYSTEMD_UNIT":  "etcd.service",

"__source__":  "***.***.***.***",

"__tag__:__hostname__":  "logtail-ds-dp48x",

"_realtime_timestamp_":  "1547975837008708",

}

Kafka

简介

service_kafka   input 插件实现了 ServiceInputV1 和 ServiceInputV2 接口，插件用于采集Kafka的消息。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 service_kafka   。

Format

String

否

ilogtail 1.6.0新增，仅ServiceInputV2支持。v2版本支持格式: raw ,  prometheus ,  otlp_metricv1 、 otlp_tracev1 </p>
说明：`raw`格式以原始请求字节流传输数据，默认值：`raw`

Version

String

是

Kafka集群版本号。

Brokers

Array

是

Kafka服务器地址列表。

ConsumerGroup

String

是

Kafka消费组名称。

Topics

Array

是

待消费的Kafka订阅主题列表。

ClientID

String

是

消费Kafka的用户ID。

Offset

String

否

Kafka初始消费位移类型，可选值包括：oldest和newest。如果未添加该参数，则默认使用oldest，表示从最早可用的位移处开始消费。

MaxMessageLen（Deprecated）

Integer

否

Kafka消息的最大允许长度，单位为字节，取值范围为：1～524288。如果未添加该参数，则默认使用524288，即512KB。 ilogtail 1.6.0不再使用此参数

SASLUsername

String

否

SASL用户名。

SASLPassword

String

否

SASL密码。

Assignor

String

否

消费组消费分区分配策略。可以设置选项：range, roundrobin, sticky，默认值：range

DisableUncompress

Boolean

否

ilogtail 1.6.0新增，禁用对于请求数据的解压缩, 默认取值为: false
目前仅针对Raw Format有效

仅v2版本有效

FieldsExtend

Boolean

否

是否支持非integer以外的数据类型(如String)

目前仅针对有 String、Bool 等额外类型的 influxdb Format 有效，仅v2版本有效

样例

采集服务器地址为172.xx.xx.48和172.xx.xx.34、主题为topicA和topicB的Kafka消息，并将采集结果输出至标准输出，其中Kafka集群的版本为2.1.1，消费组的名称为test-group，其余取默认值。

- 输入

{"payload":"foo"}

采集配置（v1）

enable: true

inputs:

- Type: service_kafka

Version: 2.1.1

Brokers:

- 172.xx.xx.48

- 172.xx.xx.34

ConsumerGroup: test-group

Topics:

- topicA

- topicB

ClientID: sls

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{"payload":"foo"}

采集配置（v2）

v2 是 ilogtail 1.6.0 新增的实现，主要是支持配置 Format 指定一些特定的数据格式化方式 raw ,  prometheus ,  otlp_metricv1 、 otlp_tracev1 ， 其它配置变更可查看【配置参数】表。如果没有特殊的需求，使用默认的 v1 即可。

enable: true

version: v2

inputs:

- Type: service_kafka

Version: 2.1.1

Brokers:

- 172.xx.xx.48

- 172.xx.xx.34

ConsumerGroup: test-group

Topics:

- topicA

- topicB

ClientID: sls

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{"eventType":"byteArray","name":"","timestamp":0,"observedTimestamp":0,"tags":{},"byteArray":"{\"payload \": \"foo \"}"}

Mock数据-Service

简介

service_mock  插件是用于模拟采集Service类型输入数据的插件，可以通过调整参数获取不同的模拟输入。源代码

版本

Stable

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 service_mock

Tags

Map，其中tagKey和tagValue为String类型， {}

可以按需求给mock数据添加tag。

Fields

Map，其中fieldKey和fieldValue为String类型， {}

可以按需求给mock数据添加字段。

File

String， ""

指定一个文件并读取，在Fields中添加一个key为content、值为文件内容的字段。

Index

Long， 0

生成的mock数据的开始编号（从下一个编号开始）。

LogsPerSecond

Integer， 0

每秒生产的日志数量。

MaxLogCount

Integer， 0

最大生产的日志总数，若为0则没有上限。

样例

- 采集配置

enable: true

inputs:

- Type: service_mock

Index: 100

Tags:

tag1: tag1

tag2: tag2

Fields:

field1: field1

field2: field2

LogsPerSecond: 2

MaxLogCOunt: 3

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"tag1":"tag1",

"tag2":"tag2",

"field1":"field1",

"field2":"field2",

"Index":"101",

"__time__":"1658814793"

}

{

"tag1":"tag1",

"tag2":"tag2",

"field1":"field1",

"field2":"field2",

"Index":"102",

"__time__":"1658814793"

}

{

"tag1":"tag1",

"tag2":"tag2",

"field1":"field1",

"field2":"field2",

"Index":"103",

"__time__":"1658814794"

}

MS Sql Server导入插件

简介

service_mssql   input 插件可以采集Sql Server查询数据。

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，指定为 service_mssql   。

Host

String， 127.0.0.1

数据库主机。

Port

Interger， 1433

数据库端口。

User

String， root

数据库用户名。

Password

String，默认值为空

数据库密码。

Database

String，默认值为空

数据库名称。

DialTimeOutMs

Interger，5000

数据库连接超时时间，单位：ms，默认5000ms

ReadTimeOutMs

Interger，5000

数据库查询超时时间，单位：ms，默认5000ms

Statement

String，默认值为空

SQL语句。设置CheckPoint为true时，StateMent中SQL语句的where条件中必须包含CheckPointColumn，并将该列的值配置为$1。例如：CheckPointColumn配置为id，则StateMent配置为SELECT * from ... where id > $1。

Limit

Boolean， false

是否使用Limit分页。不配置时，默认为false，表示不使用Limit分页。建议使用Limit进行分页。设置Limit为true后，进行SQL查询时，会自动在StateMent中追加LIMIT语句。

PageSize

Interger，无默认值

分页大小，Limit为true时必须配置。

MaxSyncSize

Interger， 0

每次同步最大记录数。不配置时，默认为0，表示无限制。

CheckPoint

Boolean， false

是否使用checkpoint。不配置时，默认为false，表示不使用checkpoint。

CheckPointColumn

String，无默认值

checkpoint列名称。 CheckPoint为true时必须配置。 注意 该列的值必须递增，否则可能会出现数据漏采集问题（每次查询结果中的最大值将作为下次查询的输入）。

CheckPointColumnType

String，无默认值

checkpoint列类型，支持int和time两种类型。int类型的内部存储为int64，time类型支持MySQL的date、datetime、time。 CheckPoint为true时必须配置。

CheckPointStart

String，无默认值

checkpoint初始值。CheckPoint为true时必须配置。

CheckPointSavePerPage

Boolean，无默认值

设置为true，则每次分页时保存一次checkpoint；设置为false，则每次同步完后保存checkpoint。

IntervalMs

Interger，无默认值

同步间隔，单位：ms。

样例

Sql Server数据库创建LogtailTest数据库，LogtailTestTable表。

- 表结构及数据信息如下

IF NOT EXISTS(SELECT * FROM sys.databases WHERE name = 'LogtailTest')

BEGIN

CREATE DATABASE [LogtailTest]

END

GO

USE [LogtailTest]

GO

IF NOT EXISTS (SELECT * FROM sysobjects WHERE name='LogtailTestTable' and xtype='U')

BEGIN

CREATE TABLE LogtailTestTable (

id INT PRIMARY KEY IDENTITY (1, 1),

name NVARCHAR(50),

quantity INT

)

END

GO

INSERT INTO LogtailTestTable (name, quantity) values('banana', 1);

INSERT INTO LogtailTestTable (name, quantity) values('banana', 2);

INSERT INTO LogtailTestTable (name, quantity) values('banana', 3);

INSERT INTO LogtailTestTable (name, quantity) values('banana', 4);

SELECT * FROM LogtailTestTable;

GO

- 采集配置

enable: true

inputs:

- Type: service_mssql

Address: 127.0.0.1

CheckPoint: true

CheckPointColumn: id

CheckPointColumnType: int

CheckPointSavePerPage: true

CheckPointStart: "0"

Database: LogtailTest

IntervalMs: 1000

Limit: true

MaxSyncSize: 100

PageSize: 100

User: sa

Password: xxxxx

StateMent: "select * from LogtailTestTable where id > ? order by id"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{"id":"1","name":"banana","quantity":"1","__time__":"1661416452"}

{"id":"2","name":"banana","quantity":"2","__time__":"1661416452"}

{"id":"3","name":"banana","quantity":"3","__time__":"1661416452"}

{"id":"4","name":"banana","quantity":"4","__time__":"1661416452"}

Open Telemetry Service Input

简介

service_otlp   input 插件实现了 ServiceInputV1 和 ServiceInputV2 接口，可以接受 Opentelemetry log/metric/trace protocol 的http/gRPC请求，并且转换输出SLSProto或PipelineGroupEvents。目前尚不支持otlp trace转换到SLSProto。

版本

Beta

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型, 固定为 service_otlp   。

Protocals

Struct

是

接收的协议

Protocals.GRPC

Struct

否

是否启用gRPC Server

Protocals.GRPC.Endpoint

string

否

gRPC Server 地址。

默认取值为:`0.0.0.0:4317`。

Protocals.GRPC.MaxRecvMsgSizeMiB

int

否

gRPC Server 最大接受Msg大小。

Protocals.GRPC.MaxConcurrentStreams

int

否

gRPC Server 最大并发流。

Protocals.GRPC.ReadBufferSize

int

否

gRPC Server读缓存大小。

Protocals.GRPC.WriteBufferSize

int

否

gRPC Server写缓存大小。

Protocals.GRPC.Compression

string

否

gRPC Server压缩算法，可以用gzip。

Protocals.GRPC.Decompression

string

否

gRPC Server解压算法，可以用gzip。

Protocals.GRPC.TLSConfig

Struct

否

gRPC Server TLS CONFIG配置。

Protocals.HTTP

Struct

否

是否启用HTTP Server

Protocals.HTTP.Endpoint

string

否

HTTP Server 地址。

默认取值为:`0.0.0.0:4318`。

Protocals.HTTP.MaxRecvMsgSizeMiB

int

否

HTTP Server 最大接受Msg大小。
默认取值为:`64(MiB)`。

Protocals.HTTP.ReadTimeoutSec

int

否

HTTP 请求读取超时时间。

默认取值为:`10s`。

Protocals.HTTP.ShutdownTimeoutSec

int

否

HTTP Server关闭超时时间。

默认取值为:`5s`。

样例

- 只接收gRPC请求。

enable: true

version: v2

inputs:

- Type: service_otlp

Protocals:

GRPC:

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 接收http/gRPC请求，使用默认otlp的默认端口。gRPC：4317，HTTP：4318.

enable: true

version: v2

inputs:

- Type: service_otlp

Protocals:

GRPC:

HTTP:

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 完整配置

enable: true

version: v2

inputs:

- Type: service_otlp

Protocals:

GRPC:

Endpoint: 0.0.0.0:4317

MaxRecvMsgSizeMiB: 64

MaxConcurrentStreams: 100

ReadBufferSize: 1024

WriteBufferSize: 1024

HTTP:

Endpoint: 0.0.0.0:4318

MaxRecvMsgSizeMiB: 64

ReadTimeoutSec: 10

ShutdownTimeoutSec: 5

flushers:

- Type: flusher_stdout

OnlyStdout: true

PostgreSQL 导入插件

简介

service_pgsql   input 插件可以采集PostgreSQL 查询数据。

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，指定为 service_pgsql   。

Host

String， 127.0.0.1

数据库主机。

Port

Interger， 5432

数据库端口。

User

String， root

数据库用户名。

Password

String，默认值为空

数据库密码。

Database

String，默认值为空

数据库名称。

DialTimeOutMs

Interger，5000

数据库连接超时时间，单位：ms，默认5000ms

Statement

String，默认值为空

SQL语句。设置CheckPoint为true时，StateMent中SQL语句的where条件中必须包含CheckPointColumn，并将该列的值配置为$1。例如：CheckPointColumn配置为id，则StateMent配置为SELECT * from ... where id > $1。

Limit

Boolean， false

是否使用Limit分页。不配置时，默认为false，表示不使用Limit分页。建议使用Limit进行分页。设置Limit为true后，进行SQL查询时，会自动在StateMent中追加LIMIT语句。

PageSize

Interger，无默认值

分页大小，Limit为true时必须配置。

MaxSyncSize

Interger， 0

每次同步最大记录数。不配置时，默认为0，表示无限制。

CheckPoint

Boolean， false

是否使用checkpoint。不配置时，默认为false，表示不使用checkpoint。

CheckPointColumn

String，无默认值

checkpoint列名称。 CheckPoint为true时必须配置。 注意 该列的值必须递增，否则可能会出现数据漏采集问题（每次查询结果中的最大值将作为下次查询的输入）。

CheckPointColumnType

String，无默认值

checkpoint列类型，支持int和time两种类型。int类型的内部存储为int64，time类型支持MySQL的date、datetime、time。 CheckPoint为true时必须配置。

CheckPointStart

String，无默认值

checkpoint初始值。CheckPoint为true时必须配置。

CheckPointSavePerPage

Boolean，无默认值

设置为true，则每次分页时保存一次checkpoint；设置为false，则每次同步完后保存checkpoint。

IntervalMs

Interger，无默认值

同步间隔，单位：ms。

样例

对postgres数据库下的specialalarmtest进行读取。

- 表结构及数据信息如下

CREATE TABLE IF NOT EXISTS specialalarmtest (

id BIGSERIAL NOT NULL,

time TIMESTAMP NOT NULL,

alarmtype varchar(64) NOT NULL,

ip varchar(16) NOT NULL,

COUNT INT NOT NULL,

PRIMARY KEY (id)

);

insert into specialalarmtest (time, alarmtype, ip, count) values(now(), 'NO_ALARM', '10.10.***.***', 0);

insert into specialalarmtest (time, alarmtype, ip, count) values(now(), 'NO_ALARM', '10.10.***.***', 1);

insert into specialalarmtest (time, alarmtype, ip, count) values(now(), 'NO_ALARM', '10.10.***.***', 2);

insert into specialalarmtest (time, alarmtype, ip, count) values(now(), 'NO_ALARM', '10.10.***.***', 3);

- 采集配置

enable: true

inputs:

- Type: service_pgsql

Address: 127.0.0.1

CheckPoint: true

CheckPointColumn: id

CheckPointColumnType: int

CheckPointSavePerPage: true

CheckPointStart: "0"

Database: postgres

IntervalMs: 1000

Limit: true

MaxSyncSize: 100

PageSize: 100

User: postgres

Password: xxxxx

StateMent: "select * from specialalarmtest where id > $1"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{"id":"1","time":"2022-08-25T06:01:07.276901Z","alarmtype":"NO_ALARM","ip":"10.10.***.***","count":"0","__time__":"1661416452"}

{"id":"2","time":"2022-08-25T06:01:07.277624Z","alarmtype":"NO_ALARM","ip":"10.10.***.***","count":"1","__time__":"1661416452"}

{"id":"3","time":"2022-08-25T06:01:07.278072Z","alarmtype":"NO_ALARM","ip":"10.10.***.***","count":"2","__time__":"1661416452"}

{"id":"4","time":"2022-08-25T06:01:07.278494Z","alarmtype":"NO_ALARM","ip":"10.10.***.***","count":"3","__time__":"1661416452"}

Syslog数据

简介

service_syslog  插件通过Logtail插件对指定的地址和端口进行监听后，Logtail开始采集数据，包括通过rsyslog采集的系统日志、 Nginx转发的访问日志或错误日志，以及通过syslog客户端转发的日志。源代码

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 service_syslog   。

Address

String， tcp://127.0.0.1:9999

指定Logtail插件监听的协议、地址和端口，Logtail插件会根据Logtail采集配置进行监听并获取日志数据。格式为 [tcp/udp]://[ip]:[port]   。注意，Logtail插件配置中设置的监听协议、地址和端口号必须与rsyslog配置文件设置的转发规则相同。如果安装Logtail的服务器有多个IP地址可接收日志，可以将地址配置为0.0.0.0，表示监听服务器的所有IP地址。

MaxConnections

Integer， 100

最大链接数，仅使用于TCP。

TimeoutSeconds

Integer， 0

在关闭远程连接之前的不活动秒数。

MaxMessageSize

Integer， 64 * 1024

通过传输协议接收的信息的最大字节数。

KeepAliveSeconds

Integer， 300

保持连接存活的秒数，仅使用于TCP。

ParseProtocol

String， ""

指定解析日志所使用的协议，默认为空，表示不解析。其中： rfc3164 ：指定使用RFC3164协议解析日志。 rfc5424 ：指定使用RFC5424协议解析日志。 auto   ：指定插件根据日志内容自动选择合适的解析协议。

IgnoreParseFailure

Boolean， true

指定解析失败后的操作，不配置表示放弃解析，直接填充所返回的content字段。配置为 false    ，表示解析失败时丢弃日志。

AddHostname

Boolean， false

当从/dev/log监听unixgram时，log中不包括hostname字段，所以使用rfc3164会导致解析错误，这时将AddHostname设置为 true   ，就会给解析器当前主机的hostname，然后解析器就可以解析tag、program、content字段了。

样例

本样例采用了udp协议监听9009端口。

- 采集配置

enable: true

inputs:

- Type: service_syslog

Address: udp://0.0.0.0:9009

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"_program_":"",

"_facility_":"-1",

"_hostname_":"iZb***4prZ",

"_content_":"<78>Dec 23 15:35:01 iZb***4prZ CRON[3364]: (root) CMD (command -v ***)",

"_ip_":"172.**.**.5",

"_priority_":"-1",

"_severity_":"-1",

"_unixtimestamp_":"1640244901606136313",

"_client_ip_":"120.**.2**.90",

"__time__":"1640244901"

}

- 采集字段含义

字段

说明

_program_

协议中的tag字段。

_hostname_

主机名, 如果日志中末提供则获取当前主机名。

_program_

协议中的tag字段。

_priority_

协议中的priority字段。

_facility_

协议中的facility字段。

_severity_

协议中的severity字段。

_unixtimestamp_

日志对应的时间戳。

_content_

日志内容, 如果解析失败的话, 此字段包含末解析日志的所有内容。

_ip_

当前主机的IP地址。

_client_ip_

传输日志的客户端ip地址。

input_ebpf_file_security 插件

简介

input_ebpf_file_security 插件可以实现利用ebpf探针采集文件安全相关动作。

版本

Dev

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_ebpf_file_security

ProbeConfig

[object]

否

ProbeConfig 默认包含一个 Option，其中包含一个默认取全部值的 CallNameFilter，其他 Filter 默认为空

ProbeConfig 可以包含多个 Option， Option 内部有多个 Filter，Filter 内部是或的关系，Filter 之间是且的关系，Option 之间是或的关系

ProbeConfig[xx].CallNameFilter

[string]

否

该插件支持的所有 callname: [ security_file_permission security_file_mmap security_path_truncate ]

内核挂载点过滤器，按照白名单模式运行，不填表示配置该插件所支持的所有挂载点

ProbeConfig[xx].FilePathFilter

[string]

否

空

文件路径过滤器，按照白名单模式运行，不填表示不进行过滤

样例

XXXX

- 输入

TODO

- 采集配置

enable: true

inputs:

- Type: input_ebpf_fileprobe_security

ProbeConfig:

- CallNameFilter:

- "security_file_permission"

FilePathFilter:

- "/etc/passwd"

- "/lib"

- CallNameFilter:

- "security_path_truncate"

FilePathFilter:

- "/etc/passwd"

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

TODO

input_ebpf_network_observer 插件

简介

input_ebpf_network_observer 插件可以实现利用ebpf探针采集网络可观测数据。

版本

Dev

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_ebpf_network_observer

ProbeConfig

object

是

/

插件配置参数列表

ProbeConfig.EnableLog

bool

否

true

是否开启日志上报

ProbeConfig.EnableSpan

bool

否

false

是否开启跨度上报

ProbeConfig.EnableMetric

bool

否

false

是否开启指标上报

ProbeConfig.EnableProtocols

[string]

否

空

允许的协议类型

ProbeConfig.DisableProtocolParse

bool

否

false

TODO

ProbeConfig.DisableConnStats

bool

否

false

TODO

ProbeConfig.EnableConnTrackerDump

bool

否

false

TODO

样例

XXXX

- 输入

TODO

- 采集配置

enable: true

inputs:

- Type: input_ebpf_sockettraceprobe_observer

ProbeConfig:

EnableLog: true

EnableMetric: false

EnableSpan: false

EnableProtocols:

- "http"

DisableConnStats: false

EnableConnTrackerDump: false

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

TODO

input_ebpf_network_security 插件

简介

input_ebpf_network_security 插件可以实现利用ebpf探针采集网络安全相关动作。

版本

Dev

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_ebpf_network_security

ProbeConfig

[object]

否

ProbeConfig 默认包含一个 Option，其中包含一个默认取全部值的 CallNameFilter，其他 Filter 默认为空

ProbeConfig 可以包含多个 Option， Option 内部有多个 Filter，Filter 内部是或的关系，Filter 之间是且的关系，Option 之间是或的关系

ProbeConfig[xx].CallNameFilter

[string]

否

该插件支持的所有 callname: [ tcp_connect tcp_close tcp_sendmsg ]

内核挂载点过滤器，按照白名单模式运行，不填表示配置该插件所支持的所有挂载点

ProbeConfig[xx].AddrFilter

object

否

/

网络地址过滤器

ProbeConfig[xx].AddrFilter.DestAddrList

[string]

否

空

目的IP地址白名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.DestPortList

[string]

否

空

目的端口白名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.DestAddrBlackList

[string]

否

空

目的IP地址黑名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.DestPortBlackList

[string]

否

空

目的端口黑名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.SourceAddrList

[string]

否

空

源IP地址白名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.SourcePortList

[string]

否

空

源端口白名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.SourceAddrBlackList

[string]

否

空

源IP地址黑名单，不填表示不进行过滤

ProbeConfig[xx].AddrFilter.SourcePortBlackList

[string]

否

空

源端口黑名单，不填表示不进行过滤

样例

XXXX

- 输入

TODO

- 采集配置

enable: true

inputs:

- Type: input_ebpf_sockettraceprobe_security

ProbeConfig:

- CallNameFilter:

- "tcp_connect"

- "tcp_close"

AddrFilter:

DestAddrList:

- "10.0.0.0/8"

- "92.168.0.0/16"

DestPortList:

- 80

SourceAddrBlackList:

- "127.0.0.1/8"

SourcePortBlackList:

- 9300

- CallNameFilter:

- "tcp_sendmsg"

AddrFilter:

DestAddrList:

- "10.0.0.0/8"

- "92.168.0.0/16"

DestPortList:

- 80

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

TODO

input_ebpf_process_security 插件

简介

input_ebpf_process_security 插件可以实现利用ebpf探针采集进程安全相关动作。

版本

Dev

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为input_ebpf_process_security

ProbeConfig

[object]

否

ProbeConfig 默认包含一个 Option，其中包含一个默认取全部值的 CallNameFilter，其他 Filter 默认为空

ProbeConfig 可以包含多个 Option， Option 内部有多个 Filter，Filter 内部是或的关系，Filter 之间是且的关系，Option 之间是或的关系

ProbeConfig[xx].CallNameFilter

[string]

否

该插件支持的所有 callname: [ sys_enter_execve sys_enter_clone disassociate_ctty acct_process wake_up_new_task ]

内核挂载点过滤器，按照白名单模式运行，不填表示配置该插件所支持的所有挂载点

样例

XXXX

- 输入

TODO

- 采集配置

enable: true

inputs:

- Type: input_ebpf_processprobe_security

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

- 输出

TODO

处理

处理插件用于对采集到的内容进行解析、过滤和加工等，可分为原生处理插件和扩展处理插件:

- 原生插件：性能较优，适用于大部分业务场景，推荐优先使用。

- 扩展插件：功能覆盖更广，当您的业务日志过于复杂以致于无法使用原生插件完成处理，您可以考虑额外使用扩展插件完成日志解析，但性能会有一定影响。

限制

- 目前，原生插件仅可用于采集文本日志 和 容器标准输出（原生插件）。

- 支持原生插件与扩展插件级联，但是原生插件不允许在扩展插件之后使用，即只支持如下几种模式：

- 原生模式：只使用原生插件

- 扩展模式：只使用扩展插件

- 级联模式：原生插件之后继续使用扩展插件

原生插件

正则解析原生处理插件

简介

processor_parse_regex_native 插件通过正则匹配解析事件指定字段内容并提取新字段

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_parse_regex_native。

SourceKey

string

是

/

源字段名。

Regex

string

是

/

正则表达式。

Keys

[string]

是

/

提取的字段列表。

KeepingSourceWhenParseFail

bool

否

false

当解析失败时，是否保留源字段。

KeepingSourceWhenParseSucceed

bool

否

false

当解析成功时，是否保留源字段。

RenamedSourceKey

string

否

空

当源字段被保留时，用于存储源字段的字段名。若不填，默认不改名。

样例

采集文件 /home/test-log/reg.log ，通过正则表达式解析日志内容并提取字段，并将结果输出到stdout。

- 输入

127.0.0.1 - - [07/Jul/2022:10:43:30 +0800] "POST /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_parse_regex_native

SourceKey: content

Regex: ([\d\.]+) \S+ \S+ \[(\S+) \S+\] \"(\w+) ([^\\"]*)\" ([\d\.]+) (\d+) (\d+) (\d+|-) \"([^\\"]*)\" \"([^\\"]*)\"

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/reg.log",

"ip": "127.0.0.1",

"time": "07/Jul/2022:10:43:30",

"method": "POST",

"url": "/PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1657161810"

}

分隔符解析原生处理插件

简介

processor_parse_delimiter_native 插件解析事件中分隔符格式字段内容并提取新字段。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_parse_delimiter_native。

SourceKey

string

是

/

源字段名。

Separator

string

是

/

分隔符。

Quote

string

否

"

引用符。

Keys

[string]

是

/

提取的字段列表。

AllowingShortenedFields

bool

否

true

是否允许提取的字段数量小于Keys的数量。若不允许，则此情景会被视为解析失败。

OverflowedFieldsTreatment

string

否

extend

当提取的字段数量大于Keys的数量时的行为。可选值包括：

- extend：保留多余的字段，且每个多余的字段都作为单独的一个字段加入日志，多余字段的字段名为\_\_column$i\_\_，其中$i代表额外字段序号，从0开始计数。

- keep：保留多余的字段，但将多余内容作为一个整体字段加入日志，字段名为\_\_column0\_\_.

- discard：丢弃多余的字段。

KeepingSourceWhenParseFail

bool

否

false

当解析失败时，是否保留源字段。

KeepingSourceWhenParseSucceed

bool

否

false

当解析成功时，是否保留源字段。

RenamedSourceKey

string

否

空

当源字段被保留时，用于存储源字段的字段名。若不填，默认不改名。

样例

采集分隔符格式文件 /home/test-log/delimiter.log ，解析日志内容并提取字段，并将结果输出到stdout。

- 输入

127.0.0.1,07/Jul/2022:10:43:30 +0800,POST,PutData?Category=YunOsAccountOpLog,0.024,18204,200,37,-,aliyun-sdk-java

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/json.log

processors:

- Type: processor_parse_delimiter_native

SourceKey: content

Separator: ','

Quote: '"'

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/json.log",

"ip": "127.0.0.1",

"time": "07/Jul/2022:10:43:30 +0800",

"method": "POST",

"url": "PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1657161028"

}

Json解析原生处理插件

简介

processor_parse_json_native 插件解析事件中 Json 格式字段内容并提取新字段。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_parse_json_native。

SourceKey

string

是

/

源字段名。

KeepingSourceWhenParseFail

bool

否

false

当解析失败时，是否保留源字段。

KeepingSourceWhenParseSucceed

bool

否

false

当解析成功时，是否保留源字段。

RenamedSourceKey

string

否

空

当源字段被保留时，用于存储源字段的字段名。若不填，默认不改名。

样例

采集Json格式文件 /home/test-log/json.log ，解析日志内容并提取字段，并将结果输出到stdout。

- 输入

{"url": "POST /PutData?Category=YunOsAccountOpLog HTTP/1.1", "ip": "10.200.98.220", "user-agent": "aliyun-sdk-java", "request": {"status": "200", "latency": "18204"}, "time": "07/Jul/2022:10:30:28"}

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/json.log

processors:

- Type: processor_parse_json_native

SourceKey: content

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/json.log",

"url": "POST /PutData?Category=YunOsAccountOpLog HTTP/1.1",

"ip": "10.200.98.220",

"user-agent": "aliyun-sdk-java",

"request": {

"status": "200",

"latency": "18204"

},

"time": "07/Jul/2022:10:30:28",

"__time__": "1657161028"

}

时间解析原生处理插件

简介

processor_parse_timestamp_native 插件解析事件中记录时间的字段，并将结果置为事件的time字段。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_parse_timestamp_native。

SourceKey

string

是

/

源字段名。

SourceFormat

string

是

/

日志时间格式。更多信息，请参见表1。

SourceTimezone

string

否

空

日志时间所属时区。格式为GMT+HH:MM（东区）或GMT-HH:MM（西区）。

- 表1：时间格式

时间格式

说明

示例

%a

星期的缩写。

Fri

%A

星期的全称。

Friday

%b

月份的缩写。

Jan

%B

月份的全称。

January

%d

每月第几天，十进制，范围为01~31。

07, 31

%h

月份的缩写，等同于%b。

Jan

%H

小时，24小时制。

22

%I

小时，12小时制。

11

%m

月份，十进制，范围为01~12。

08

%M

分钟，十进制，范围为00~59。

59

%n

换行符。

换行符

%p

AM或PM。

AM、PM

%r

12小时制的时间组合，等同于%I:%M:%S %p。

11:59:59 AM

%R

小时和分钟组合，等同于%H:%M。

23:59

%S

秒数，十进制，范围为00~59。

59

%t

Tab符号，制表符。

无

%y

年份，十进制，不带世纪，范围为00~99。

04、98

%Y

年份，十进制。

2004、1998

%C

世纪，十进制，范围为00~99。

16

%e

每月第几天，十进制，范围为1~31。如果是个位数字，前面需要加空格。

7、31

%j

一年中的天数，十进制，范围为001~366。

365

%u

星期几，十进制，范围为1~7，1表示周一。

2

%U

每年的第几周，星期天是一周的开始，范围为00~53。

23

%V

每年的第几周，星期一是一周的开始，范围为01~53。如果一月份刚开始的一周>=4天，则认为是第1周，否则认为下一个星期是第1周。

24

%w

星期几，十进制，范围为0~6，0代表周日。

5

%W

每年的第几周，星期一是一周的开始，范围为00~53。

23

%c

标准的日期和时间。

Tue Nov 20 14:12:58 2020

%x

标准的日期，不带时间。

Tue Nov 20 2020

%X

标准的时间，不带日期。

11:59:59

%s

Unix时间戳。

1476187251

样例

采集文件 /home/test-log/reg.log ，通过正则表达式解析日志内容并提取字段，然后将解析日志中的时间作为事件的time，最后将结果输出到stdout。

- 输入

127.0.0.1 - - [2023-12-28T08:07:12.187340] "POST /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_parse_regex_native

SourceKey: content

Regex: ([\d\.]+) \S+ \S+ \[(\S+) \S+\] \"(\w+) ([^\\"]*)\" ([\d\.]+) (\d+) (\d+) (\d+|-) \"([^\\"]*)\" \"([^\\"]*)\"

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

- Type: processor_parse_timestamp_native

SourceKey: time

SourceFormat: '%Y-%m-%dT%H:%M:%S'

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/reg.log",

"ip": "127.0.0.1",

"time": "2023-12-28T08:07:12.187340",

"method": "POST",

"url": "/PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1703722032"

}

过滤原生处理插件

简介

processor_filter_regex_native 插件根据事件字段内容来过滤事件。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_filter_regex_native。

FilterKey

[string]

是

/

过滤字段名，需配套 FilterRegex   参数使用，表示如果当前事件要被采集，则key指定的字段内容所需要满足的条件。多个条件之间为“且”的关系，仅当所有条件均满足时，该条日志才会被采集。

FilterRegex

[string]

是

/

与 FilterKey 对应的过滤正则表达式。必须与 FilterKey   长度相同。

样例

采集文件 /home/test-log/reg.log ，通过正则表达式解析日志内容并提取字段，然后只采集method为POST或PUT且状态码为200的日志，并将结果输出到stdout。

- 输入

127.0.0.1 - - [07/Jul/2022:10:43:30 +0800] "POST /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"

127.0.0.1 - - [07/Jul/2022:10:44:30 +0800] "Get /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_parse_regex_native

SourceKey: content

Regex: ([\d\.]+) \S+ \S+ \[(\S+) \S+\] \"(\w+) ([^\\"]*)\" ([\d\.]+) (\d+) (\d+) (\d+|-) \"([^\\"]*)\" \"([^\\"]*)\"

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

- Type: processor_filter_regex_native

FilterKey:

- method

- status

FilterRegex:

- ^(POST|PUT)$

- ^200$

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/reg.log",

"ip": "127.0.0.1",

"time": "07/Jul/2022:10:43:30",

"method": "POST",

"url": "/PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1657161810"

}

脱敏原生处理插件

简介

processor_filter_regex_native 插件根据事件字段内容来过滤事件。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为processor_desensitize_native。

SourceKey

string

是

/

源字段名。

Method

string

是

/

脱敏方式。可选值包括：

- const：用常量替换敏感内容。

- md5：用敏感内容的MD5值替换相应内容。

ReplacingString

string

否，当Method取值为const时必选

/

用于替换敏感内容的常量字符串。

ContentPatternBeforeReplacedString

string

是

/

敏感内容的前缀正则表达式。

ReplacedContentPattern

string

是

/

敏感内容的正则表达式。

ReplacingAll

bool

否

true

是否替换所有的匹配的敏感内容。

样例

采集文件 /home/test-log/sen.log ，将日志内容中的密码替换成**，并将结果输出到stdout。

- 输入

{"account":"1812213231432969","password":"04a23f38"}

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_desensitize_native

SourceKey: content

Method: const

ReplacingString: '******'

ContentPatternBeforeReplacedString: 'password":"'

ReplacedContentPattern: '[^"]+'

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/reg.log",

"content": "{\"account\":\"1812213231432969\",\"password\":\"******\"}",

"__time__": "1657161810"

}

扩展插件

添加字段

简介

processor_add_fields processor 插件可以添加日志字段。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型。

Fields

Map

是

待添加字段和字段值。键值对格式，支持添加多个。

IgnoreIfExist

Boolean

否

当Key相同时是否忽略。如果未添加该参数，则默认使用false，表示不忽略。

样例

采集 /home/test-log/ 路径下的 test.log 文件，并添加字段service: A用于标识日志所在服务。

- 输入

echo 'this is a test log' >> /home/test-log/test.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_add_fields

Fields:

service: A

IgnoreIfExist: false

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/key_value.log",

"content": "this is a test log",

"service": "A",

"__time__": "1657354602"

}

添加云资产信息

简介

processor_cloud_meta 插件可以添加为日志增加云平台元数据信息。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Metadata

[]string

是

增加元信息配置,，默认追加名字为元信息标签名，支持标签请参考支持元信息标签。

Platform

String

否

云平台名称，目前支持 alibaba_cloud_ecs、auto，auto 模式支持动态选择云平台，默认值auto。

JSONPath

String

否

为空时直接添加字段，不为空时表示为json序列化字段增加元数据标签，支持多层结构增加云平台元信息，最内层结构需要为json结构，如存在 Log_Content 结构 a: {"b":{}} ，当在 a 子结构下追加是JSONPath为 a ，当在 b 子结构下追加时JSONPath 为  a.b

RenameMetadata

map[string]string

否

重命名Metadata名称

ReadOnce

bool

否

true表示仅读取一次，不支持感知动态变化，默认值false。

支持元信息标签

标签

说明

__cloud_instance_id__

云服务器实例id

__cloud_instance_name__

云服务器实例名

__cloud_zone__

云服务器实例zone

__cloud_region__

云服务器实例region

__cloud_instance_type__

云服务器实例规格

__cloud_vswitch_id__

云服务器实例vswitch id

__cloud_vpc_id__

云服务器实例vpcid

__cloud_image_id__

云服务器实例镜像id

__cloud_max_ingress__

云服务器实例最大内网入带宽

__cloud_max_egress__

云服务器实例最大内网出带宽

__cloud_instance_tags__

云服务器实例标签前缀，如配置  cloud_instance_tags：custom_tag  ，当云实例存在标签 a：b  时，将增加  custom_tag_a:b    数据

json Mode 配置举例

Data Input

JSONPath

Metadata

RenameMetadata

Data Output

A:{}

""

["cloud_zone  "]

{}

A:{},"__cloud_zone__":"xxxx"

B:{}

"A"

["cloud_zone  "]

{"cloud_zone  ":"zone"}

B:{},A:{"zone":"xxxx"}

A:""

"A"

["cloud_zone  "]

{"cloud_zone  ":"zone"}

选中A字段，但A字段非json结构，因此跳过追加，输出 A:""

A:{"a":{"b":{}}}

"A.a.b"

["cloud_zone  "]

{"cloud_zone  ":"zone"}

A:{"a":{"b":{"zone":"xxxx"}}}

A:{"a":{"b":{}}}

"A.a.b.c"

["cloud_zone  "]

{"cloud_zone  ":"zone"}

A:{"a":{"b":{c:{"zone":"xxxx"}}}}

样例

content 模式

- 采集配置

enable: true

inputs:

- Type: service_mock

LogsPerSecond: 10

MaxLogCount: 100

Fields:

content: "abc"

processors:

- Type: processor_cloud_meta

Platform: mock

Mode: add_fields

Metadata:

- "__cloud_instance_id__"

- "__cloud_instance_tags__"

RenameMetadata:

__cloud_instance_id__: instance_id_name

__cloud_instance_tags__: instance_tag_prefix

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"1","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"2","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"3","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"4","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"5","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

2023-03-13 20:42:04 {"content":"{\"a\":{\"b\":{}}}","Index":"6","instance_id_name":"id_xxx","instance_tag_prefix_tag_key":"tag_val","__time__":"1678711324"}

}

json 模式

- 采集配置

enable: true

inputs:

- Type: service_mock

LogsPerSecond: 10

MaxLogCount: 100

Fields:

content: "{\"a\":{\"b\":{}}}"

processors:

- Type: processor_cloud_meta

Platform: mock

JSONPath: "content.a.b"

Metadata:

- "__cloud_instance_id__"

- "__cloud_instance_tags__"

RenameMetadata:

__cloud_instance_id__: instance_id_name

__cloud_instance_tags__: instance_tag_prefix

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

2023-03-13 20:39:02 {"content":"{\"a\":{\"b\":{\"instance_id_name\":\"id_xxx\",\"instance_tag_prefix_tag_key\":\"tag_val\"}}}","Index":"1","__time__":"1678711142"}

2023-03-13 20:39:02 {"content":"{\"a\":{\"b\":{\"instance_id_name\":\"id_xxx\",\"instance_tag_prefix_tag_key\":\"tag_val\"}}}","Index":"2","__time__":"1678711142"}

2023-03-13 20:39:02 {"content":"{\"a\":{\"b\":{\"instance_id_name\":\"id_xxx\",\"instance_tag_prefix_tag_key\":\"tag_val\"}}}","Index":"3","__time__":"1678711142"}

2023-03-13 20:39:02 {"content":"{\"a\":{\"b\":{\"instance_id_name\":\"id_xxx\",\"instance_tag_prefix_tag_key\":\"tag_val\"}}}","Index":"4","__time__":"1678711142"}

2023-03-13 20:39:02 {"content":"{\"a\":{\"b\":{\"instance_id_name\":\"id_xxx\",\"instance_tag_prefix_tag_key\":\"tag_val\"}}}","Index":"5","__time__":"1678711142"}

原始数据

简介

processor_default 插件不对数据任何操作，只是简单的数据透传。源代码

支持的Event类型

LogGroup(v1)

EventTypeLogging

EventTypeMetric

EventTypeSpan

✅

✅

✅

✅

版本

Stable

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 processor_default

样例

采集 /home/test-log/ 路径下的 default.log 文件，提取文件的原始数据。

- 输入

echo "2022/07/14/11:32:47 test log" >> /home/test-log/default.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_default

SourceKey: content

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__":"/home/test-log/default.log",

"content":"2022/07/14/11:32:47 test log",

"__time__":"1657769827"}

}

数据脱敏

简介

processor_desensitize 插件可以通过正则表达式匹配并实现文本日志中敏感数据的脱敏。源代码

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值(必填)

插件类型，固定为 processor_desensitize

SourceKey

String，无默认值(必填)

日志字段名称。

Method

String，无默认值(必填)

脱敏方式。可选值如下：

const：将敏感内容替换成 ReplaceString 参数处配置等字符串。

md5：将敏感内容替换为其对应的MD5值。

Match

String，无默认值(必填)

指定敏感数据。可选值如下：

full：字段全文。

regex：使用正则提取敏感数据。

ReplaceString

String，无默认值

用于替换敏感内容等字符串，当 Method 设置为 const 时必选。

RegexBegin

String，无默认值

用于指定敏感内容前缀的正则表达式，当 Match 配置为 regex 时必选。

RegexContent

String，无默认值

用于指定敏感内容的正则表达式，当 Match 配置为 regex 时必选。

样例

采集 /home/test-log/ 路径下包含敏感数据的 processor-desensitize.log 文件，根据指定的配置选项提取日志信息。

- 输入

echo "[{'account':'1812213231432969','password':'04a23f38'}, {account':'1812213685634','password':'123a'}]" >> /home/test-ilogtail/test-log/processor-desensitize.log

- 采集配置1

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_desensitize

SourceKey: content

Method: "const"

Match: "full"

ReplaceString: "********"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出1

{

"content":"********",

}

- 采集配置2

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_desensitize

SourceKey: content

Method: "const"

Match: "regex"

ReplaceString: "********"

RegexBegin: "'password':'"

RegexContent: "[^']*"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出2

{

"content":"[{'account':'1812213231432969','password':'********'}, {'account':'1812213685634','password':'********'}]",

}

- 采集配置3

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_desensitize

SourceKey: content

Method: "md5"

Match: "regex"

ReplaceString: "********"

RegexBegin: "'password':'"

RegexContent: "[^']*"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出3

{

"content":"[{'account':'1812213231432969','password':'9c525f463ba1c89d6badcd78b2b7bd79'}, {'account':'1812213685634','password':'1552c03e78d38d5005d4ce7b8018addf'}]",

}

丢弃字段

简介

processor_drop processor 插件可以丢弃日志字段。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型。

DropKeys

String[]

是

指定待丢弃的字段，支持配置多个。

样例

采集 /home/test-log/ 路径下的 json.log 文件，并按照 Json 格式进行日志解析，然后对解析后的字段进行丢弃。

- 输入

echo '{"key1": 123456, "key2": "abcd"}' >> /home/test-log/json.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_json

SourceKey: content

KeepSource: false

ExpandDepth: 1

ExpandConnector: ""

- Type: processor_drop

DropKeys:

- key1

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-dir/test_log/json.log",

"key2": "abcd",

"__time__": "1657354602"

}

字段加密

简介

processor_encrypt 插件可以使用 AES-128、AES-192、AES-256 算法对指定的字段加密，采用 PKCS7 填充算法。由于密文可能包含不可见字符，插件会对其进行十六进制编码。

版本

Stable

参数说明

参数

类型，默认值

说明

Type

String，无默认值(必填)

插件类型，固定为 processor_encrypt

SourceKeys

String[]，无默认值(必填)

指定需要加密的字段名，支持指定多个。

EncryptionParameters

EncryptionParameter，无默认值(必填)

指定加密参数。

KeepSourceValueIfError

Boolean， false

如果发生加密失败，是否保留原始值，如果不保留的话，字段值会被替换为  ENCRYPT_ERROR 。为了保护您的数据安全，默认值为  false   ，即失败时进行替换。

- EncryptionParameter 类型说明

参数

类型，默认值

说明

Key

String，无默认值

指定密钥（十六进制），未配置 KeyFilePath 时必选。AES-128、AES-192、AES-256 分别要求密钥为 16、24、32 字节，所以直接以此参数指定密钥时，需要填入 32、48、64 个十六进制字符。

IV

String，默认全 0

指定加密的初始向量（十六进制），若配置了KeyFilePath可不填写。此参数值大小等于内部 block 大小，AES-128、AES-192、AES-256 下分别为 8、12、16 字节，所以需要填入 16、24、32 个十六进制字符。

KeyFilePath

String，无默认值

指定保存加密参数的文件路径，未配置 Key 时必选。支持将前述参数（Key、IV）保存至文件（JSON 格式），文件中指定的值会覆盖通过前述参数指定的值。

样例

示例 1：直接指定 Key 且使用默认 IV

对字段  important  进行加密，假设密钥（Key）为二进制全 0 组成（256 bits）、不设置初始向量（IV），使用插件默认值，则配置详情及处理结果如下：

- 采集配置

processors:

- Type: processor_encrypt

SourceKeys:

- "important"

EncryptionParameters:

Key: "0000000000000000000000000000000000000000000000000000000000000000"

- 输入

"normal_key": "1",

"another_normal_key": "2",

"important": "0123456"

- 输出（由于加密后内容包含不可见字符，加密后会将其转换为十六进制）

"normal_key": "1",

"another_normal_key": "2",

"important": "bc3acdbd40c283d91f7dc7010fd7d2b1"

- 利用 openssl 进行解密

$ printf "%b" '\xbc\x3a\xcd\xbd\x40\xc2\x83\xd9\x1f\x7d\xc7\x01\x0f\xd7\xd2\xb1' > ciphertext

$ openssl enc -d -aes-256-cbc -iv 00000000000000000000000000000000 \

-K 0000000000000000000000000000000000000000000000000000000000000000 \

-in ciphertext -out plaintext

$ cat plaintext

0123456

示例 2：直接指定 Key 和 IV

对字段  important  进行加密，假设密钥（Key）为二进制全 0 组成（256 bits）、初始向量（IV）为二进制全 1 组成（128 bits），则配置详情及处理结果如下：

- 输入

"normal_key": "1",

"another_normal_key": "2",

"important": "0123456"

- 配置详情（注意 Key/IV 都是十六进制表示）

processors:

- Type: processor_encrypt

SourceKeys:

- "important"

EncryptionParameters:

Key: "0000000000000000000000000000000000000000000000000000000000000000"

IV: "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"

- 输出（由于加密后内容包含不可见字符，加密后会将其转换为十六进制）

"normal_key": "1",

"another_normal_key": "2",

"important": "af6428af62d698be617b82cffd9e109b"

- 利用 openssl 进行解密

$ printf "%b" '\xaf\x64\x28\xaf\x62\xd6\x98\xbe\x61\x7b\x82\xcf\xfd\x9e\x10\x9b' > ciphertext

$ openssl enc -d -aes-256-cbc -iv FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF \

-K 0000000000000000000000000000000000000000000000000000000000000000 \

-in ciphertext -out plaintext

$ cat plaintext

0123456

示例 3：通过文件指定 Key

对字段  important  进行加密，假设密钥（Key）为二进制全 1 组成（256 bits），密钥保存在机器的本地文件  /home/admin/aes_key  中，文件内容中未指定 IV 参数，使用插件默认值，配置详情及处理结果如下：

- 前置条件

运行 logtail 的机器上需要创建文件  /home/admin/aes_key.json （JSON 格式），并将密钥以十六进制存放在其中，命令如下：

printf "{\"Key\": \"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF\"}" > /home/admin/aes_key.json

- 输入

"normal_key": "1",

"another_normal_key": "2",

"important": "0123456"

- 配置详情

processors:

- Type: processor_encrypt

SourceKeys:

- "important"

EncryptionParameters:

KeyFilePath: "/home/admin/aes_key.json"

- 输出

"normal_key": "1",

"another_normal_key": "2",

"important": "bc3acdbd40c283d91f7dc7010fd7d2b1"

- 利用 openssl 进行解密

$ printf "%b" '\xbc\x3a\xcd\xbd\x40\xc2\x83\xd9\x1f\x7d\xc7\x01\x0f\xd7\xd2\xb1' > ciphertext

$ openssl enc -d -aes-256-cbc -iv 00000000000000000000000000000000 \

-K 0000000000000000000000000000000000000000000000000000000000000000 \

-in ciphertext -out plaintext

$ cat plaintext

0123456

条件字段处理

简介

processor_fields_with_condition 插件支持根据日志部分字段的取值，动态进行字段扩展或删除。源代码

版本

Stable

条件判断

- 支持多字段取值比较。

- 关系运算符：equals（默认）、regexp、contains、startwith。

- 逻辑运算符：and（默认）、or。

过滤能力

- 默认仅做字段动态处理。

- 可以开启过滤功能，未命中任意条件则丢弃。

处理能力

- 与现有插件processor_add_fields、processor_drop保持近似的使用习惯。

- 可以支持多组条件（Case）进行动态字段处理，但是按顺序匹配上一条后即退出。

配置参数

processor_fields_with_condition 配置

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 processor_fields_with_condition

DropIfNotMatchCondition

Boolean， false

当条均件不满足时，日志是被丢弃（true）还是被保留（false）。

Switch

Array，其中value为Condition，无默认值（必填）

切换行动的条件。

Condition 类型说明

参数

类型，默认值

说明

Case

ConditionCase，无默认值（必填）

日志数据满足的条件。

Actions

Array，其中value为ConditionAction，无默认值（必填）

满足条件时执行的动作。

ConditionCase 类型说明

参数

类型，默认值

说明

LogicalOperator

String， and

多个条件字段之间的逻辑运算符（and/or）。

RelationOperator

String， equals

条件字段的关系运算符（equals/regexp/contains/startwith）。

FieldConditions

Map，其中fieldKey和fieldValue为String类型，无默认值（必填）

字段名和表达式的键值对。

ConditionAction 类型说明

参数

类型，默认值

说明

type

String，无默认值（必填）

行动类型，可选值是 processor_add_fields / processor_drop   。

IgnoreIfExist

Boolean， false

当相同的键存在时是否要忽略。

Fields

Map，其中fieldKey和fieldValue为String类型，无默认值（必填）

附加字段的键值对。

DropKeys

Array，其中value为String，无默认值（必填）

丢弃字段。

样例

- 采集配置(使用 metric_mock 插件模拟输入)

enable: true

inputs:

- Type: metric_mock

Fields:

content : "{\"t1\": \"2022-07-22 12:50:08.571218122\", \"t2\": \"2022-07-22 12:50:08\", \"a\":\"b\",\"c\":2,\"d\":10, \"seq\": 20}"

t1 : "2022-07-22 12:50:08.571218122"

t2 : "2022-07-22 12:50:08"

a : b

c : "2"

d : "10"

seq : "20"

processors:

- Type: processor_fields_with_condition

DropIfNotMatchCondition: true

Switch:

- Case:

FieldConditions:

seq: "10"

d: "10"

Actions:

- type: processor_add_fields

IgnoreIfExist: false

Fields:

eventCode: event_00001

name: error_oom

- type: processor_drop

DropKeys:

- c

- Case:

FieldConditions:

seq: "20"

d: "10"

Actions:

- type: processor_add_fields

IgnoreIfExist: false

Fields:

eventCode: event_00002

name: error_oom2

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"Index":"1",

"a":"b",

"c":"2",

"content":"{\"t1\": \"2022-07-22 12:50:08.571218122\", \"t2\": \"2022-07-22 12:50:08\", \"a\":\"b\",\"c\":2,\"d\":10, \"seq\": 20}",

"d":"10",

"seq":"20",

"t1":"2022-07-22 12:50:08.571218122",

"t2":"2022-07-22 12:50:08",

"eventCode":"event_00002",

"name":"error_oom2",

"__time__":"1658490721"

}

日志过滤

简介

processor_filter_regex processor 插件可以实现对日志的过滤。一条日志只有完全匹配Include中的正则表达式，且不匹配Exclude中的正则表达式时才会被采集，否则直接丢弃。

版本

Stable

配置参数

参数

类型，默认值

说明

Include

Map， {}

Key为日志字段，Value为该字段值匹配的正则表达式。Key之间为与关系。如果日志中所有字段的值符合对应的正则表达式，则采集该日志。

Exclude

Map， {}

Key为日志字段，Value为该字段值匹配的正则表达式。Key之间为或关系。如果日志中任意一个字段的值符合对应的正则表达式，则不采集该日志。

样例

采集 /home/test-log/ 路径下的 proccessor-filter-regex.log 文件，并按照 Json 格式进行日志解析, 然后对部分日志进行过滤。

- 输入

echo '{"ip": "10.**.**.**", "method": "POST", "brower": "aliyun-sdk-java"}' >> /home/test-log/proccessor-filter-regex.log

echo '{"ip": "10.**.**.**", "method": "POST", "brower": "chrome"}' >> /home/test-log/proccessor-filter-regex.log

echo '{"ip": "192.168.**.**", "method": "POST", "brower": "aliyun-sls-ilogtail"}' >> /home/test-log/proccessor-filter-regex.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_json

SourceKey: content

KeepSource: false

ExpandDepth: 1

ExpandConnector: ""

- Type: processor_filter_regex

Include:

ip: "10\\..*"

method: POST

Exclude:

brower: "aliyun.*"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/proccessor-filter-regex.log",

"__time__": "1658837955",

"brower": "chrome",

"ip": "10.**.**.**",

"method": "POST"

}

Gotime

版本

Stable

配置参数

参数

类型

是否必选

说明

SourceKey

String

是

原始字段名。

SourceFormat

String

是

原始时间的格式。

SourceLocation

Int

否

原始时间的时区。参数值为空时，表示iLogtail所在主机或容器的时区。

DestKey

String

是

解析后的目标字段。

DestFormat

String

是

解析后的时间格式。

DestLocation

Int

否

解析后的时区。参数值为空时，表示本机时区。

SetTime

Boolean

否

是否将解析后的时间设置为日志时间。true（默认值）：是。false：否。

KeepSource

Boolean

否

被解析后的日志中是否保留原始字段。true（默认值）：保留。false：不保留。

NoKeyError

Boolean

否

原始日志中无您所指定的原始字段时，系统是否报错。true（默认值）：报错。false：不报错。

AlarmIfFail

Boolean

否

提取日志时间失败，系统是否报错。true（默认值）：报错。false：不报错。

注意 SourceFormat 和 DestFormat 的格式需要符合 Go 时间中的 layout。Go 中采用基于规则的方法对时间格式进行解析，例如，时间格式中 "1" 的时间单位为月份，"15" 的时间单位为小时。因此，为了避免解析失败，推荐选择 Go 中的时间原点 "2006-01-02 15:04:05" 作为 SourceFormat 和 DestFormat 的样例时间。 或者采用以下的标准时间格式：

const (

ANSIC       = "Mon Jan _2 15:04:05 2006"

UnixDate    = "Mon Jan _2 15:04:05 MST 2006"

RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"

RFC822      = "02 Jan 06 15:04 MST"

RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone

RFC850      = "Monday, 02-Jan-06 15:04:05 MST"

RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"

RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone

RFC3339     = "2006-01-02T15:04:05Z07:00"

RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"

Kitchen     = "3:04PM"

// Handy time stamps.

Stamp      = "Jan _2 15:04:05"

StampMilli = "Jan _2 15:04:05.000"

StampMicro = "Jan _2 15:04:05.000000"

StampNano  = "Jan _2 15:04:05.000000000"

DateTime   = "2006-01-02 15:04:05"

DateOnly   = "2006-01-02"

TimeOnly   = "15:04:05"

)

样例

采集 /home/test-log/ 目录下的 simple.log 文件，根据指定的配置选项提取日志信息。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_gotime

SourceKey: "content"

SourceFormat: "2006-01-02 15:04:05"

SourceLocation: 8

DestKey: "d_key"

DestFormat: "2006/01/02 15:04:05"

DestLocation: 9

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输入

echo "2006-01-02 15:04:05" >> simple.log

- 输出

{

"content":"2006-01-02 15:04:05",

"d_key":"2006/01/02 16:04:05"

}

Grok

简介

processor_grok 插件可以通过 Grok 语法匹配的模式，实现文本日志的字段提取。源代码

版本

Beta

配置参数

参数

类型，默认值

说明

Type

String，无默认值（必填）

插件类型，固定为 processor_grok

CustomPatternDir

Array，其中 value 为 String， []

自定义的GROK模式所在的文件夹地址，会读取文件夹内的所有文件。需要重启生效。

CustomPatterns

Map，其中 key 和 value 为 String， {}

自定义的GROK模式，key 为规则名，value 为 grok 表达式。

SourceKey

String， content

需要匹配的目标字段。

Match

Array，其中 value 为 String， []

用来匹配的 Grok 表达式数组。Grok 插件会从上至下依次使用 Match 中的表达式对日志进行匹配，并返回第一个匹配成功的结果。配置多条会影响性能，可以参考效率与优化

TimeoutMilliSeconds

Long， 0

解析 grok 表达式的最大尝试时间，单位为毫秒，设置为 0 禁用超时。

IgnoreParseFailure

Boolean， true

指定解析失败后的操作，不配置表示放弃解析，直接填充所返回的 content 字段。配置为 false ，表示解析失败时丢弃日志。

KeepSource

Boolean， true

是否保留原字段。

NoKeyError

Boolean， false

无匹配的原始字段时是否报错。

NoMatchError

Boolean， true

Match 中的表达式全不匹配时是否报错。

TimeoutError

Boolean， true

匹配超时是否返回错误。

样例

采集 /home/test-log/ 路径下的 processor-grok.log 文件，根据指定的配置选项提取日志信息。

- 采集配置

enable: true

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_grok

SourceKey: content

KeepSource: false

CustomPatterns:

HTTP: '%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes} %{NUMBER:duration}'

Match:

- '%{HTTP}'

- '%{WORD:word1} %{NUMBER:request_time} %{WORD:word2}'

- '%{YEAR:year} %{MONTH:month} %{MONTHDAY:day} %{QUOTEDSTRING:motto}'

IgnoreParseFailure: false

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输入1

echo 'begin 123.456 end' >> /home/test-ilogtail/test-log/processor-grok.log

- 输出1

{

"__tag__:__path__":"/home/test-ilogtail/test-log/processor-grok.log",

"word1":"begin",

"request_time":"123.456",

"word2":"end",

"__time__":"1662618045"

}

- 输入2

echo '2019 June 24 "I am iron man"' >> /home/test-ilogtail/test-log/processor-grok.log

- 输出2

{

"__tag__:__path__":"/home/test-ilogtail/test-log/processor-grok.log",

"year":"2019",

"month":"June",

"day":"24",

"motto":"\"I am iron man\"",

"__time__":"1662618059"

}

- 输入3

echo 'WRONG LOG' >> /home/test-ilogtail/test-log/processor-grok.log

- 输出3

{

"__tag__:__path__":"/home/test-ilogtail/test-log/processor-grok.log",

"__time__":"1662618069"

}

- 输入4

echo '10.0.0.0 GET /index.html 15824 0.043' >> /home/test-ilogtail/test-log/processor-grok.log

- 输出4

{

"__tag__:__path__":"/home/test-ilogtail/test-log/processor-grok.log",

"client":"10.0.0.0",

"method":"GET",

"request":"/index.html",

"bytes":"15824",

"duration":"0.043",

"__time__":"1662618081"

}

- 输出说明

在样例一中，processor_grok 插件首先使用 Match 中的第一个表达式 '%{HTTP}' 匹配日志，失败后进行下一个尝试。然后匹配 Match 中的第二个表达式 '%{WORD:word1} %{NUMBER:request_time} %{WORD:word2}' 成功，返回结果。由于 KeepSource 参数设置为 false，所以原日志的 content 的字段被丢弃了。 样例二、样例四与样例一类似，分别使用 Match 中的第三和第一个表达式成功匹配日志。 在样例三中，processor_grok 插件使用 Match 中的三个表达式均匹配失败，所以没有任何结果。又因为 IgnoreParseFailure 设置为了 false，所以匹配失败的样例输出三的 content 字段被丢弃了。

Grok 模式

processor_grok  插件主要使用 SLS 的 GROK 模式。SLS数据加工提供了 70+ 常用的 GROK 模式，例如身份证号、邮箱、MAC 地址、IPV4、IPV6、时间解析、URL 解析等。此外，还整合了一些其他通用的 Grok 模式。

所有的 Grok 模式模版请见链接。

效率与优化

正则引擎

由于 Golang 原生的  regexp  库不支持一些高级的正则语法，故  processor_grok  的正则引擎使用第三方的 regexp2 库。 regexp2  库与 Golang 原生的  regexp  的简单性能对比可以参考源代码中的 Benchmark 测试。

优化匹配失败时间

Grok 语法在匹配失败的情况下时间开销巨大。为了提高插件解析的效率，必须优化匹配失败的时间，这里给出几种可以优化匹配失败时间的思路。

- 表达式与数据尽量完全匹配

- 在 grok 表达式中添加锚点，例如^、$等，减少不必要的匹配尝试

- 设置超时时间，即配置参数中的 TimeoutMilliSeconds 参数

多项匹配优化

processor_grok  插件支持多项匹配，即可以在 Match 中设置多个 Grok 表达式，依次对日志进行匹配尝试。但使用多项匹配时，由于需要一个个匹配合适的表达式，会经历很多匹配失败的情况。可以参考源代码中的 Benchmark 测试，其对 Match 中有1、2、3、5条表达式的情况，分别做了简单的模拟匹配失败的性能测试，可以看出效率是成倍降低的。

因此，在使用  processor_grok  插件时，最好尽量不使用多项匹配，或者 Match 中设置尽可能少的 Grok 表达式。也可以通过减少重复的匹配，来优化效率。下面是使用分层策略减少重复匹配的一个样例。

- 输入

输入共三条数据

'8.8.8.8 process-name[666]: a b 1 2 a lot of text at the end'

'8.8.8.8 process-name[667]: a 1 2 3 a lot of text near the end;4'

'8.8.8.8 process-name[421]: a completely different format | 1111'

- 常规配置

标准的多项匹配，一个一个匹配完整的表达式。

processors:

- Type: processor_grok

SourceKey: content

Match:

- '%{IPORHOST:clientip} %{DATA:process_name}\[%{NUMBER:process_id}\]: %{WORD:word_1} %{WORD:word_2} %{NUMBER:number_1} %{NUMBER:number_2} %{DATA:data}'

- '%{IPORHOST:clientip} %{DATA:process_name}\[%{NUMBER:process_id}\]: %{WORD:word_1} %{NUMBER:number_1} %{NUMBER:number_2} %{NUMBER:number_3} %{DATA:data};%{NUMBER:number_4}'

- '%{IPORHOST:clientip} %{DATA:process_name}\[%{NUMBER:process_id}\]: %{DATA:data} \| %{NUMBER:number}'

- 优化配置

先统一处理前半部分，然后统一处理后半部分

processors:

- Type: processor_grok

SourceKey: content

Match:

- '%{IPORHOST:clientip} %{DATA:process_name}\[%{NUMBER:process_id}\]: %{GREEDYDATA:content_2}'

KeepSource: false

- Type: processor_grok

SourceKey: content_2

Match:

- '%{WORD:word_1} %{WORD:word_2} %{NUMBER:number_1} %{NUMBER:number_2} %{GREEDYDATA:data}'

- '%{WORD:word_1} %{NUMBER:number_1} %{NUMBER:number_2} %{NUMBER:number_3} %{DATA:data};%{NUMBER:number_4}'

- '%{DATA:data} \| %{NUMBER:number}'

KeepSource: false

Json

简介

processor_json processor 插件可以实现对 Json 格式日志的解析。

备注：当作为第一个日志解析插件时，建议使用Json加速插件替代。

支持的Event类型

LogGroup(v1)

EventTypeLogging

EventTypeMetric

EventTypeSpan

✅

✅

❌

❌

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

SourceKey

String

是

原始字段名

NoKeyError

Boolean

否

无匹配字段时是否报错。如果未添加该参数，则默认使用true，表示报错。

ExpandDepth

Int

否

JSON展开的深度。如果未添加该参数，则默认为0，表示不限制。1表示当前层级，以此类推。

ExpandConnector

String

否

JSON展开时的连接符，可以为空。如果未添加该参数，则默认使用下划线（_）。

Prefix

String

否

JSON展开时对字段附加的前缀。如果未添加该参数，则默认为空。

KeepSource

Boolean

否

是否保留原始字段。如果未添加该参数，则默认使用true，表示保留。

UseSourceKeyAsPrefix

Boolean

否

是否将原始字段名作为所有JSON展开字段名的前缀。如果未添加该参数，则默认使用false，表示否。

KeepSourceIfParseError

Boolean

否

解析失败时，是否保留原始日志。如果未添加该参数，则默认使用true，表示保留原始日志。

IgnoreFirstConnector

Boolean

否

是否忽略第一个连接符。如果未添加该参数，则默认使用false，表示忽略第一个连接符。

ExpandArray

Boolean

否

是否展开JSON数组。如果未添加该参数，则默认使用false，表示不展开数组。

样例

采集 /home/test-log/ 路径下的 json.log 文件，并按照 Json 格式进行日志解析。

- 输入

echo '{"key1": 123456, "key2": "abcd"}' >> /home/test-log/json.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_json

SourceKey: content

KeepSource: false

ExpandDepth: 1

ExpandConnector: ""

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-dir/test_log/json.log",

"key1": "123456",

"key2": "abcd",

"__time__": "1657354602"

}

日志转换为sls metric

简介

processor_log_to_sls_metric 插件可以根据配置将日志转换为sls metric。

版本

Beta

配置参数

参数

类型

必选或可选

参数说明

MetricTimeKey

String

可选

指定要用作时间戳  __time_nano__  的字段。默认取 log.Time   。确保指定的字段是合法的、符合格式的时间戳，目前支持second(秒，10位长度)、millisecond(毫秒，13位长度)、microsecond(微秒，16位长度)、nanosecond(纳秒，19位长度) 为单位的 Unix 时间戳。

MetricLabelKeys

Array

必选

__labels__  字段的key列表，key需遵循正则表达式：  ^[a-zA-Z_][a-zA-Z0-9_]*$ ，不能包含 __labels__ 。如果原始字段中存在  __labels__    字段，该值将被追加到列表中。 Label的Value不能包含竖线（\

）和 "#$#"。

MetricValues

Map

必选

时序字段名所使用的key与时序值使用的key的映射。name需遵循正则表达式： ^[a-zA-Z_:][a-zA-Z0-9_:]*$    ，时序值需要是double类型的字符串。

CustomMetricLabels

Map

可选

要追加的自定义  __labels__  字段。 key需遵循正则表达式：  ^[a-zA-Z_][a-zA-Z0-9_]*$   ，Value不能包含竖线（\

）和 "#$#"。

IgnoreError

Bool

可选

当日志没有匹配时是否输出Error日志。如果未添加该参数，则默认使用false，表示不忽略。

注意：MetricTimeKey、MetricLabelKeys、MetricValues、CustomMetricLabels的字段不可相互重复。

样例

以下是一个示例配置，展示了如何使用  processor_log_to_sls_metric  插件来处理数据：

采集 /home/test-log/ 路径下的 nginx.log 文件，首先使用 processor_regex 插件提取log内容，然后测试 processor_log_to_sls_metric 的功能。

- 输入

echo '::1 - - [18/Jul/2022:07:28:01 +0000] "GET /hello/ilogtail HTTP/1.1" 404 153 "-" "curl/7.74.0" "-"' >> /home/test-log/nginx.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_regex

SourceKey: content

Regex: '([\d\.:]+) - (\S+) \[(\S+) \S+\] \"(\S+) (\S+) ([^\\"]+)\" (\d+) (\d+) \"([^\\"]*)\" \"([^\\"]*)\" \"([^\\"]*)\"'

Keys:

- remote_addr

- remote_user

- time_local

- method

- url

- protocol

- status

- body_bytes_sent

- http_referer

- http_user_agent

- http_x_forwarded_for

- Type: processor_log_to_sls_metric

MetricLabelKeys:

- url

- method

MetricValues:

remote_addr: status

CustomMetricLabels:

nginx: test

IgnoreError: false

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__labels__":"method#$#GET|nginx#$#test|url#$#/hello/ilogtail",

"__name__":"::1",

"__value__":"404",

"__time_nano__":"1688956340000000000",

"__time__":"1688956340"

}

正则

简介

processor_regex processor 插件可以通过正则匹配的模式实现文本日志的字段提取。

备注：当作为第一个日志解析插件时，建议使用正则加速插件替代。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

SourceKey

String

是

原始字段名

Regex

String

是

正则表达式，使用()标注待提取的字段。

Keys

String数组

是

提取的字段名，例如["ip", "time", "method"]。

NoKeyError

Boolean

否

无匹配的原始字段时是否报错。如果未添加该参数，则默认使用false，表示不报错。

NoMatchError

Boolean

否

正则表达式与原始字段的值不匹配时是否报错。如果未添加该参数，则默认使用false，表示不报错。

KeepSource

Boolean

否

是否保留原始字段。如果未添加该参数，则默认使用false，表示不保留。

FullMatch

Boolean

否

如果未添加该参数，则默认使用true，表示只有字段完全匹配Regex参数中的正则表达式时才被提取。配置为false，表示部分字段匹配也会进行提取。

KeepSourceIfParseError

Boolean

否

解析失败时，是否保留原始日志。如果未添加该参数，则默认使用true，表示保留原始日志。

样例

采集 /home/test-log/ 路径下的 reg.log 文件，日志内容按照提取字段。

- 输入

echo '127.0.0.1 - - [10/Aug/2017:14:57:51 +0800] "POST /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"' >> /home/test-log/reg.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_regex

SourceKey: content

Regex: ([\d\.]+) \S+ \S+ \[(\S+) \S+\] \"(\w+) ([^\\"]*)\" ([\d\.]+) (\d+) (\d+) (\d+|-) \"([^\\"]*)\" \"([^\\"]*)\"

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/reg.log",

"ip": "127.0.0.1",

"time": "10/Aug/2017:14:57:51",

"method": "POST",

"url": "/PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1657362166"

}

重命名字段

简介

processor_rename processor 插件可以将日志字段重命名。

支持的Event类型

LogGroup(v1)

EventTypeLogging

EventTypeMetric

EventTypeSpan

✅

✅

✅ 重命名Tag

✅ 重命名Tag

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型。

NoKeyError

Boolean

否

无匹配字段时是否报错。如果未添加该参数，则默认使用false，表示不报错。

SourceKeys

String[]

是

待重命名的原始字段。

DestKeys

String[]

是

重命名后的字段。

样例

采集 /home/test-log/ 路径下的 json.log 文件，并按照 Json 格式进行日志解析，然后对解析后的字段进行重命名。

- 输入

echo '{"key1": 123456, "key2": "abcd"}' >> /home/test-log/json.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_json

SourceKey: content

KeepSource: false

ExpandDepth: 1

ExpandConnector: ""

- Type: processor_rename

SourceKeys:

- key1

DestKeys:

- new_key1

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/key_value.log",

"new_key1": "123456",

"key2": "abcd",

"__time__": "1657354602"

}

分隔符

简介

processor_split_char processor 插件可以通过单字符的分隔符提取字段，该方式支持使用引用符对分隔符进行包裹。

processor_split_string processor 插件可以通过多字符的分隔符提取字段，该方式不支持使用引用符对分隔符进行包裹。

版本

Stable

配置参数

processor_split_char 配置

参数

类型

是否必选

说明

Type

String

是

插件类型

SourceKey

String

是

原始字段名

SplitSep

String

是

分隔符。必须为单字符，可设置为不可见字符，例如\u0001。

SplitKeys

String数组

是

分割日志后设置的字段名，例如["ip", "time", "method"]。

QuoteFlag

Boolean

否

是否使用引用符。如果未添加该参数，则默认使用false，表示不使用。

Quote

String

否

仅当QuoteFlag配置为true时有效。

NoKeyError

Boolean

否

无匹配的原始字段时是否报错。如果未添加该参数，则默认使用false，表示不报错。

NoMatchError

Boolean

否

分隔符不匹配时是否报错。如果未添加该参数，则默认使用false，表示不报错。

KeepSource

Boolean

否

是否保留原始字段。如果未添加该参数，则默认使用false，表示不保留。

processor_split_string 配置

参数

类型

是否必选

说明

Type

String

是

插件类型

SourceKey

String

是

原始字段名

SplitSep

String

是

分隔符。可以设置不可见字符，例如\u0001\u0002。

SplitKeys

String数组

是

分割日志后设置的字段名，例如["ip", "time", "method"]。

PreserveOthers

Boolean

否

如果待分割的字段长度大于SplitKeys参数中的字段长度时是否保留超出部分。如果未添加该参数，则默认使用false，表示不保留。

ExpandOthers

Boolean

否

是否解析超出部分。如果未添加该参数，则默认使用false，表示不继续解析。

ExpandKeyPrefix

String

否

超出部分的命名前缀。例如配置expand_，则Key为expand_1、expand_2。

NoKeyError

Boolean

否

无匹配的原始字段时是否报错。如果未添加该参数，则默认使用false，表示不报错。

NoMatchError

Boolean

否

分隔符不匹配时是否报错。如果未添加该参数，则默认使用false，表示不报错。

KeepSource

Boolean

否

是否保留原始字段。如果未添加该参数，则默认使用false，表示不保留。

样例

采集 /home/test-log/ 路径下的 delimiter.log 文件，使用竖线 （|） 分隔符提取日志的字段值。

- 输入

echo "127.0.0.1|10/Aug/2017:14:57:51 +0800|POST|PutData?Category=YunOsAccountOpLog|0.024|18204|200|37|-|aliyun-sdk-java" >> /home/test-log/delimiter.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_split_char

SourceKey: content

SplitSep: "|"

SplitKeys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/delimiter.log",

"ip": "127.0.0.1",

"time": "10/Aug/2017:14:57:51 +0800",

"method": "POST",

"url": "PutData?Category=YunOsAccountOpLog",

"request_time": "0.024",

"request_length": "18204",

"status": "200",

"length": "37",

"ref_url": "-",

"browser": "aliyun-sdk-java",

"__time__": "1657361070"

}

键值对

简介

processor_split_key_value processor 插件可以通过切分键值对的方式提取字段。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型。

SourceKey

String

否

原始字段名。

Delimiter

String

否

键值对之间的分隔符。如果未添加该参数，则默认使用制表符\t。

Separator

String

否

单个键值对中键与值之间的分隔符。如果未添加该参数，则默认使用冒号（:）。

KeepSource

Boolean

否

是否保留原始字段。如果未添加该参数，则默认使用true，表示保留。

ErrIfKeyIsEmpty

Boolean

否

当key为空字符串时是否告警。如果未添加该参数，则默认使用true，表示告警。

EmptyKeyPrefix

String

否

如果key是空字符串，可通过该参数设置key的前缀，默认为"emptykey  "，最终key的格式为前缀+序号，比如"empty_key_0"。

DiscardWhenSeparatorNotFound

Boolean

否

无匹配的原始字段时是否丢弃该键值对。如果未添加该参数，则默认使用false，表示不丢弃。

NoSeparatorKeyPrefix

Boolean

否

无匹配的原始字段时，如果保留该键值对，可通过该参数设置key的前缀，默认为"noseparator_key  ", 最终保存下来的格式为前缀+序号:报错键值对，比如"no_separator_key_0":"报错键值对"

ErrIfSourceKeyNotFound

Boolean

否

无匹配的原始字段时是否告警。如果未添加该参数，则默认使用true，表示告警。

ErrIfSeparatorNotFound

Boolean

否

当指定的分隔符（Separator）不存在时是否告警。如果未添加该参数，则默认使用true，表示告警。

Quote

String

否

引用符，当设定后若值被引用符包含，就提取引用符内的值。

注意引用符若为双引号，需要加转义符\。

当引用符内包含\字符与引用连用的情况，作为值的一部分输出。

引用符支持多字符。

默认不开启引用符功能。

样例

切分键值对1

采集 /home/test-log/ 路径下的 key_value.log 文件，并按照键值对间分隔符为制表符 \t ，键值对中的分隔符为冒号 :  的格式进行日志解析。

- 输入

echo -e 'class:main\tuserid:123456\tmethod:get\tmessage:\"wrong user\"' >> /home/test-log/key_value.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_split_key_value

SourceKey: content

Delimiter: "\t"

Separator: ":"

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/key_value.log",

"class": "main",

"userid": "123456",

"method": "get",

"message": "\"wrong user\"",

"__time__": "1657354602"

}

包含引用符的切分键值对

采集 /home/test-log/ 路径下的 key_value.log 文件，并按照键值对间分隔符为制表符 \t ，键值对中的分隔符为冒号 :  的格式进行日志解析。

- 输入

echo -e 'class:main http_user_agent:"User Agent" "中文" "hello\t\"ilogtail\"\tworld"' >> /home/test-log/key_value.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_split_key_value

SourceKey: content

Delimiter: " "

Separator: ":"

Quote: "\""

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/key_value.log",

"class": "main",

"http_user_agent": "User Agent",

"no_separator_key_0": "中文",

"no_separator_key_1": "hello\t\"ilogtail\"\tworld",

"__time__": "1657354602"

}

包含多字符引用符的切分键值对

采集 /home/test-log/ 路径下的 key_value.log 文件，并按照键值对间分隔符为制表符 \t ，键值对中的分隔符为冒号 :  的格式进行日志解析。

- 输入

echo -e 'class:main http_user_agent:"""User Agent""" """中文"""' >> /home/test-log/key_value.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_split_key_value

SourceKey: content

Delimiter: " "

Separator: ":"

Quote: "\"\"\""

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/key_value.log",

"class": "main",

"http_user_agent": "User Agent",

"no_separator_key_0": "中文",

"__time__": "1657354602"

}

多行切分

简介

processor_split_log_regex processor 插件实现多行日志（例如Java程序日志）的采集。

备注：建议使用正则加速或分隔符加速插件中的多行切分功能替代。 单独与非加速插件配合时，该插件必须设置为 processor 的第一个插件。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

SplitKey

String

是

切分依据的字段。

SplitRegex

String

是

行首正则，只有匹配上的才认为是多行日志块的行首。

默认为.*，表示每行都进行切分。

PreserveOthers

Boolen

否

是否保留其他非SplitKey字段。

NoKeyError

Boolean

否

无匹配的原始字段时是否报错。如果未添加该参数，则默认使用false，表示不报错。

样例

采集 /home/test-log/ 路径下的 multiline.log 文件，并按行首正则进行多行切分。

- 输入

echo -e  '[2022-03-03 18:00:00] xxx1\nyyyyy\nzzzzzz\n[2022-03-03 18:00:01] xxx2\nyyyyy\nzzzzzz' >> /home/test-log/multiline.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_split_log_regex

SplitRegex: \[\d+-\d+-\d+\s\d+:\d+:\d+]\s.*

SplitKey: content

PreserveOthers: true

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test-log/multiline.log",

"content": "[2022-03-03 18:00:00] xxx1\nyyyyy\nzzzzzz\n",

"__time__": "1657367638"

}

{

"__tag__:__path__": "/home/test-log/multiline.log",

"content": "[2022-03-03 18:00:01] xxx2\nyyyyy\nzzzzzz",

"__time__": "1657367638"

}

字符串替换

简介

processor_string_replace processor 插件可以通过全文、正则匹配、去转义的方式实现文本日志的替换。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

SourceKey

String

是

匹配字段名

Method

String

是

无默认值。匹配方式，可选值如下：

const：字符串全文替换。

regex：使用正则提取替换。

unquote：去除转义符。

Match

String

否

无默认值。匹配指定数据。

const：输入需要匹配的字符串。当多个子串符合匹配条件时全部替换。

regex：输入需要匹配的正则表达式。当多个子串符合匹配条件时全部替换，也可以用正则分组的方式匹配指定分组。

unquote：去除转义符不需要输入。

ReplaceString

String

否

默认值""。替换数据。

const：为匹配后替换的字符串。

regex：为匹配后替换的字符串，支持分组替换。

unquote：去除转义符不需要输入。

DestKey

String

否

无默认值。字符串替换后的值存储的新字段，默认不存储新字段。

样例

示例 1：全文匹配与替换

采集 /home/test-log/ 路径下的 string_replace.log 文件，测试日志内容的正则匹配与替换功能。

- 输入

echo 'hello,how old are you? nice to meet you' >> /home/test-log/string_replace.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_string_replace

SourceKey: content

Method: const

Match: 'how old are you?'

ReplaceString: ''

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/string_replace.log",

"content": "hello, nice to meet you",

"__time__": "1680353730"

}

示例 2：基本正则匹配与替换

采集 /home/test-log/ 路径下的 string_replace.log 文件，测试日志内容的正则匹配与替换功能。

- 输入

echo '2022-09-16 09:03:31.013 \u001b[32mINFO \u001b[0;39m \u001b[34m[TID: N/A]\u001b[0;39m [\u001b[35mThread-30\u001b[0;39m] \u001b[36mc.s.govern.polygonsync.job.BlockTask\u001b[0;39m : 区块采集------结束------\r' >> /home/test-log/string_replace.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_string_replace

SourceKey: content

Method: regex

Match: \\u\w+\[\d{1,3};*\d{1,3}m|N/A

ReplaceString: ''

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/string_replace.log",

"content": "2022-09-16 09:03:31.013 INFO  [TID: ] [Thread-30] c.s.govern.polygonsync.job.BlockTask : 区块采集------结束------\r",

"__time__": "1680353730"

}

示例 3：根据正则分组匹配与替换并输出到新的字段

采集 /home/test-log/ 路径下的 string_replace.log 文件，测试日志内容的正则分组匹配与替换功能。 注：分组替换ReplaceString中不能存在{}，选择分组只能使用$1、$2 这种方式。

- 输入

echo '10.10.239.16' >> /home/test-log/string_replace.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_string_replace

SourceKey: content

Method: regex

Match: (\d.*\.)\d+

ReplaceString: $1*/24

DestKey: new_ip

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/string_replace.log",

"content": "10.10.239.16",

"new_ip": "10.10.239.*/24",

"__time__": "1680353730"

}

示例 4：替换转义字符

采集 /home/test-log/ 路径下的 string_replace.log 文件，测试转义自付替换功能。

- 输入

echo '{\\x22UNAME\\x22:\\x22\\x22,\\x22GID\\x22:\\x22\\x22,\\x22PAID\\x22:\\x22\\x22,\\x22UUID\\x22:\\x22\\x22,\\x22STARTTIME\\x22:\\x22\\x22,\\x22ENDTIME\\x22:\\x22\\x22,\\x22UID\\x22:\\x222154212790\\x22,\\x22page_num\\x22:1,\\x22page_size\\x22:10}' >> /home/test-log/string_replace.log

echo '\\u554a\\u554a\\u554a' >> /home/test-log/string_replace.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

processors:

- Type: processor_string_replace

SourceKey: content

Method: unquote

flushers:

- Type: flusher_stdout

OnlyStdout: true

- 输出

{

"__tag__:__path__": "/home/test_log/string_replace.log",

"content": "{\"UNAME\":\"\",\"GID\":\"\",\"PAID\":\"\",\"UUID\":\"\",\"STARTTIME\":\"\",\"ENDTIME\":\"\",\"UID\":\"2154212790\",\"page_num\":1,\"page_size\":10}",

"__time__": "1680353730"

}

{

"__tag__:__path__": "/home/test_log/string_replace.log",

"content": "啊啊啊",

"__time__": "1680353730"

}

聚合

聚合插件用于将事件进行打包，从而提升发送效率。仅限以下场景使用：

- 使用了除SLS输出插件

- 使用了SLS输出插件，且同时使用了扩展处理插件

对于上述场景，如果用户的采集配置中未指定聚合插件，则 iLogtail 会使用默认聚合插件，即上下文聚合插件。

基础聚合

简介

aggregator_base   aggregator 插件可以实现对单条日志的聚合。

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 aggregator_base   。

MaxLogGroupCount

Int

否

在执行Flush之前，内存中允许存在的最大LogGroup数量。如果未添加该参数，则默认内存中最多允许存在4个LogGroup。

MaxLogCount

Int

否

每个LogGroup最多可包含的日志条数。如果未添加该参数，则默认每个LogGroup最多可包含1024条日志。

PackFlag

Boolean

否

是否需要在LogGroup的LogTag中添加pack_id字段。如果未添加改参数，则默认在LogGroup的LogTag中添加pack_id  字段。

Topic

String

否

LogGroup的Topic名。如果未添加该参数，则默认每个LogGroup的Topic名为空。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，使用基础聚合功能，设定Topic为“file”，并将采集结果发送到SLS。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

aggregators:

- Type: aggregator_base

Topic: file

flushers:

- Type: flusher_stdout

OnlyStdout: true

上下文聚合

简介

aggregator_context   aggregator 插件可以实现根据日志来源对单条日志进行聚合。

版本

Beta

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 aggregator_context   。

MaxLogGroupCount

Int

否

在执行Flush之前，每一个日志来源所允许存在的最大LogGroup数量。如果未添加该参数，则默认每一个日志来源最多允许存在2个LogGroup。

MaxLogCount

Int

否

每个LogGroup最多可包含的日志条数。如果未添加该参数，则默认每个LogGroup最多可包含1024条日志。

PackFlag

Boolean

否

是否需要在LogGroup的LogTag中添加pack_id字段。如果未添加改参数，则默认在LogGroup的LogTag中添加pack_id  字段。

Topic

String

否

额外设置的LogGroup的Topic名。如果未添加该参数，则每个LogGroup的Topic名默认值如下：
空，如果input插件不提供设置Topic的能力；

input插件中设置的topic名称，如果input插件提供设置Topic的能力。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，使用上下文聚合功能，将来源于同一文件的日志聚合在一起，并将采集结果发送到SLS。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

aggregators:

- Type: aggregator_context

flushers:

- Type: flusher_stdout

OnlyStdout: true

基础聚合

简介

aggregator_content_value_group   aggregator 插件可以实现对单条日志按照指定的 Key 进行聚合。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 aggregator_content_value_group   。

GroupKeys

[]String

是

指定需要按照其值分组的Key列表

EnablePackID

Boolean

否

是否需要在LogGroup的LogTag中添加pack_id字段。如果未添加改参数，则默认在LogGroup的LogTag中添加pack_id  字段。

Topic

String

否

LogGroup的Topic名。如果未添加该参数，则默认每个LogGroup的Topic名为空。

ErrIfKeyNotFound

Boolean

否

当指定的Key在Log的Contents中找不到时，是否打印错误日志

样例

采集 /home/test-log/ 路径下的所有文件名匹配 reg.log 规则的文件，使用 processor_regex 提取字段后，再按照字段 url 、 method 字段聚合，并将采集结果发送到SLS。

- 输入

echo '127.0.0.1 - - [10/Aug/2017:14:57:51 +0800] "POST /PutData?Category=YunOsAccountOpLog" 0.024 18204 200 37 "-" "aliyun-sdk-java"' >> /home/test-log/reg.log

- 采集配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/reg.log

processors:

- Type: processor_regex

SourceKey: content

Regex: ([\d\.]+) \S+ \S+ \[(\S+) \S+\] \"(\w+) ([^\\"]*)\" ([\d\.]+) (\d+) (\d+) (\d+|-) \"([^\\"]*)\" \"([^\\"]*)\"

Keys:

- ip

- time

- method

- url

- request_time

- request_length

- status

- length

- ref_url

- browser

aggregators:

- Type: aggregator_content_value_group

GroupKeys:

- url

- method

flushers:

- Type: flusher_stdout

OnlyStdout: true

GroupMetadata聚合

简介

aggregator_metadata_group   aggregator 插件可以实现对PipelineGroupEvents按照指定的 Metadata Key 进行重新聚合。仅支持v2版本。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，指定为 aggregator_metadata_group   。

GroupMetadataKeys

[]String

否

指定需要按照其值分组的Key列表, 为空是表示丢弃Metadata, 只进行打包聚合。

GroupMaxEventLength

int

否

聚合时，单个PipelineGroupEvents中的最大Events数量，默认1024

GroupMaxByteLength

int

否

聚合时，单个PipelineGroupEvents中Events总的字节长度，仅支持ByteArray类型，默认3MiB

DropOversizeEvent

int

否

遇到单个PipelineGroupEvent字节长度超过上限是否丢弃,默认为true

样例

采集 service_http_server 输入插件获取的字节流，使用 GroupMetadataKeys  指定Metadata中用于聚合的字段，聚合后将采集结果通过http请求发送到指定目的。本样例中需要使用v2版本插件。

在样例中，首先通过input插件的配置 QueryParams 定义Metadata的数据来源，然后才能在aggregator插件中使用Metadata Key进行聚合，相同 db 的Events会被放在同一个PipelineGroupEvents向后传递。在flusher_http中，每个PipelineGroupEvents中的所有Events会在一次请求中输出。

- 输入

curl --request POST 'http://127.0.0.1:12345?db=mydb' --data 'test,host=server01,region=cn value=0.1'

- 采集配置

enable: true

version: "v2"

inputs:

- Type: service_http_server

Format: raw

Address: "http://127.0.0.1:12345"

QueryParams:

- db

aggregators:

- Type: aggregator_metadata_group

GroupMetadataKeys:

- db

flushers:

- Type: flusher_http

RemoteURL: "http://127.0.0.1:8086/write"

Query:

db: "%{metadata.db}"

Convert:

Protocol: raw

Encoding: custom

输出

Kafka

简介

flusher_kafka   flusher 插件可以实现将采集到的数据，经过处理后，发送到Kafka。

版本

Deprecated，请使用 flusher_kafka_v2

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

Brokers

String数组

是

Kafka Brokers

Topic

String

是

Kafka Topic

SASLUsername

String

否

SASL用户名

SASLPassword

String

否

SASL密码

PartitionerType

String

否

Partitioner类型。取值： roundrobin 、 hash 、 random 。默认为： random   。

HashKeys

String数组

否

PartitionerType为 hash   时，需指定HashKeys。

HashOnce

Boolean

否

ClientID

String

否

写入Kafka的Client ID，默认取值： LogtailPlugin   。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到Kafka。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

Topic: KafkaTestTopic

Kafka

简介

flusher_kafka_v2   flusher 插件可以实现将采集到的数据，经过处理后，发送到Kafka。

版本

Beta

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

Brokers

String数组

是

Kafka Brokers

Topic

String

是

Kafka Topic,支持动态topic, 例如:  test_%{content.appname}

Version

String

否

Kafka协议版本号 ,例如： 2.0.0 ，默认值： 1.0.0

Headers

header数组

否

kafka消息头 ，配置使用请参考本文中 Headers   配置用例

Convert

Struct

否

iLogtail数据转换协议配置

Convert.Protocol

String

否

iLogtail数据转换协议，kafka flusher 可选值： custom_single , custom_single_flatten , otlp_log_v1 。默认值： custom_single

Convert.Encoding

String

否

iLogtail flusher数据转换编码，可选值： json 、 none 、 protobuf ，默认值： json

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

iLogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

Authentication

Struct

否

Kafka连接访问认证配置，支持 SASL/PLAIN   ，根据kafka服务端认证方式选择配置

Authentication.PlainText.Username

String

否

PlainText认证用户名

Authentication.PlainText.Password

String

否

PlainText认证密码

Authentication.SASL.Username

String

否

SASL认证用户名

Authentication.SASL.Password

String

否

SASL认证密码

Authentication.Sasl.SaslMechanism

String

否

SASL认证，配置可选项： PLAIN 、 SCRAM-SHA-256 、 SCRAM-SHA-512

Authentication.TLS.Enabled

Boolean

否

是否启用TLS安全连接,

Authentication.TLS.CAFile

String

否

TLS CA根证书文件路径

Authentication.TLS.CertFile

String

否

TLS连接 kafka   证书文件路径

Authentication.TLS.KeyFile

String

否

TLS连接 kafka   私钥文件路径

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

Authentication.TLS.InsecureSkipVerify

Boolean

否

是否跳过TLS证书校验

Authentication.Kerberos.ServiceName

String

否

服务名称，例如：kafka

Authentication.Kerberos.UseKeyTab

Boolean

否

是否采用keytab，配置此项后需要配置KeyTabPath，默认为： false

Authentication.Kerberos.Username

Boolean

否

UseKeyTab设置为 false   的情况下，需要指定用户名

Authentication.Kerberos.Password

String

否

UseKeyTab设置为 false   的情况下，需要指定密码

Authentication.Kerberos.Realm

String

否

kerberos认证管理域,大小写敏感

Authentication.Kerberos.ConfigPath

Boolean

否

Kerberos krb5.conf

Authentication.Kerberos.KeyTabPath

String

否

keytab的路径

PartitionerType

String

否

Partitioner类型。取值： roundrobin 、 hash 、 random 。默认为： random   。

RequiredAcks

int

否

ACK的可靠等级.0=无响应,1=等待本地消息,-1=等待所有副本提交.默认1，

Compression

String

否

压缩算法，可选值： none ,  snappy ， lz4 和 gzip ，默认值 none

CompressionLevel

Int

否

压缩级别，可选值： 1~9 ，默认值： 4 ,设置为 0 则禁用 Compression

MaxMessageBytes

Int

否

一个批次提交的大小限制，配置和 message.max.bytes 对应，默认值： 1000000

MaxOpenRequests

Int

否

一个连接允许的最大打开的请求数，默认值: 5

MaxRetries

Int

否

提交失败重试次数，最大 3 次，默认值： 3

BulkMaxSize

Int

否

单次请求提交事件数，默认 2048

BulkFlushFrequency

Int

否

发送批量 Kafka 请求之前等待的时间,0标识没有时延，默认值: 0

Timeout

Int

否

等待Kafka brokers响应的超时时间，默认 30s

BrokerTimeout

int

否

kafka broker等待请求的最大时长，默认 10s

Metadata.Retry.Max

int

否

最大重试次数，默认值： 3

Metadata.Retry.Backoff

int

否

在重试之前等待leader选举发生的时间，默认值： 250ms

Metadata.RefreshFrequency

int

否

Metadata刷新频率，默认值： 250ms

Metadata.Full

int

否

获取原数数据的策略，获取元数据时使用的策略，当此选项为 true 时，客户端将为所有可用主题维护一整套元数据，如果此选项设置为 false ，它将仅刷新已配置主题的元数据。默认值: false   。

HashKeys

String数组

否

PartitionerType为 hash   时，需指定HashKeys。

HashOnce

Boolean

否

ClientID

String

否

写入Kafka的Client ID，默认取值： LogtailPlugin   。

- Version 需要填写的是 kafka protocol version 版本号， flusher_kafka_v2 当前支持的 kafka 版本范围： 0.8.2.x~3.3.1 。 请根据自己的 kafka 版本号参照下面的 kafka protocol version 规则进行配置。建议根据自己的 kafka  版本指定对应 protocol version ,  kafka protocol version 支持版本号如下：

0.8.2.0,0.8.2.1,0.8.2.2

0.9.0.0,0.9.0.1

0.10.0.0,0.10.0.1,0.10.1.0,0.10.1.1,0.10.2.0,0.10.2.1,0.10.2.2

0.11.0.0,0.11.0.1,0.11.0.2

1.0.0,1.0.1,1.0.2,1.1.0,1.1.1,

2.0.0,2.0.1,2.1.0,2.1.1,2.2.0,2.2.1,2.2.2,2.3.0,2.3.1,2.4.0,2.4.1,2.5.0,2.5.1,2.6.0,2.6.1,2.6.2,2.7.0,2.7.1,2.8.0,2.8.1,2.8.2

3.0.0,3.0.1,3.0.2,3.1.0,3.1.1,3.1.2,3.2.0,3.2.1,3.2.2,3.2.3,3.3.0,3.3.1,3.3.2,3.4.0,3.4.1,3.5.0,3.5.1,3.6.0

- Brokers 是个数组，多个 Broker 地址不能使用 ; 或者 , 来隔开放在一行里， yaml 配置文件中正确的多个 Broker 地址配置参考如下：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Topic: KafkaTestTopic

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到Kafka。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Topic: KafkaTestTopic

进阶配置

以下面的一段日志为例，后来将展开介绍ilogtail kafka flusher的一些高阶配置

2022-07-22 10:19:23.684 ERROR [springboot-docker] [http-nio-8080-exec-10] com.benchmark.springboot.controller.LogController : error log

以上面这行日志为例 , 我们通 ilogtail 的 processor_regex 插件，将上面的日志提取处理后几个关键字段：

- time

- loglevel

- appname

- thread

- class

- message

最后推送到 kafka 的数据样例如下：

{

"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

}

动态topic

针对上面写入的这种日志格式，如果想根据 application 名称针对不用的应用推送到不同的 topic ， 则 topic 可以这样配置。

Topic: test_%{content.application}

最后 ilogtail 就自动将日志推送到 test_springboot-docker 这个 topic 中。  topic 动态表达式规则：

- %{content.fieldname} 。 content 代表从 contents 中取指定字段值

- %{tag.fieldname} , tag 表示从 tags 中取指定字段值，例如： %{tag.k8s.namespace.name}

- ${env_name} , 读取系统变量绑定到动态 topic 上， ilogtail 1.5.0 开始支持。

- 其它方式暂不支持

动态topic中使用系统变量

动态 topic 绑定系统变量的两种场景：

- 将系统变量采集添加到日志的 tag 中，然后使用 %{tag.fieldname} 规则完成绑定。

- 对系统变量无采集存储需求，只是想根据设定的系统变量将日志推送到指定的 topic 中，直接采用 ${env_name}  规则完成绑定，此方式需要 1.5.0 才支持。

由于上面提到的两种系统变量的采集绑定都需要做一些特殊配置，因此下面将分别介绍下相关的配置操作。

（1）将系统变量采集到日志中完成动态 topic 绑定

将系统变量采集添加到日志中有两种方式，一种是在 ilogtail 容器 env 添加，另一种是通过 processor_add_fields  插件添加， 两种方式不同的配置参考下面的介绍

- 在 daemonset 或者 sidecar 方式部署的 ilogtail 容器 env 配置部分添加自定义的系统变量，配置参考案例如下：

env:

- name: ALIYUN_LOG_ENV_TAGS       # add log tags from env

value: _node_name_|_node_ip_|_app_name_

- name: _app_name_  # 添加自定义_app_name_变量，

value: kafka

自定义的变量 _app_name_ 被添加到 ALIYUN_LOG_ENV_TAGS 中，日志的 tags 中会看到自定义的变量， 此时动态  topic  采用 %{tag.fieldname} 规则配置即可。

- 使用 processor_add_fields  插件系统变量添加到日志中，配置参考如下：

processors:

- Type: processor_add_fields

Fields:

service: ${env_name}

IgnoreIfExist: false

这里 ${env_name} 生效依赖于 ilogtail 的 enable_env_ref_in_config 配置，从 ilogtail 1.5.0 开始支持。

（2）直接采用 $ 符将系统变量绑定动态 topic 中

在 daemonset 或者 sidecar 方式部署的 ilogtail 容器 env 配置部分添加自定义的系统变量，配置参考案例如下：

env:

- name: ALIYUN_LOG_ENV_TAGS       # add log tags from env

value: _node_name_|_node_ip_

- name: app_name  # 添加自定义app_name变量，

value: kafka

app_name 添加到系统变量中后，直接采用动态topic的： ${env_name} 规则即可绑定。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Topic: ilogtail_${app_name}

- ${app_name} 就是我们上面添加的系统变量。

TagFieldsRename

例如将 tags 中的 host.name 重命名为 hostname ，配置参考如下：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Convert:

TagFieldsRename:

host.name: hostname

Topic: KafkaTestTopic

ProtocolFieldsRename

对 ilogtail 协议字段重命名，在 ilogtail 的数据转换协议中， 最外层三个字段 contents , tags 和 time 属于协议字段。 ProtocolFieldsRename 只能对  contents , tags 和 time 这个三个字段进行重命名。 例如在使用 Elasticsearch 你可能想直接将 time 重命名为 @timestamp ，则配置参考如下：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Convert:

TagFieldsRename:

host.name: hostname

ProtocolFieldsRename:

time: '@timestamp'

Topic: KafkaTestTopic

指定分区分发

ilogtail 一共支持三种分区分发方式：

- random 随机分发, 默认。

- roundrobin 轮询分发。

- hash 分发。

random 和 roundrobin 分发只需要配置 PartitionerType 指定对应的分区分发方式即可。  hash 分发相对比较特殊，可以指定 HashKeys ， HashKeys 的中配置的字段名只能是 contents 中的字段属性。

配置用例：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

PartitionerType: hash

HashKeys:

- content.application

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Topic: KafkaTestTopic

- content.application 中表示从 contents 中取数据 application 字段数据，如果对 contents 协议字段做了重命名， 例如重名为 messege ，则应该配置为 messege.application

配置Headers

iLogtail 中 Kafka 的消息头是以键值对数组的形式配置的。 header 中 value 仅支持字符串类型。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Topic: KafkaTestTopic

Headers:

- key: "key1"

value: "value1"

- key: "key2"

value: "value2"

数据平铺

ilogtail 1.8.0 新增数据平铺协议 custom_single_flatten ， contents 、 tags 和 time 三个 convert 层的协议字段中数据做一级打平。 当前 convert 协议在单条数据处理仅支持 json 编码，因此 custom_single_flatten 需要配合 json 编码一起使用。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Convert:

Protocol: custom_single_flatten

Encoding: json

Topic: KafkaTestTopic

非平铺前写入 kafka 的消息格式

{

"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 全部被一级平铺。

{

"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

}

安全连接配置

flusher_kafka_v2 支持多种安全认证连接 kafka 服务端。

- PlainText 认证， ilogtail v1.3.0 开始支持;

- SASL 认证， ilogtail v1.3.0 开始支持;

- TLS 认证， ilogtail v1.4.0 开始支持;

- Kerberos 认证(待测试验证)， ilogtail v1.4.0 开始支持;

前面两种配置比较简单，下面主要介绍下 TLS 和 Kerberos 两种认证的配置。

TLS配置参考

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

PartitionerType: hash

HashKeys:

- content.application

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Authentication:

TLS:

Enabled: true

CAFile: /data/cert/ca.crt

CertFile: /data/cert/client.crt

KeyFile: /data/cert/client.key

MinVersion: "1.1"

MaxVersion: "1.2"

Topic: KafkaTestTopic

注: 配置仅供参考，证书文件请自行生成后根据事情情况配置。

Kerberos配置参考

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_kafka_v2

PartitionerType: hash

HashKeys:

- content.application

Brokers:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

- 192.XX.XX.3:9092

Authentication:

Kerberos:

ServiceName: kafka

Realm: test

UseKeyTab: true

ConfigPath: "/etc/krb5.conf"

KeyTabPath: "/etc/security/kafka.keytab"

Topic: KafkaTestTopic

ClickHouse

简介

flusher_clickhouse   flusher 插件可以实现将采集到的数据，经过处理后，发送到 ClickHouse，需要 ClickHouse 版本至少为  22.3 。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Addresses

String数组

是

ClickHouse 地址

Convert

Struct

否

ilogtail数据转换协议配置

Convert.Protocol

String

否

ilogtail数据转换协议，kafka flusher 可选值： custom_single , otlp_log_v1 。默认值： custom_single

Convert.Encoding

String

否

ilogtail flusher数据转换编码，可选值： json 、 none 、 protobuf ，默认值： json

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

ilogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

Authentication

Struct

是

Clickhouse 连接访问认证配置

Authentication.PlainText.Username

String

否

ClickHouse 用户名

Authentication.PlainText.Password

String

否

ClickHouse 密码

Authentication.PlainText.Database

String

是

插入数据目标数据库名称

Authentication.TLS.Enabled

Boolean

否

是否启用 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

Cluster

String

否

数据库对应集群名称

Table

String

是

插入数据目标 null engine 数据表名称

MaxExecutionTime

Int

否

单次请求最长执行时间，默认 60 秒

DialTimeout

String

否

Dial 超时时间，默认 10 秒

MaxOpenConns

Int

否

最大连接数，默认 5

MaxIdleConns

Int

否

连接池连接数，默认 5

ConnMaxLifetime

String

否

连接维持最大时长，默认 10 分钟

BufferNumLayers

Int

否

Buffer 缓冲区数量，默认 16

BufferMinTime

Int

否

缓冲区数据刷新限制条件 min_time，默认 10

BufferMaxTime

Int

否

缓冲区数据刷新限制条件 max_time，默认 100

BufferMinRows

Int

否

缓冲区数据刷新限制条件 min_rows，默认 10000

BufferMaxRows

Int

否

缓冲区数据刷新限制条件 max_rows，默认 1000000

BufferMinBytes

Int

否

缓冲区数据刷新限制条件 min_bytes，默认 10000000

BufferMaxBytes

Int

否

缓冲区数据刷新限制条件 max_bytes，默认 100000000

Compression

String

否

压缩方式，默认 lz4，可选 none/gzip/deflate/lz4/br/zstd

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到 ClickHouse。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_clickhouse

Addresses:

- 192.XX.XX.1:9092

- 192.XX.XX.2:9092

Authentication:

PlainText:

Database: default

Username: user

Password: 123456

Table: demo

ElasticSearch

简介

flusher_elasticsearch   flusher 插件可以实现将采集到的数据，经过处理后，发送到 ElasticSearch，需要 ElasticSearch 版本至少为  8 。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，固定为 flusher_elasticsearch

Addresses

String数组

是

ElasticSearch 地址

Convert

Struct

否

ilogtail数据转换协议配置

Convert.Protocol

String

否

ilogtail数据转换协议，elasticsearch flusher 可选值： custom_single , custom_single_flatten , otlp_log_v1 。默认值： custom_single

Convert.Encoding

String

否

ilogtail flusher数据转换编码，可选值： json 、 none 、 protobuf ，默认值： json

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

ilogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

Index

String

是

插入数据目标索引

Authentication

Struct

是

ElasticSearch 连接访问认证配置

Authentication.PlainText.Username

String

是

ElasticSearch 用户名

Authentication.PlainText.Password

String

是

ElasticSearch 密码

Authentication.TLS.Enabled

Boolean

否

是否启用 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

样例

常规索引

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到 ElasticSearch。

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 ），更多关于动态索引格式化的信息请参考这里

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

数据平铺写入

ilogtail 1.8.0 新增数据平铺协议 custom_single_flatten ， contents 、 tags 和 time 三个 convert 层的协议字段中数据做一级打平。 当前 convert 协议在单条数据处理仅支持 json 编码，因此 custom_single_flatten 需要配合 json 编码一起使用。

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 的数据格式

{

"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 全部被一级平铺。

{

"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

}

SLS

简介

flusher_sls   flusher 插件将采集到的事件发送至SLS。

使用本插件时，必须在启动参数中配置AK和SK。

版本

Stable

配置参数

参数

类型

是否必填

默认值

说明

Type

string

是

/

插件类型。固定为flusher_sls。

Project

string

是

/

Project名称。

Logstore

stirng

是

/

LogStrore名称。

Region

string

是

/

Project所在区域。

Endpoint

string

是

/

SLS接入点地址  。

Match

map

否

/

发送路由，当pipeline event group的属性满足指定的条件时，该group才会发送到当前flusher。如果该字段为空，则表示所有group均会发送到当前flusher。具体参数详见路由  。

安全性说明

flusher_sls  默认使用  HTTPS  协议发送数据到  SLS ，也可以使用data_server_port参数更改发送协议。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到SLS。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_sls

Region: cn-hangzhou

Endpoint: cn-hangzhou.log.aliyuncs.com

Project: test_project

Logstore: test_logstore

标准输出/文件

简介

flusher_stdout   flusher 插件可以实现将采集到的数据，经过处理后，打印到标准输出或者自定义文件。

支持的Event类型

LogGroup(v1)

EventTypeLogging

EventTypeMetric

EventTypeSpan

✅

✅

✅

✅

版本

Stable

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

OnlyStdout

Boolean

否

是否打印打印到标准输出。true表示标准输出；false表示文件。

FileName

String

否

打印到文件时，需指定文件名。

MaxSize

Int

否

打印到文件时，需指定单个文件大小。默认1M。

MaxRolls

Int

否

打印到文件时，需指定文件的轮转个数。默认为1。

KeyValuePairs

Boolean

否

Tags

Boolean

否

打印  __tag__   ，默认false。如果将flusher-stdout用于调试，建议设置为true。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果打印到标准输出。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_stdout

OnlyStdout: true

Tags: true

OTLP Log

简介

flusher_otlp   flusher 插件可以实现将采集到的数据，经过处理后，发送到支持 Opentelemetry Protocol 的后端。 v1流水线目前只支持Logs数据，v2流水线支持Logs/Metrics/Traces三种数据。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

Version

String

否

otlp 协议默认，默认为 v1

Logs

Struct

否

Logs gRPC 配置项

Logs.Endpoint

String

否

Logs gRPC Server 地址

Logs.Compression

String

否

Logs gRPC 数据压缩协议，可选 gzip、snappy、zstd。默认为 nono

Logs.Headers

String数组

否

Logs gRPC 自定义 Headers

Logs.Timeout

int

否

Logs gRPC 连接超时时间，单位为ms，默认为5000

Logs.WaitForReady

bool

否

Logs gRPC 数据发送前是否等待就绪, 默认为false

Metrics

Struct

否

Metrics gRPC 配置项

Metrics.Endpoint

String

否

Metrics gRPC Server 地址

Metrics.Compression

String

否

Metrics gRPC 数据压缩协议，可选 gzip、snappy、zstd。默认为 nono

Metrics.Headers

String数组

否

Metrics gRPC 自定义 Headers

Metrics.Timeout

int

否

Metrics gRPC 连接超时时间，单位为ms，默认为5000

Metrics.WaitForReady

bool

否

Metrics gRPC 数据发送前是否等待就绪, 默认为false

Traces

Struct

否

Traces gRPC 配置项

Traces.Endpoint

String

否

Traces gRPC Server 地址

Traces.Compression

String

否

Traces gRPC 数据压缩协议，可选 gzip、snappy、zstd。默认为 nono

Traces.Headers

String数组

否

Traces gRPC 自定义 Headers

Traces.Timeout

int

否

Traces gRPC 连接超时时间，单位为ms，默认为5000

Traces.WaitForReady

bool

否

Traces gRPC 数据发送前是否等待就绪, 默认为false

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到  Opentelemetry  Log后端。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_otlp

Logs:

Endpoint: http://192.168.xx.xx:8176

Headers:

X-AppKey: 8bc8f787-b0b2-4f26-89c6-d3950a090fef

Retry:

MaxCount: 3

v2 Pipeline

监听4316端口的 Opentelemetry 的gRPC请求，并将采集结果发送到  Opentelemetry  后端。其中Logs发送到http://192.168.xx.xx:4317，Metrics发送到http://192.168.xx.xx:4319，Traces不发送。

enable: true

version: v2

inputs:

- Type: service_otlp

Protocals:

GRPC:

Endpoint: 0.0.0.0:4316

flushers:

- Type: flusher_otlp

Logs:

Endpoint: http://192.168.xx.xx:4317

Metrics:

Endpoint: http://192.168.xx.xx:4319

监听4316端口的 Opentelemetry 的gRPC请求，并将采集结果发送到  Opentelemetry  后端。Logs、Metrics、Traces发送到不同的后端。

enable: true

version: v2

inputs:

- Type: service_otlp

Protocals:

GRPC:

Endpoint: 0.0.0.0:4316

flushers:

- Type: flusher_otlp

Logs:

Endpoint: 0.0.0.0:4318

Metrics:

Endpoint: 0.0.0.0:4319

Traces:

Endpoint: 0.0.0.0:4320

Pulsar

简介

flusher_pulsar   flusher 插件可以实现将采集到的数据，经过处理后，发送到 Pulsar 。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

Url

String

是

Pulsar url,多地址用逗号分隔，可以参考本文中的用例配置

Topic

String

是

Pulsar Topic,支持动态topic, 例如:  test_%{contents.appname}

Name

String

否

producer名称，默认ilogtail

Convert

Struct

否

ilogtail数据转换协议配置

Convert.Protocol

String

否

ilogtail数据转换协议，kafka flusher 可选值： custom_single , custom_single_flatten , otlp_log_v1 。默认值： custom_single

Convert.Encoding

String

否

ilogtail flusher数据转换编码，可选值： json 、 none 、 protobuf ，默认值： json

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

ilogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

EnableTLS

Boolean

否

是否启用TLS安全连接，对应采用TLS和Athenz两种认证模式都需要设置为true，默认值： false

TLSTrustCertsFilePath

String

否

TLS CA根证书文件路径，对应采用TLS和Athenz认证时需要指定

Authentication

Struct

否

Pulsar连接访问认证配置

Authentication.TLS.CertFile

String

否

TLS连接 Pulsar   证书文件路径

Authentication.TLS.KeyFile

String

否

TLS连接 Pulsar   私钥文件路径

Authentication.Token.Token

String

否

采用JWT 认证方式的token

Authentication.Athenz.ProviderDomain

String

否

Provider domain name

Authentication.Athenz.TenantDomain

String

否

租户域

Authentication.Athenz.TenantService

String

否

租户服务

Authentication.Athenz.PrivateKey

String

否

Tenant private key path

Authentication.Athenz.KeyID

String

否

Key id for the tenant private key

Authentication.Athenz.PrincipalHeader

String

否

Authentication.Athenz.ZtsURL

String

否

ZTS server的地址

Authentication.OAuth2.Enabled

Boolean

否

是否启用OAuth2认证

Authentication.OAuth2.IssuerURL

String

是

认证提供商的URL，OAuth2.Enabled开启时必填

Authentication.OAuth2.PrivateKey

String

是

JSON 凭据文件的 URL，OAuth2.Enabled开启时必填

Authentication.OAuth2.Audience

String

否

Pulsar 集群的 OAuth 2.0 “资源服务” 的标识符

Authentication.OAuth2.Scope

String

否

访问范围

CompressionType

String

否

压缩算法， NONE,LZ4,ZLIB,ZSTD ，默认值 NONE

BlockIfQueueFull

Boolean

否

队列满的时候是否阻塞，默认值: false

SendTimeout

Int

否

发送超时时间，默认 30s

OperationTimeout

Int

否

pulsar producer创建、订阅、取消订阅的超时时间，默认 30s

ConnectionTimeout

Int

否

tcp连接建立超时时间，默认 5s

MaxConnectionsPerBroker

Int

否

单个broker连接池保持的连接数，默认 1

MaxReconnectToBroker

Int

否

重连broker的最大重试次数，默认为无限

HashingScheme

Int

否

消息push分区的分发方式： JavaStringHash , Murmur3_32Hash ,默认值： JavaStringHash

BatchingMaxPublishDelay

int

否

提交时延，默认值： 1ms

BatchingMaxMessages

int

否

批量提交最大消息数，默认值： 1000

MaxCacheProducers

int

否

动态topic情况下最大Producer数量 ，默认最大数量：8,使用动态topic的使用可以根据自己的情况调整。

PartitionKeys

String数组

否

指定消息分区分发的key。

ClientID

String

否

写入Pulsar的Client ID，默认取值： iLogtail   。

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到Pulsar。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Topic: PulsarTestTopic

进阶配置

以下面的一段日志为例，后来将展开介绍ilogtail pulsar flusher的一些高阶配置

2022-07-22 10:19:23.684 ERROR [springboot-docker] [http-nio-8080-exec-10] com.benchmark.springboot.controller.LogController : error log

以上面这行日志为例 , 我们通 ilogtail 的 processor_regex 插件，将上面的日志提取处理后几个关键字段：

- time

- loglevel

- appname

- thread

- class

- message

最后推送到 kafka 的数据样例如下：

{

"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

}

动态topic

针对上面写入的这种日志格式，如果想根据 application 名称针对不用的应用推送到不通的 topic ， 则 topic 可以这样配置。

Topic: test_%{content.application}

最后 ilogtail 就自动将日志推送到 test_springboot-docker 这个 topic 中。

topic 动态表达式规则：

- %{content.fieldname} 。 content 代表从 contents 中取指定字段值

- %{tag.fieldname} , tag 表示从 tags 中取指定字段值，例如： %{tag.k8s.namespace.name}

- ${env_name} , 读取系统变量绑定到动态 topic 上， ilogtail 1.5.0 开始支持。可以参考 flusher-kafka_v2 中的使用。

- 其它方式暂不支持

TagFieldsRename

例如将 tags 中的 host.name 重命名为 hostname ，配置参考如下：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Convert:

TagFieldsRename:

host.name: hostname

Topic: PulsarTestTopic

ProtocolFieldsRename

对 ilogtail 协议字段重命名，在 ilogtail 的数据转换协议中， 最外层三个字段 contents , tags 和 time 属于协议字段。 ProtocolFieldsRename 只能对  contents , tags 和 time 这个三个字段进行重命名。 例如在使用 Elasticsearch 你可能想直接将 time 重命名为 @timestamp ，则配置参考如下：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Convert:

TagFieldsRename:

host.name: hostname

ProtocolFieldsRename:

time: '@timestamp'

Topic: PulsarTestTopic

指定分区分发

ilogtail flusher pulsar 使用的官方 SDK 只支持 hash 方式分区投递，通过 HashingScheme 来选择不同的 hash 算法。 分发是可以指定 PartitionKeys ， PartitionKeys 的中配置的字段名只能是 contents 中的字段属性。

配置用例：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

PartitionKeys:

- content.application

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Topic: PulsarTestTopic

- content.application 中表示从 contents 中取数据 application 字段数据，如果对 contents 协议字段做了重命名， 例如重名为 messege ，则应该配置为 messege.application

数据平铺

ilogtail 1.8.0 新增数据平铺协议 custom_single_flatten ， contents 、 tags 和 time 三个 convert 层的协议字段中数据做一级打平。 当前 convert 协议在单条数据处理仅支持 json 编码，因此 custom_single_flatten 需要配合 json 编码一起使用。

配置用例：

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

Convert:

Protocol: custom_single_flatten

Encoding: json

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Topic: PulsarTestTopic

非平铺前写入 pulsar 的消息格式

{

"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 全部被一级平铺。

{

"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

}

安全连接配置

flusher_pulsar 支持多种安全认证连接 pulsar 服务端。

- TLS 认证;

- Token JWT Token认证;

- Athenz  pulsar租户域认证;

- OAuth2 认证；

JWT Token认证配置比较简单，参照前面的配置表配置即可，下面主要介绍下 OAuth2 , TLS 和 Athenz 两种认证的配置。

OAuth2认证配置参考(待验证)

下面配置仅供参考，请根据服务器实际部署情况配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar://192.168.6.128:6650,192.168.6.129:6650,192.168.6.130:6650"

Authentication:

OAuth2:

Enabled: true

IssuerURL: https://accounts.google.com

PrivateKey: file:/path/to/file/credentials_file.json

Audience: https://broker.example.com

Scope: api://pulsar-cluster-1/.default

Topic: PulsarTestTopic

credentials_file.json配置内容样例

{

"type": "client_credentials",

"client_id": "d9ZyX97q1ef8Cr81WHVC4hFQ64vSlDK3",

"client_secret": "on1uJ...k6F6R",

"client_email": "1234567890-abcdefghijklmnopqrstuvwxyz@developer.gserviceaccount.com",

"issuer_url": "https://accounts.google.com"

}

TLS配置参考(待验证)

下面配置仅供参考，请根据服务器实际部署情况配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar+ssl://192.168.6.128:6651,192.168.6.129:6651,192.168.6.130:6651"

EnableTLS: true

TLSTrustCertsFilePath: /data/cert/ca.crt

Authentication:

TLS:

CertFile: /data/cert/client.crt

KeyFile: /data/cert/client.key

Topic: PulsarTestTopic

- EnableTLS  如果要启用 TLS 必须设置为 true 。开始 TLS 的情况下，URL头部为 pulsar+ssl://

- TLSTrustCertsFilePath 根证书需要设置。 注: 配置仅供参考，证书文件请自行生成后根据事情情况配置。

Athenz认证配置参考(待验证)

下面配置仅供参考，请根据服务器实际部署情况配置

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_pulsar

URL: "pulsar+ssl://192.168.6.128:6651,192.168.6.129:6651,192.168.6.130:6651"

EnableTLS: true

TLSTrustCertsFilePath: /data/cert/ca.crt

Authentication:

Athenz:

ProviderDomain: pulsar

TenantDomain: shopping

TenantService: some_app

PrivateKey: file:///path/to/client-key.pem

KeyID: v1

Topic: PulsarTestTopic

- EnableTLS  如果要启用 Athenz 认证必须设置为 true 。开始 TLS 的情况下， URL 头部为 pulsar+ssl://

- TLSTrustCertsFilePath 根证书需要设置。

标准输出/文件

简介

flusher_http   flusher 插件可以实现将采集到的数据，经过处理后，通过http格式发送到指定的地址。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型，固定为 flusher_http

RemoteURL

String

是

要发送到的URL地址，示例： http://localhost:8086/write

Headers

Map

否

发送时附加的http请求header，如可添加 Authorization、Content-Type等信息，支持动态变量写法，如 {"x-db":"%{tag.db}"}
v2版本支持从Group的Metadata或者Group.Tags中获取动态变量，如`{"x-db":"%{metadata.db}"}`或者`{"x-db":"%{tag.db}"}`

Query

Map

否

发送时附加到url上的query参数，支持动态变量写法，如 {"db":"%{tag.db}"}
v2版本支持从Group的Metadata或者Group.Tags中获取动态变量，如`{"db":"%{metadata.db}"}`或者`{"db":"%{tag.db}"}`

Timeout

String

否

请求的超时时间，默认  60s

Retry.Enable

Boolean

否

是否开启失败重试，默认为  true

Retry.MaxRetryTimes

Int

否

最大重试次数，默认为  3

Retry.InitialDelay

String

否

首次重试时间间隔，默认为  1s   ，重试间隔以会2的倍数递增

Retry.MaxDelay

String

否

最大重试时间间隔，默认为  30s

Convert

Struct

否

ilogtail数据转换协议配置

Convert.Protocol

String

否

ilogtail数据转换协议，可选值： custom_single , influxdb ,  jsonline 。默认值： custom_single
v2版本可选值：`raw`

Convert.Encoding

String

否

ilogtail flusher数据转换编码，可选值： json ,  custom ，默认值： json

Convert.Separator

String

否

ilogtail数据转换时，PipelineGroupEvents中多个Events之间拼接使用的分隔符。如 \n 。若不设置，则默认不拼接Events，即每个Event作为独立请求向后发送。 默认值为空。
当前仅在`Convert.Protocol: raw`有效。

Convert.IgnoreUnExpectedData

Boolean

否

ilogtail数据转换时，遇到非预期的数据的行为，true 跳过，false 报错。默认值 true

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

ilogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

Concurrency

Int

否

向url发起请求的并发数，默认为 1

QueueCapacity

Int

否

内部channel的缓存大小，默认为1024

AsyncIntercept

Boolean

否

异步过滤数据，默认为否

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果以  custom_single  协议、 json 格式提交到  http://localhost:8086/write 。 且提交时，附加 header x-filepath，其值使用log中的 Tag:path 的值

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write"

Headers:

x-filepath: "%{tag.__path__}"

Convert:

Protocol: custom_single

Encoding: json

采集Docker日志，并将采集结果以 jsonline 协议发送到 http://localhost:9428/insert/jsonline 。

enable: true

inputs:

- Type: service_docker_stdout

Stderr: true

Stdout: true

processors:

- Type: processor_json

SourceKey: content

KeepSource: true

ExpandDepth: 1

ExpandConnector: ""

KeepSourceIfParseError: true

flushers:

- Type: flusher_http

RemoteURL: http://localhsot:9428/insert/jsonline

QueueCapacity: 64

Convert:

Protocol: jsonline

Encoding: json

需要注意的是，由于使用 jsonline 协议（会将日志的content和tag打平），所以仅支持使用 json 格式进行提交。 由于 jsonline 默认会批量提交日志，所以建议调低 QueueCapacity ，避免在日志量较大的情况下，发生内存占用过多或OOM的问题。

Loki

简介

flusher_loki   flusher 插件可以实现将采集到的数据，经过处理后，发送到 Loki。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Type

String

是

插件类型

Convert

Struct

否

ilogtail数据转换协议配置

Convert.Protocol

String

否

ilogtail数据转换协议，可选值： custom_single ,  custom_single_flatten , otlp_log_v1 。默认值： custom_single

Convert.Encoding

String

否

ilogtail数据转换编码，可选值： json 、 none 、 protobuf ，默认值： json

Convert.TagFieldsRename

Map

否

对日志中tags中的json字段重命名

Convert.ProtocolFieldsRename

Map

否

ilogtail日志协议字段重命名，可当前可重命名的字段： contents , tags 和 time

Convert.OnlyContents

Bool

否

仅发送contents中的字段，目前只能和 custom_single_flatten 协议一起使用，默认值： false

URL

String

是

Loki 推送地址，例如： http://localhost:3100/loki/api/v1/push

TenantID

String

否

Loki 的租户 ID（需要 Loki 开启该功能），默认为空，表示单租户模式

MaxMessageWait

Int

否

发送 batch 前的最长等待时间，默认  1    秒

MaxMessageBytes

Int

否

发送积累的最大的 batch 大小，默认  1024 * 1024    bytes

Timeout

Int

否

等待 Loki 响应的最大时间，默认  10    秒

MinBackoff

Int

否

重试之间的最短退避时间，默认  500   毫秒

MaxBackoff

Int

否

重试的最长退避时间，默认  5   分钟

MaxRetries

Int

否

最大重试次数，默认  10

DynamicLabels

String数组

两种Label至少选择一项

需要从日志中动态解析的标签列表，例如： content.field1

StaticLabels

Map

两种Label至少选择一项

需要添加到每条日志上的静态标签

样例

本样例采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果发送到 Loki。在执行该任务之前，需要确保系统已经安装了Loki。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_loki

URL: http://<loki 服务的地址与端口>/loki/api/v1/push

TenantID: ilogtail

MaxMessageWait: 100000000

MaxMessageBytes: 16

Timeout: 1000000000000

MinBackoff: 100000000000

MaxBackoff: 1000000000000

MaxRetries: 10

StaticLabels:

source: ilogtail

运行  ilogtail  并收集到日志后，在  Grafana  或  Logcli  中可以通过以下的命令查询日志：

{ source="ilogtail" }

进阶配置

以下面的一段日志为例，后来将展开介绍ilogtail loki flusher的一些高阶配置

2022-07-22 10:19:23.684 ERROR [springboot-docker] [http-nio-8080-exec-10] com.benchmark.springboot.controller.LogController : error log

接下来，我们通过 ilogtail 的 processor_regex 插件，将上面的日志提取处理后几个关键字段。

- time

- level

- application

- thread

- class

- message

最后推送到 Loki 的数据样例如下：

{

"contents": {

"class": "org.springframework.web.servlet.DispatcherServlet@initServletBean:547",

"application": "springboot-docker",

"level": "ERROR",

"message": "error log",

"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": "/home/test-log/test.log"

},

"time": 1664435098

}

动态 Label

针对上面写入的这种日志格式，如果想在 Loki 中根据 application 名称进行查询，那么需要进行如下的配置。

DynamicLabels:

- content.application

flusher_loki  会将去除前缀后的字符串作为存入 Loki 的 label。之后，在 Loki 中即可以  {application="springboot-docker"}  进行查询。  DynamicLabels  表达式规则：

- content.fieldname ： content  代表从  contents  中解析指定字段值。

- tag.fieldname ： tag  代表从  tags  中解析指定字段值。

tag 重命名

ilogtail  中的  converter  支持通过配置对  tags  中的字段进行重命名。在 flusher_loki 中进行如下的配置，即可对存入 Loki 中动态 label 进行重命名：

flushers:

- Type: flusher_loki

URL: http://<loki 服务的地址与端口>/loki/api/v1/push

DynamicLabels:

- tag.my.host.name

Convert:

TagFieldsRename:

host.name: my.host.name

之后在 Loki 中进行查询时，可以通过重命名后的 label，  {my.host.name="master"}  进行查询。

扩展

扩展插件用于对其它插件能力的补充（e.g. 鉴权、编解码、熔断、限流……）

BasicAuth认证扩展

简介

ext_basicauth  扩展插件，实现了 extensions.ClientAuthenticator 接口，可以在 http_flusher 插件中引用，提供向请求中添加 basic auth Header 的能力。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Username

String

是

用户名

Password

String

是

密码

样例

采集 /home/test-log/ 路径下的所有文件名匹配 *.log 规则的文件，并将采集结果以  custom_single  协议、 json 格式提交到  http://localhost:8086/write 。 且提交时，使用 basic auth 认证扩展。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write"

Convert:

Protocol: custom_single

Encoding: json

Authenticator:

Type: ext_basicauth

extensions:

- Type: ext_basicauth

Username: user1

Password: pwd1

使用命名扩展

当希望在同一个pipeline中使用多个扩展时，可一给同一类型的不同扩展实例附加一个命名，引用时可以通过full-name来引用特定的实例。

如下示例，通过将 Type: ext_basicauth  改写为  Type: ext_basicauth/user1 ，追加命名为 user1 ，在 http_flusher插件中通过  ext_basicauth/user1 来引用。

enable: true

inputs:

- Type: input_file

FilePaths:

- /home/test-log/*.log

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write"

Convert:

Protocol: custom_single

Encoding: json

Authenticator:

Type: ext_basicauth/user1

extensions:

- Type: ext_basicauth/user1

Username: user1

Password: pwd1

- Type: ext_basicauth/user2

Username: user2

Password: pwd2

DefaultDecoder Decoder扩展

简介

ext_default_decoder 扩展，实现了 Decoder 接口，可以用在  service_http_server 、 udp_server  等插件中用于解析不同的协议数据。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Format

String

是

具体的协议，查看支持的具体协议列表

FieldsExtend

Boolean

否

是否启用增强字段功能，默认为false，仅针对Format=influxdb时有效

DisableUncompress

Boolean

是

否不解压数据，默认为false，仅针对Format=raw时有效

样例

使用  service_http_server  input 插件，配置接收  influxdb  协议数据。

enable: true

inputs:

- Type: service_http_server

Address: ":18888"

Format: influxdb

Decoder: ext_default_decoder

flushers:

- Type: flusher_stdout

OnlyStdout: true

使用如下命令测试：

curl http://localhost:18888/write?db=mydb --data-binary 'weather,city=hz value=34'

DefaultEncoder Encoder扩展

简介

ext_default_encoder 扩展，实现了 Encoder 接口，可以用在  flusher_http  等插件中用于序列化不同的协议数据。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Format

String

是

具体的协议，查看支持的具体协议列表

SeriesLimit

Int

否

触发序列化时序切片的最大长度，默认 1000，仅针对 Format=prometheus 时有效

样例

使用  flusher_http  flusher 插件，配置发送  prometheus  协议数据。

enable: true

flushers:

- Type: flusher_http

...

Encoder:

Type: ext_default_encoder/prometheus

...

...

extensions:

- Type: ext_default_encoder/prometheus

Format: 'prometheus'

SeriesLimit: 1024

GroupInfoFilter FlushInterceptor 扩展

简介

ext_groupinfo_filter  扩展插件，实现了 extensions.FlushInterceptor 接口，可以在 http_flusher 插件中引用，提供在向远端最终提交前筛选数据的能力。

版本

Alpha

配置参数

参数

类型

是否必选

说明

Tags

Map

否

需要过滤的GroupInfo.Tags的 key,value

Metas

Map

否

需要过滤的GroupInfo.Metadata的 key,value

其中，Condition 的字段结构如下：

字段

类型

是否必填

说明

Pattern

String

是

匹配正则表达式

Reverse

Boolean

否

是否反向选择，即选择不匹配 Pattern 的数据

样例

使用  metric_mock  input 插件生成数据，并将采集结果以  custom_single  协议、 json 格式提交到  http://localhost:8086/write 。

且在flusher处理时，仅选择GroupInfo的Tags中包含  tag1=tag1  的数据发送

enable: true

version: v2

inputs:

- Type: metric_mock

GroupMeta:

meta1: meta1

GroupTags:

tag1: tag1

- Type: metric_mock

GroupMeta:

meta2: meta2

GroupTags:

tag2: tag2

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write"

Convert:

Protocol: custom_single

Encoding: json

FlushInterceptor:

Type: ext_groupinfo_filter

extensions:

- Type: ext_groupinfo_filter

Tags:

tag1:

Pattern: tag1

使用命名扩展

当希望在同一个pipeline中使用多个扩展时，可一给同一类型的不同扩展实例附加一个命名，引用时可以通过full-name来引用特定的实例。

如下示例，通过将 Type: ext_groupinfo_filter  改写为  Type: ext_groupinfo_filter/tag1 ，追加命名 tag1 ，在 http_flusher插件中通过  ext_groupinfo_filter/tag1 来引用。

enable: true

version: v2

inputs:

- Type: metric_mock

GroupMeta:

meta1: meta1

GroupTags:

tag1: tag1

- Type: metric_mock

GroupMeta:

meta2: meta2

GroupTags:

tag2: tag2

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write_select_tag1"

Convert:

Protocol: custom_single

Encoding: json

FlushInterceptor:

Type: ext_groupinfo_filter/tag1

- Type: flusher_http

RemoteURL: "http://localhost:8086/write_select_tag2"

Convert:

Protocol: custom_single

Encoding: json

FlushInterceptor:

Type: ext_groupinfo_filter/tag2

extensions:

- Type: ext_groupinfo_filter/tag1

Tags:

tag1:

Pattern: tag1

- Type: ext_groupinfo_filter/tag2

Tags:

tag2:

Pattern: tag2

RequestBreaker 请求拦截扩展

简介

ext_request_breaker  扩展插件，实现了 extensions.RequestInterceptor 接口，课题在 http_flusher 插件中引用，提供请求熔断的能力。

版本

Alpha

配置参数

参数

类型

是否必选

说明

FailureRatio

Float

是

熔断的阈值，失败的请求在 WindowInSeconds 窗口时间内的失败率，默认值 0.10

WindowInSeconds

Int

是

统计请求成功失败的窗口时间，默认值 10

样例

使用  metric_mock  input 插件生成数据，并将采集结果以  custom_single  协议、 json 格式提交到  http://localhost:8086/write 。

且在flusher处理时，配置熔断策略

enable: true

version: v2

inputs:

- Type: metric_mock

GroupMeta:

meta1: meta1

GroupTags:

tag1: tag1

- Type: metric_mock

GroupMeta:

meta2: meta2

GroupTags:

tag2: tag2

flushers:

- Type: flusher_http

RemoteURL: "http://localhost:8086/write"

Convert:

Protocol: custom_single

Encoding: json

RequestInterceptors:

- Type: ext_request_breaker

FailureRatio: 0.1

WindowInSeconds: 10

extensions:

- Type: ext_groupinfo_filter

Tags:

tag1: tag1

文件发现

Good to know: depending on the product you're building, it can be useful to explicitly document use cases. Got a product that can be used by a bunch of people in different ways? Maybe consider splitting it out!

插件系统

背景

作为日志服务的采集 Agent，iLogtail 目前已运行于 100W+ 机器上，为万级别的应用提供服务，为了能够更好地实现与开源生态的融合并满足用户不断丰富的接入需求，我们为 iLogtail 引入了插件系统，目前，我们已通过插件系统支持了若干数据源，包括 HTTP、MySQL Query、MySQL Binlog 等。

本文将对 iLogtail 插件系统进行简要介绍，包括插件系统的实现原理、插件系统的组成及设计。

实现原理

本节我们以如下流程图来说明 iLogtail 插件系统的实现原理。

为了支持插件系统，我们引入了 libPluginAdaptor 和 libPluginBase（以下简称 adaptor 和 base）这两个动态库，它们与 iLogtail 之间的关系如下：

- iLogtail 动态依赖于这两个动态库（即 binary 中不依赖），在初始化时，iLogtail 会尝试使用动态库接口（如 dlopen）动态加载它们，获取所需的符号。这种设计的好处在于：即使动态加载失败，也仅仅是插件功能不可用，不影响 iLogtail 本身已有的功能。

- Adaptor 充当一个中间层，iLogtail 和 base 均依赖它，iLogtail 首先注册回调，adpator 将这些回调记录下来，以接口的形式暴露给 base 使用。这间接构成了 base 调用 iLogtail 方法，从而 base 不会依赖 iLogtail。这些回调中的一个关键方法为 SendPb，base 可以通过它将数据添加到 iLogtail 的发送队列，进而递交给 LogHub。

- Base 是插件系统的主体，它包含插件系统所必须的采集、处理、聚合以及输出（向 iLogtail 递交可以视为其中一种）等功能。因此，对插件系统的扩展实质上是对 base 的扩展。 回到流程图，我们来简要说明下其中的各个步骤：

- iLogtail 初始化阶段，动态加载 adaptor，并通过得到的符号注册回调。

- iLogtail 初始化阶段，动态加载 base，获取符号，包括本流程中所用到的 LoadConfig 符号。Base 在 binary 上依赖了 adaptor，所以这一步它会加载 adaptor。

- iLogtail 从 LogHub 处获取用户的配置（插件类型）。

- iLogtail 通过 LoadConfig 将配置传递给 base。

- Base 应用配置并启动配置，从指定的数据源获取数据。

- Base 调用 adaptor 提供的接口来进行数据递交。

- Adaptor 将 base 递交的数据通过回调直接交给 iLogtail。

- iLogtail 将数据加入发送队列，发送到 LogHub。

系统组成及设计

本节我们将聚焦于 libPluginBase，对插件系统的整体架构以及一些系统设计进行介绍。

整体架构

如上图所示，插件系统目前的主体由 Input、Processor、Aggregator 和 Flusher 四部分组成，针对每一个配置，它们之间的关系：

- Input: 作为输入层，一个配置可以同时配置多个 input，它们可以同时工作，采集所得到的数据将递交给 processor。

- Processor: 作为处理层，可以对输入的数据进行过滤，比如检查特定字段是否符合要求或是对字段进行增删改。每一个配置可以同时配置多个 processor，它们之间采用串行结构，即上一个 processor 的输出作为下一个 processor 的输入，最后一个 processor 的输出会传递到 aggregator。

- Aggregator: 作为聚合层，可以将数据按照需要的形式进行聚合，比如将多个数据打包成组、统计数据中某些字段的最大值最小值等。类似 input，一个配置可以同时配置多个 aggregator 来实现不同目的。Aggregator 可以在新数据到来时主动地将处理后数据递交给 flusher，也可以设置一个刷新间隔，周期性地将数据递交给 flusher。

- Flusher: 作为输出层，将数据按照配置输出到指定的目标，比如本地文件、iLogtail（通过 adaptor 的接口）等。一个配置可以同时配置多个 flusher，从而一份数据可以同时输出到多个目标。 除此以外，插件系统还提供了 Checkpoint、Statistics 和 Alarm 三部分内容，分别负责提供检查点、统计以及报警相关的功能，我们将它们进行了整体封装，以 context 的形式提供给所有插件，插件仅需调用 context 提供的接口（比如创建检查点、加载检查点、发送 Alarm 等），无需关心如何完成。对于这些功能，我们将在后文中进行介绍。

系统设计

下面我们将简单地介绍插件系统中的几点关键设计，这其中包含了一些我们在设计之初时的目标：

易扩展、易开发：使用 Go 语言实现 兼容 iLogtail 现有体系，降低用户学习成本：配置动态更新、统一 Alarm / Statistics 为插件开发提供通用功能：Checkpoint

使用 Go 语言实现

为了达到易扩展、易开发的目标，我们最终选择 Go 作为插件系统的实现语言，具体考虑的因素有以下几点：

- 并发隔离：在生产环境中，iLogtail 可能会同时运行多个插件来满足不同的采集需求，不同插件之间的隔离和并发是必须解决的问题。Go 语言面向并发程序的设计使得我们能够较为简单地实现隔离和并发的需求，从而在开发 iLogtail 插件时，开发者可以更关注于自身逻辑，而无需关心系统整体。

- 动态加载：由于 iLogtail 已经有不小的装机量，使用动态加载来尽可能隔离插件系统，降低对 iLogtail 主体的影响也是我们考虑的因素之一。Go 原生支持生成为动态库可以很好地满足我们的需求。

- 贴近社区：目前 Telegraf 以及 Beats 这两个开源 Agent 均采用 Go 实现，因而使用 Go 能够使得我们的插件系统更加贴近社区，降低社区开发者的学习难度。

- Go plugin：我们也在观望着 Go plugin 的进展，一旦觉得时机成熟，通过 Go plugin 来实现完全地动态扩展将能够更好地为用户提供助力。

- 易开发：Go 语言的开发效率在一般情况下都高于 iLogtail 所采用的 C++，更适合插件这类需要快速开发的场景。

动态更新配置

目前，日志服务支持通过控制台进行采集配置，然后自动下发到 iLogtail 进行应用执行，当配置发生变化时，iLogtail 也会及时地获取这些配置并进行动态更新。插件系统作为配置内容的一部分，同样要具有这种动态更新配置的能力。

在插件系统中，我们以配置为单位对插件进行了组织，每个配置实例根据配置的具体内容，创建并维护其中的 input、processor 等插件的实例。为了实现这种动态更新配置的能力，libPluginBase 提供了相应的 HoldOn/Resume/LoadConfig 接口进行支持，更新流程如下：

1. iLogtail 检查配置更新的内容是否有关于插件系统的更新，如果有，调用 HoldOn 暂停插件系统；

2. 插件系统执行 HoldOn 时，会依次停止当前的所有配置实例，这个过程中会存储必要的检查点数据；

3. 在 HoldOn 调用完毕后，iLogtail 通过 LoadConfig 加载发生更新或者新增的配置，这个调用会在插件系统内创建新的配置实例，新实例会覆盖之前的实例。 此处为了避免数据的丢失，新创建的实例会将被覆盖的实例中的数据进行转移过来，从而在恢复后能够继续处理这些数据；

4. 当配置更新完毕后，iLogtail 调用 Resume 恢复插件系统的运行，动态更新配置完毕。

统一 Statistics、Alarm

在 iLogtail 中，为了更好地帮助用户进行统计数据分析和问题排查，我们实现了 Statistics 和 Alarm 机制。插件系统同样会有这样的需求（每一个插件在运行期间都可能会产生各自的统计或报警数据），对此，我们希望能够与 iLogtail 现有的 Statistics 和 Alarm 机制进行统一。因此，在独立于用户配置之外，我们构造了两个全局的配置，分别用于接收来自其他配置内插件的 Statistics 和 Alarm 数据，然后统一输出。

如图所示，右侧是两个独立的全局配置实例，分别对应于 Statistics 和 Alarm 的接收和输出，它们采用和用户配置一样的结构，入口处使用一个内置的 input 插件从 channel 中读取数据，经过中间的处理传递，将数据交由 flusher 插件输出到 iLogtail。左侧的用户配置实例中的任意插件都可以根据自身逻辑输出统计或报警数据，通过 Go channel 发送给右侧的全局配置实例。

Checkpoint

在实现采集 Agent 的过程中，为了保证在崩溃、更新、重启等情况下不丢失数据，一般都会通过记录检查点来维护采集进度。对于部分插件而言，这同样是一个必需功能，比如 MySQL Binlog 插件要记录自己当前采集的 binlog 文件名以及偏移量。因此，我们在插件系统中实现了通用的检查点功能，通过 context 输出相应的键值 API 供插件使用。

type Context interface {

SaveCheckPoint(key string, value []byte) error

GetCheckPoint(key string) (value []byte, exist bool)

SaveCheckPointObject(key string, obj interface{}) error

GetCheckPointObject(key string, obj interface{}) (exist bool)

# ...

}

日志

开发环境

虽然源代码编译已经提供了方便的iLogtail编译方法，但却不适合开发场景。因为开发过程中需要不断进行编译调试，重复全量编译的速度太慢，因此需要构建支持增量编译开发环境。

进程结构

iLogtail为了支持插件系统，引入了 libPluginAdaptor 和 libPluginBase（以下简称 adaptor 和 base）这两个动态库，它们与 iLogtail 之间的关系如下：

iLogtail 动态依赖于这两个动态库（即 binary 中不依赖），在初始化时，iLogtail 会尝试使用动态库接口（如 dlopen）动态加载它们，获取所需的符号。

Adaptor 充当一个中间层，iLogtail 和 base 均依赖它，iLogtail 向 adaptor 注册回调，adpator 将这些回调记录下来以接口的形式暴露给 base 使用。

Base 是插件系统的主体，它包含插件系统所必须的采集、处理、聚合以及输出（向 iLogtail 递交可以视为其中一种）等功能。

因此，完整的iLogtail包含ilogtail、libPluginAdaptor.so 和 libPluginBase.so 3个二进制文件。

目录结构

iLogtail的大致目录结构如下：

.

├── core                  # C++核心代码

│   ├── CMakeLists.txt    # C++项目描述文件

│   └── ilogtail.cpp      # C++主函数

├── plugins               # Go插件代码

├── go.mod                # Go项目描述文件

├── docker                # 辅助编译的镜像描述目录

├── scripts               # 辅助编译的脚本目录

└── Makefile              # 编译描述文件

core目录包含了iLogtail C++核心代码，ilogtail.cpp是其主函数入口文件。C++项目使用CMake描述，CMakeLists.txt是总入口，各子目录中还有CMakeLists.txt描述子目录下的编译目标。

顶层目录.本身就是一个Go项目，该项目为iLogtail插件，go.mod为其描述文件。插件代码主体在plugins目录。

docker目录和scripts目录分别为辅助编译的镜像描述目录和脚本目录。Makefile为整个iLogtail的编译描述文件，对编译命令进行了封装。

开发镜像

iLogtail依赖了诸多第三方库（详见编译依赖），为了简化编译流程ilogtail提供了预编译依赖的镜像辅助编译。开发镜像的地址在 sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux ，可通过下面命令获取。

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux

开发镜像预先安装了gcc和go编译器，更新了git，为了代码风格统一安装了clang-format、go-tools，为了便于调试也安装了gdb、go-delve等工具。为方便国内开发者，预先设置了GOPROXY="https://goproxy.cn,direct"。

$ gcc --version

gcc (GCC) 9.3.1 20200408 (Red Hat 9.3.1-2)

$ go version

go version go1.16.15 linux/amd64

$ git --version

git version 2.29.3

C++核心的编译依赖在/opt/logtail/deps/目录下，该路径是CMakeLists.txt的DEFAULT_DEPS_ROOT（可以查看./core/dependencies.cmake找到修改路径的变量）。

$ ls /opt/logtail/deps/

bin  include  lib  lib64  share  ssl

如果需要安装更多工具或编译依赖，可以在开发镜像上镜像叠加，制作自定义的开发镜像。

from sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux

yum -y install ...

go install ...

使用VS Code构建开发环境

VS Code通过Remote Development插件可以实现远程开发、在镜像中开发，甚至远程+镜像中开发，在镜像中开发的功能使得编译环境在不同部署间都能保持统一。由于VS Code免费而功能强大，因此我们选用VS Code来为iLogtail创建一致的、可移植的开发环境。

1. 安装插件

在VS Code的Marketplace中搜索“Remote Development”安装插件。

2. 创建镜像开发环境配置

在iLogtail代码库的顶层目录创建 .devcontainer 目录，并在里面创建 devcontainer.json 文件，文件的内容如下：

{

"image": "sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux:2.0.3",

"customizations": {

"vscode": {

"extensions": [

"golang.Go",

"ms-vscode.cpptools-extension-pack",

"DavidAnson.vscode-markdownlint",

"redhat.vscode-yaml"

]

}

}

}

其中，image指定了ilogtail的开发镜像地址，customizations.vscode.extensions指定了开发环境的插件。部分插件介绍如下，开发者也可以按照自己的习惯进行修改，欢迎讨论。

插件名

用途

golang.Go

Go开发必备插件

ms-vscode.cpptools-extension-pack

C++开发必备插件

DavidAnson.vscode-markdownlint

Markdown代码风格检查

redhat.vscode-yaml

YAML语言支持

3. 在容器中打开代码库

使用Shift + Command + P（Mac）或Ctrl + Shift + P（Win）打开命令面板，输入 reopen ，选择 Remote-Containers: Reopen in Container 。

或者若出现如下图提示，则可以直接点击在容器中重新打开。

首次打开时会比较慢，因为要下载编译镜像并安装插件，后面再次打开时速度会很快。按照提示进行镜像Build。

完成上述步骤后，我们已经可以使用VS Code进行代码编辑，并在其中进行代码编译。

注：如果以前拉取过编译镜像，可能需要触发 Remote-Containers: Rebuild Container Without Cache 重新构建。

4. 在容器中进行编译

打开新Terminal（找不到的可以在命令面板中打Terminal，选择新开一个）

- 编译Go插件

go mod tidy       # 若需要更新插件库

make plugin_local # 每次更新插件代码后从这里开始

如果只是对插件代码进行了修改，则只需要执行最后一行命令即可增量编译。

- 编译C++代码

mkdir -p core/build # 若之前没有建过

cd core/build

cmake ..            # 若增删文件，修改CMakeLists.txt后需要重新执行

make -sj$(nproc)    # 每次更新core代码后从这里开始

如果只是对core代码进行了修改，则只需要执行最后一行命令即可增量编译。

默认的编译选项代码可能被优化，若需要Debug建议修改CMAKE_BUILD_TYPE开关。替换上述第2行为

cmake -D CMAKE_BUILD_TYPE=Debug ..

同理，若需要明确需要代码优化，则将上面的Debug改为Release。

默认的编译开关没有打开UT，如果需要编译UT，需要增加BUILD_LOGTAIL_UT开关。替换上述第2行为

cmake -DBUILD_LOGTAIL_UT=ON ..

- 制作镜像

目前不支持，没有安装docker，请直接在主机上进行编译。

5. 获取编译产出

由于VS Code是直接将代码库目录挂载到镜像内的，因此主机上可以直接访问镜像内的编译产出。

目前，镜像使用的是root用户权限，因此在主机上可能需要执行 sudo chown -R $USER . 来修复一下权限。

可以将C++核心的构建结果拷贝到 ./output 目录组装出完整的构建结果。

cp -a ./core/build/ilogtail ./output

cp -a ./core/build/go_pipeline/libPluginAdapter.so ./output

最终组装的 ./output 目录的结构如下

./output

├── ilogtail (主程序）

├── libPluginAdapter.so（插件接口）

├── libPluginBase.h

└── libPluginBase.so (插件lib）

直接使用镜像编译

如果不方便使用VS Code，也可以通过Docker手动挂载代码库目录的方式，启动编译镜像进入编译。

1. 进入源代码顶层目录

2. 创建编译容器，并挂载代码目录

docker run --name ilogtail-build -d \

-v `pwd`:/src -w /src \

sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux:2.0.3 \

bash -c "sleep infinity"

3. 进入容器

docker exec -it ilogtail-build bash

4. 在容器内编译

后续步骤均与VS Code的操作步骤相同。

使用编译产出

在主机上，编译的后的产出可以直接替换对应的文件使用。而对于容器场景，虽然在编译镜像内没有制作镜像能力，但通过下面的方法可以在不制作新镜像的情况下实现快速测试。

1. 修改官方镜像entrypoint

基于官方镜像包进行调试，首先用bash覆盖官方镜像的entrypoint，避免杀死ilogtail后容器直接退出。

- docker：指定CMD

docker run -it --name docker_ilogtail -v /:/logtail_host:ro -v /var/run:/var/run aliyun/ilogtail:<VERSION> bash

- k8s：用command覆盖entrypoint

command:

- sleep

- 'infinity'

# 删除livenessProbe，要不然会因为探测不到端口重启

2. 将自己编的二进制文件、so，替换到容器里

由于ilogtail容器挂载了主机目录，因此将需要替换掉文件放到主机目录上容器内就能访问。

# 将开发机上编译的so scp到container所在node上

scp libPluginBase.so <user>@<node>:/home/<user>

主机的根路径在ilogtail容器中位于/logtail_host，找到对应目录进行copy即可。

cp /logtail_host/home/<user>/libPluginBase.so /usr/local/ilogtail

常见问题

1. 更新代码后编译错误

如果发生编译错误，如

/src/core/common/CompressTools.cpp:18:23: fatal error: zstd/zstd.h: No such file or directory

#include <zstd/zstd.h>

^

compilation terminated.

请确保本地编译镜像为最新版本。可使用以下命令更新：

docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/ilogtail-community-edition/ilogtail-build-linux

若使用VS Code进行开发，请重新编译开发容器镜像。使用Shift + Command + P（Mac）或Ctrl + Shift + P（Win）打开命令面板，输入rebuild，选择 Dev-Containers: Rebuild Without Cache and Reopen in Container 。

日志协议

iLogtail的日志数据默认以sls自定义协议的形式与外部进行交互，但也支持日志数据在sls协议和其它标准协议或自定义协议之间的转换。除此之外，对于某种协议，iLogtail还支持对日志数据进行不同方式的编码。

目前，iLogtail日志数据支持的协议及相应的编码方式如下表所示，其中协议类型可分为自定义协议和标准协议：

协议类型

协议名称

支持的编码方式

标准协议

sls协议

json、protobuf

自定义协议

单条协议

json

标准协议

Influxdb协议

custom

字节流协议

raw协议

custom

协议转换

在开发Flusher插件时，用户往往需要将日志数据从sls协议转换成其他协议。在扩展Metric数据模型后，v2版本的Flusher插件还需要支持从PipelineGroupEvents数据转换成其他协议的场景。为了加快开发插件流程，iLogtail提供了通用协议转换模块，用户只需要指定目标协议的名称和编码方式即可获得编码后的字节流。

Converter结构

日志协议转换器的具体实现为 Converter 结构，其定义如下：

type Converter struct {

Protocol             string

Encoding             string

TagKeyRenameMap      map[string]string

ProtocolKeyRenameMap map[string]string

}

其中，各字段的含义如下：

- Protocol ：协议名称

- Encoding ：编码方式

- TagKeyRenameMap ：tag字段Key重命名表，可用于重命名sls协议中LogTag字段的Key，其中系统保留的LogTag的Key默认值见附录。如果需要删去某个tag，则只需将该tag重命名为空字符串即可。

- ProtocolKeyRenameMap ：协议字段Key重命名表，可用于重命名协议字段的Key，仅部分编码模式下可用，详见附录

用户可以使用如下函数创建 Converter 对象实例：

func NewConverter(protocol, encoding string, tagKeyRenameMap, protocolKeyRenameMap map[string]string) (*Converter, error)

其中， protocol 字段和 encoding 的可选取值为见附录。

转换方法

Converter 结构支持如下几种方法：

func (c *Converter) Do(logGroup *sls.LogGroup) (logs interface{}, err error)

func (c *Converter) ToByteStream(logGroup *sls.LogGroup) (stream interface{}, err error)

func (c *Converter) DoWithSelectedFields(logGroup *sls.LogGroup, targetFields []string) (logs interface{}, values []map[string]string, err error)

func (c *Converter) ToByteStreamWithSelectedFields(logGroup *sls.LogGroup, targetFields []string) (stream interface{}, values []map[string]string, err error)

func (c *Converter) ToByteStreamWithSelectedFieldsV2(groupEvents *models.PipelineGroupEvents, targetFields []string) (stream interface{}, values []map[string]string, err error)

各方法的用法如下：

- Do ：给定日志组 logGroup ，根据 Converter 中设定的协议，将sls日志组中的各条日志分别转换为与目标协议相对应的数据结构，并将结果组装在 logs 中；

- ToByteStream ：在完成 Do 方法的基础上，根据 Converter 中设定的编码格式，对转换后的日志进行编码形成字节流，并将结果组装在 stream 中；

- DoWithSelectedFields ：在完成和 Do 方法一致的日志转换基础上，在各条日志及日志组tag中找到 targetFields 数组中指定字段的值，以map的形式将结果保存于 values 数组中。如果没有找到该字段，则 values 的各个map中将不包括该字段。 targetFields 中各字符串的的格式要求如下：

- 如果需要获取某个日志字段的值，则字符串的命名方式为“content.XXX"，其中XXX为该字段的键名；

- 如果需要获取某个日志tag的值，则字符串的命名方式为“tag.XXX"，其中XXX为该字段的键名。

- ToByteStreamWithSelectedFields ：与 DoWithSelectedFields 方法类似，在完成和 ToByteStream 方法一致的日志转换基础上，在各条日志及日志组tag中找到 targetFields 数组中指定字段的值，以map的形式将结果保存于 values 数组中， targetFields 中各字符串的的格式要求同上。

- ToByteStreamWithSelectedFieldsV2 ：作用与 ToByteStreamWithSelectedFields 方法一致，只是作用于v2版本的数据模版的协议转换

使用步骤

这里给出使用 Converter 进行日志转换的典型步骤：

1. 在当前文件中引入 protocol 包：

import "github.com/alibaba/ilogtail/pkg/protocol"

2. 使用选定的转换参数创建 Converter 对象实例：

c, err := protocol.NewConverter(...)

3. 给定一个日志组,

- 如果只需要对日志格式进行转换，则调用 Converter 的 Do 方法获得转换后的数据结构：

convertedLogs, err := c.Do(logGroup)

- 如果需要对日志格式进行转换并编码，则调用 Converter 的 ToByteStream 方法获得编码后的字节流：

serializedLogs, err := c.ToByteStream(logGroup)

- 如果在对日志格式进行转换的同时，还想额外获取日志中某些字段的值，则调用 Converter 的 DoWithSelectedFields 方法同时获得转换后的数据结构与选定日志字段的值：

convertedLogs, targetValues, err := c.DoWithSelectedFields(logGroup, selectedFields)

- 如果在对日志格式进行转换并编码的同时，还想额外获取日志中某些字段的值，则调用 Converter 的 ToByteStreamWithSelectedFields 方法同时获得编码后的字节流与选定日志字段的值：

serializedLogs, targetValues, err := c.ToByteStreamWithSelectedFields(logGroup, selectedFields)

示例

假设需要将日志从sls协议转换为单条协议，编码方式选择“json”，同时将tag中的host.name键更名为hostname，将协议中的time键更名为@timestamp，则创建 Converter 的代码如下：

c, err := protocol.NewConverter("custom_single", "json", map[string]string{"host.name":"hostname"}, map[string]string{"time", "@timestamp"})

附录

- 可选协议名

| 协议名 | 意义 | |------------------------------------------| ------ | | custom_single | 单条协议 | | custom_single_flatten | 单条协议，数据平铺 ，如写入kafka的json消息体 | | influxdb | Influxdb协议 | | raw | 原始Byte流协议，仅支持v2版本中ByteArray类型的Event的协议转换 |

- 可选编码方式

| 编码方式 | 意义 | | ------ | ------ | | json | json编码方式 | | protobuf | protobuf编码方式 | | custom | 自定义编码方式 |

- sls协议中系统保留LogTag的Key默认值：

| 字段名 | 描述 | | ------ | ------ | | host.ip | iLogtail所属机器或容器的ip地址 | | log.topic | 日志的topic | | log.file.path | 被采集文件的路径 | | host.name | iLogtail所属机器或容器的主机名 | | k8s.node.ip | iLogtail容器所处K8s节点的ip | | k8s.node.name | iLogtail容器所处K8s节点的名称 | | k8s.namespace.name | 业务容器所属的K8s命名空间 | | k8s.pod.name | 业务容器所属的K8s Pod名称 | | k8s.pod.ip | 业务容器所属的K8s Pod ip | | k8s.pod.uid | 业务容器所属的K8s Pod uid | | (k8s.)container.name | 业务容器的名称。如果处于K8s环境中，则增加“k8s”前缀 | | (k8s.)container.ip | 业务容器的ip。如果处于K8s环境中，则增加“k8s”前缀 | | (k8s.)container.image.name | 用于创建业务容器的镜像名称。如果处于K8s环境中，则增加“k8s”前缀 |

- 可用于重命名协议字段Key的编码格式：

json

增加新的日志协议

如果iLogtail暂时不支持您所需的日志协议，您可以为iLogtail增加该协议并添加相应的协议转换函数，具体步骤如下：

1. 如果您的协议支持Protobuf或其它可通过模式定义生成相应内存结构的编码方式，您需要首先在 ./pkg/protocol 目录下新建一个以协议名为命名的文件夹，然后在该文件夹中增加一个以编码方式为命名的子文件夹，在该文件中存放相应的模式定义文件，然后将由代码生成工具生成的与该模式定义文件相对应的Go代码文件放置在父目录中。目录组织结构如下：

./pkg/protocol/

├── <protocol_name>

│   ├── <encoding>

│       └──  模式定义文件

│   └── 代码生成工具生成的Go文件

└── converter

├── converter.go

├── <protocol>_log.go

└── 测试文件

2. 在 ./pkg/protocol/converter 目录下新建一个以 <protocol>_log.go 命名的文件，并在该文件中实现下列函数：

func (c *Converter) ConvertToXXXProtocolLogs(logGroup *sls.LogGroup, targetFields []string) (logs interface{}, values [][]string, err error)

func (c *Converter) ConvertToXXXProtocolStream(logGroup *sls.LogGroup, targetFields []string) (stream interface{}, values [][]string, err error)

其中，函数名中的“XXX”为协议名（可缩写），参数中的 logGroup 为sls日志组， targetFields 为需要提取值的字段名，返回值中的 logs 为与协议对应的数据结构组成的数组， stream 为代表该日志组的字节流， values 为每条日志或日志组tag中 targetFields 字段对应的值， err 为返回的错误。

该函数必须支持以下功能：

1. 对输入日志进行相应的转换

2. 能够根据 c.TagKeyRenameMap 重命名sls协议中LogTag字段的Key

3. 能够根据 targetFields 找到对应字段的值

4. 对于部分编码格式，能够根据 c.ProtocolKeyRenameMap 重命名协议字段的Key

为了完成上述第2和第3点，iLogtail提供了下列帮助函数：

func convertLogToMap(log *sls.Log, logTags []*sls.LogTag, src, topic string, tagKeyRenameMap map[string]string) (contents map[string]string, tags map[string]string)

func findTargetValues(targetFields []string, contents, tags, tagKeyRenameMap map[string]string) (values map[string]string, err error)

各函数的用途如下：

5. convertLogToMap ：将符合sls协议的日志以及对应logGroup中的其他元信息转换成以map形式存储的 contents 和 tags ，同时根据 tagKeyRenameMap 重命名sls协议中LogTag字段的Key。

6. findTargetValues ：在 convertLogToMap 获得的 contents 和 tags 中寻找 targetFields 字段对应的值，如果 targetFields 中包含被更名的默认tag键，则寻找过程还需要借助 tagKeyRenameMap 。

3. 在 ./pkg/protocol/converter/converter.go 中，依次做出如下改变：

- 新增 protocolXXX 常量，“XXX”为协议名，常量的值也为协议名

- 如果协议支持新的编码方式，则新增 encodingXXX 常量，“XXX”为编码方式，常量的值也为编码方式

- 在 supportedEncodingMap 中，增加该协议支持的编码类型

- 在 c.DoWithSelectedFields 方法的 switch 语句中新增一个 case 子句， case 名为协议名，子句内容为 return c.ConvertToXXXProtocolLogs(logGroup, targetFields) ，其中涉及的函数即为第2步中编写的函数

- 在 c.ToByteStreamWithSelectedFields 方法的 switch 语句中新增一个 case 子句， case 名为协议名，子句内容为 return c.ConvertToXXXProtocolStream(logGroup, targetFields) ，其中涉及的函数即为第2步中编写的函数

4. 在 ./doc/cn/developer-guide/log-protocol/converter.md 的附录、 README.md 中增加协议相关内容，并在 ./doc/cn/developer-guide/log-protocol/protocol-spec 文件夹下新增 <protocol>.md 文件描述具体的协议形式。

sls协议

sls协议对应的Protobuf模式定义如下：

Content & LogTag

传输数据字段以及标签，简单的 key/value 对。

message Content

{

required string Key = 1;

required string Value = 2;

}

message LogTag

{

required string Key = 1;

required string Value = 2;

}

Log

Log 是表示单条日志的数据类型，Time 字段为日志时间，Contents 字段维护了此日志的内容，由一个 key/value 列表组成。

message Log

{

required uint32 Time = 1;// UNIX Time Format

repeated Content Contents = 2;

}

LogGroup

LogGroup（日志组）是对多条日志的包装：

- Logs：包含所有日志。

- Category：日志服务Logstore，可以类比Kafka 独立集群， 数据存储的独立单元。

- Topic: 日志服务Topic，一个Category（Logstore）可以划分为多个topic，不填写时Topic 为空字符串，可以类比Kafka 独立集群下的Topic概念。

- Source/MachineUUID：iLogtail 所在节点的信息，前者为 IP，后者为 UUID。

- LogTags：所有日志共同的 tag，同样由 key/value 列表组成。

message LogGroup

{

repeated Log Logs = 1;

optional string Category = 2;

optional string Topic = 3;

optional string Source = 4;

optional string MachineUUID = 5;

repeated LogTag LogTags = 6;

}

代码风格

iLogtail C++遵循基于Google代码规范的风格，详细格式约束见.clang-format。

Go遵循Effective Go风格。

Markdown遵循基于markdownlint的风格，并为了兼容GitBook排除MD033。

格式化C++代码

使用VSCode的Clang-Format (by xaver)插件。

或使用命令行进行格式化

find core/ -type f -iname '*.h' -o -iname '*.cpp' | xargs clang-format -i

格式化Go代码

使用VSCode的Go (by Go Team at Google)插件。

或使用命令行进行格式化

find ./ -type f -iname '*.go' -not -iname '*.pb.go' | grep -E -v '/external/' | xargs gofmt -w

格式化Markdown

使用VSCode的Markdownlint (by David Anson)插件。

数据模型

iLogtail 目前支持  SLS Log Protocol  和  Pipeline Event  两种数据模型，两种模型的描述和对比如下：

| | SLS Log Protocol | Pipeline Event | | ---- | ---- | ---- | | 描述 | SLS 日志的专用处理结构 | 可扩展的可观测性数据模型，支持Metrics、Trace、Logging、Bytes、Profile等 | | 流水线配置版本 | v1 | v2 | | Logging 数据结构 | 支持 | 支持 | | Metric 数据结构 | 不支持 | 支持 | | Trace 数据结构 | 不支持 | 支持 | | ByteArray 数据结构 | 不支持 | 支持 | | Profile 数据结构 | 不支持 | 支持 | | 自定义数据结构 | 不支持 | 支持 |

SLS Log Protocol

参考 SLS 协议

Pipeline Event

PipelineEvent  是数据处理管道中的抽象数据接口，定义如下

type PipelineEvent interface {

GetName() string

SetName(string)

GetTags() Tags

GetType() EventType

GetTimestamp() uint64

GetObservedTimestamp() uint64

SetObservedTimestamp(uint64)

Clone() PipelineEvent

}

我们还需要引入聚合的概念  PipelineGroupEvents ，来支持部分需要对数据进行分组的操作，聚合事件也允许有独立的 meta 和 tags，一般是从数据中提取

type PipelineGroupEvents struct {

Group  *GroupInfo

Events []PipelineEvent

}

type GroupInfo struct {

Metadata Metadata

Tags     Tags

}

Metric 模型

Metric模型定义如下：

type MetricEvent struct {

Name              string

MetricType        MetricType

Timestamp         uint64

ObservedTimestamp uint64

Unit              string

Description       string

Tags              Tags

Value             MetricValue

TypedValue        MetricTypedValues

}

主流的metrics数据有单值(eg. Prometheus)和多值(eg. influxdb)两种设计，iLogtail 中也需要支持两种不同的设计，基于此设计了 MetricValue 接口和MetricSingleValue 和 MetricMultiValue 两个不同的实现

type MetricValue interface {

IsSingleValue() bool

IsMultiValues() bool

GetSingleValue() float64

GetMultiValues() MetricFloatValues

}

type MetricSingleValue struct {

Value float64

}

type MetricMultiValue struct {

Values MetricFloatValues

}

通常情况下，对于 counter 、gauge 类型的 metric 会使用单值 ，Histogram 和 Summary 类型在不同的TSDB上可能使用单值或者多值，对于单值和多值的处理，可以使用下面的API

if metric.Value.IsSingleValue() {

value := metric.Value.GetSingleValue()

}

if metric.Value.IsMultiValues() {

values := metric.Value.GetMultiValues()

for field, value := range values.Iterator() {

// field 为 string 类型,表示多值的字段名

// value 为 float64 类型

}

}

TypedValue 设计。MetricValue 不管是单值还是多值的value类型都是float64，在一些 TSDB 中比如 influxdb，除了数值类型，还支持string bool 等非数值类型 influxdb field-value 。为此，我们扩展了一个额外的 TypedValue 字段用来存储非数值的 field 值。

type TypedValue struct {

Type  ValueType

Value interface{}

}

type MetricTypedValues interface {

KeyValues[*TypedValue]

}

Trace 模型

目前主流的开源 tracing 模型有opentracing opentelemetry skywalking 等几种不同的规范。 不管在哪种 trace 模型中，trace 都是由多个 Span 组成的，(不同的是在 skywalking 和许多私有协议中，trace 和 span 中间还有一个 segment 或者 transaction 概念）。

在 Span 中，一般还会定义携带数据语义的 Tags ，和记录一些关键事件发生的 logs 或 events 。

其中zipkin jaeger 都是 opentracing 的一种实现，而opentelemetry 可以认为是在opentracing的基础上扩展的新规范和超集（兼容 w3c 和定义了明确的 OTLP 协议）。 所以我们定义的 Span 结构要兼容上面提到的几种开源协议，具体的结构如下

type SpanLink struct {

TraceID    string

SpanID     string

TraceState string

Tags       Tags

}

type SpanEvent struct {

Timestamp int64

Name      string

}

type Span struct {

TraceID      string

SpanID       string

ParentSpanID string

Name         string

TraceState   string

StartTime         uint64

EndTime           uint64

ObservedTimestamp uint64

Kind   SpanKind

Status StatusCode

Tags   Tags

Links  []*SpanLink

Events []*SpanEvent

}

Log 模型

Log 模型可以兼容非结构化和结构化日志，并且预留链路信息记录的字段。

- 其中 Offset 记录了日志文件采集时，日志在文件中的偏移量，可选

- Name 对 Log 也是可选的

- SpanID 、TraceID 在数据关联时使用，可选

- Contents 在日志结构化的场景使用，存储从 Body 原始日志文本分析的 KV

type LogContents KeyValues[string]

type Log struct {

Name              string

Level             string

SpanID            string

TraceID           string

Tags              Tags

Timestamp         uint64

ObservedTimestamp uint64

Offset            uint64

Contents          LogContents

}

其中Level字段，对齐Open Telemetry Logs，支持以下等级：  Trace ,  Trace2 ,  Trace3 ,  Trace4 ,  Debug ,  Debug2 ,  Debug3 ,  Debug4 ,  Info ,  Info2 ,  Info3 ,  Info4 ,  Warn ,  Warn2 ,  Warn3 ,  Warn4 ,  Error ,  Error2 ,  Error3 ,  Error4 ,  Fatal ,  Fatal2 ,  Fatal3 ,  Fatal4 ,  Unspecified .

插件开发

Checkpoint接口

Logger接口

https://github.com/alibaba/ilogtail/blob/main/pkg/logger/logger.go

Logger提供了DBG、INFO、WARN、ERR 4个级别的日志打印，每个级别分别提供kv和format形式打印接口。

// kv form

func Debug(ctx context.Context, kvPairs ...interface{})

func Info(ctx context.Context, kvPairs ...interface{})

func Warning(ctx context.Context, alarmType string, kvPairs ...interface{})

func Error(ctx context.Context, alarmType string, kvPairs ...interface{})

// format form

func Debugf(ctx context.Context, format string, params ...interface{})

func Infof(ctx context.Context, format string, params ...interface{})

func Warningf(ctx context.Context, alarmType string, format string, params ...interface{})

func Errorf(ctx context.Context, alarmType string, format string, params ...interface{})

其中WARN和ERR级别的alarmType参数，通常使用全大写XXX_ALARM。

基本使用示例

func (p *plugin) func1() {

logger.Debug(p.context.GetRuntimeContext(), "foo", "bar")

logger.Warningf(p.context.GetRuntimeContext()， "TEST_ALARM", "msg %s", "param ignored")

}

2021-08-24 18:20:02 [DBG] [logger_test.go:174] [func1] [mock-configname,mock-logstore] foo:bar

2021-08-24 18:20:02 [WARN] [logger_test.go:175] [func1] [mock-configname,mock-logstore] AlarmType:TEST_ALARM msg param ignored

打印采集配置元信息

对于iLogtail，具有多租户的特点，可以支持多份采集配置同时工作，iLogtail 支持将采集配置的元信息打印到日志中，便于问题的排查与定位。

import (

"github.com/alibaba/ilogtail/pkg/logger"

)

以下代码块是一个插件所必备的内容，我们打印日志时仅需要将context.GetRuntimeContext() 传入logger包的第一个参数，打印效果如下，会自动附加采集配置与logstore 名称。

type plugin struct {

context ilogtail.Context

}

func (p *plugin) func1() {

logger.Debug(p.context.GetRuntimeContext(), "foo", "bar")

}

If config and logstore name in context:

2021-08-24 18:20:02 [DBG] [logger_test.go:174] [func1] [mock-configname,mock-logstore] foo:bar

If config and logstore name not in context:

2021-08-24 18:20:02 [DBG] [logger_test.go:174] [func1] foo:bar

测试中使用Logger

一般用法

对于大多数情况，只需要引入 _ "github.com/alibaba/ilogtail/pkg/logger/test" 包即可。

import (

"context"

"testing"

"github.com/alibaba/ilogtail/pkg/logger"

_ "github.com/alibaba/ilogtail/pkg/logger/test"

)

func Test_plugin_func1(t *testing.T) {

logger.Info(context.Background(), "foo", "bar")

}

高级用法-自定义Logger

你可以使用logger.ConfigOption设置Logger 的行为，比如输出、日志级别、异步打印等。

package test

import (

"context"

"testing"

"github.com/alibaba/ilogtail/pkg/logger"

)

func init() {

logger.InitTestLogger(logger.OptionDebugLevel)

}

func Test_plugin_func1(t *testing.T) {

logger.Debug(context.Background(), "foo", "bar")

}

高级用法-读取日志内容

某些单测下，开发者可能需要读取日志来验证代码的分支覆盖行为。在这种情况下可以使用 logger.OptionOpenMemoryReceiver  参数。

import (

"context"

"strings"

"testing"

"github.com/alibaba/ilogtail/pkg/logger"

"github.com/stretchr/testify/assert"

)

func init() {

logger.InitTestLogger(logger.OptionOpenMemoryReceiver)

}

func Test_plugin_func1(t *testing.T) {

logger.ClearMemoryLog()

logger.Info(context.Background(), "foo", "bar")

assert.Equal(t, 1, logger.GetMemoryLogCount())

assert.Truef(t, strings.Contains(logger.ReadMemoryLog(1), "foo:bar"), "got %s", logger.ReadMemoryLog(1))

}

启动时控制日志行为

启动iLogtail 时，默认的日志行为是异步文件Info级别输出，如果需要动态调整，可以参考以下内容进行设置：

调整日志级别

启动时如果启动程序相对路径下没有 plugin_logger.xml 文件，则可以使用以下命令设置：

./ilogtail --logger-level=debug

如果存在 plugin_logger.xml 文件，可以修改文件，或使用以下命令强制重新生成日志配置文件：

./ilogtail --logger-level=info --logger-retain=false

是否开启控制台打印

默认生成环境关闭控制台打印，如果本地调试环境想开启控制台日志，相对路径下没有 plugin_logger.xml 文件，则可以使用以下命令：

./ilogtail --logger-console=true

如果存在 plugin_logger.xml 文件，可以修改文件，或使用以下命令强制重新生成日志配置文件：

./ilogtail --logger-console=true --logger-retain=false

插件自监控接口

iLogtail提供了指标接口，可以方便地为插件增加一些自监控指标，目前支持Counter，Gauge，String，Latency等类型。

接口：

https://github.com/alibaba/ilogtail/blob/main/pkg/pipeline/self_metric.go

实现：

https://github.com/alibaba/ilogtail/blob/main/pkg/helper/self_metrics_vector_imp.go

用户使用时需要引入pkg/helper包：

import (

"github.com/alibaba/ilogtail/pkg/helper"

)

创建指标

指标必须先定义后使用，在插件的结构体内声明具体指标。

type ProcessorRateLimit struct {

// other fields

context         pipeline.Context

limitMetric     pipeline.CounterMetric  // 第一个指标

processedMetric pipeline.CounterMetric   // 第二个指标

}

创建指标时，需要将其注册到iLogtail Context 的 MetricRecord 中，以便 iLogtail 能够采集上报数据，在插件的Init方法中，调用context 的 GetMetricRecord()方法来获取MetricRecord，然后调用helper.NewXXXMetricAndRegister函数去注册一个指标，例如：

metricsRecord := p.context.GetMetricRecord()

p.limitMetric = helper.NewCounterMetricAndRegister(metricsRecord, fmt.Sprintf("%v_limited", pluginType))

p.processedMetric = helper.NewCounterMetricAndRegister(metricsRecord, fmt.Sprintf("%v_processed", pluginType))

用户在声明一个Metric时可以还额外注入一些插件级别的静态Label，这是一个可选参数，例如flusher_http就把RemoteURL等配置进行上报：

metricsRecord := f.context.GetMetricRecord()

metricLabels := f.buildLabels()

f.matchedEvents = helper.NewCounterMetricAndRegister(metricsRecord, "http_flusher_matched_events", metricLabels...)

指标打点

不同类型的指标有不同的打点方法，直接调用对应Metric类型的方法即可。 Counter：

p.processedMetric.Add(1)

Latency:

tracker.ProcessLatency.Observe(float64(time.Since(startProcessTime)))

StringMetric:

sc.lastBinLogMetric.Set(string(r.NextLogName))

指标上报

iLogtial会自动采集所有注册的指标，默认采集间隔为60s，然后通过default_flusher上报，数据格式为LogGroup，格式如下：

{"Logs":[{"Time":0,"Contents":[{"Key":"http_flusher_matched_events","Value":"2.0000"},{"Key":"__name__","Value":"http_flusher_matched_events"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]},{"Time":0,"Contents":[{"Key":"http_flusher_unmatched_events","Value":"0.0000"},{"Key":"__name__","Value":"http_flusher_unmatched_events"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]},{"Time":0,"Contents":[{"Key":"http_flusher_dropped_events","Value":"0.0000"},{"Key":"__name__","Value":"http_flusher_dropped_events"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]},{"Time":0,"Contents":[{"Key":"http_flusher_retry_count","Value":"2.0000"},{"Key":"__name__","Value":"http_flusher_retry_count"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]},{"Time":0,"Contents":[{"Key":"http_flusher_flush_failure_count","Value":"2.0000"},{"Key":"__name__","Value":"http_flusher_flush_failure_count"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]},{"Time":0,"Contents":[{"Key":"http_flusher_flush_latency_ns","Value":"2504448312.5000"},{"Key":"__name__","Value":"http_flusher_flush_latency_ns"},{"Key":"db","Value":"%{metadata.db}"},{"Key":"flusher_http_id","Value":"0"},{"Key":"RemoteURL","Value":"http://testeof.com/write"},{"Key":"project","Value":"p"},{"Key":"config_name","Value":"c"},{"Key":"plugins","Value":""},{"Key":"category","Value":"p"},{"Key":"source_ip","Value":"100.80.230.110"}]}],"Category":"","Topic":"","Source":"","MachineUUID":""}

一组LogGroup中会有多条Log，每一条Log都对应一条指标，其中 {"Key":"__name__","Value":"http_flusher_matched_events"} 是一个特殊的Label，代表指标的名字。

高级功能

动态Label

和Prometheus SDK类似，iLogtail也允许用户在自监控时上报可变Label，对于这些带可变Label的指标集合，iLogtail称之为MetricVector， MetricVector同样也支持上述的指标类型，因此把上面的Metric看作是MetricVector不带动态Label的特殊实现。 用例：

type FlusherHTTP struct {

// other fields

context     pipeline.Context

statusCodeStatistics pipeline.MetricVector[pipeline.CounterMetric] // 带有动态Label的指标

}

声明并注册MetricVector时，可以使用helper.NewXXXMetricVectorAndRegister方法， 需要将其带有哪些动态Label的Name也进行声明：

f.statusCodeStatistics = helper.NewCounterMetricVectorAndRegister(metricsRecord,

"http_flusher_status_code_count",

map[string]string{"RemoteURL": f.RemoteURL},

[]string{"status_code"},

)

打点时通过WithLabels API传入动态Label的值，拿到一个Metric对象，然后进行打点：

f.statusCodeStatistics.WithLabels(pipeline.Label{Key: "status_code", Value: strconv.Itoa(response.StatusCode)}).Add(1)

示例

可以参考内置的一些插件：

限流插件： https://github.com/alibaba/ilogtail/blob/main/plugins/processor/ratelimit/processor_rate_limit.go

http flusher插件： https://github.com/alibaba/ilogtail/blob/main/plugins/flusher/http/flusher_http.go

如何开发Input插件

了解如何开发Input插件前你需要先了解Input 插件接口，目前的Input 插件分为2类，分别为MetricInput 与ServiceInput，分别为MetricInput可以由全局控制采集频率，适合Metric指标拉取等情况，ServiceInput 更适合接收外部输入情况，比如接收SkyWalking的Trace 数据推送。

MetricInput 接口定义

- Init：插件初始化接口，主要供插件做一些参数检查，并为其提供上下文对象 Context。 返回值的第一个参数表示调用周期（毫秒），插件系统会以该值作为数据获取周期。如果返回 0 的话，插件系统会使用全局的数据获取周期。 返回值的第二个参数表示初始化中发生的错误，一旦发生错误该插件实例将被忽略，插件系统不会向获取数据。

- Description：插件自描述接口。

- Collect： MetricInput 最关键的接口，插件系统通过此接口从插件实例中获取数据。插件系统会周期性地调用此接口，将数据收集到传入 Collector 中。

// MetricInput ...

type MetricInput interface {

// Init called for init some system resources, like socket, mutex...

// return call interval(ms) and error flag, if interval is 0, use default interval

Init(Context) (int, error)

// Description returns a one-sentence description on the Input

Description() string

// Collect takes in an accumulator and adds the metrics that the Input

// gathers. This is called every "interval"

Collect(Collector) error

}

MetricInput 开发

MetricInput 的开发分为以下步骤:

1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。

2. 实现MetricInput 接口，这里我们使用样例模式进行介绍，详细样例请查看input/example/metric，你可以使用 example.json 试验此插件功能。

3. 通过init将插件注册到MetricInputs，MetricInputs插件的注册名（即json配置中的plugintype）必须以"metric"开头，详细样例请查看input/example/metric。

4. 将插件加入全局插件定义中心, 如果仅运行于指定系统，请添加到Linux插件定义中心 或 Windows插件定义中心.

5. 进行单测或者E2E测试，请参考如何使用单测 与 如何使用E2E测试.

6. 使用 make lint 检查代码规范。

7. 提交Pull Request。

ServiceInput 接口定义

- Init/Description：同 MetricInput 接口，但是 Init 的一个返回值对于 ServiceInput 没有意义，因为它不会被周期性调用。

- Start：由于 ServiceInput 的定位是常驻型输入，所以插件系统为此类型的插件实例都创建了独立的 goroutine，在 goroutine 中调用此接口来开始数据收集。Collector 的作用依旧是充当插件实例和插件系统之间的数据管道。

- Stop：提供终止插件的能力。插件必须正确地实现此接口，以避免 hang 住插件系统导致 Logtail 也无法正确退出。

// ServiceInput ...

type ServiceInput interface {

// Init called for init some system resources, like socket, mutex...

// return interval(ms) and error flag, if interval is 0, use default interval

Init(Context) (int, error)

// Description returns a one-sentence description on the Input

Description() string

// Start starts the ServiceInput's service, whatever that may be

Start(Collector) error

// Stop stops the services and closes any necessary channels and connections

Stop() error

}

ServiceInput 开发

ServiceInput 的开发分为以下步骤:

1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。

2. 实现 ServiceInput 接口，这里我们使用样例模式进行介绍，详细样例请查看input/example/service, 你可以使用 example.json 试验此插件功能。

3. 通过init将插件注册到ServiceInputs，ServiceInputs插件的注册名（即json配置中的plugintype）必须以"service"开头，详细样例请查看input/example/service。

4. 将插件加入插件引用配置文件的 common 配置节, 如果仅运行于指定系统，请添加到 linux 或 windows 配置节.

5. 进行单测或者E2E测试，请参考如何使用单测 与 如何使用E2E测试.

6. 使用 make lint 检查代码规范。

7. 提交Pull Request。

如何开发Processor插件

Processor 插件对输入数据进行二次加工，以下将从接口定义与案例2方面指导如何开发Processor 插件

Processor 接口定义

Processor 插件接口方法非常容易理解，除 Init/Description 这两个标准方法外，只有一个 ProcessLogs 接口，它的输入输出都是 []*Log，即接受一个 Log 列表，经过处理后返回一个 Log 列表。很自然地，processor 插件实例之间通过此接口构成了一个串行的处理链。

// Processor also can be a filter

type Processor interface {

// Init called for init some system resources, like socket, mutex...

Init(Context) error

// Description returns a one-sentence description on the Input

Description() string

// Apply the filter to the given metric

ProcessLogs(logArray []*protocol.Log) []*protocol.Log

}

Processor 开发

Processor 的开发分为以下步骤:

1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。

2. 实现Processor 接口，这里我们使用样例模式进行介绍，详细样例请查看processor/addfields，你可以使用 example.json 试验此插件功能。

3. 通过init将插件注册到Processors，Processor插件的注册名（即json配置中的plugintype）必须以"processor"开头，详细样例请查看processor/addfields。

4. 将插件加入插件引用配置文件的 common 配置节, 如果仅运行于指定系统，请添加到 linux 或 windows 配置节.

5. 进行单测或者E2E测试，请参考如何使用单测 与 如何使用E2E测试.

6. 使用 make lint 检查代码规范。

7. 提交Pull Request。

Processor 准入性能规范

基础case参考：512随机字符作为内容，完整执行一次processor中的逻辑。

处理速度准入条件：4w/s。

如何开发Aggregator插件

Aggregator 插件对输入数据进行打包，以下将从接口定义与案例2方面指导如何开发 Aggregator 插件

Aggregator 接口定义

Aggregator 插件的作用就是将一条条独立的 Log 根据一定规则聚合成 LogGroup，进而提交给下一级的 flusher 插件处理。

- Add 接口供外部输入 Log

- Flush 接口供外部获取聚合得到的 LogGroug

- Reset 接口目前仅在内部使用，可以忽略

- Init 接口，类似于 input 插件的 Init 接口，该接口返回值的第一个参数表示插件系统调用 Flush 接口的周期值，该值为 0 时使用全局参数，第二个参数表示一个初始化错误。 但不同于 input 插件，aggregator 插件的 Init 接口新增了一个 LogGroupQueue 类型的参数，该类型定义于 loggroup_queue.go 文件中，如下：

type LogGroupQueue interface {

// Returns errAggAdd immediately if queue is full.

Add(loggroup *LogGroup) error

// Wait at most @duration if queue is full and returns errAggAdd if timeout.

// Do not use this method if you are unsure.

AddWithWait(loggroup *LogGroup, duration time.Duration) error

}

该接口对应的实例实际上充当了一个队列，aggregator 插件实例可以将聚合得到的 LogGroup 对象立即通过 AddXXX 接口插入队列。 这是一个可选项，从之前的描述可以看到，Add->Flush 是一个周期性调用的数据链路，而 LogGroupQueue 可以提供一个实时性更高的链路，在 aggregator 一得到新聚合的 LogGroup 后就直接提交，不必等到 Flush 被调用。

但需要注意的是，在队列满的时候，Add 会返回错误，这一般意味着 flusher 发生了阻塞，比如网络异常。

// Aggregator is an interface for implementing an Aggregator plugin.

// the RunningAggregator wraps this interface and guarantees that

// Add, Push, and Reset can not be called concurrently, so locking is not

// required when implementing an Aggregator plugin.

type Aggregator interface {

// Init called for init some system resources, like socket, mutex...

// return flush interval(ms) and error flag, if interval is 0, use default interval

Init(Context, LogGroupQueue) (int, error)

// Description returns a one-sentence description on the Input.

Description() string

// Add the metric to the aggregator.

Add(log *protocol.Log) error

// Flush pushes the current aggregates to the accumulator.

Flush() []*protocol.LogGroup

// Reset resets the aggregators caches and aggregates.

Reset()

}

Aggregator 开发

Aggregator 的开发分为以下步骤:

1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。

2. 实现 Aggregator 接口，这里我们使用样例模式进行介绍，详细样例请查看aggregator/defaultone。

3. 通过init将插件注册到Aggregators，Aggregator插件的注册名（即json配置中的plugintype）必须以"aggregator"开头，详细样例请查看aggregator/defaultone。

4. 将插件加入插件引用配置文件的 common 配置节, 如果仅运行于指定系统，请添加到 linux 或 windows 配置节.

5. 进行单测或者E2E测试，请参考如何使用单测 与 如何使用E2E测试.

6. 使用 make lint 检查代码规范。

7. 提交Pull Request。

如何开发 Flusher 插件

Flusher 插件与外部系统进行交互，将数据发送到外部，以下将从接口定义与案例2方面指导如何开发 Flusher 插件

Flusher 接口定义

- Init: 插件初始化接口，对于Flusher 主要作用是创建外部资源链接

- Description： 插件描述

- IsReady：插件系统在调用 Flush 前会调用该接口检查当前 flusher 是否仍能够处理更多数据，如果答案为否的话，它会等待一段时间再重试。

- Flush 接口是插件系统向 flusher 插件实例提交数据的入口，用于将数据输出到外部系统。为了映射到日志服务的概念中，我们增加了三个 string 参数，它代表这个 flusher 实例所属的 project/logstore/config。详细解释请参与数据结构 与 基本结构 。

- SetUrgent： 标识iLogtail 即将退出，将系统状态传递给具体Flusher 插件，可以供Flusher 插件自动适应系统状态，比如加快输出速率等。(SetUrgent调用发生在其他类型插件的Stop之前，当前尚无有意义的实现)

- Stop：停止Flusher 插件，比如断开与外部系统交互的链接

type Flusher interface {

// Init called for init some system resources, like socket, mutex...

Init(Context) error

// Description returns a one-sentence description on the Input.

Description() string

// IsReady checks if flusher is ready to accept more data.

// @projectName, @logstoreName, @logstoreKey: meta of the corresponding data.

// Note: If SetUrgent is called, please make some adjustment so that IsReady

//   can return true to accept more data in time and config instance can be

//   stopped gracefully.

IsReady(projectName string, logstoreName string, logstoreKey int64) bool

// Flush flushes data to destination, such as SLS, console, file, etc.

// It is expected to return no error at most time because IsReady will be called

// before it to make sure there is space for next data.

Flush(projectName string, logstoreName string, configName string, logGroupList []*protocol.LogGroup) error

// SetUrgent indicates the flusher that it will be destroyed soon.

// @flag indicates if main program (Logtail mostly) will exit after calling this.

//

// Note: there might be more data to flush after SetUrgent is called, and if flag

//   is true, these data will be passed to flusher through IsReady/Flush before

//   program exits.

//

// Recommendation: set some state flags in this method to guide the behavior

//   of other methods.

SetUrgent(flag bool)

// Stop stops flusher and release resources.

// It is time for flusher to do cleaning jobs, includes:

// 1. Flush cached but not flushed data. For flushers that contain some kinds of

//   aggregation or buffering, it is important to flush cached out now, otherwise

//   data will lost.

// 2. Release opened resources: goroutines, file handles, connections, etc.

// 3. Maybe more, it depends.

// In a word, flusher should only have things that can be recycled by GC after this.

Stop() error

}

Flusher 开发

Flusher 的开发分为以下步骤:

1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。

2. 实现 Flusher 接口，这里我们使用样例模式进行介绍，详细样例请查看flusher/stdout

3. 通过init将插件注册到Flushers，Flusher插件的注册名（即json配置中的plugintype）必须以"flusher"开头，详细样例请查看flusher/stdout。 ，你可以使用 example.json 试验此插件功能。

4. 将插件加入插件引用配置文件的 common 配置节, 如果仅运行于指定系统，请添加到 linux 或 windows 配置节.

5. 进行单测或者E2E测试，请参考如何使用单测 与 如何使用E2E测试.

6. 使用 make lint 检查代码规范。

7. 提交Pull Request。

如何生成插件文档

用法

使用 comment  tag 标记的大写字符开头的字段，这些字段将会被自动提取到文档中。如果字段还有 json ,  yaml  或  mapstructure  tag 标记，字段的名称会被上述tag中的名字所替换, 此外init 注册函数设置的默认值同样会被提取到默认值字段。

type TestDoc struct {

Field1 int               `json:"field_1" comment:"field one"`

Field2 string            `json:"field_2" comment:"field two"`

Field3 int64             `json:"field_3" mapstructure:"field_33" comment:"field three"`

Field4 []string          `json:"field_4" comment:"field four"`

Field5 map[string]string `json:"field_5" comment:"field five"`

ignoreField string

}

func (t TestDoc) Description() string {

return "this is a test doc demo"

}

# test-plugin

## Description

this is a test doc demo

## Config

|  field   |   type   |   description   | default value   |

| ---- | ---- | ---- | ---- |

|field_1|int|field one|1|

|field_2|string|field two|"filed 2"|

|field_33|int64|field three|3|

|field_4|[]string|field four|["field","4"]|

|field_5|map[string]string|field five|{"k":"v"}|

生成用法

1. 执行  make docs  生成插件文档. 注意: 如果你编写的插件只运行在具体的操作系统，如linux，请在具体的操作系统环境进行执行，否则不会生成。

2. 由于文档建设目前还不完善，每次生成后会覆盖 plugin-list.md 里的插件列表，请保证此插件列表只增加您的插件，并且git 提交只新增贡献插件的插件文档文件。

纯插件模式启动

纯插件模式为iLogtail插件开发提供轻量级测试能力，以下我们将介绍如以纯插件模式启动iLogtail。

本地启动

在根目录下执行  make plugin_main  命令，会得到  output/ilogtail  可执行文件，使用以下命令可以快速启动iLogtail 程序，并将日志使用控制台输出。

# 默认插件启动行为是使用metric_mock 插件mock 数据，并将数据进行日志模式打印。

./output/ilogtail --logger-console=true --logger-retain=false

配置

iLogtail 目前提供以下4种模式进行配置设置：

- 指定配置文件模式启动。

- 文件至文件快速测试

- iLogtail 暴露Http 端口，可以进行配置变更。

- iLogtail-C程序通过程序API进行配置变更。

指定配置文件模式启动

在使用独立模式编译得到 ilogtail 这个可执行程序后，你可以通过为其指定一个配置文件（不指定的话默认为当前目录下 plugin.json）来启动它。

{

"inputs": [

{

"type": "plugin name"

"detail": {

"Parameter1": "value"

"Parameter2": 10

}

},

{ ... }

],

"processors": [ ... ],

"aggregators": [ ... ],

"flushers": [ ... ]

}

首先，如上所示，配置文件是一个标准的 JSON 文件。其中的四个顶层键分别对应于文章中所说的四类插件：

- inputs: 输入插件，获取数据。

- processors: 处理插件，对得到的数据进行处理。

- aggregators: 聚合插件，对数据进行聚合。

- flushers: 输出插件，将数据输出到指定 sink。

从它们的类型是 array 可知，在一个配置中，每类插件都可以同时指定多项，但需要注意同时指定的多个同类插件之间的关系，除了 processors 之间是串型关系以外，其他都是并行的关系，如下图所示：

对于 array 中的每一个 object，它们指定了一个个具体插件，type 字段指定插件的名字，detail 字段对应的 object 指定了对于该插件的配置。

如下是一个非常简单地示例配置文件（plugin.quickstart.json）：

- inputs: 使用 metric_mock 插件来生成 mock 数据，通过设置 detail，两个插件生成的 mock 数据将有所不同。

- processors: 使用 processor_default 插件，该插件不对数据任何操作，只是简单地返回，保持数据的原样。

- flushers: 使用 flusher_stdout 插件将数据输出到本地文件，类似地，我们也通过 detail 来将数据同时输出到两个文件。

{

"inputs":[

{

"type":"metric_mock",

"detail":{

"Index":0,

"Fields":{

"Content":"quickstart_input_1"

}

}

},

{

"type":"metric_mock",

"detail":{

"Index":100000000,

"Fields":{

"Content":"quickstart_input_2"

}

}

}

],

"processors":[

{

"type":"processor_default"

}

],

"flushers":[

{

"type":"flusher_stdout",

"detail":{

"FileName":"quickstart_1.stdout"

}

},

{

"type":"flusher_stdout",

"detail":{

"FileName":"quickstart_2.stdout"

}

}

]

}

执行  ./output/ilogtail --plugin=plugin.quickstart.json ，在一段时间后，使用 ctrl+c 中断运行。通过查看目录，会发现生成了 quickstart_1.stdout 和 quickstart_2.stdout 两个文件，并且它们的内容一致。查看内容可以发现，其中的每条数据都包含 Index 和 Content 两个键，并且由于有两个输入插件，Content 会有所不同。

文件至文件快速测试

可以使用如下指令，从文件输入数据并输出到文件，快速进行配置测试

./output/ilogtail --plugin=plugin.json --file-io=true

在测试前，需要创建上文所说的json格式的配置文件。与上文不同的是，这里的配置文件不需要配置inputs和flushers（如果配置，inputs会失效，flushers会保留）。当file-io开关被打开时，会自动指定为文件输入，并输出到文件。默认的输入文件是input.log，默认的输出文件是output.log，也可以设置input-file和output-file参数来修改输入和输出文件。

需要说明的是，读取的每行数据的fieldKey默认都是content，可以通过input-field参数来修改Field名称。输入文件并不是全部读入，而是默认从头读取1000行，可以通过修改input-line-limit参数读取需要的行数。

下面是一个简单的例子，创建一个采集配置plugin.file2filetest.json进行json解析，输入源文件是stdin.log，输出结果到stdout.log文件。

配置文件plugin.file2filetest.json如下：

{

"processors": [

{

"detail": {

"SourceKey": "content",

"KeepSource": false,

"ExpandDepth": 1,

"ExpandConnector": ""

},

"type": "processor_json"

}

]

}

stdin.log内容如下：

{"inputs":[{"type":"metric_mock","detail":{"Tags":{"tag1":"aaaa","tag2":"bbb"},"Fields":{"content":"xxxxx","time":"2017.09.12 20:55:36"}}}],"flushers":[{"type":"flusher_stdout"}]}

执行如下命令：

./output/ilogtail --plugin=plugin.file2filetest.json --file-io=true --input-file=stdin.log --output-file=stdout.log

可以发现生成了一个stdout.log文件，内容如下：

2023-05-23 11:33:48 {"inputs":"[{\"type\":\"metric_mock\",\"detail\":{\"Tags\":{\"tag1\":\"aaaa\",\"tag2\":\"bbb\"},\"Fields\":{\"content\":\"xxxxx\",\"time\":\"2017.09.12 20:55:36\"}}}]","flushers":"[{\"type\":\"flusher_stdout\"}]","__time__":"1684841628"}

HTTP API 配置变更

当iLogtail 以独立模式运行时，可以使用HTTP API 进行配置文件变更。

- 端口： iLogtail 独立运行时，默认启动18689 端口进行监听配置输入。

- 接口：/loadconfig

接下来我们将使用HTTP 模式重新进行动态加载指定配置文件模式启动篇幅中的静态配置案例。

1. 首先我们启动 iLogtail 程序：  ./output/ilogtail

2. 使用以下命令进行配置重新加载。

curl 127.0.0.1:18689/loadconfig -X POST -d '[{"project":"e2e-test-project","logstore":"e2e-test-logstore","config_name":"test-case_0","logstore_key":1,"json_str":"{\"inputs\":[{\"type\":\"metric_mock\",\"detail\":{\"Index\":0,\"

Fields\":{\"Content\":\"quickstart_input_1\"}}},{\"type\":\"metric_mock\",\"detail\":{\"Index\":100000000,\"Fields\":{\"Content\":\"quickstart_input_2\"}}}],\"processors\":[{\"type\":\"processor_default\"}],\"flushers\":[{\"type\":\"flusher_stdout\",\"detail\":{\"FileName\":\"quickstart_1.stdout\"}},{\"type\":\"flusher_stdout\",\"detail\":{\"FileName\":\"quickstart_2.stdout\"}}]}\n"}]'

3. 查看日志观察到配置变更。

2021-11-15 14:38:42 [INF] [logstore_config.go:113] [Start] [logtail_alarm,logtail_alarm]        config start:begin

2021-11-15 14:38:42 [INF] [logstore_config.go:151] [Start] [logtail_alarm,logtail_alarm]        config start:success

2021-11-15 14:38:42 [INF] [logstore_config.go:113] [Start] [test-case_0,e2e-test-logstore]      config start:begin

2021-11-15 14:38:42 [INF] [logstore_config.go:151] [Start] [test-case_0,e2e-test-logstore]      config start:success

4. 通过查看目录，会发现行为与上述静态配置方式一致，生成了 quickstart_1.stdout 和 quickstart_2.stdout 两个文件，并且它们的内容一致。

C API 配置变更

以C-shared模式编译，与C程序结合使用，对外开放API参考 plugin_export.go。

测试

单元测试

C++单元测试

C++部分单测基于 gtest 实现，具体编写方法可以参考已有测试用例。

单测覆盖率统计

在开发镜像中，内置了C++单测覆盖率统计工具 gcovr，可以通过以下命令在本地查看覆盖率。

1. 进入开发容器中，参考开发环境。

2. CMake 设置参数 BUILD_LOGTAIL_UT=ON，编译单测

cmake -DBUILD_LOGTAIL_UT=ON <其他编译参数> ..

3. 运行脚本  ./scripts/run_core_ut.sh ，运行单测

4. 生成覆盖率报告

mkdir -p coverage-report

# 生成详细的报告

gcovr -r ./core --txt coverage-report/index.txt --html-details --html coverage-report/index.html -e ".*sdk.*" -e ".*observer.*" -e ".*log_pb.*" -e ".*unittest.*" -e ".*config_server.*" -e ".*fuse.*" -e ".*go_pipeline.*"

# 生成本次commit diff的报告

python3 tools/coverage-diff/main.py coverage-report/index.txt

Go插件单元测试

测试框架

如何需要一些测试指令，比如  assert ,  require ,  mock  以及  suite ，可以使用这个包协助你进行测试：  github.com/stretchr/testify 。更多使用方法可以查看 使用说明。

测试工具

从插件开发以及 日志打印 篇幅可以看到，ilogtail.Context 接口包含了iLogtail 的元配置信息，因此提供了Mock Context 以及Mock Collector 实现进行单元测试。

import (

"github.com/stretchr/testify/assert"

"github.com/alibaba/ilogtail/pkg/pipeline"

"github.com/alibaba/ilogtail/plugins/test"

"github.com/alibaba/ilogtail/plugins/test/mock"

"testing"

)

func TestInputSystem_CollectOpenFD(t *testing.T) {

cxt := mock.NewEmptyContext("project", "store", "config")

p := pipeline.MetricInputs["metric_system_v2"]().(*InputSystem)

_, err := p.Init(cxt)

assert.NoError(t, err, "cannot init the mock process plugin: %v", err)

c := &test.MockMetricCollector{}

p.CollectOpenFD(c)

assert.Equal(t, 2, len(c.Logs))

m := make(map[string]string)

for _, log := range c.Logs {

for _, content := range log.Contents {

if content.Key == "__name__" {

m[content.Value] = "exist"

}

}

}

assert.NotEqual(t, "", m["fd_allocated"])

assert.NotEqual(t, "", m["fd_max"])

}

测试插件行为

如果需要日志的方式进行验证插件具体行为，可以参加日志功能高级用法

E2E测试

iLogtail提供了一个完整的E2E测试引擎，方便您快速开展集成测试，从而进一步保证代码质量。在大部分情况下，您只需要编写一个配置文件来定义测试行为，即可轻松完成测试。

工作原理

E2E测试采用行为驱动开发（Behavior-Driven Development）的设计思路，通过定义一系列测试行为，并通过配置文件的方式来描述测试场景，从而实现对插件的集成测试。测试引擎会根据配置文件中的内容，正则匹配对应的函数，并解析配置文件中的参数，传递给对应的函数。从而完成自动创建测试环境、启动iLogtail、触发日志生成、验证日志内容等一系列操作，最终输出测试报告。 相关参考：

- https://cucumber.io/docs/bdd/

- https://github.com/cucumber/godog

测试流程

环境准备

在准备开始进行集成测试前，您首先需要准备以下内容：

- 测试环境：主机（可通过SSH访问）、K8s集群（可通过kubeconfig访问）、Docker-Compose环境（需在本地安装docker-compose）

- 部署 iLogtail

配置文件

对于每一个新的功能，您都需要在./test/e2e/test_cases目录下创建一个新的feature配置文件。每个配置文件中可以包含多个测试场景，每个测试场景由一个或多个步骤组成。

配置文件的基本框架如下所示：

@input

Feature: input static file

Test input static file

@e2e @docker-compose

Scenario: TestInputStaticFile

Given {docker-compose} environment

Given subcribe data from {grpc} with config

"""

"""

Given {input-static-file-case} local config as below

"""

enable: true

global:

UsingOldContentTag: true

DefaultLogQueueSize: 10

inputs:

- Type: input_file

FilePaths:

- "/root/test/**/a*.log"

MaxDirSearchDepth: 10

"""

Given iLogtail container mount {./a.log} to {/root/test/1/2/3/axxxx.log}

When start docker-compose {input_static_file}

Then there is at least {1000} logs

Then the log fields match kv

"""

"__tag__:__path__": "^/root/test/1/2/3/axxxx.log$"

content: "^\\d+===="

"""

- Feature 定义了一个测试功能，下面为这个功能的描述信息。在 Feature 下可以定义多个测试场景。

- Scenario 定义了一个测试场景。在 Scenario 下可以定义多个行为。

- 行为定义分为三类：

- Given ：定义了一些准备测试条件的行为。

- When ：定义了一些触发测试条件的行为。

- Then ：定义了一些验证测试条件的行为。

- 行为中使用 {} 作为标识符，该部分内容将作为参数，传递给对应的Go函数。

- @ 表示一个tag，在运行测试时，会根据tag的不同，分别运行。除了自定义的tag外，测试框架定义了一些默认的tag：

- @e2e ：表示该测试场景为E2E测试。

- @regression ：表示该测试场景为回归测试。

- @host ：表示该测试场景在host环境下运行。

- @k8s ：表示该测试场景在k8s环境下运行。

- @docker-compose ：表示该测试场景在本地启动docker-compose运行

运行测试

在所有测试内容准备完毕后，您可以直接在test目录下以go test的方式运行E2E测试。根据您的需求，可以选择运行所有测试或者指定测试。

# 运行所有测试

go test -v -timeout 30m -run ^TestE2EOnDockerCompose$ github.com/alibaba/ilogtail/test/e2e

# 运行指定测试，以input_canal为例

TEST_CASE=input_canal go test -v -timeout 30m -run ^TestE2EOnDockerCompose$ github.com/alibaba/ilogtail/test/e2e

拓展

如果目前engine中已有的测试行为无法满足您的需求，您可以参考以下添加指南，自行拓展测试行为。

代码检查

检查代码规范

检查Go代码规范

LogtailPlugin 使用 golangci-lint 检查代码风格。  SCOPE  定义是 可选，默认范围是根目录。

SCOPE=xxx make lint

xxx为限定的目录名称。

检查文件许可证

LogtailPlugin 遵循标准的 Apache 2.0 许可，所有文件必须具有许可证声明。 所以贡献者应该检查贡献的文件是否拥有此许可证。

检查许可证

如果要检查整个项目文件，请运行以下命令。 没有许可证的文件将被找到并保存为 license_coverage.txt。

make check-license

当需要固定范围时，请在命令中附加 SCOPE 。

SCOPE=xxx make check-license

xxx为限定的目录名称。

添加许可证

当某些带有许可证的文件建立后，您可以通过以下方式将许可证添加到文件中。 请注意，这种方式将修复所有缺少许可证的文件。

make license

同上，如果你想限制变化范围，请在命令中附加 SCOPE 。

SCOPE=xxx make license

xxx为限定的目录名称。

检查依赖包许可证

iLogtail 基于Apache 2.0 协议进行开源，开发者需要保证依赖包协议与Apache 2.0 协议兼容，所有依赖包或源码引入License 说明位于根目录  licenses  文件夹。

检查依赖包License

开发者可以使用以下命令进行依赖包License 扫描。

make check-dependency-licenses

- 当提示  DEPENDENCIES CHECKING IS PASSED  时，说明依赖包检查通过。

- 当提示  FOLLOWING DEPENDENCIES SHOULD BE ADDED to LICENSE_OF_ILOGTAIL_DEPENDENCIES.md  时，说明依赖包将需要被添加（需要保证协议与Apache 2.0 协议兼容），可以查看  find_licenses/LICENSE-{liencese type} 文件查看待添加依赖包协议。

- 当提示  FOLLOWING DEPENDENCIES IN LICENSE_OF_ILOGTAIL_DEPENDENCIES.md SHOULD BE REMOVED  时，说明存在多余的依赖包，按提示进行删除即可。

Fork 代码库管理

出于某些特性不支持原因，或精简依赖包原因，iLogtail 会存在某些Fork代码库，所有Fork代码库存在于iLogtail组织进行管理，出于License风险问题，禁止引入私人Fork版本。

go.mod 管理

1. Fork 仓库： 对于Fork代码库，出于尊重原作者，禁止修改go.mod 仓库module地址，如样例所示。

2. iLogtail仓库: iLogtail 仓库对于Fork代码库要求使用replace 方式引入，用以保持代码文件声明的引入包地址保持原作者仓库地址。

require (

github.com/VictoriaMetrics/metrics v1.23.0

)

replace (

github.com/VictoriaMetrics/metrics => github.com/iLogtail/metrics v1.23.0-ilogtail

)

License 声明

请执行 make check-dependency-licenses  指令，脚本程序将自动在find_licenses文件夹生成markdown 说明，请将说明放置于LICENSE_OF_ILOGTAIL_DEPENDENCIES.md文件末端，如下样例。

## iLogtail used or modified source code from these projects

- [github.com/iLogtail/VictoriaMetrics fork from github.com/VictoriaMetrics/VictoriaMetrics](http://github.com/iLogtail/VictoriaMetrics) based on Apache-2.0

- [github.com/iLogtail/metrics fork from github.com/VictoriaMetrics/metrics](http://github.com/iLogtail/metrics) based on MIT

建议

如Fork 特性为原代码库的能力补充，非特定场景如精简依赖包等因素，建议对原始代码库提出PullRequest, 如原始仓库接受此次PullRequest，请将iLogtail 仓库依赖包地址修改为原始仓库地址，并删除Fork仓库。

贡献指南

欢迎来到 iLogtail 的社区！感谢您为iLogtail贡献代码、文档及案例！

iLogtail 自从开源以来，受到了很多社区同学的关注。社区的每一个 Issue、每一个 pull request (PR)，都是在为 iLogtail 的发展添砖加瓦。衷心地希望越来越多的社区同学能参与到 iLogtail 项目中来，跟我们一起把 iLogtail 做好。

行为准则

参与 iLogtail 社区贡献，请阅读并同意遵守阿里巴巴开源行为准则，共同营造一个开放透明且友好的开源社区环境。

贡献流程

我们随时欢迎任何贡献，无论是简单的错别字修正，BUG 修复还是增加新功能，包括但不限于代码、文档、案例等任何形式的社区互动。我们也同样重视与其它开源项目的结合，欢迎在这方面做出贡献。

如何入手？

如果您是初次贡献，可以先从 good first issue 列表中认领一个相对小的任务来快速参与社区贡献。

认领方式: 您可以直接在相应 Issue 中回复参与意愿，然后参照下面的 GitHub 工作流指引解决 issue 并按照规范提交 PR，通过 review 后即可合入到 main 分支。

GitHub 完整工作流

我们使用 main 分支作为我们的开发分支，这代表它是不稳定的分支。稳定版本归档在 Release 中，每发布一个 Release 版本，都会打上对应版本 Tag。

创建/认领 Issue

我们使用 GitHub Issues 以及 Pull Requests 来管理/追踪需求或者问题。如果您希望开发新的特性、功能完善，或者发现了代码的 BUG，或者文档的增加、完善，或者希望提建议等，都可以创建一个 Issue；也可以认领我们发布出来的一些 Issue。

新建的 Issue 请按照模板规范填写内容，以便我们更好地理解您需求。另外，也需要您打上对应标签，方便我们进行分类管理。

设计交流

如果您的 PR 包含非常大的变更(比如模块的重构或者添加新的组件)，请务必发起详细讨论，编写详细的文档来阐述其设计、解决的问题和用途，达成一致后再进行变更。您可以在 Issue 或 Discussions ideas 中给出详细的设计。如果需要我们的支持可以扫描加入钉钉群，我们可以提供一对一的交流。

对于一些小的变更，也请在 Issue 中简单描述您的设计。

开发测试

设计定稿后，即可进行开发流程。下面是开源贡献者常用的工作流（workflow）：

1. 将 iLogtail 仓库 fork 到个人 GitHub 下。

2. 基于个人 fork 分支进行开发、测试工作。详细流程：

1. 保持个人 main 分支跟 iLogtail 主仓库 main 分支及时同步。

2. 将 fork 后的个人仓库 clone 到本地。

3. 创建新的开发分支，并进行开发。请确保对应的变更都有 UnitTest 或 E2E 测试。

4. 在本地提交变更。注意 commit log 保持简练、规范，提交的 email 需要和 GitHub 的 email 保持一致。

5. 将变更 push 到远程个人分支。

3. 向 iLogtail main 分支创建一个 pull request (PR)，在进行较大的变更的时候请确保 PR 有一个对应的 Issue，并进行关联。

1. 发起 PR 前请进行如下规范性检查：代码/文档风格、编码规范、依赖包许可证、文件许可证。

2. 为了更好的进行版本管理，对于一些独立的特性或者关键BUG修复，请提交Changelog.

注意一个 PR 尽量不要过于大，如果的确需要有大的变更，可以将其按功能拆分成多个单独的 PR。

若您是初次提交 PR，请先签署 CLA（PR 页面会有自动回复指引）。在提交 PR 后，系统会运行持续集成，请确保所有的 CI 均为 pass 状态。一切就绪后，我们会为 PR 分配一个或多个 reviewer，review通过后即可合入 main。

在合并 PR 的时候，请把多余的提交记录都 squash 成一个，保证最终的提交信息的简练、规范。

标签

我们使用标签来进行 Issue、PR、Discussion 的管理。您可以根据实际情况打上对应的标签。

- 全新特性，对应 label: feature request。

- 现有功能完善，对应 label: enhancement。

- 适合新手开发，对应 label: good first issue。

- Bug，对应 label: bug。

- 测试框架或测试用例，对应 label: test。

- 配置样例或K8s部署案例，对应 label: example config。

- 文档（document），对应 label: documentation。

- 案例类，对应 label: awesome ilogtail。

- 回答、解决问题，对应 label: question。我们建议优先提到 Discussions 中讨论。

以下为附加标签：

- 希望社区参与贡献，对应 label: community。

- 核心功能开发或变更，对应 label: core。

Code review

所有的代码都需要经过 committer 进行 review。以下是我们推荐的一些原则：

- 可读性：所有提交请遵循我们的代码规范、文档规范。

- 优雅性：代码简练、复用度高，有着完善的设计。

- 测试：重要的代码需要有完善的测试用例（单元测试、E2E 测试），对应的衡量标准是测试覆盖率。

配置分享

除了共享代码，您也可以为我们的配置样板库做出贡献。

example_config/data_pipelines 目录包含场景化的采集配置模版，重点突出processor / aggregator插件功能。如您对某些常见日志（如Apache、Spring Boot）的处理有一定心得，可以参考已有样例和README进行提交。

k8s_templates 目录包含完整的K8s部署案例，从源到典型处理到输出，以input / flusher插件进行划分。如您对某些常见的日志处理场景（如将数据采集到Elastic Search、Clickhouse）的部署有一定心得，可以参考已有样例和README进行提交。

案例分享

我们也欢迎您分享任何关于 iLogtail 的使用案例。我们在知乎建立了专栏 iLogtail社区，欢迎大家投稿，分享 iLogtail 的使用案例。

1. 在知乎写文章，例如一文搞懂 SAE 日志采集架构。

2. 推荐自己的文章到“iLogtail社区”专栏。

3. GitHub上修改use-cases.md并发起PR，Label选awesome ilogtail。

参与社区讨论

如果您在使用 iLogtail 中遇到任何问题，欢迎到 Discussions 进行交流互动。也欢迎在这里帮助其他使用者解答一些使用中的问题。

Discussion 分类：

- Announcements：iLogtail官方公告。

- Help：使用 iLogtail 中遇到问题，想在社区寻求帮助。

- Ideas：关于 iLogtail 的一些想法，欢迎随时交流。

- Show and tell：可以在这里展示任何跟 iLogtail 相关的工作，例如一些小工具等。

联系我们

开发者

社区角色

iLogtail 社区包含 Maintainer、Committer、Contributor、User 等角色，每种角色的标准定义如下。

Maintainer：是对 iLogtail 项目的演进和发展做出显著贡献的个人。

- 成为 Maintainer 的标准：

- 完成多个关键模块或者工程的设计与开发，是项目的核心开发人员；

- 持续的投入和激情，能够积极参与社区、官网、Issue、Pull Request(PR) 、Discussion 等项目相关事项的维护；

- 在社区中具有有目共睹的影响力，能够代表 iLogtail 参加重要的社区会议和活动。

- 成为 Maintainer，您也将获得如下权利：

- 具有 iLogtail GitHub 仓库管理权限。

- 参与新晋 Committer 或 Maintainer 的提名及投票。

Committer：是对 iLogtail 社区某些特定领域做出显著贡献的人。

- 成为 Maintainer 的标准：

- 成为某个模块的专家，能够长时间地并持续性地贡献 Issue、PR （代码、测试用例、文档、案例）；

- 参与重要 Feature 的讨论、设计、开发、测试；

- 参与 Code Review。

- 成为 Maintainer，您也将获得如下权利：

- 具有 iLogtail GitHub 仓库 Write 权限。

- 参与 iLogtail 演进、发展的讨论，及核心模块设计评审等。

Contributor：是对 iLogtail 项目有贡献的个人。

- 成为 Contributor 的标准：

- 提交过 PR 并被合并，包括不限于文档、代码、案例等；

- 在 iLogtail 开源社区参与相关问题讨论，并能积极回复。

User：通过使用 iLogtail 社区版构建自己的业务架构的开发者。

如何成为 Contributor 及 Committer？

只要您对 iLogtail 项目有兴趣，每个人都可以成为 iLogtail 项目的贡献者 (Contributor)。可以从贡献文档 或 回答社区问题（礼貌地）开始参与社区贡献，并逐步参与代码的贡献。更多详见 如何贡献。

如果您能够持续地对 iLogtail 项目进行有价值的贡献，达到了 Committer 的要求，那么接下来就是找到一个项目的 PMC 来提名你为 Committer，经PMC成员投票通过后，即可成为 iLogtail 社区的 Committer。

总之，您需要在 iLogtail 社区建立影响力和发言权，积极参与任何形式的社区建设，让其他人认可你的贡献，并愿意与你建立信任关系。成为 Committer 是一个荣誉与责任共存的事情，成为 Committer 不是终点，而是一个更高的起点。

iLogtail 的开发团队

感谢所有开发者对社区的贡献！我们会定期将所有贡献者的名字进行展示，当然也可以自己提交 PR 添加。

注：排名不分先后。如有遗漏，请提交 PR 添加。

PMC(项目管理委员会，Project Management Committee)

- Kejia Xu(@messixukejia)

- Tao Yu(@yyuuttaaoo)

- Jiapeng Liu(@EvanLjp)

- Cheng Zhang(@shabicheng)

- Goclis Yao(@Goclis)

- Haoyang Liu(@liuhaoyang)

Committer

- Runqi Lin(@linrunqi08)

- Qiansheng(@qiansheng91)

- Yonghua Sun(@yonghua-sun)

- Haoxiang Zhang(@henryzhx8)

- Gangping Guo(@snakorse)

- Yu Sun(@shalousun)

- Shunjia Zhu(@shunjiazhu)

Contributor

https://github.com/alibaba/ilogtail/graphs/contributors

成就

Junior Developer

成功提交1次任意 PR，并被社区接受。

- Cheng Zhang(@shabicheng)

- Goclis Yao(@Goclis)

- Qian Sheng(@qiansheng91)

- Yonghua Sun(@yonghua-sun)

- Weilong Pan(@panawala)

- Haorui(@haoruilee)

- Chao Lee(@chaolee50)

- Jinchen(@pj1987111)

- timchenxiaoyu(@timchenxiaoyu)

- Doslin(@Doslin)

- Howie(@Howie59)

- Xiaolei Wang(@fatelei)

- Lework(@lework)

- niuttt(@tong549761863)

- mrddz(@mrddz)

- TDAkory(@TDAkory)

- XLPE(@XLPE)

- chenxujun(@co63oc)

- william(@panawala)

- codingdancer(@codingdancer)

- timchenxiaoyu(@timchenxiaoyu)

- urnotsally(@urnotsally)

- Minxiang Du(@kl7sn)

- Zhu Shunjia(@shunjiazhu)

Senior Developer

解决至少10个PR或2个重大PR，并被社区接受（统计commit对应PR数量）。

- Kejia Xu(@messixukejia)

- Tao Yu(@yyuuttaaoo)

- Jiapeng Liu(@EvanLjp)

- Haoxiang Zhang(@henryzhx8)

- Haoyang Liu(@liuhaoyang)

- Zehua Yang(@Takuka0311)

- Runqi Lin(@linrunqi08)

- Gangping Guo(@snakorse)

- Yu Sun(@shalousun)

Junior Ambassador

为iLogtail做出至少1次宣传。

- Haoxiang Zhang(@henryzhx8)

- Weilong Pan(@panawala)

- Jinchen(@pj1987111)

- niuttt(@tong549761863)

Senior Ambassador

为iLogtail做出至少5次宣传（统计awesome ilogtail tag的issue）。

- Kejia Xu(@messixukejia)

- Cheng Zhang(@shabicheng)

- Tao Yu(@yyuuttaaoo)

Junior Moderator

在论坛中回答问题，并获得至少1个被接受答案。

- Tao Yu(@yyuuttaaoo)

- Haoxiang Zhang(@henryzhx8)

- XLPE(@XLPE)

- Gangping Guo(@snakorse)

- Jiapeng Liu(@EvanLjp)

- Weilong Pan(@panawala)

- Yu Sun(@shalousun)

- Zehua Yang(@Takuka0311)

- bad-youngster(@bad-youngster)

- Shiyao Liu(@hanzoi)

- mcy567(@mcy567)

Senior Moderator

在论坛中回答问题，并获得至少10个被接受答案（统计accepted的answer数量）。

- Kejia Xu(@messixukejia)

证书展示

您可以在GitHub的个人档案档案中展示所获得的证书，向您的小伙伴展示您所取得的成就。就像这样：

全部6种徽章的代码如下，请自行裁剪：

<p align="center">

<!-- 初级开发者 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#junior-developer"><img alt="Junior Developer" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Jr.Dev.png" /></a>

<!-- 高级开发者 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#senior-developer"><img alt="Senior Developer" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Sr.Dev.png" /></a>

<!-- 初级布道师 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#junior-ambassador"><img alt="Junior Ambassador" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Jr.Amb.png" /></a>

<!-- 高级布道师 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#senior-ambassador"><img alt="Senior Ambassador" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Sr.Amb.png" /></a>

<!-- 初级答题王 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#junior-moderator"><img alt="Junior Moderator" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Jr.Mod.png" /></a>

<!-- 高级答题王 -->

<a href="https://github.com/alibaba/ilogtail/blob/main/docs/cn/contributing/achievement.md#senior-moderator"><img alt="Senior Moderator" width="200" height="200" src="https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/contributing/achievement/Sr.Mod.png" /></a>

</p>

容器场景iLogtail与Filebeat性能对比测试

前言

前段时间, iLogtail（https://github.com/alibaba/ilogtail）阿里千万实例可观测采集器开源，其中介绍了iLogtail采集性能可以达到单核100MB/s，相比开源采集Agent有5-10倍性能优势。很多小伙伴好奇iLogtail具体的性能数据和资源消耗如何，本文将针对目前业界使用度较高且性能相对较优的Agent FileBeat进行对比，测试这两个Agent在不同压力场景下的表现如何。

测试试验描述

随着Kubernetes 普及，Kubernetes 下的日志收集的需求也日益常态化，因此下文将分别进行容器标准输出流采集与容器内静态文件采集对比试验（使用静态文件采集的小伙伴可以参考容器内静态文件采集对比试验, iLogtail 纯静态文件采集会略优于试验2容器内文件静态采集），试验项具体如下：

- 实验1：恒定采集配置4，Filebeat & iLogtail 在原始日志产生速率 1M/s、2M/s、 3M/s 下的标准输出流采集性能对比。

- 实验2：恒定采集配置4，Filebeat & iLogtail 在原始日志产生速率 1M/s、2M/s、 3M/s 下的容器内文件采集性能对比。

而在真实的生产环境中，日志采集组件的可运维性也至关重要，为运维与后期升级便利，相比于Sidecar模式，K8s下采用Daemonset模式部署采集组件更加常见。但由于Daemonset 同时将整个集群的采集配置下发到各个采集节点的特性，单个采集节点正在工作的配置必定小于全量采集配置数目，因此我们还会进行以下2部分试验，验证采集配置的膨胀是否会影响采集器的工作效率：

- 实验3：恒定输入速率3M/s，Filebeat & iLogtail 在采集配置50、100、500、1000 份下的标准输出流采集性能对比。

- 实验4：恒定输入速率3M/s，Filebeat & iLogtail 在采集配置50、100、500、1000 份下的容器内文件采集性能对比。

最后会进行iLogtail 的大流量压测，具体如下：

- 实验5：iLogtail 在 5M/s、10M/s、10M/s、40M/s 下的标准输出流采集性能。

- 实验5：iLogtail 在 5M/s、10M/s、10M/s、40M/s 下的容器内文件采集性能。

试验环境

所有采集环境数据存储于https://github.com/EvanLjp/ilogtail-comparison， 感兴趣的同学可以自己动手进行整个对比测试实验， 以下部分分别描述了不同采集模式的具体配置，如果只关心采集对比结果，可以直接跳过此部分继续阅读。

环境

运行环境：阿里云ACK Pro 版本 节点配置：ecs.g6.xlarge (4 vCPU 16GB) 磁盘ESSD 底层容器：Containerd iLogtail版本：1.0.28 FileBeat版本：v7.16.2

数据源

对于数据源，我们首先去除因正则解析或多行拼接能力带来的差异，仅仅以最基本的单行采集进行对比，数据产生源模拟产生nginx访问日志，单条日志大小为283B，以下配置描述了1000条/s 速率下的输入源：

apiVersion: batch/v1

kind: Job

metadata:

name: nginx-log-demo-0

namespace: default

spec:

template:

metadata:

name: nginx-log-demo-0

spec:

restartPolicy: Never

containers:

- name: nginx-log-demo-0

image: registry.cn-hangzhou.aliyuncs.com/log-service/docker-log-test:latest

command: ["/bin/mock_log"]

args:  ["--log-type=nginx",  "--path=/var/log/medlinker/access.log", "--total-count=1000000000", "--log-file-size=1000000000", "--log-file-count=2", "--logs-per-sec=1000"]

volumeMounts:

- name: path

mountPath: /var/log/medlinker

subPath: nginx-log-demo-0

resources:

limits:

memory: 200Mi

requests:

cpu: 10m

memory: 10Mi

volumes:

- name: path

hostPath:

path: /testlog

type: DirectoryOrCreate

nodeSelector:

kubernetes.io/hostname: cn-beijing.192.168.0.140

Filebeat 标准输出流采集配置

Filebeat 原生支持容器文件采集，通过add_kubernetes_metadata组件增加kubernetes 元信息，为避免输出组件导致的性能差异，通过drop_event插件丢弃数据，避免输出，filebeat测试配置如下（harvester_buffer_size 调整设置为512K，filebeat.registry.flush: 30s，queue.mem 参数适当扩大，增加吞吐）：

filebeat.yml: |-

filebeat.registry.flush: 30s

processors:

- add_kubernetes_metadata:

host: ${NODE_NAME}

matchers:

- logs_path:

logs_path: "/var/log/containers/"

- drop_event:

when:

equals:

input.type: container

output.console:

pretty: false

queue:

mem:

events: 4096

flush.min_events: 2048

flush.timeout: 1s

max_procs: 4

filebeat.inputs:

- type: container

harvester_buffer_size: 524288

paths:

- /var/log/containers/nginx-log-demo-0-*.log

Filebeat 容器文件采集配置

Filebeat 原生不支持容器内文件采集，因此需要人工将日志打印路径挂载于宿主机HostPath，这里我们使用 subPath以及DirectoryOrCreate功能进行服务打印路径的分离, 以下为模拟不同服务日志打印路径独立情况。 filebeat 使用基础日志读取功能读取/testlog路径下的日志，为避免输出组件导致的性能差异，通过drop_event插件丢弃数据，避免输出，测试配置如下（harvester_buffer_size 调整设置为512K，filebeat.registry.flush: 30s，queue.mem 参数适当扩大，增加吞吐）：

filebeat.yml: |-

filebeat.registry.flush: 30s

output.console:

pretty: false

queue:

mem:

events: 4096

flush.min_events: 2048

flush.timeout: 1s

max_procs: 4

filebeat.inputs:

- type: log

harvester_buffer_size: 524288

paths:

- /testlog/nginx-log-demo-0/*.log

processors:

- drop_event:

when:

equals:

log.file.path: /testlog/nginx-log-demo-0/access.log

iLogtail 标准输出流采集配置

iLogtail 原生同样支持标准输出流采集，service_docker_stdout 组件已经会提取kubernetes 元信息，为避免输出组件导致的性能差异，通过processor_filter_regex，进行所有日志的过滤，测试配置如下：

{

"inputs":[

{

"detail":{

"ExcludeLabel":{

},

"IncludeLabel":{

"io.kubernetes.container.name":"nginx-log-demo-0"

}

},

"type":"service_docker_stdout"

}

],

"processors":[

{

"type":"processor_filter_regex",

"detail":{

"Exclude":{

"_namespace_":"default"

}

}

}

]

}

iLogtail 容器文件采集配置

iLogtail 原生支持容器内文件采集，但由于文件内采集元信息存在于tag标签，暂无过滤插件，为避免输出组件导致的性能差异，因此我们使用空输出插件进行输出，测试配置如下：

{

"metrics":{

"c0":{

"advanced":{

"k8s":{

"IncludeLabel":{

"io.kubernetes.container.name":"nginx-log-demo-0"

}

}

},

......

"plugin":{

"processors":[

{

"type":"processor_default"

}

],

"flushers":[

{

"type":"flusher_statistics",

"detail":{

"RateIntervalMs":1000000

}

}

]

},

"local_storage":true,

"log_begin_reg":".*",

"log_path":"/var/log/medlinker",

......

}

}

}

Filebeat与iLogtail对比测试

Filebeat 与 iLogtail 的对比项主要包含以下内容：标准输出流采集性能、容器内文件采集性能、标准输出流多用户配置性能、容器内文件多用户配置性能以及大流量采集性能。

标准输出流采集性能对比

输入数据源: 283B/s, 底层容器contianerd，标准输出流膨胀后为328B， 共4个输入源：

- 1M/s 输入日志3700条/s,

- 2M/s 输入日志7400条/s,

- 3M/s 输入日志条11100条/s。

以下显示了标准输出流不同采集的性能对比，可以看到iLogtail相比于Filebeat 有十倍级的性能优势（CPU的百分比为单核的百分比）：

Filebeat

ILogtail

1M/s

20%

2%

2M/s

37%

3.3%

3M/s

52%

4.1%

以下显示了标准输出流不同采集的内存对比，可以看到logtail 和filebeat 整体内存相差不大，没有出现随采集流量上升内存暴涨情况：

Filebeat

ILogtail

1M/s

136M

90M

2M/s

134M

90M

3M/s

144M

90M

容器内文件采集性能对比

输入数据源: 283B/s, 共4个输入源：

- 1M/s 输入日志3700条/s,

- 2M/s 输入日志7400条/s,

- 3M/s 输入日志条11100条/s。

以下显示了容器内文件不同采集的性能对比，Filebeat 容器内文件由于与container 采集共用采集组件，并省略了Kubernets meta 相关组件，所以相比于标准输出流采集有大性能提升，iLogtail 的容器内文件采集采用Polling + inotify机制，同样相比于容器标准输出流采集有性能提升， 但可以看到iLogtail相比于Filebeat 有5倍级的性能优势（CPU的百分比为单核的百分比）：

Filebeat

ILogtail

1M/s

5%

1.3%

2M/s

11%

2%

3M/s

15%

3%

以下显示了标准输出流不同采集的内存对比，可以看到logtail 和filebeat 整体内存相差不大，没有出现随采集流量上升内存暴涨情况：

Filebeat

ILogtail

1M/s

136M

126M

2M/s

140M

141M

3M/s

141M

142M

采集配置膨胀性能对比

采集配置膨胀性能对比，输入源设置为4，总输入速率为3M/s, 分别进行50采集配置，100采集配置，500采集配置，1000采集配置 对比。

标准输出流采集配置膨胀对比

以下显示了标准输出流不同采集的性能对比，可以看到Filebeat 由于容器采集与静态文件采集底层共用相同静态文件采集逻辑，会在标准输出流采集路径var/log/containers下存在大量正则匹配的工作，可以看到虽然采集数据量没有增加由于采集配置的增加，CPU消耗增加10%+，而iLogtail 针对容器采集模型全局共享容器路径发现机制，所以避免了正则逻辑带来的性能损耗（CPU的百分比为单核的百分比）。

采集配置

Filebeat

ILogtail

50

65%

5%

100

68%

6.30%

500

75%

7%

1000

82%

8.70%

在内存膨胀方面，可以看到不论是Filebeat 还是iLogtail 都存在由于采集配置增加导致的内存膨胀，但2者的膨胀大小都处于可接受范围。

采集配置

Filebeat

ILogtail

50

148M

95M

100

149M

98M

500

163M

115M

1000

177M

149M

容器内文件采集配置膨胀对比

以下显示了容器内文件采集不同采集器的性能对比，可以看到Filebeat 静态文件采集由于避免标准输出流通用路径正则，相较于标准增加CPU消耗较少，而iLogtail CPU 变化同样很小，且相比于标准输出流采集性能略好（CPU的百分比为单核的百分比）。

采集配置

Filebeat

ILogtail

50

16%

4.30%

100

16.30%

4.30%

500

20.00%

5.60%

1000

22%

7.30%

在内存膨胀方面，同样可以看到不论是Filebeat 还是iLogtail 都存在由于采集配置增加导致的内存膨胀，但2者的膨胀大小都处于可接受范围。

采集配置

Filebeat

ILogtail

50

142M

99M

100

145M

104M

500

164M

128M

1000

183M

155M

iLogtail 采集性能测试

由于FileBeat在日志量大的场景下出现采集延迟问题，所以以下场景仅针对iLogtail进行测试，分别在5M/s、10M/s、20M/s 下针对iLogtail 进行容器标准输出流采集与容器内文件采集的性能压测。

- 输入源数量：10

- 单条日志大小283B

- 5M/s 对应日志速率 18526条/s，单输入源产生速率1852条/s

- 10M/s 对应日志速率 37052条/s，单输入源产生速率3705条/s

- 20M/s 对应日志速率 74104条/s，单输入源产生速率7410条/s

- 40M/s 对应日志速率 148208条/s，单输入源产生速率14820条/s

和上述试验类似可以看到CPU消耗方面容器文件采集略好于容器标准输出流采集性能（CPU的百分比为单核的百分比），主要是由于容器文件采集底层Polling + inotify机制，感兴趣的同学可以阅读Logtail技术分享一了解更多内容。

速率

容器文件采集

标准输出流采集

5M/s

5.70%

4.70%

10M/s

10.00%

10.30%

20M/s

15.00%

18.70%

40M/s

22%

36%

在内存方面，由于标准输出流采集主要依赖于GO，而容器文件采集主要依赖于C，可以由于GC机制的存在，随着速率的上升，标准输出流采集消耗的内存会逐渐超过容器内文件采集消耗的内存。

速率

容器文件采集

标准输出流采集

5M/s

148M

100M

10M/s

146M

130M

20M/s

147M

171M

40M/s

150M

220M

对比总结

CPU 对比结论

内存对比结论

容器标准输出流采集性能

同流量输入下，iLogtail 相较于Filebeat 十倍级别性能

iLogtail 与Filebeat 内存消耗差异不大。

容器文件采集采集性能

同流量输入下，iLogtail 相较于Filebeat 5倍级别性能

iLogtail 与Filebeat 内存消耗差异不大。

容器标准输出流采集多配置性能

同流量输入下，随着采集配置增加，Filebeat CPU 增加量为iLogtail CPU增加量的3倍。

iLogtail 与Filebeat 都会因采集配置增加产生内存膨胀，都处于可接受范围。

容器文件采集多配置性能

同流量输入下，随着采集配置增加，Filebeat CPU 增加量为iLogtail CPU增加量的2倍。

iLogtail 与Filebeat 都会因采集配置增加产生内存膨胀，都处于可接受范围。

为什么Filebeat 容器标准输出与文件采集差异巨大？

通过上述试验可以看到Filebeat 在不同工作模式下有较大的CPU差异，通过dump 容器标准输出流采集的pprof 可以得到如下火焰图，可以看到Filebeat 容器采集下的add_kubernetes_metadata 插件是性能瓶颈，同时Filebeat 的add_kubernetes_metadata 采用与每个节点监听api-server 模式，也存在api-server 压力问题。 而iLogtail 取kubernetes meta 完全是兼容kubernetes CRI 协议，直接通过kubernets sandbox 进行meta 数据读取，保证了iLogtail 的高性能采集效率。

iLogtail DaemonSet 场景优化

通过以上对比，可以看到iLogtail 相比于Filebeat 具有了优秀的内存以及CPU 消耗，有小伙伴可能好奇iLogtail 拥有如此极致性能背后原因，下文主要讲解iLogtail Daemonset 场景下的优化，如何标准输出流相比于Filebeat 拥有10倍性能，其他具体优化措施请参考：Logtail技术分享一与 Logtail技术分享二。 首先对于标准输出流场景，相比于其他开源采集器，例如Filebeat 或Fluentd。一般都是通过监听var/log/containers或/var/log/pods/ **实现容器标准输出流文件的采集，比如/var/log/pods/ 的路径结构为： /var/log/pods///， 通过此路径复用物理机静态文件采集模式进行采集。 而对于iLogtail，做到了容器化的全支持，iLogtail 通过发现机制，全局维护对Node 节点容器的列表，并实时监听与维护此容器列表。当我们拥有容器列表后，我们便具有了如下优势：

- 采集路径不在依赖于静态配置路径，可以靠容器标签动态选择采集源，从而简化用户接入成本。

- 可以根据容器元信息探测容器自动挂载节点的动态路径，所以iLogtail 无需挂载即可采集容器内文件，而如Filebeat 等采集器需要将容器内路径挂载于宿主机路径，再进行静态文件采集。

- 对于新接入采集配置复用历史容器列表，快速接入采集，而对于空采集配置，由于容器发现全局共享机制的存在，也就避免了存在空轮训监听路径机制的情况，进而保证了在容器这样动态性极高的环境中，iLogtail 可运维性的成本达到可控态。

结语

综上所述，在动态性极高的Kubernetes 环境下，iLogtail不会因为采用Daemonset 的部署模型带来的多配置问题，造成内存大幅度膨胀，而且在静态文件采集方面，iLogtail 拥有5倍左右的性能优势，而对于标准输出流采集，由于iLogtail 的采集机制，iLogtail 拥有约10倍左右的性能优势。但是相比于Filebeat 或Fluentd 等老牌开源产品，在文档建设与社区建设上还欠缺很多，欢迎对iLogtail 感兴趣的小伙伴一起参与进来，共同打造易用且高性能的iLogtail 产品。

参考文献

- Logtail技术分享一

- Logtail技术分享二

- Filebeat 配置

- Filebeat 容器化部署

- iLogtail 使用指南

使用介绍

简介

目前可观测采集 Agent，例如 iLogtail，主要提供了本地采集配置管理模式，当涉及实例数较多时，需要逐个实例进行配置变更，管理比较复杂。此外，多实例场景下 Agent 的版本信息、运行状态等也缺乏统一的监控。因此，需要提供全局管控服务用于对可观测采集 Agent 的采集配置、版本信息、运行状态等进行统一的管理。

ConfigServer 就是这样的一款可观测 Agent 管控工具，目前支持：

- 采集 Agent 注册到 ConfigServer

- 以 Agent 组的形式对采集 Agent 进行统一管理

- 远程批量配置采集 Agent 的采集配置

- 监控采集 Agent 的运行状态

术语表

- 采集 Agent：数据采集器。可以是 iLogtail，或者其他的采集器。

- 采集配置：一个数据采集 Pipeline，对应一组独立的数据采集配置。

- AgentGroup：可以将相同属性的Agent划分为一个组，只需要绑定采集配置到 AgentGroup 即可在组内所有 Agent 生效。目前仅支持单 AgentGroup（即默认的 AgentGroup  default ）。

- ConfigServer：采集配置管控的服务端。

功能描述

对采集 Agent 进行全局管控。任何服从协议的Agent，都可以受到统一的管控。

实例注册

- Agent 侧配置已部署的 ConfigServer 信息。

- Agent 启动后，定期向 ConfigServer 进行心跳注册，证明存活性。

- 上报包括但不限于如下的信息，供 ConfigServer 汇集后统一通过API对外呈现。

- Agent 的 instance_id，作为唯一标识。

- 版本号

- 启动时间

- 运行状态

AgentGroup 管理

- Agent 管理的基本单元是 AgentGroup ，采集配置通过关联 AgentGroup 生效到组内的 Agent 实例上。

- 系统默认创建 default 组，所有 Agent 也会默认加到 default 组。

- 支持通过 AgentGroup 的 Tag 实现自定义分组。如果 Agent 的 Tag 与 AgentGroup 的 Tag 匹配，则加入该组。

- 一个 AgentGroup 可以包含多个 Agent，一个 Agent 可以属于多个组。

采集配置全局管控

- 采集配置通过API进行服务端配置，之后与 AgentGroup 绑定后，即可生效到组内 Agent 实例上。

- 通过采集配置版本号区分采集配置差异，增量变更到 Agent 侧。

状态监控

- Agent 定期向 ConfigServer 发送心跳，上报运行信息。

- ConfigServer 汇集后统一通过API对外呈现。

运行

ConfigServer 分为 UI 和 Service 两部分，可以分别独立运行。

Agent 配置

Agent 侧需要配置 ConfigServer 信息，才能使用管控功能。

iLogtail 配置 ConfigServer

打开 iLogtail 目录下的 ilogtail_config.json 文件，配置 ConfigServer 相关参数  ilogtail_configserver_address  和  ilogtail_tags 。

ilogtail_configserver_address  是 ConfigServer 部署的地址与端口号，可以配置多个 ConfigServer 地址， iLogtail 将自动切换选择可以链接的 ConfigServer。需要注意的是，目前的 ConfigServer 仅支持单机版， ilogtail_configserver_address  即使配置了多个地址，多个 ConfigServer 之间也并不支持数据同步。我们预留了 ConfigServer 支持分布式部署的扩展性，欢迎社区积极贡献开发。

ilogtail_tags  是 iLogtail 在 ConfigServer 处的标签，支持配置多个。虽然该参数暂时无法使用，但我们同样预留了支持通过自定义标签分组管理 Agent 的扩展性。

下面是一个简单的配置示例。

{

...

"ilogtail_configserver_address" : [

"127.0.0.1:8899"

],

...

}

Service

Service 为分布式的结构，支持多地部署，负责与采集 Agent 和用户/ui 通信，实现了管控的核心能力。

启动

从 GitHub 下载 iLogtail 源码，进入 ConfigServer 后端目录下，编译运行代码。

cd config_server/service

go build -o ConfigServer

nohup ./ConfigServer > stdout.log 2> stderr.log &

配置选项

配置文件为  config_server/service/seeting/setting.json 。可配置项如下：

- ip ：Service 服务启动的 ip 地址，默认为  127.0.0.1 。

- port ：Service 服务启动的端口，默认为  8899 。

- store_mode ：数据持久化的工具，默认为  leveldb 。当前仅支持基于 leveldb 的单机数据持久化。

- db_path ：数据持久化的存储地址或数据库连接字符串，默认为  ./DB 。

- agent_update_interval ：将采集 Agent 上报的数据批量写入存储的时间间隔，单位为秒，默认为  1  秒。

- config_sync_interval ：Service 从存储同步采集 Config 的时间间隔，单位为秒，默认为  3  秒。

配置样例：

{

"ip":"127.0.0.1",

"store_mode": "leveldb",

"port": "8899",

"db_path": "./DB",

"agent_update_interval": 1,

"config_sync_interval": 3

}

UI

UI 为一个 Web 可视化界面，与 Service 连接，方便用户对采集 Agent 进行管理。

快速开始

git clone https://github.com/iLogtail/config-server-ui

cd config-server-ui

yarn install

yarn start

更多信息

请参考这里

通信协议

由iLogtail社区联合哔哩哔哩共同建设。服从HTTP/HTTPS协议。

通用参数

ip 和 port 为 ConfigServer 的 ip 和接收端口，默认为127.0.0.1和8899。

API 响应规范

数据的发送及接收均为 protocol buffer 格式，参见源代码中的 config_server/protocol 文件夹（v1.0）。

在调用API接口过程中，若返回HTTP状态码为 200，则表示请求成功，若返回HTTP状态码为其他，例如404等，则表示调用API接口失败。服务端会返回请求响应信息如下。code为响应码，表示请求成功/失败的类型；message 是响应信息，包含详细的请求成功信息/失败说明。

{

"code" : <Code>,

"message" : <Message>

}

主要响应码如下所示：

HTTP状态码

响应码

说明

200

Accept

请求成功

400

INVALID_PARAMETER

无效的参数

500

INTERNAL_SERVER_ERROR

内部服务调用错误

通信时常见数据类型说明

Agent

通信传输中的采集 Agent 信息。

参数

类型

说明

agent_type

string

Agent 的类型

agent_id

string

Agent 的唯一标识

attributes

AgentAttributes

Agent 的运行信息

string

string[]

Agent 的标签

running_status

string

Agent 的运行状态

startup_time

int64

Agent 的启动时间

interval

int32

Agent 的心跳间隔

AgentAttributes

参数

类型

说明

version

string

Agent 的版本

category

string

Agent 的类型（用于拉取AGENT_CONFIG）

ip

string

Agent 的IP

hostname

string

Agent 的主机名

region

string

Agent 的地域

zone

string

Agent 的可用区

extras

map

Agent 的其他信息

AgentGroup

通信传输中的 AgentGroup 信息。

参数

类型

说明

group_name

string

AgentGroup 的唯一标识

description

string

AgentGroup 的备注说明

tags

AgentGroupTag[]

AgentGroup 的标签数组

AgentGroupTag

通信传输中的 AgentGroup 的 Tag 信息。

参数

类型

说明

name

string

AgentGroupTag 的标签名

value

string

AgentGroupTag 的标签值

CheckStatus（枚举类型）

拉取配置文件更新时返回的更新状态。

值

说明

NEW

新增的配置文件

DELETED

删除的配置文件

MODIFIED

有改动的配置文件

Command

Agent 从 ConfigServer 接收到的指令。

参数

类型

说明

type

string

指令的类型

name

string

指令名

id

string

指令的编号

args

map

指令的参数

ConfigCheckResult

ConfigServer 返回给 Agent 的配置文件更新信息。

参数

类型

说明

type

ConfigType

Config 的类型

name

string

Config 的唯一标识

old_version

int64

Config 的本地版本

new_version

int64

Config 的最新版本

context

string

Config 的上下文

check_status

CheckStatus

Config 的更新状态

ConfigDetail

通信传输中的采集 Config 的信息。

参数

类型

说明

type

ConfigType

Config 的类型

name

string

Config 的唯一标识

version

int64

Config 的版本

context

string

Config 的上下文

detail

string

Config 的详细数据

ConfigInfo

Agent 向 ConfigServer 请求时携带的配置文件信息。

参数

类型

说明

type

ConfigType

Config 的类型

name

string

Config 的唯一标识

version

int64

Config 的版本

context

string

Config 的上下文

ConfigType（枚举类型）

配置文件的类型。

值

说明

PIPELINE_CONFIG

采集 pipeline 配置

AGENT_CONFIG

Agent 运行配置

RespCode（枚举类型）

通信时返回的状态码。

值

说明

ACCEPT

请求成功

INVALID_PARAMETER

请求失败，参数有误

INTERNAL_SERVER_ERROR

请求失败，服务内部错误

接口说明

以API的形式对外提供统一的管控。总体分为两大类：

- 用户API

- AgentGroup 创建/修改/删除/查看

- 采集配置 创建/修改/删除/查看

- 采集配置与 AgentGroup 绑定/解绑

- Agent API

- Agent心跳

- 采集配置获取

用户API: AgentGroup 创建/修改/删除/查看

ip:port/User/CreateAgentGroup

- 功能：新建 AgentGroup

- 请求方式：POST

- 参数：

参数

类型，默认值

说明

agent_group

AgentGoup，无默认值（必填）

新建的 AgentGroup 的信息

- 返回值： 无

ip:port/User/UpdateAgentGroup

- 功能：修改已有的 AgentGroup 的信息

- 请求方式：PUT

- 参数：

参数

类型，默认值

说明

agent_group

AgentGoup，无默认值（必填）

修改后的 AgentGroup 的信息

- 返回值： 无

ip:port/User/DeleteAgentGroup/

- 功能：删除已建立的 AgentGroup

- 请求方式：DELETE

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

要删除的 AgentGroup 的名称

- 返回值： 无

ip:port/User/GetAgentGroup/

- 功能：查看 AgentGroup 的信息

- 请求方式：GET

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

要获取的 AgentGroup 的名称

- 返回值：

参数

类型

说明

agent_group

AgentGroup

目标 AgentGroup 的信息

ip:port/User/ListAgentGroups/

- 功能：获取所有的 AgentGroup 列表

- 请求方式：GET

- 参数：无

- 返回值：

参数

类型

说明

agent_groups

AgentGroup[]

包含所有 AgentGroup 信息的数组

用户API：采集配置 创建/修改/删除/查看

ip:port/User/CreateConfig/

- 功能：导入本地 Config

- 请求方式：POST

- 参数：

参数

类型，默认值

说明

config_detail

ConfigDetail，无默认值（必填）

新增的 Config 的信息

- 返回值： 无

ip:port/User/UpdateConfig/

- 功能：修改已有的 Config 的信息

- 请求方式：PUT

- 参数：

参数

类型，默认值

说明

config_detail

ConfigDetail，无默认值（必填）

修改后的 Config 的信息

- 返回值： 无

ip:port/User/DeleteConfig/

- 功能：删除已保存的 Config

- 请求方式：DELETE

- 参数：

参数

类型，默认值

说明

config_name

string，无默认值（必填）

要删除的 Config 的名称

- 返回值： 无

ip:port/User/GetConfig/

- 功能：查看指定的 Config 的信息

- 请求方式：GET

- 参数：

参数

类型，默认值

说明

config_name

string，无默认值（必填）

要获取的 config 名称

- 返回值：

参数

类型

说明

config_detail

ConfigDetail

目标 Config 的信息

ip:port/User/ListConfigs/

- 功能：获取所有的 Config 列表

- 请求方式：GET

- 参数：无

- 返回值：

参数

类型

说明

config_details

ConfigDetail[]

包含所有 Config 信息的数组

用户API：采集配置与 AgentGroup 绑定/解绑

ip:port/User/ApplyConfigToAgentGroup/

- 功能：向 AgentGroup 中添加 Config

- 请求方式：PUT

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

目标 AgentGroup 的名字

config_name

string，无默认值（必填）

目标 Config 的名字

- 返回值： 无

ip:port/User/RemoveConfigFromAgentGroup/

- 功能：删除 AgentGroup 中的 Config

- 请求方式：DELETE

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

目标 AgentGroup 的名字

config_name

string，无默认值（必填）

目标 Config 的名字

- 返回值： 无

ip:port/User/GetAppliedConfigsForAgentGroup/

- 功能：查看 AgentGroup 中的 Config 列表

- 请求方式：GET

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

目标 AgentGroup 名称

- 返回值：

参数

类型

说明

config_names

string[]

AgentGroup 关联的所有 Config 名称的数组

ip:port/User/GetAppliedAgentGroups/

- 功能：查看 Config 关联的 AgentGroup 列表

- 请求方式：GET

- 参数：

参数

类型，默认值

说明

config_name

string，无默认值（必填）

目标 Config 名称

- 返回值：

参数

类型

说明

agent_group_names

string[]

Config 关联的所有 AgentGroup 名称的数组

ip:port/User/ListAgents/

- 功能：获取 AgentGroup 中 Agent 列表

- 请求方式：GET

- 参数：

参数

类型，默认值

说明

group_name

string，无默认值（必填）

目标 AgentGroup 名称

- 返回值：

参数

类型

说明

agents

Agent[]

包含 AgentGroup 中所有的 Agent 信息及其状态的数组

Agent API：写入心跳

ip:port/Agent/HeartBeat/

- 功能：Agent 向 ConfigServer发送心跳

- 请求方式：POST

- 参数：

参数

类型，默认值

说明

agent_id

string，无默认值（必填）

Agent 的唯一标识符

agent_type

string，无默认值（必填）

Agent 的种类

attributes

AgentAttributes，无默认值（必填）

Agent 的信息

tags

string[]，无默认值（必填）

Agent 拥有的 tag

running_status

string，无默认值（必填）

Agent 的运行状态

startup_time

int64，无默认值（必填）

Agent 的启动时间

interval

int32，无默认值（必填）

Agent 的心跳间隔

pipeline_configs

ConfigInfo，无默认值（必填）

Agent 拥有的采集配置信息

agent_configs

ConfigInfo，无默认值（必填）

Agent 拥有的运行配置信息

- 返回值：

参数

类型

说明

pipeline_check_results

ConfigCheckResult[]

Agent 拉取的采集配置更新信息

agent_check_results

ConfigCheckResult[]

Agent 拉取的运行配置更新信息

custom_commands

Command[]

Agent 接收到的命令

Agent API：根据 Agent 获取采集配置（含变更信息）

ip:port/Agent/FetchPipelineConfig/

- 功能：Agent 向 ConfigServer 发送已有的采集配置列表，获取更新

- 请求方式：POST

- 参数：

参数

类型，默认值

说明

agent_id

string，无默认值（必填）

Agent 的唯一标识符

req_configs

ConfigInfo[]

Agent 需要拉取的配置文件信息

- 返回值：

参数

类型

说明

config_details

ConfigDetail[]

Agent 拉取的配置文件完整信息

ip:port/Agent/FetchAgentConfig/

- 功能：Agent 向 ConfigServer 发送已有的运行配置列表，获取更新

- 请求方式：POST

- 参数：

参数

类型，默认值

说明

agent_id

string，无默认值（必填）

Agent 的唯一标识符

attributes

AgentAttributes，无默认值（必填）

Agent 的信息

req_configs

ConfigInfo[]

Agent 需要拉取的配置文件信息

- 返回值：

参数

类型

说明

config_details

ConfigDetail[]

Agent 拉取的配置文件完整信息

开发指南

更改管控协议

1. 在管控协议讨论版提出修改意见

2. 意见通过后，修改管控协议文件

3. 管控协议生成对应语言的版本，并进行代码适配

- ilogtail C++ 部分：agent.proto

- ConfigServer Golang 部分：agent.proto & user.proto

开发

- 添加接口

接口统一添加到  router  文件夹下的  router.go  文件中，并在  manger  和  interface  文件夹的相应位置添加实现接口的代码。

- 增加存储适配

若想扩展存储方式，例如实现  mysql  存储等，可以在  store  文件夹下实现已有的数据库接口  interface_database  ，并在  store.go  的  newStore  函数中添加对应的存储类型。

编译

进入 Config Server 的  service  文件夹下

go build -o ConfigServer

测试

测试文件统一存放在  test  文件夹下。

可以通过如下方式查看测试覆盖率：

go test -cover github.com/alibaba/ilogtail/config_server/service/test -coverpkg github.com/alibaba/ilogtail/config_server/service/... -coverprofile coverage.out -v

go tool cover -func=coverage.out -o coverage.txt

# Visualization results: go tool cover -html=coverage.out -o coverage.html

cat coverage.txt

走近iLogtail社区版

- 2024-04-17 破浪前行：iLogtail十年老架构如何浴火重生

- 2024-04-17 跟着iLogtail学习无锁化编程

- 2024-02-21 你好，iLogtail 2.0！

- 2023-08-30 跟着iLogtail学习设计模式

- 2023-02-17 鲲鹏展翅凌云志：iLogtail社区2022年度开源报告

- 2022-12-08 性能与可靠的超强碰撞：第三方测评开源日志采集器

- 2022-12-02 阿里十年技术沉淀｜深度解析百PB级数据总线技术

- 2022-09-09 零信任策略下K8s安全监控最佳实践

- 2021-09-01 您有一份来自iLogtail社区的礼物待查收

- 2022-07-12 千万级可观测数据采集器--iLogtail代码完整开源

- 2022-08-23 iLogtail开源之路

iLogtail社区版使用入门

- 如何将业务日志采集到Kafka

- 使用DaemonSet模式采集K8s容器日志

- 主机环境采集业务日志到SLS

- K8s环境采集业务日志到SLS

- iLogtail日志处理实战

- iLogtail配置文件热加载

- 采集MySQL Binlog

iLogtail社区版开发者指南

- 一招解决开发环境问题 —— 远程容器开发指南

- 快速搭建编译和开发环境

iLogtail社区版使用案例

- OpenKruise x iLogtail：管理可观测数据采集Sidecar容器最佳实践

- File2Kafka性能测试

- 基于Logtail的阿里云EMR日志分析链路演进

- 一文搞懂 SAE 日志采集架构

- 树莓派上玩转iLogtail：构建/采集/分析NAS日志

Table of Contents

什么是iLogtail

发展历史

产品优势

开源协议

社区版和企业版的对比说明

开源之夏 2024

iLogtail 社区项目介绍

iLogtail 数据吞吐性能优化

ConfigServer 能力升级 + 体验优化（全栈）

快速开始

Docker使用

Kubernetes使用

守护进程

发布记录

发布记录(1.x版本)

支持的操作系统

源代码

下载

编译

Docker镜像

编译依赖

镜像站

关键概念

采集配置

系统参数

日志

概览

版本管理

输入

文本日志

容器标准输出（原生插件）

脚本执行数据

容器标准输出

文本日志（debug）

MetricInput示例插件

主机Meta数据

Mock数据-Metric

eBPF网络调用数据

主机监控数据

MySQL Binlog

GO Profile

GPU数据

HTTP数据

ServiceInput示例插件

Journal数据

Kafka

Mock数据-Service

SqlServer 查询数据

OTLP数据

PostgreSQL 查询数据

Syslog数据

eBPF文件安全数据

eBPF网络可观测数据

eBPF网络安全数据

eBPF进程安全数据

处理

原生插件

正则解析

分隔符解析

Json解析

时间解析

过滤

脱敏

扩展插件

添加字段

添加云资产信息

原始数据

数据脱敏

丢弃字段

字段加密

条件字段处理

日志过滤

Go时间格式解析

Grok

Json

日志转SLS Metric

正则

重命名字段

分隔符

键值对

多行切分

字符串替换

聚合

基础

上下文

按Key分组

按GroupMetadata分组

输出

Kafka（Deprecated）

kafkaV2

ClickHouse

ElasticSearch

SLS

标准输出/文件

OTLP日志

Pulsar

HTTP

Loki

扩展

BasicAuth鉴权

协议解码/反序列化

协议编码/序列化

数据筛选

请求熔断

文件发现

插件系统

日志

开发环境

日志协议

协议转换

增加新的日志协议

sls协议

代码风格

数据模型

插件开发

Checkpoint接口

Logger接口

自监控指标接口

如何开发Input插件

如何开发Processor插件

如何开发Aggregator插件

如何开发Flusher插件

如何生成插件文档

纯插件模式启动

测试

单元测试

E2E测试

代码检查

检查代码规范

检查文件许可证

检查依赖包许可证

贡献指南

开发者

成就

容器场景iLogtail与Filebeat性能对比测试

使用介绍

通信协议

开发指南

走近iLogtail社区版

iLogtail社区版使用入门

iLogtail社区版开发者指南

iLogtail社区版使用案例