From 0ebb5105f7ada0a6f2da612f668f370d9fe4bc50 Mon Sep 17 00:00:00 2001 From: Takuka0311 <1914426213@qq.com> Date: Mon, 9 Dec 2024 17:11:43 +0800 Subject: [PATCH] update developer-guide and fix pure-plugin-start --- docs/cn/README.md | 26 ++++++---- .../code-check/check-dependency-license.md | 10 ++-- docs/cn/developer-guide/codestyle.md | 2 +- docs/cn/developer-guide/data-model.md | 4 +- .../development-environment.md | 49 ++++++++++--------- .../log-protocol/How-to-add-new-protocol.md | 4 +- .../cn/developer-guide/log-protocol/README.md | 4 +- .../developer-guide/log-protocol/converter.md | 10 ++-- .../log-protocol/protocol-spec/sls.md | 2 +- .../how-to-custom-builtin-plugins.md | 4 +- .../how-to-write-external-plugins.md | 6 +-- .../how-to-write-flusher-plugins.md | 2 +- .../plugin-debug/logger-api.md | 12 ++--- .../plugin-debug/plugin-self-monitor-guide.md | 34 ++++++++++--- .../plugin-debug/pure-plugin-start.md | 27 +++++----- .../plugin-development-guide.md | 34 +++++++++---- .../plugin-docs/plugin-doc-templete.md | 2 +- .../test/How-to-add-subscriber.md | 6 +-- docs/cn/developer-guide/test/benchmark.md | 2 +- docs/cn/developer-guide/test/e2e-test-step.md | 19 +++---- docs/cn/developer-guide/test/e2e-test.md | 12 +++-- docs/cn/developer-guide/test/unit-test.md | 10 ++-- .../release-notes/release-notes.md | 1 + pkg/logger/logger.go | 6 ++- scripts/plugin_build.sh | 2 +- 25 files changed, 172 insertions(+), 118 deletions(-) diff --git a/docs/cn/README.md b/docs/cn/README.md index b5915e12ea..224bd2c605 100644 --- a/docs/cn/README.md +++ b/docs/cn/README.md @@ -1,10 +1,16 @@ # 什么是LoongCollector -![]() +![logo]() LoongCollector 是一款集卓越性能、超强稳定性和灵活可编程性于一身的数据采集器，专为构建下一代可观测 Pipeline 设计。源自阿里云可观测性团队所开源的 iLogtail 项目，在继承了 iLogtail 强大的日志采集与处理能力的基础上，进行了全面的功能升级与扩展。从原来单一日志场景，逐步扩展为可观测数据采集、本地计算、服务发现的统一体。 -[![GitHub stars](https://camo.githubusercontent.com/674a26318ece2d770231086a733bebdbb174c15721f03714f5b79930574a800a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f616c69626162612f696c6f677461696c)](https://github.com/alibaba/loongcollector/stargazers) [![GitHub issues](https://camo.githubusercontent.com/4266ec67b48f666bc0d440f9d1399e4b56ffc4eca3af3764e062731be83b2873/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f616c69626162612f696c6f677461696c)](https://github.com/alibaba/loongcollector/issues) [![GitHub license](https://camo.githubusercontent.com/608afe55a7ca2ed062304f89208d3b929fddcbde8923cd09ef40edb2d2c3bf76/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f616c69626162612f696c6f677461696c)](https://github.com/alibaba/loongcollector/blob/main/LICENSE) +[![GitHub contributors](https://img.shields.io/github/contributors/alibaba/ilogtail)](https://github.com/alibaba/loongcollector/contributors) +[![GitHub stars](https://img.shields.io/github/stars/alibaba/ilogtail)](https://github.com/alibaba/loongcollector/stargazers) +[![GitHub issues](https://img.shields.io/github/issues/alibaba/ilogtail)](https://github.com/alibaba/loongcollector/issues) +[![GitHub license](https://img.shields.io/github/license/alibaba/ilogtail)](https://github.com/alibaba/loongcollector/blob/main/LICENSE) +[![Coverity Scan Build Status](https://img.shields.io/coverity/scan/28764.svg)](https://scan.coverity.com/projects/alibaba-ilogtail) +[![Coverage Status](https://codecov.io/gh/alibaba/ilogtail/branch/main/graph/badge.svg)](https://codecov.io/gh/alibaba/ilogtail) +[![Go Report Card](https://goreportcard.com/badge/github.com/alibaba/loongcollector)](https://goreportcard.com/report/github.com/alibaba/loongcollector) ## 品牌寓意 @@ -20,11 +26,11 @@ LoongCollector 社区将紧密围绕既定的愿景蓝图，专注于核心价 LoongCollector 始终将追求极致的采集性能和超强可靠性放在首位，坚信这是实践长期主义理念的根基。我们深知，LoongCollector 核心价值在于为大规模分布式系统提供稳固、高效的可观测性数据统一采集 Agent 与端到端 Pipeline。不管在过去、现在、未来，LoongCollector 都将持续通过技术革新与优化，实现资源利用效率的提升与在极端场景下的稳定运行。 -![]() +![uncompromised_performance_and_reliability]() ### 遥测数据，无限边界 Unlimited Telemetry Data -![]() +![unlimited_telemetry_data]() LoongCollector 坚信 All-in-One 的设计理念，致力于所有的采集工作用一个 Agent 实现 Logs、Metric、Traces、Events、Profiles 的采集、处理、路由、发送等功能。展望未来，LoongCollector 将着重强化其 Prometheus 抓取能力，深度融入 eBPF（Extended Berkeley Packet Filter）技术以实现无侵入式采集，提供原生的指标采集功能，做到真正的 OneAgent。 @@ -39,7 +45,7 @@ LoongCollector 通过 SPL 与多语言 Plugin 双引擎加持，构建完善的 * 不同引擎都可以相互打通，通过灵活的组合实现预期的计算能力。 * 设计通用的 Event 数据模型，可扩展表达 Logs、Metric、Traces、Events、Profiles 等在内的多种可观测类型，为通用计算提供便捷。 -![]() +![unrestricted_programmable_pipeline]() 开发者可以根据自身需求灵活选择可编程引擎。如果看重执行效率，可以选择原生插件；如果看重算子全面性，需要处理复杂数据，可以选择 SPL 引擎；如果强调低门槛的自身定制化，可以选择扩展插件，采用 Golang 进行编程。 @@ -61,15 +67,15 @@ LoongCollector 通过 SPL 与多语言 Plugin 双引擎加持，构建完善的 同时，对于存储适配层进行了抽象，便于开发者对接符合自己环境需求的持久化存储。 -![]() +![config_server]() LoongCollector 极大地完善了自身可观测性的建设。不管是 LoongCollector 自身运行状态，还是采集 Pipeline 节点都有完整指标。开发者只需要将这些指标对接到可观测系统，即可体验对 LoongCollector 运行状态的清晰洞察。 -![]() +![self_monitor]() ## 核心场景：不仅仅是 Agent -![]() +![not_only_agent]() 作为一款高性能的可观测数据采集与处理 Pipeline，LoongCollector 的部署模式在很大程度上能够被灵活定制以满足各种不同的业务需求和技术架构。 @@ -103,7 +109,7 @@ cd output 未来，LoongCollector 社区将持续围绕长期主义进行建设，打造核心竞争力。同时，也期待更多小伙伴的加入。 -![]() +![roadmap]() * 通过框架能力增强，构建高性能、高可靠的基础底座。 * 通用发送重构框架 @@ -157,4 +163,4 @@ cd output * 知乎：[iLogtail社区](https://www.zhihu.com/column/c_1533139823409270785) * 扫描二维码加入微信/钉钉交流群 - +![chatgroup](https://ilogtail-community-edition.oss-cn-shanghai.aliyuncs.com/images/chatgroup/chatgroup.png) diff --git a/docs/cn/developer-guide/code-check/check-dependency-license.md b/docs/cn/developer-guide/code-check/check-dependency-license.md index 199cb150ce..8f4fc48474 100644 --- a/docs/cn/developer-guide/code-check/check-dependency-license.md +++ b/docs/cn/developer-guide/code-check/check-dependency-license.md @@ -1,6 +1,6 @@ # 检查依赖包许可证 -iLogtail 基于Apache 2.0 协议进行开源，开发者需要保证依赖包协议与Apache 2.0 协议兼容，所有依赖包或源码引入License 说明位于根目录 `licenses` 文件夹。 +LoongCollector 基于Apache 2.0 协议进行开源，开发者需要保证依赖包协议与Apache 2.0 协议兼容，所有依赖包或源码引入License 说明位于根目录 `licenses` 文件夹。 ## 检查依赖包License @@ -16,12 +16,12 @@ make check-dependency-licenses ## Fork 代码库管理 -出于某些特性不支持原因，或精简依赖包原因，iLogtail 会存在某些Fork代码库，所有Fork代码库存在于[iLogtail](https://github.com/iLogtail)组织进行管理，出于License风险问题，禁止引入私人Fork版本。 +出于某些特性不支持原因，或精简依赖包原因，LoongCollector 会存在某些Fork代码库，所有Fork代码库存在于[iLogtail](https://github.com/iLogtail)组织进行管理，出于License风险问题，禁止引入私人Fork版本。 ### go.mod 管理 1. Fork 仓库： 对于Fork代码库，出于尊重原作者，禁止修改go.mod 仓库module地址，如[样例](https://github.com/iLogtail/go-mysql/blob/master/go.mod)所示。 -2. iLogtail仓库: iLogtail 仓库对于Fork代码库要求使用replace 方式引入，用以保持代码文件声明的引入包地址保持原作者仓库地址。 +2. LoongCollector仓库: LoongCollector 仓库对于Fork代码库要求使用replace 方式引入，用以保持代码文件声明的引入包地址保持原作者仓库地址。 ```go require ( @@ -38,11 +38,11 @@ replace ( 请执行`make check-dependency-licenses` 指令，脚本程序将自动在find_licenses文件夹生成markdown 说明，请将说明放置于[LICENSE_OF_ILOGTAIL_DEPENDENCIES.md](../../../../licenses/LICENSE_OF_ILOGTAIL_DEPENDENCIES.md)文件末端，如下样例。 ```go -## iLogtail used or modified source code from these projects +## LoongCollector 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仓库。 +如Fork 特性为原代码库的能力补充，非特定场景如精简依赖包等因素，建议对原始代码库提出PullRequest, 如原始仓库接受此次PullRequest，请将 LoongCollector 仓库依赖包地址修改为原始仓库地址，并删除Fork仓库。 diff --git a/docs/cn/developer-guide/codestyle.md b/docs/cn/developer-guide/codestyle.md index 5895364e84..4cf7526938 100644 --- a/docs/cn/developer-guide/codestyle.md +++ b/docs/cn/developer-guide/codestyle.md @@ -1,6 +1,6 @@ # 代码风格 -iLogtail C++遵循基于[Google代码规范](https://google.github.io/styleguide/cppguide.html)的风格，详细格式约束见[.clang-format](https://github.com/alibaba/loongcollector/blob/main/.clang-format)。 +LoongCollector C++遵循基于[Google代码规范](https://google.github.io/styleguide/cppguide.html)的风格，详细格式约束见[.clang-format](https://github.com/alibaba/loongcollector/blob/main/.clang-format)。 Go遵循[Effective Go](https://go.dev/doc/effective_go)风格。 diff --git a/docs/cn/developer-guide/data-model.md b/docs/cn/developer-guide/data-model.md index 1cc9c5b909..3e2185835d 100644 --- a/docs/cn/developer-guide/data-model.md +++ b/docs/cn/developer-guide/data-model.md @@ -1,6 +1,6 @@ # 数据模型 -iLogtail 目前支持 `SLS Log Protocol` 和 `Pipeline Event` 两种数据模型，两种模型的描述和对比如下： +LoongCollector 目前支持 `SLS Log Protocol` 和 `Pipeline Event` 两种数据模型，两种模型的描述和对比如下： | | SLS Log Protocol | Pipeline Event | | ---- | ---- | ---- | | 描述 | SLS 日志的专用处理结构 | 可扩展的可观测性数据模型，支持Metrics、Trace、Logging、Bytes、Profile等 | @@ -72,7 +72,7 @@ type MetricEvent struct { } ``` -主流的metrics数据有单值(eg. Prometheus)和多值(eg. influxdb)两种设计，iLogtail 中也需要支持两种不同的设计，基于此设计了 MetricValue 接口和MetricSingleValue 和 MetricMultiValue 两个不同的实现 +主流的metrics数据有单值(eg. Prometheus)和多值(eg. influxdb)两种设计，LoongCollector 中也需要支持两种不同的设计，基于此设计了 MetricValue 接口和MetricSingleValue 和 MetricMultiValue 两个不同的实现 ```go type MetricValue interface { diff --git a/docs/cn/developer-guide/development-environment.md b/docs/cn/developer-guide/development-environment.md index 0a0b597253..ef24430f99 100644 --- a/docs/cn/developer-guide/development-environment.md +++ b/docs/cn/developer-guide/development-environment.md @@ -1,20 +1,20 @@ # 开发环境 -虽然[源代码编译](../installation/sources/build.md)已经提供了方便的iLogtail编译方法，但却不适合开发场景。因为开发过程中需要不断进行编译调试，重复全量编译的速度太慢，因此需要构建支持增量编译开发环境。 +虽然[源代码编译](../installation/sources/build.md)已经提供了方便的 LoongCollector 编译方法，但却不适合开发场景。因为开发过程中需要不断进行编译调试，重复全量编译的速度太慢，因此需要构建支持增量编译开发环境。 ## 进程结构 -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个二进制文件。 +LoongCollector 为了支持插件系统，引入了 libPluginAdaptor 和 libPluginBase（以下简称 adaptor 和 base）这两个动态库，它们与 LoongCollector 之间的关系如下：
+LoongCollector 动态依赖于这两个动态库（即 binary 中不依赖），在初始化时，LoongCollector 会尝试使用动态库接口（如 dlopen）动态加载它们，获取所需的符号。
+Adaptor 充当一个中间层，LoongCollector 和 base 均依赖它，LoongCollector 向 adaptor 注册回调，adpator 将这些回调记录下来以接口的形式暴露给 base 使用。
+Base 是插件系统的主体，它包含插件系统所必须的采集、处理、聚合以及输出（向 LoongCollector 递交可以视为其中一种）等功能。
+因此，完整的 LoongCollector 包含loongcollector 、libPluginAdaptor.so 和 libPluginBase.so 3个二进制文件。 ![image.png](https://sls-opensource.oss-us-west-1.aliyuncs.com/ilogtail/ilogtail-adapter-cgo.png) ## 目录结构 -iLogtail的大致目录结构如下： +LoongCollector 的大致目录结构如下： ```shell . @@ -28,15 +28,17 @@ iLogtail的大致目录结构如下： └── Makefile # 编译描述文件 ``` -core目录包含了iLogtail C++核心代码，ilogtail.cpp是其主函数入口文件。C++项目使用CMake描述，CMakeLists.txt是总入口，各子目录中还有CMakeLists.txt描述子目录下的编译目标。 +core目录包含了 LoongCollector C++核心代码，ilogtail.cpp是其主函数入口文件。C++项目使用CMake描述，CMakeLists.txt是总入口，各子目录中还有CMakeLists.txt描述子目录下的编译目标。 -顶层目录.本身就是一个Go项目，该项目为iLogtail插件，go.mod为其描述文件。插件代码主体在plugins目录。 +顶层目录.本身就是一个Go项目，该项目为 LoongCollector 插件，go.mod为其描述文件。插件代码主体在plugins目录。 -docker目录和scripts目录分别为辅助编译的镜像描述目录和脚本目录。Makefile为整个iLogtail的编译描述文件，对编译命令进行了封装。 +docker目录和scripts目录分别为辅助编译的镜像描述目录和脚本目录。Makefile为整个 LoongCollector 的编译描述文件，对编译命令进行了封装。 ## 开发镜像 -loongcollector 依赖了诸多第三方库（详见[编译依赖](../installation/sources/dependencies.md)），为了简化编译流程ilogtail提供了预编译依赖的镜像辅助编译。开发镜像的地址在`sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/loongcollector-community-edition/loongcollector-build-linux`，可通过下面命令获取。 +LoongCollector 依赖了诸多第三方库（详见[编译依赖](../installation/sources/dependencies.md) + +LoongCollector 提供了预编译依赖的镜像辅助编译。开发镜像的地址在`sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/loongcollector-community-edition/loongcollector-build-linux`，可通过下面命令获取。 ```shell docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/loongcollector-community-edition/loongcollector-build-linux @@ -70,7 +72,7 @@ go install ... ## 使用VS Code构建开发环境 -[VS Code](https://code.visualstudio.com/)通过[Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)插件可以实现远程开发、在镜像中开发，甚至远程+镜像中开发，在镜像中开发的功能使得编译环境在不同部署间都能保持统一。由于VS Code免费而功能强大，因此我们选用VS Code来为iLogtail创建一致的、可移植的开发环境。 +[VS Code](https://code.visualstudio.com/)通过[Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)插件可以实现远程开发、在镜像中开发，甚至远程+镜像中开发，在镜像中开发的功能使得编译环境在不同部署间都能保持统一。由于VS Code免费而功能强大，因此我们选用VS Code来为 LoongCollector 创建一致的、可移植的开发环境。 ### 1. 安装插件 @@ -78,7 +80,7 @@ go install ... ### 2. 创建镜像开发环境配置 -在iLogtail代码库的顶层目录创建`.devcontainer`目录，并在里面创建`devcontainer.json`文件，文件的内容如下： +在 LoongCollector 代码库的顶层目录创建`.devcontainer`目录，并在里面创建`devcontainer.json`文件，文件的内容如下： ```json { @@ -94,10 +96,9 @@ go install ... } } } - ``` -其中，image指定了ilogtail的开发镜像地址，customizations.vscode.extensions指定了开发环境的插件。部分插件介绍如下，开发者也可以按照自己的习惯进行修改，[欢迎讨论](https://github.com/alibaba/loongcollector/discussions/299)。 +其中，image指定了 LoongCollector 的开发镜像地址，customizations.vscode.extensions指定了开发环境的插件。部分插件介绍如下，开发者也可以按照自己的习惯进行修改，[欢迎讨论](https://github.com/alibaba/loongcollector/discussions/299)。 | **插件名** | **用途** | | --- | --- | @@ -161,7 +162,7 @@ cmake -DBUILD_LOGTAIL_UT=ON .. 可以将C++核心的构建结果拷贝到`./output`目录组装出完整的构建结果。 ```bash -cp -a ./core/build/ilogtail ./output +cp -a ./core/build/loongcollector ./output cp -a ./core/build/go_pipeline/libPluginAdapter.so ./output ``` @@ -169,7 +170,7 @@ cp -a ./core/build/go_pipeline/libPluginAdapter.so ./output ```text ./output -├── ilogtail (主程序） +├── loongcollector (主程序） ├── libPluginAdapter.so（插件接口） ├── libPluginBase.h └── libPluginBase.so (插件lib） @@ -184,7 +185,7 @@ cp -a ./core/build/go_pipeline/libPluginAdapter.so ./output ### 2. 创建编译容器，并挂载代码目录 ```bash -docker run --name ilogtail-build -d \ +docker run --name loongcollector-build -d \ -v `pwd`:/src -w /src \ sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/loongcollector-community-edition/loongcollector-build-linux:2.0.5 \ bash -c "sleep infinity" @@ -193,7 +194,7 @@ docker run --name ilogtail-build -d \ ### 3. 进入容器 ```bash -docker exec -it ilogtail-build bash +docker exec -it loongcollector-build bash ``` ### 4. 在容器内编译 @@ -206,12 +207,12 @@ docker exec -it ilogtail-build bash ### 1. 修改官方镜像entrypoint -基于官方镜像包进行调试，首先用bash覆盖官方镜像的entrypoint，避免杀死ilogtail后容器直接退出。 +基于官方镜像包进行调试，首先用bash覆盖官方镜像的entrypoint，避免杀死 LoongCollector 后容器直接退出。 - docker：指定CMD ```bash -docker run -it --name docker_ilogtail -v /:/logtail_host:ro -v /var/run:/var/run aliyun/ilogtail: bash +docker run -it --name docker_loongcollector -v /:/logtail_host:ro -v /var/run:/var/run aliyun/loongcollector: bash ``` - k8s：用command覆盖entrypoint @@ -225,17 +226,17 @@ docker run -it --name docker_ilogtail -v /:/logtail_host:ro -v /var/run:/var/run ### 2. 将自己编的二进制文件、so，替换到容器里 -由于ilogtail容器挂载了主机目录，因此将需要替换掉文件放到主机目录上容器内就能访问。 +由于 LoongCollector 容器挂载了主机目录，因此将需要替换掉文件放到主机目录上容器内就能访问。 ```bash # 将开发机上编译的so scp到container所在node上 scp libPluginBase.so @:/home/ ``` -主机的根路径在ilogtail容器中位于/logtail_host，找到对应目录进行copy即可。 +主机的根路径在 LoongCollector 容器中位于/logtail_host，找到对应目录进行copy即可。 ```bash -cp /logtail_host/home//libPluginBase.so /usr/local/ilogtail +cp /logtail_host/home//libPluginBase.so /usr/local/loongcollector ``` ## 常见问题 diff --git a/docs/cn/developer-guide/log-protocol/How-to-add-new-protocol.md b/docs/cn/developer-guide/log-protocol/How-to-add-new-protocol.md index 1bb4acbd4b..7517792d15 100644 --- a/docs/cn/developer-guide/log-protocol/How-to-add-new-protocol.md +++ b/docs/cn/developer-guide/log-protocol/How-to-add-new-protocol.md @@ -1,6 +1,6 @@ # 增加新的日志协议 -如果iLogtail暂时不支持您所需的日志协议，您可以为iLogtail增加该协议并添加相应的协议转换函数，具体步骤如下： +如果 LoongCollector 暂时不支持您所需的日志协议，您可以为 LoongCollector 增加该协议并添加相应的协议转换函数，具体步骤如下： 1. 如果您的协议支持Protobuf或其它可通过模式定义生成相应内存结构的编码方式，您需要首先在`./pkg/protocol`目录下新建一个以协议名为命名的文件夹，然后在该文件夹中增加一个以编码方式为命名的子文件夹，在该文件中存放相应的模式定义文件，然后将由代码生成工具生成的与该模式定义文件相对应的Go代码文件放置在父目录中。目录组织结构如下： @@ -32,7 +32,7 @@ 3. 能够根据`targetFields`找到对应字段的值 4. 对于部分编码格式，能够根据`c.ProtocolKeyRenameMap`重命名协议字段的Key - 为了完成上述第2和第3点，iLogtail提供了下列帮助函数： + 为了完成上述第2和第3点，LoongCollector 提供了下列帮助函数： ```Go func convertLogToMap(log *sls.Log, logTags []*sls.LogTag, src, topic string, tagKeyRenameMap map[string]string) (contents map[string]string, tags map[string]string) diff --git a/docs/cn/developer-guide/log-protocol/README.md b/docs/cn/developer-guide/log-protocol/README.md index cec487ae17..0db26822db 100644 --- a/docs/cn/developer-guide/log-protocol/README.md +++ b/docs/cn/developer-guide/log-protocol/README.md @@ -1,8 +1,8 @@ # 日志协议 -iLogtail的日志数据默认以sls自定义协议的形式与外部进行交互，但也支持日志数据在sls协议和其它标准协议或自定义协议之间的转换。除此之外，对于某种协议，iLogtail还支持对日志数据进行不同方式的编码。 +LoongCollector 的日志数据默认以sls自定义协议的形式与外部进行交互，但也支持日志数据在sls协议和其它标准协议或自定义协议之间的转换。除此之外，对于某种协议，LoongCollector 还支持对日志数据进行不同方式的编码。 -目前，iLogtail日志数据支持的协议及相应的编码方式如下表所示，其中协议类型可分为自定义协议和标准协议： +目前，LoongCollector 日志数据支持的协议及相应的编码方式如下表所示，其中协议类型可分为自定义协议和标准协议： | 协议类型 | 协议名称 | 支持的编码方式 | |-------|--------------------------------------------------------------------------------------------------|---------------| diff --git a/docs/cn/developer-guide/log-protocol/converter.md b/docs/cn/developer-guide/log-protocol/converter.md index 187a331b0f..f791036107 100644 --- a/docs/cn/developer-guide/log-protocol/converter.md +++ b/docs/cn/developer-guide/log-protocol/converter.md @@ -1,6 +1,6 @@ # 协议转换 -在开发Flusher插件时，用户往往需要将日志数据从sls协议转换成其他协议。在扩展Metric数据模型后，v2版本的Flusher插件还需要支持从PipelineGroupEvents数据转换成其他协议的场景。为了加快开发插件流程，iLogtail提供了通用协议转换模块，用户只需要指定目标协议的名称和编码方式即可获得编码后的字节流。 +在开发Flusher插件时，用户往往需要将日志数据从sls协议转换成其他协议。在扩展Metric数据模型后，v2版本的Flusher插件还需要支持从PipelineGroupEvents数据转换成其他协议的场景。为了加快开发插件流程，LoongCollector 提供了通用协议转换模块，用户只需要指定目标协议的名称和编码方式即可获得编码后的字节流。 ## Converter结构 @@ -129,12 +129,12 @@ c, err := protocol.NewConverter("custom_single", "json", map[string]string{"host | 字段名 | 描述 | | ------ | ------ | - | host.ip | iLogtail所属机器或容器的ip地址 | + | host.ip | LoongCollector所属机器或容器的ip地址 | | log.topic | 日志的topic | | log.file.path | 被采集文件的路径 | - | host.name | iLogtail所属机器或容器的主机名 | - | k8s.node.ip | iLogtail容器所处K8s节点的ip | - | k8s.node.name | iLogtail容器所处K8s节点的名称 | + | host.name | LoongCollector所属机器或容器的主机名 | + | k8s.node.ip | LoongCollector容器所处K8s节点的ip | + | k8s.node.name | LoongCollector容器所处K8s节点的名称 | | k8s.namespace.name | 业务容器所属的K8s命名空间 | | k8s.pod.name | 业务容器所属的K8s Pod名称 | | k8s.pod.ip | 业务容器所属的K8s Pod ip | diff --git a/docs/cn/developer-guide/log-protocol/protocol-spec/sls.md b/docs/cn/developer-guide/log-protocol/protocol-spec/sls.md index 608d03754e..f0e8bac1cf 100644 --- a/docs/cn/developer-guide/log-protocol/protocol-spec/sls.md +++ b/docs/cn/developer-guide/log-protocol/protocol-spec/sls.md @@ -39,7 +39,7 @@ LogGroup（日志组）是对多条日志的包装： - Logs：包含所有日志。 - Category：日志服务Logstore，可以类比Kafka 独立集群， 数据存储的独立单元。 - Topic: 日志服务Topic，一个Category（Logstore）可以划分为多个topic，不填写时Topic 为空字符串，可以类比Kafka 独立集群下的Topic概念。 -- Source/MachineUUID：iLogtail 所在节点的信息，前者为 IP，后者为 UUID。 +- Source/MachineUUID：LoongCollector 所在节点的信息，前者为 IP，后者为 UUID。 - LogTags：所有日志共同的 tag，同样由 key/value 列表组成。 ```protobuf diff --git a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-custom-builtin-plugins.md b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-custom-builtin-plugins.md index 06641e0ad5..254ad0bedc 100644 --- a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-custom-builtin-plugins.md +++ b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-custom-builtin-plugins.md @@ -2,9 +2,9 @@ ## 插件引用机制 -iLogtail 通过 [插件引用配置文件](https://github.com/alibaba/loongcollector/blob/main/plugins.yml) 来定义要包含在构建产物中的插件，该文件中默认包含了iLogtail仓库中的所有插件。 +LoongCollector 通过 [插件引用配置文件](https://github.com/alibaba/loongcollector/blob/main/plugins.yml) 来定义要包含在构建产物中的插件，该文件中默认包含了LoongCollector 仓库中的所有插件。 -同时，iLogtail 也以同样的机制支持引入外部私有插件，关于如何开发外部插件，请参阅[如何构建外部私有插件](how-to-write-external-plugins.md)。iLogtail 默认会检测仓库根目录下的 `external_plugins.yml` 文件来查找外部插件定义。 +同时，LoongCollector 也以同样的机制支持引入外部私有插件，关于如何开发外部插件，请参阅[如何构建外部私有插件](how-to-write-external-plugins.md)。LoongCollector 默认会检测仓库根目录下的 `external_plugins.yml` 文件来查找外部插件定义。 当执行诸如 `make all` 等构建指令时，该配置文件会被解析并生成 go import 文件到 [plugins/all](https://github.com/alibaba/loongcollector/tree/main/plugins/all) 目录下。 diff --git a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-external-plugins.md b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-external-plugins.md index 6a51bd6888..92f7e155a9 100644 --- a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-external-plugins.md +++ b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-external-plugins.md @@ -2,7 +2,7 @@ ## 场景 -某些情况下，您可能想要开发自己的非公开插件，但又希望能够及时更新使用到社区iLogtail不断迭代的更新功能（而不是在社区版本上分叉），iLogtail 的外部插件开发机制可以满足您这样的需求。 +某些情况下，您可能想要开发自己的非公开插件，但又希望能够及时更新使用到社区 LoongCollector 不断迭代的更新功能（而不是在社区版本上分叉），LoongCollector 的外部插件开发机制可以满足您这样的需求。 ## 步骤 @@ -153,9 +153,9 @@ import ( ### 7. 编写插件引用配置文件 -**以下内容在 iLogtail 主仓库执行**。 +**以下内容在 LoongCollector 主仓库执行**。 -在 iLogtail 仓库根目录创建名为 `external_plugins.yml` 的配置文件，写入如下内容： +在 LoongCollector 仓库根目录创建名为 `external_plugins.yml` 的配置文件，写入如下内容： ```yaml plugins: diff --git a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-flusher-plugins.md b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-flusher-plugins.md index d0371eae50..744d0837ed 100644 --- a/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-flusher-plugins.md +++ b/docs/cn/developer-guide/plugin-development/extended-plugins/how-to-write-flusher-plugins.md @@ -10,7 +10,7 @@ Flusher 插件与外部系统进行交互，将数据发送到外部，以下将 - Flush 接口是插件系统向 flusher 插件实例提交数据的入口，用于将数据输出到外部系统。为了映射到日志服务的概念中，我们增加了三个 string 参数，它代表这个 flusher 实例所属的 project/logstore/config。详细解释请参与[数据结构](../data-structure.md) 与 [基本结构](../../../principle/plugin-system.md) 。 -- SetUrgent： 标识iLogtail 即将退出，将系统状态传递给具体Flusher 插件，可以供Flusher 插件自动适应系统状态，比如加快输出速率等。(SetUrgent调用发生在其他类型插件的Stop之前，当前尚无有意义的实现) +- SetUrgent： 标识 LoongCollector 即将退出，将系统状态传递给具体Flusher 插件，可以供Flusher 插件自动适应系统状态，比如加快输出速率等。(SetUrgent调用发生在其他类型插件的Stop之前，当前尚无有意义的实现) - Stop：停止Flusher 插件，比如断开与外部系统交互的链接 ```go diff --git a/docs/cn/developer-guide/plugin-development/plugin-debug/logger-api.md b/docs/cn/developer-guide/plugin-development/plugin-debug/logger-api.md index c1b3a023a5..f57634e31d 100644 --- a/docs/cn/developer-guide/plugin-development/plugin-debug/logger-api.md +++ b/docs/cn/developer-guide/plugin-development/plugin-debug/logger-api.md @@ -35,7 +35,7 @@ func (p *plugin) func1() { ## 打印采集配置元信息 -对于iLogtail，具有多租户的特点，可以支持多份采集配置同时工作，iLogtail 支持将采集配置的元信息打印到日志中，便于问题的排查与定位。 +对于 LoongCollector，具有多租户的特点，可以支持多份采集配置同时工作，LoongCollector 支持将采集配置的元信息打印到日志中，便于问题的排查与定位。 ```go import ( @@ -139,20 +139,20 @@ func Test_plugin_func1(t *testing.T) { ## 启动时控制日志行为 -启动iLogtail 时，默认的日志行为是异步文件Info级别输出，如果需要动态调整，可以参考以下内容进行设置： +启动 LoongCollector 时，默认的日志行为是异步文件Info级别输出，如果需要动态调整，可以参考以下内容进行设置： ### 调整日志级别 启动时如果启动程序相对路径下没有 plugin_logger.xml 文件，则可以使用以下命令设置： ```shell -./ilogtail --logger-level=debug +./loongcollector --logger-level=debug ``` 如果存在 plugin_logger.xml 文件，可以修改文件，或使用以下命令强制重新生成日志配置文件： ```shell -./ilogtail --logger-level=info --logger-retain=false +./loongcollector --logger-level=info --logger-retain=false ``` ### 是否开启控制台打印 @@ -160,11 +160,11 @@ func Test_plugin_func1(t *testing.T) { 默认生成环境关闭控制台打印，如果本地调试环境想开启控制台日志，相对路径下没有 plugin_logger.xml 文件，则可以使用以下命令： ```shell -./ilogtail --logger-console=true +./loongcollector --logger-console=true ``` 如果存在 plugin_logger.xml 文件，可以修改文件，或使用以下命令强制重新生成日志配置文件： ```shell -./ilogtail --logger-console=true --logger-retain=false +./loongcollector --logger-console=true --logger-retain=false ``` diff --git a/docs/cn/developer-guide/plugin-development/plugin-debug/plugin-self-monitor-guide.md b/docs/cn/developer-guide/plugin-development/plugin-debug/plugin-self-monitor-guide.md index 562897b4ad..6b3f56c98f 100644 --- a/docs/cn/developer-guide/plugin-development/plugin-debug/plugin-self-monitor-guide.md +++ b/docs/cn/developer-guide/plugin-development/plugin-debug/plugin-self-monitor-guide.md @@ -1,5 +1,6 @@ # 插件自监控接口 -iLogtail提供了指标接口，可以方便地为插件增加一些自监控指标，目前支持Counter，Gauge，String，Latency等类型。 + +LoongCollector 提供了指标接口，可以方便地为插件增加一些自监控指标，目前支持Counter，Gauge，String，Latency等类型。 接口： @@ -10,6 +11,7 @@ iLogtail提供了指标接口，可以方便地为插件增加一些自监控指 用户使用时需要引入pkg/helper包： + ```go import ( "github.com/alibaba/ilogtail/pkg/helper" @@ -17,7 +19,9 @@ import ( ``` ## 创建指标 + 指标必须先定义后使用，在插件的结构体内声明具体指标。 + ```go type ProcessorRateLimit struct { // other fields @@ -27,13 +31,16 @@ type ProcessorRateLimit struct { } ``` -创建指标时，需要将其注册到iLogtail Context 的 MetricRecord 中，以便 iLogtail 能够采集上报数据，在插件的Init方法中，调用context 的 GetMetricRecord()方法来获取MetricRecord，然后调用helper.New**XXX**MetricAndRegister函数去注册一个指标，例如： +创建指标时，需要将其注册到 LoongCollector Context 的 MetricRecord 中，以便 LoongCollector 能够采集上报数据，在插件的Init方法中，调用context 的 GetMetricRecord()方法来获取MetricRecord，然后调用helper.New**XXX**MetricAndRegister函数去注册一个指标，例如： + ```go 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等配置进行上报： + ```go metricsRecord := f.context.GetMetricRecord() metricLabels := f.buildLabels() @@ -41,35 +48,46 @@ f.matchedEvents = helper.NewCounterMetricAndRegister(metricsRecord, "http_flushe ``` ## 指标打点 + 不同类型的指标有不同的打点方法，直接调用对应Metric类型的方法即可。 Counter： + ```go p.processedMetric.Add(1) ``` + Latency: + ```go tracker.ProcessLatency.Observe(float64(time.Since(startProcessTime))) ``` + StringMetric: + ```go sc.lastBinLogMetric.Set(string(r.NextLogName)) ``` ## 指标上报 -iLogtial会自动采集所有注册的指标，默认采集间隔为60s，然后通过default_flusher上报，数据格式为LogGroup，格式如下： + +LoongCollector 会自动采集所有注册的指标，默认采集间隔为60s，然后通过default_flusher上报，数据格式为LogGroup，格式如下： + ```json {"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， + +和Prometheus SDK类似，LoongCollector 也允许用户在自监控时上报可变Label，对于这些带可变Label的指标集合，LoongCollector 称之为MetricVector， MetricVector同样也支持上述的指标类型，因此把上面的Metric看作是MetricVector不带动态Label的特殊实现。 用例： + ```go type FlusherHTTP struct { // other fields @@ -78,8 +96,10 @@ type FlusherHTTP struct { statusCodeStatistics pipeline.MetricVector[pipeline.CounterMetric] // 带有动态Label的指标 } ``` + 声明并注册MetricVector时，可以使用helper.New**XXX**MetricVectorAndRegister方法， 需要将其带有哪些动态Label的Name也进行声明： + ```go f.statusCodeStatistics = helper.NewCounterMetricVectorAndRegister(metricsRecord, "http_flusher_status_code_count", @@ -89,15 +109,17 @@ f.statusCodeStatistics = helper.NewCounterMetricVectorAndRegister(metricsRecord, ``` 打点时通过WithLabels API传入动态Label的值，拿到一个Metric对象，然后进行打点： + ```go f.statusCodeStatistics.WithLabels(pipeline.Label{Key: "status_code", Value: strconv.Itoa(response.StatusCode)}).Add(1) ``` ## 示例 + 可以参考内置的一些插件： 限流插件： http flusher插件： - \ No newline at end of file + diff --git a/docs/cn/developer-guide/plugin-development/plugin-debug/pure-plugin-start.md b/docs/cn/developer-guide/plugin-development/plugin-debug/pure-plugin-start.md index 2765e976b6..32e1bbe621 100644 --- a/docs/cn/developer-guide/plugin-development/plugin-debug/pure-plugin-start.md +++ b/docs/cn/developer-guide/plugin-development/plugin-debug/pure-plugin-start.md @@ -1,28 +1,29 @@ # 纯插件模式启动 -纯插件模式为iLogtail插件开发提供轻量级测试能力，以下我们将介绍如以纯插件模式启动iLogtail。 +纯插件模式为 LoongCollector 插件开发提供轻量级测试能力，以下我们将介绍如以纯插件模式启动 LoongCollector。 ## 本地启动 -在根目录下执行 `make plugin_main` 命令，会得到 `output/ilogtail` 可执行文件，使用以下命令可以快速启动iLogtail 程序，并将日志使用控制台输出。 +在根目录下执行 `make plugin_main` 命令，会得到 `output/loongcollector` 可执行文件，使用以下命令可以快速启动 LoongCollector 程序，并将日志使用控制台输出。 ```shell # 默认插件启动行为是使用metric_mock 插件mock 数据，并将数据进行日志模式打印。 - ./output/ilogtail --logger-console=true --logger-retain=false +cd output +./loongcollector --logger-console=true --logger-retain=false ``` ## 配置 -iLogtail 目前提供以下4种模式进行配置设置： +LoongCollector 目前提供以下4种模式进行配置设置： * 指定配置文件模式启动。 * 文件至文件快速测试 -* iLogtail 暴露Http 端口，可以进行配置变更。 -* iLogtail-C程序通过程序API进行配置变更。 +* LoongCollector 暴露Http 端口，可以进行配置变更。 +* loongcollector-C程序通过程序API进行配置变更。 ### 指定配置文件模式启动 -在使用独立模式编译得到 ilogtail 这个可执行程序后，你可以通过为其指定一个配置文件（不指定的话默认为当前目录下 plugin.json）来启动它。 +在使用独立模式编译得到 LoongCollector 这个可执行程序后，你可以通过为其指定一个配置文件（不指定的话默认为当前目录下 plugin.json）来启动它。 ```json { @@ -105,14 +106,14 @@ iLogtail 目前提供以下4种模式进行配置设置： } ``` -执行 `./output/ilogtail --plugin=plugin.quickstart.json`，在一段时间后，使用 ctrl+c 中断运行。通过查看目录，会发现生成了 quickstart\_1.stdout 和 quickstart\_2.stdout 两个文件，并且它们的内容一致。查看内容可以发现，其中的每条数据都包含 Index 和 Content 两个键，并且由于有两个输入插件，Content 会有所不同。 +执行 `./loongcollector --plugin=plugin.quickstart.json`，在一段时间后，使用 ctrl+c 中断运行。通过查看目录，会发现生成了 quickstart\_1.stdout 和 quickstart\_2.stdout 两个文件，并且它们的内容一致。查看内容可以发现，其中的每条数据都包含 Index 和 Content 两个键，并且由于有两个输入插件，Content 会有所不同。 ### 文件至文件快速测试 可以使用如下指令，从文件输入数据并输出到文件，快速进行配置测试 ```shell -./output/ilogtail --plugin=plugin.json --file-io=true +./output/loongcollector --plugin=plugin.json --file-io=true ``` 在测试前，需要创建上文所说的json格式的配置文件。与上文不同的是，这里的配置文件不需要配置inputs和flushers（如果配置，inputs会失效，flushers会保留）。当file-io开关被打开时，会自动指定为文件输入，并输出到文件。默认的输入文件是input.log，默认的输出文件是output.log，也可以设置input-file和output-file参数来修改输入和输出文件。 @@ -148,7 +149,7 @@ stdin.log内容如下： 执行如下命令： ```shell -./output/ilogtail --plugin=plugin.file2filetest.json --file-io=true --input-file=stdin.log --output-file=stdout.log +./loongcollector --plugin=plugin.file2filetest.json --file-io=true --input-file=stdin.log --output-file=stdout.log ``` 可以发现生成了一个stdout.log文件，内容如下： @@ -159,14 +160,14 @@ stdin.log内容如下： ### HTTP API 配置变更 -当iLogtail 以独立模式运行时，可以使用HTTP API 进行配置文件变更。 +当 LoongCollector 以独立模式运行时，可以使用HTTP API 进行配置文件变更。 -* 端口： iLogtail 独立运行时，默认启动18689 端口进行监听配置输入。 +* 端口： LoongCollector 独立运行时，默认启动18689 端口进行监听配置输入。 * 接口：/loadconfig 接下来我们将使用HTTP 模式重新进行动态加载**指定配置文件模式启动**篇幅中的静态配置案例。 -1. 首先我们启动 iLogtail 程序： `./output/ilogtail` +1. 首先我们启动 LoongCollector 程序： `./loongcollector` 2. 使用以下命令进行配置重新加载。 ```shell diff --git a/docs/cn/developer-guide/plugin-development/plugin-development-guide.md b/docs/cn/developer-guide/plugin-development/plugin-development-guide.md index 98543bc6dd..bbaf97a466 100644 --- a/docs/cn/developer-guide/plugin-development/plugin-development-guide.md +++ b/docs/cn/developer-guide/plugin-development/plugin-development-guide.md @@ -1,12 +1,24 @@ # 开源插件开发引导 -## 了解 ilogtail 插件 +## 了解 LoongCollector 插件 -ilogtail插件的实现原理、整体架构、系统设计等介绍，请参考[插件系统](../../principle/plugin-system.md)。 +LoongCollector 插件的实现原理、整体架构、系统设计等介绍，请参考[插件系统](../../principle/plugin-system.md)。 -## 开发流程 +## 原生插件开发流程（C++语言） -ilogtail 插件的开发主要有以下步骤： +LoongCollector 原生插件的开发主要有以下步骤： + +1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。 +2. 开发对应插件，可以参考以下文档： + * [如何开发原生Input插件](native-plugins/how-to-write-native-input-plugins.md) + * [如何开发原生Flusher插件](native-plugins/how-to-write-native-flusher-plugins.md) + * [插件配置项基本原则](extended-plugins/principles-of-plugin-configuration.md) +3. 进行单测或者E2E测试，请参考[如何使用单测](../test/unit-test.md) 与 [如何使用E2E测试](../test/e2e-test.md). +4. 提交Pull Request。 + +## 扩展插件开发流程（go语言） + +LoongCollector 插件的开发主要有以下步骤： 1. 创建Issue，描述开发插件功能，会有社区同学参与讨论插件开发的可行性，如果社区review 通过，请参考步骤2继续进行。 2. 实现相应接口。 @@ -16,16 +28,18 @@ ilogtail 插件的开发主要有以下步骤： 6. 使用 *make lint* 检查代码规范。 7. 提交Pull Request。 -在开发时，[Logger接口](plugin-debug/logger-api.md)或许能对您有所帮助。此外，可以使用[纯插件模式启动](plugin-debug/pure-plugin-start.md) iLogtail，用于对插件进行轻量级测试。 +在开发时，[Logger接口](plugin-debug/logger-api.md)和[自监控指标接口](plugin-debug/plugin-self-monitor-guide.md)或许能对您有所帮助。此外，可以使用[纯插件模式启动](plugin-debug/pure-plugin-start.md) LoongCollector，用于对插件进行轻量级测试。 更详细的开发细节，请参考： -* [如何开发Input插件](extended-plugins/how-to-write-input-plugins.md) -* [如何开发Processor插件](extended-plugins/how-to-write-processor-plugins.md) -* [如何开发Aggregator插件](extended-plugins/how-to-write-aggregator-plugins.md) -* [如何开发Flusher插件](extended-plugins/how-to-write-flusher-plugins.md) -* [如何开发Extension插件](extended-plugins/how-to-write-extension-plugins.md) +* [如何开发扩展Input插件](extended-plugins/how-to-write-input-plugins.md) +* [如何开发扩展Processor插件](extended-plugins/how-to-write-processor-plugins.md) +* [如何开发扩展Aggregator插件](extended-plugins/how-to-write-aggregator-plugins.md) +* [如何开发扩展Flusher插件](extended-plugins/how-to-write-flusher-plugins.md) +* [如何开发扩展Extension插件](extended-plugins/how-to-write-extension-plugins.md) * [插件配置项基本原则](extended-plugins/principles-of-plugin-configuration.md) +* [如何开发外部私有插件](extended-plugins/how-to-write-external-plugins.md) +* [如何自定义构建产物中默认包含的插件](extended-plugins/how-to-custom-builtin-plugins.md) ## 文档撰写流程 diff --git a/docs/cn/developer-guide/plugin-development/plugin-docs/plugin-doc-templete.md b/docs/cn/developer-guide/plugin-development/plugin-docs/plugin-doc-templete.md index 38755ef886..63ecda7ac4 100644 --- a/docs/cn/developer-guide/plugin-development/plugin-docs/plugin-doc-templete.md +++ b/docs/cn/developer-guide/plugin-development/plugin-docs/plugin-doc-templete.md @@ -1,6 +1,6 @@ # 插件文档规范 -这是一份 ilogtail 插件的中文文档的模版及格式说明。 +这是一份 LoongCollector 插件的中文文档的模版及格式说明。 ## 格式说明 diff --git a/docs/cn/developer-guide/test/How-to-add-subscriber.md b/docs/cn/developer-guide/test/How-to-add-subscriber.md index a60310e390..4690ee07e2 100644 --- a/docs/cn/developer-guide/test/How-to-add-subscriber.md +++ b/docs/cn/developer-guide/test/How-to-add-subscriber.md @@ -1,6 +1,6 @@ # 如何编写Subscriber插件 -订阅器（Subscribe）插件是测试引擎中用于接收数据的组件，在接收到数据后，订阅器会进一步将数据发送至验证器（Validator）进行校验。如果您为iLogtail开发了新的输出插件，则您必须为该输出插件编写一个对应的订阅器，用于从您输出插件对应的存储单元中拉取iLogtail写入的数据，并在集成测试中使用该订阅器。 +订阅器（Subscribe）插件是测试引擎中用于接收数据的组件，在接收到数据后，订阅器会进一步将数据发送至验证器（Validator）进行校验。如果您为 LoongCollector 开发了新的输出插件，则您必须为该输出插件编写一个对应的订阅器，用于从您输出插件对应的存储单元中拉取 LoongCollector 写入的数据，并在集成测试中使用该订阅器。 ## Subscriber接口定义 @@ -8,7 +8,7 @@ - `Start()`：启动订阅器，不断地从目标存储单元中拉取所需要的数据，在对数据进行转换后，将数据发送至`SubscribeChan()`返回的通道； - `Stop()`：停止订阅器； - `SubscribeChan()`：返回用于向验证器发送接收到的数据的通道，其中通道的数据类型所对应协议的具体信息可参见[LogGroup](../../docs/cn/developer-guide/data-structure.md)； -- `FlusherConfig()`：返回与该订阅器相对应的iLogtail输出插件的默认配置，可直接返回空字符串。 +- `FlusherConfig()`：返回与该订阅器相对应的 LoongCollector 输出插件的默认配置，可直接返回空字符串。 ```go type Subscriber interface { @@ -21,7 +21,7 @@ type Subscriber interface { Stop() // SubscribeChan returns the channel used to transmit received data to validator SubscribeChan() <-chan *protocol.LogGroup - // FlusherConfig returns the default flusher config for Ilogtail container correspoding to this subscriber + // FlusherConfig returns the default flusher config for LoongCollector container correspoding to this subscriber FlusherConfig() string } ``` diff --git a/docs/cn/developer-guide/test/benchmark.md b/docs/cn/developer-guide/test/benchmark.md index 06755d0776..93cb84ff20 100644 --- a/docs/cn/developer-guide/test/benchmark.md +++ b/docs/cn/developer-guide/test/benchmark.md @@ -35,7 +35,7 @@ Feature: performance file to blackhole vector - `@e2e-performance @docker-compose`: 表示测试场景为e2e-performance，测试场景由本地docker-compose运行 - `Given {docker-compose} environment`: 配置启动测试环境，以docker-compose环境启动测试 -- `Given docker-compose boot type {benchmark}`: 配置docker-compose启动模式，以benchmark模式启动docker-compose，`{}`中参数有两种选项，`e2e`/`benchmark`。以`e2e`模式启动会默认启动ilogtail、goc-server容器，用作e2e测试；以`benchmark`模式启动会默认启动cadvisor容器，用于监控容器运行过程中的资源占用；若在配置文件中不配置该参数，则默认以上一个scenario的启动模式启动。 +- `Given docker-compose boot type {benchmark}`: 配置docker-compose启动模式，以benchmark模式启动docker-compose，`{}`中参数有两种选项，`e2e`/`benchmark`。以`e2e`模式启动会默认启动 LoongCollector、goc-server容器，用作e2e测试；以`benchmark`模式启动会默认启动cadvisor容器，用于监控容器运行过程中的资源占用；若在配置文件中不配置该参数，则默认以上一个scenario的启动模式启动。 - `When start docker-compose {directory}`: `{}`中参数为当前scenario的文件夹名，该行动作会读取`directory`文件夹下的docker-compose.yaml文件，通过docker-compose命令启动所有容器 - `When start monitor {vector}`: `{}`中参数为待监控的容器，该参数需要与docker-compose中的service name相同 - `When generate random logs to file`: 向文件中按照速率生成json格式测试数据，其他生成测试数据的方法请参考[e2e-test-step.md](e2e-test-step.md) diff --git a/docs/cn/developer-guide/test/e2e-test-step.md b/docs/cn/developer-guide/test/e2e-test-step.md index f9c2cc49a5..578231c615 100644 --- a/docs/cn/developer-guide/test/e2e-test-step.md +++ b/docs/cn/developer-guide/test/e2e-test-step.md @@ -1,6 +1,6 @@ # E2E测试——如何添加新的测试行为 -iLogtail提供了一个完整的E2E测试引擎，方便您快速开展集成测试，从而进一步保证代码质量。在大部分情况下，您只需要编写一个配置文件来定义测试行为，即可轻松完成测试。 +LoongCollector 提供了一个完整的E2E测试引擎，方便您快速开展集成测试，从而进一步保证代码质量。在大部分情况下，您只需要编写一个配置文件来定义测试行为，即可轻松完成测试。 ## 目前支持的测试行为 @@ -9,14 +9,14 @@ iLogtail提供了一个完整的E2E测试引擎，方便您快速开展集成测 | 行为类型 | 模板 | 参数 | 说明 | | --- | --- | --- | --- | | Given | ^\{(\S+)\} environment$ | 环境类型 | 初始化远程测试环境 | -| Given | ^iLogtail depends on containers \{(.*)\} | 容器 | iLogtail依赖容器，可多次执行，累积添加 | -| Given | ^iLogtail expose port \{(.*)\} to \{(.*)\} | 端口号 | iLogtail暴露端口，可多次执行，累积添加 | +| Given | ^LoongCollector depends on containers \{(.*)\} | 容器 | LoongCollector依赖容器，可多次执行，累积添加 | +| Given | ^LoongCollector expose port \{(.*)\} to \{(.*)\} | 端口号 | LoongCollector暴露端口，可多次执行，累积添加 | | Given | ^\{(.*)\} local config as below | 1. 配置名 2. 配置文件内容 | 添加本地配置 | | Given | ^\{(.*)\} http config as below | 1. 配置名 2. 配置文件内容 | 通过http添加配置 | | Given | ^remove http config \{(.*)\} | 配置名 | 通过http移除配置 | | Given | ^subcribe data from \{(\S+)\} with config | 1. 数据源 2. 配置文件内容 | 订阅数据源 | | When | ^generate \{(\d+)\} regex logs, with interval \{(\d+)\}ms$ | 1. 生成日志数量 2. 生成日志间隔 | 生成正则文本日志（路径为/tmp/ilogtail/regex_single.log） | -| When | ^generate \{(\d+)\} http logs, with interval \{(\d+)\}ms, url: \{(.*)\}, method: \{(.*)\}, body: | 1. 生成日志数量 2. 生成日志间隔 3. url 4. method 5. body | 生成http日志，发送到iLogtail input_http_server | +| When | ^generate \{(\d+)\} http logs, with interval \{(\d+)\}ms, url: \{(.*)\}, method: \{(.*)\}, body: | 1. 生成日志数量 2. 生成日志间隔 3. url 4. method 5. body | 生成http日志，发送到LoongCollector input_http_server | | When | ^add k8s label \{(.*)\} | k8s标签 | 为k8s资源添加标签 | | When | ^remove k8s label \{(.*)\} | k8s标签 | 为k8s资源移除标签 | | When | ^start docker-compose dependencies \{(\S+)\} | 依赖服务 | 启动docker-compose依赖服务 | @@ -39,6 +39,7 @@ iLogtail提供了一个完整的E2E测试引擎，方便您快速开展集成测 ### 1. 编写行为函数 如果您需要添加新的行为函数，可以在`engine`目录下添加一个Go函数。不同目录下的行为函数的职责有所不同： + - `cleanup`：清理测试环境，其中的测试函数会默认在测试结束后执行。无需在配置文件中显式声明使用。 - `control`：管控相关的行为函数，如初始化环境、添加配置等。 - `setup`：初始化测试环境，并提供远程调用的相关功能。 @@ -65,12 +66,12 @@ return context.WithValue(ctx, key, value), nil ```go func scenarioInitializer(ctx *godog.ScenarioContext) { - // Given + // Given - // When + // When - // Then - ctx.Then(`^there is \{(\d+)\} logs$`, verify.LogCount) + // Then + ctx.Then(`^there is \{(\d+)\} logs$`, verify.LogCount) } ``` @@ -92,4 +93,4 @@ ctx.Then(`^there is \{(\d+)\} logs$`, verify.LogCount) Then there is {100} logs ``` -在运行测试时，测试框架会根据配置文件中的行为，调用对应的行为函数，并传递参数。 \ No newline at end of file +在运行测试时，测试框架会根据配置文件中的行为，调用对应的行为函数，并传递参数。 diff --git a/docs/cn/developer-guide/test/e2e-test.md b/docs/cn/developer-guide/test/e2e-test.md index 1b7d1596fa..ae55c336f9 100644 --- a/docs/cn/developer-guide/test/e2e-test.md +++ b/docs/cn/developer-guide/test/e2e-test.md @@ -1,11 +1,13 @@ # E2E测试 -iLogtail提供了一个完整的E2E测试引擎，方便您快速开展集成测试，从而进一步保证代码质量。在大部分情况下，您只需要编写一个配置文件来定义测试行为，即可轻松完成测试。 +LoongCollector 提供了一个完整的E2E测试引擎，方便您快速开展集成测试，从而进一步保证代码质量。在大部分情况下，您只需要编写一个配置文件来定义测试行为，即可轻松完成测试。 ## 工作原理 -E2E测试采用行为驱动开发（Behavior-Driven Development）的设计思路，通过定义一系列测试行为，并通过配置文件的方式来描述测试场景，从而实现对插件的集成测试。测试引擎会根据配置文件中的内容，正则匹配对应的函数，并解析配置文件中的参数，传递给对应的函数。从而完成自动创建测试环境、启动iLogtail、触发日志生成、验证日志内容等一系列操作，最终输出测试报告。 +E2E测试采用行为驱动开发（Behavior-Driven Development）的设计思路，通过定义一系列测试行为，并通过配置文件的方式来描述测试场景，从而实现对插件的集成测试。测试引擎会根据配置文件中的内容，正则匹配对应的函数，并解析配置文件中的参数，传递给对应的函数。从而完成自动创建测试环境、启动 LoongCollector、触发日志生成、验证日志内容等一系列操作，最终输出测试报告。 + 相关参考： + - [https://cucumber.io/docs/bdd/](https://cucumber.io/docs/bdd/) - [https://github.com/cucumber/godog](https://github.com/cucumber/godog) @@ -16,7 +18,7 @@ E2E测试采用行为驱动开发（Behavior-Driven Development）的设计思 在准备开始进行集成测试前，您首先需要准备以下内容： - 测试环境：主机（可通过SSH访问）、K8s集群（可通过kubeconfig访问）、Docker-Compose环境（需在本地安装docker-compose） -- 部署 iLogtail +- 部署 LoongCollector ### 配置文件 @@ -47,7 +49,7 @@ Feature: input static file - "/root/test/**/a*.log" MaxDirSearchDepth: 10 """ - Given iLogtail container mount {./a.log} to {/root/test/1/2/3/axxxx.log} + Given LoongCollector 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 @@ -84,4 +86,4 @@ TEST_CASE=input_canal go test -v -timeout 30m -run ^TestE2EOnDockerCompose$ gith ### 拓展 -如果目前engine中已有的测试行为无法满足您的需求，您可以参考以下[添加指南](e2e-test-step.md)，自行拓展测试行为。 \ No newline at end of file +如果目前engine中已有的测试行为无法满足您的需求，您可以参考以下[添加指南](e2e-test-step.md)，自行拓展测试行为。 diff --git a/docs/cn/developer-guide/test/unit-test.md b/docs/cn/developer-guide/test/unit-test.md index ebfef61dc9..ad4f58395a 100644 --- a/docs/cn/developer-guide/test/unit-test.md +++ b/docs/cn/developer-guide/test/unit-test.md @@ -10,9 +10,11 @@ C++部分单测基于 gtest 实现，具体编写方法可以参考已有测试 1. 进入开发容器中，参考[开发环境](../development-environment.md)。 2. CMake 设置参数 BUILD_LOGTAIL_UT=ON，编译单测 -``` -cmake -DBUILD_LOGTAIL_UT=ON <其他编译参数> .. -``` + + ```shell + cmake -DBUILD_LOGTAIL_UT=ON <其他编译参数> .. + ``` + 3. 运行脚本 `./scripts/run_core_ut.sh`，运行单测 4. 生成覆盖率报告 @@ -32,7 +34,7 @@ python3 tools/coverage-diff/main.py coverage-report/index.txt ### 测试工具 -从插件开发以及 [日志打印](How-to-use-logger.md) 篇幅可以看到，ilogtail.Context 接口包含了iLogtail 的元配置信息，因此提供了Mock Context 以及Mock Collector 实现进行单元测试。 +从插件开发以及 [日志打印](How-to-use-logger.md) 篇幅可以看到，ilogtail.Context 接口包含了 LoongCollector 的元配置信息，因此提供了Mock Context 以及Mock Collector 实现进行单元测试。 ```go import ( diff --git a/docs/cn/installation/release-notes/release-notes.md b/docs/cn/installation/release-notes/release-notes.md index cdf1d507ee..110b65ecfd 100644 --- a/docs/cn/installation/release-notes/release-notes.md +++ b/docs/cn/installation/release-notes/release-notes.md @@ -97,4 +97,5 @@ docker pull sls-opensource-registry.cn-shanghai.cr.aliyuncs.com/loongcollector-c ## iLogtail 版本 [iLogtail 发布记录(2.x版本)](release-notes-ilogtail-2x.md) + [iLogtail 发布记录(1.x版本)](release-notes-ilogtail-1x.md) diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go index 6b5e6f6e61..b778daff60 100644 --- a/pkg/logger/logger.go +++ b/pkg/logger/logger.go @@ -123,7 +123,11 @@ func initNormalLogger() { for _, option := range defaultProductionOptions { option() } - setLogConf(path.Join(config.LoongcollectorGlobalConfig.LoongcollectorConfDir, "plugin_logger.xml")) + confDir := config.LoongcollectorGlobalConfig.LoongcollectorConfDir + if _, err := os.Stat(confDir); os.IsNotExist(err) { + os.MkdirAll(confDir, os.ModePerm) + } + setLogConf(path.Join(confDir, "plugin_logger.xml")) } // initTestLogger extracted from Init method for unit test. diff --git a/scripts/plugin_build.sh b/scripts/plugin_build.sh index fa70e344de..74f651d0f3 100755 --- a/scripts/plugin_build.sh +++ b/scripts/plugin_build.sh @@ -30,7 +30,7 @@ OUT_DIR=${3:-output} VERSION=${4:-0.0.1} PLUGINS_CONFIG_FILE=${5:-${PLUGINS_CONFIG_FILE:-plugins.yml,external_plugins.yml}} GO_MOD_FILE=${6:-${GO_MOD_FILE:-go.mod}} -NAME=ilogtail +NAME=loongcollector LDFLAGS="${GO_LDFLAGS:-}"' -X "github.com/alibaba/ilogtail/pkg/config.BaseVersion='$VERSION'"' BUILD_FLAG=${BUILD_FLAG:-}