From 5a448915439858afb9b68ae9272949bc0561a6a5 Mon Sep 17 00:00:00 2001 From: ethfoo Date: Tue, 8 Mar 2022 20:15:41 +0800 Subject: [PATCH] Docs: update user-guide --- README.md | 16 + docs/developer-guide/code/coding-guide.md | 2 +- docs/developer-guide/metric/metric-guide.md | 0 docs/getting-started/overview.md | 7 +- .../discovery/kubernetes/clusterlogconfig.md | 11 +- .../discovery/kubernetes/interceptors.md | 4 +- .../discovery/kubernetes/logconfig.md | 37 +- .../discovery/kubernetes/overview.md | 18 - docs/reference/discovery/kubernetes/sink.md | 4 +- docs/reference/global/defaults.md | 39 +++ docs/reference/global/monitor.md | 63 +--- docs/reference/global/system.md | 51 --- docs/reference/index.md | 86 ++++- docs/reference/monitor/filesource.md | 62 ++++ docs/reference/monitor/filewatcher.md | 86 +++++ docs/reference/monitor/logalert.md | 13 + docs/reference/monitor/overview.md | 37 ++ docs/reference/monitor/queue.md | 45 +++ docs/reference/monitor/reload.md | 18 + docs/reference/monitor/sink.md | 48 +++ .../pipelines/interceptor/addk8smeta.md | 63 ++++ .../pipelines/interceptor/normalize.md | 129 ++++++- .../pipelines/interceptor/overview.md | 31 ++ docs/reference/pipelines/queue/channel.md | 6 - docs/reference/pipelines/sink/codec.md | 147 -------- docs/reference/pipelines/sink/file.md | 66 ++++ docs/reference/pipelines/sink/kafka.md | 25 ++ docs/reference/pipelines/sink/overview.md | 36 ++ docs/reference/pipelines/source/dev.md | 25 ++ docs/reference/pipelines/source/grpc.md | 5 +- docs/reference/pipelines/source/kafka.md | 51 ++- .../source/{kubeEvent.md => kube-event.md} | 0 docs/reference/pipelines/source/overview.md | 103 ++++++ .../pipelines/source/prometheus-exporter.md | 37 ++ docs/reference/pipelines/source/unix.md | 44 +++ docs/user-guide/architecture/advantages.md | 16 +- docs/user-guide/architecture/background.md | 32 +- docs/user-guide/architecture/compare.md | 58 +++- docs/user-guide/architecture/config.md | 3 - docs/user-guide/architecture/core-arch.md | 12 +- docs/user-guide/architecture/schema.md | 57 +--- .../aggregator.md | 15 +- docs/user-guide/best-practice/log-clean.md | 0 docs/user-guide/best-practice/log-format.md | 316 +++++++++--------- docs/user-guide/best-practice/log-process.md | 19 +- .../enterprise-log-practice.md | 7 - docs/user-guide/index.md | 8 +- docs/user-guide/monitor/loggie-monitor.md | 8 +- docs/user-guide/monitor/service-log-alarm.md | 2 +- docs/user-guide/troubleshot/FAQ.md | 1 - .../troubleshot/general-problems.md | 1 - .../collect-container-logs.md | 21 +- .../use-in-kubernetes/collect-node-logs.md | 4 +- .../use-in-kubernetes/kube-event-source.md | 16 +- docs/user-guide/use-in-kubernetes/sidecar.md | 5 - nav.yml | 52 +-- 56 files changed, 1389 insertions(+), 679 deletions(-) create mode 100644 README.md delete mode 100644 docs/developer-guide/metric/metric-guide.md delete mode 100644 docs/reference/discovery/kubernetes/overview.md delete mode 100644 docs/reference/global/system.md create mode 100644 docs/reference/monitor/filesource.md create mode 100644 docs/reference/monitor/filewatcher.md create mode 100644 docs/reference/monitor/logalert.md create mode 100644 docs/reference/monitor/overview.md create mode 100644 docs/reference/monitor/queue.md create mode 100644 docs/reference/monitor/reload.md create mode 100644 docs/reference/monitor/sink.md create mode 100644 docs/reference/pipelines/interceptor/addk8smeta.md create mode 100644 docs/reference/pipelines/interceptor/overview.md delete mode 100644 docs/reference/pipelines/sink/codec.md create mode 100644 docs/reference/pipelines/sink/file.md create mode 100644 docs/reference/pipelines/sink/overview.md create mode 100644 docs/reference/pipelines/source/dev.md rename docs/reference/pipelines/source/{kubeEvent.md => kube-event.md} (100%) create mode 100644 docs/reference/pipelines/source/overview.md create mode 100644 docs/reference/pipelines/source/prometheus-exporter.md create mode 100644 docs/reference/pipelines/source/unix.md delete mode 100644 docs/user-guide/architecture/config.md rename docs/user-guide/{use-in-kubernetes => best-practice}/aggregator.md (86%) delete mode 100644 docs/user-guide/best-practice/log-clean.md delete mode 100644 docs/user-guide/enterprise-practice/enterprise-log-practice.md delete mode 100644 docs/user-guide/troubleshot/FAQ.md delete mode 100644 docs/user-guide/troubleshot/general-problems.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a52791 --- /dev/null +++ b/README.md @@ -0,0 +1,16 @@ +# Loggie documentation + +This is the source file repository for Loggie documentation. + +## Run the website locally +The Loggie documentation website is built using [mkdocs-material](https://squidfunk.github.io/mkdocs-material/). + +The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. + +``` +docker pull squidfunk/mkdocs-material + +docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` + +Point your browser to localhost:8000 and you should see the webside. diff --git a/docs/developer-guide/code/coding-guide.md b/docs/developer-guide/code/coding-guide.md index 5cc4d57..3ebf356 100644 --- a/docs/developer-guide/code/coding-guide.md +++ b/docs/developer-guide/code/coding-guide.md @@ -45,7 +45,7 @@ ## 监控 -* 任何新组件都应该带有适当的指标，以便监控功能正常工作（参考[metric上报](../metric/metric-guide.md)） +* 任何新组件都应该带有适当的指标，以便监控功能正常工作 * 应该认真对待这些指标，并且只上报有用的指标，这些指标将在生产中用于监测/提醒系统的健康状况，或排查问题 ## 单元测试 diff --git a/docs/developer-guide/metric/metric-guide.md b/docs/developer-guide/metric/metric-guide.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 7aaed65..0133272 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -26,12 +26,7 @@ ## :question: 解答 在使用Loggie的时候遇到问题？ - -运维排障，请看「[一般问题排查思路](../user-guide/troubleshot/general-problems.md)」。 - -使用上的疑惑，可以先参考「[FAQ](../user-guide/troubleshot/FAQ.md)」。 - -如果还是不能解决你的问题，请提issues或者联系我们。 +请提issues或者联系我们。 ## :globe_with_meridians: 参与 如果你对Loggie的具体实现感兴趣，想参与Loggie开源的研发？想自研插件？请看「[开发手册](../developer-guide/contributing.md)」。 diff --git a/docs/reference/discovery/kubernetes/clusterlogconfig.md b/docs/reference/discovery/kubernetes/clusterlogconfig.md index 1959701..adb5063 100644 --- a/docs/reference/discovery/kubernetes/clusterlogconfig.md +++ b/docs/reference/discovery/kubernetes/clusterlogconfig.md @@ -1,6 +1,10 @@ # ClusterLogConfig -表示选择一批Pod进行日志采集、采集Node节点上的日志或者将pipeline配置下发至指定cluster的Pipeline配置。 +Cluster级别CRD，可用于： + +- 采集任意Namespace的Pod日志 +- 采集Node节点上的日志 +- 将Pipeline配置下发至指定Loggie集群 !!! example @@ -90,8 +94,5 @@ ## spec.pipelines -和在配置文件中Pipelines的区别在： -- sources为实际为string，在yaml中使用`｜`表示保留换行符，同时增加了几个特殊的参数。 -- 没有sink，只有sinkRef，表示引用的Sink CRD实例 -- 没有interceptors，只有interceptorsRef，表示引用的Interceptors CRD实例 \ No newline at end of file +配置和LogConfig一致。 \ No newline at end of file diff --git a/docs/reference/discovery/kubernetes/interceptors.md b/docs/reference/discovery/kubernetes/interceptors.md index b40fc76..174d5c0 100644 --- a/docs/reference/discovery/kubernetes/interceptors.md +++ b/docs/reference/discovery/kubernetes/interceptors.md @@ -1,6 +1,6 @@ -# interceptor +# Interceptor -表示一个interceptor组。 +表示一个interceptor组。用于在LogConfig/ClusterLogConfig中被引用。 !!! example diff --git a/docs/reference/discovery/kubernetes/logconfig.md b/docs/reference/discovery/kubernetes/logconfig.md index dfe767b..aeef0b1 100644 --- a/docs/reference/discovery/kubernetes/logconfig.md +++ b/docs/reference/discovery/kubernetes/logconfig.md @@ -1,6 +1,6 @@ # Logconfig -表示一个日志采集任务或者一个Pipeline配置。 +namespace级别CRD，表示一个日志采集任务，用于采集Pod容器日志。 !!! example @@ -22,14 +22,13 @@ paths: - stdout sinkRef: default - + interceptorsRef: default ``` ## spec.selector 表示Pipeline配置适用的范围，可以选择采集一批Pods的日志 - ### type: pod 采集Pods日志 @@ -50,7 +49,7 @@ 表示采集该namespace下的带有label `app: nginx`的所有Pods日志。 !!! warning - 在`type: pod`时，下面的Pipeline只能使用file source，此时的场景只能是采集日志。 + 在`type: pod`时，下面的Pipeline只支持使用file source，此时的场景只能是采集日志。 ### cluster @@ -60,24 +59,27 @@ -## spec.pipelines +## spec.pipeline + +表示一个Pipeline，不支持填写多个Pipeline。 + 和在配置文件中Pipelines的区别在： -- sources为实际为string，在yaml中使用`｜`表示保留换行符，同时增加了几个特殊的参数。 +- sources为实际为string，在yaml中使用`｜`表示保留换行符 - 没有sink，只有sinkRef，表示引用的Sink CRD实例 - 没有interceptors，只有interceptorsRef，表示引用的Interceptors CRD实例 ### sources -在LogConfig中，如果`type: pod`，`file source`新增有几个专门针对容器化的参数： +在LogConfig中，如果`type: pod`，`file source`新增几个专门针对容器化的参数： | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | | containerName | string | 非必填 | | 表示指定采集的容器名称，建议在Pod里包含多个容器时填写 | +| excludeContainerPatterns | string数组 | 非必填 | | 排除的容器名称，使用正则表达式形式 | | matchFields | | 非必填 | | 将Pod中的信息加入到Fields中 | | matchFields.labelKey | string数组 | 非必填 | | 指定增加的Pod上的Label Key值，比如Pod上包含Label: `app: demo`，此处填写`labelKey: app`，此时会将Pod上的`app: demo` label增加到file source fields中，采集到的日志会被加上该label信息。适用于匹配的Pod的label存在不一致的场景。 | -| annotationKey | string数组 | 非必填 | | 和上面labelKey类似，注入的为Pod Annoatation的值 | -| env | string数组 | 非必填 | | 和上面labelKey类似，注入的为Pod Env环境变量的值 | - +| matchFields.annotationKey | string数组 | 非必填 | | 和上面labelKey类似，注入的为Pod Annoatation的值 | +| matchFields.env | string数组 | 非必填 | | 和上面labelKey类似，注入的为Pod Env环境变量的值 | !!! example @@ -102,4 +104,17 @@ paths: - stdout - ``` \ No newline at end of file + ``` + +### sinkRef + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| sinkRef | string | 非必填 | | 表示该Pipeline引用的Sink CR | + + +### interceptorsRef + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| interceptorsRef | string | 非必填 | | 表示该Pipeline引用的Interceptor CR | diff --git a/docs/reference/discovery/kubernetes/overview.md b/docs/reference/discovery/kubernetes/overview.md deleted file mode 100644 index 5ac52fe..0000000 --- a/docs/reference/discovery/kubernetes/overview.md +++ /dev/null @@ -1,18 +0,0 @@ -# Kubernetes下的Loggie配置 - - -Loggie定义了3个CRD用于在Kubernetes集群环境里下发配置： - -## [`LogConfig`](logconfig.md) -namespace级别，表示一个Pipeline配置，采集Pods的容器日志 - -## [`ClusterLogConfig`](clusterlogconfig.md) -cluster级别，表示一个Pipeline配置，包括采集Node节点上的日志，将pipeline配置下发至指定cluster的Loggie集群 - -## [`Sink`](sink.md) -cluster级别，表示一个sink配置，可以在LogConfig中引用该Sink - -## [`Interceptors`](interceptors.md) -cluster级别，表示一个interceptors组，可以在LogConfig中引用该interceptors组 - - diff --git a/docs/reference/discovery/kubernetes/sink.md b/docs/reference/discovery/kubernetes/sink.md index a07caaa..dc308f3 100644 --- a/docs/reference/discovery/kubernetes/sink.md +++ b/docs/reference/discovery/kubernetes/sink.md @@ -1,6 +1,6 @@ -# sink +# Sink -表示一个sink配置。 +表示一个sink配置。用于在LogConfig/ClusterLogConfig中被引用。 !!! example diff --git a/docs/reference/global/defaults.md b/docs/reference/global/defaults.md index bd0339f..f2df450 100644 --- a/docs/reference/global/defaults.md +++ b/docs/reference/global/defaults.md @@ -32,6 +32,45 @@ defaults用于设置Pipelines配置中的默认值。当Pipeline中没有设置 和Pipeline中的sink一致，如果集群只需要设置一个全局的sink输出源，则只需要在这里配置一次，避免在每个Pipeline中填写。 ## interceptors +defaults中配置的interceptors会添加到pipeline中定义的interceptors中，但pipeline中的interceptor会覆盖defaults中的同一个type的interceptor。 +如果不希望覆盖相同类型的interceptor，而是添加相同type的interceptor，依次进行处理，需要额外填写name字段，进行唯一性标识。 + +在defaults中已经定义normalize interceptor如下: + +```yaml +defaults: + interceptors: + - type: normalize + processor: + - addMeta: ~ +``` + +如果在pipelines中定义如下normalize interceptor： + +```yaml +pipelines: + interceptors: + - type: normalize + processor: + - drop: + ... +``` + +此时defaults中的normalize interceptor会被覆盖，不会生效。 + +如果我们希望先执行defaults中的normalize interceptor，接着再执行pipeline中的normalize interceptor，可以在defaults中改为： + +```yaml +defaults: + interceptors: + - type: normalize + name: global # 用于区分pipelines中的normalize + order: 500 # 默认normalize的order值为900，这里定义一个相对较小值，可控制先执行defaults中的normalize + processor: + - addMeta: ~ + +``` + Loggie会默认设置`metric`、`maxbytes`、`retry`3个系统内置interceptors。 如果需要添加其他的默认interceptors，会覆盖掉以上的内置interceptors，所以强烈建议此时将内置interceptors加上，除非你确认不需要以上系统内置的interceptors。 diff --git a/docs/reference/global/monitor.md b/docs/reference/global/monitor.md index 1168922..00815fb 100644 --- a/docs/reference/global/monitor.md +++ b/docs/reference/global/monitor.md @@ -2,6 +2,8 @@ # Monitor 监控事件总线，所有的组件都可以发出自己的metrics指标数据，由listeners消费处理。 +具体请参考[这里](../monitor/overview.md)。 + !!! example ```yaml @@ -14,63 +16,4 @@ filewatcher: ~ reload: ~ sink: ~ - ``` - -## logger - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| logger | map | 非必填 | | 控制监控指标metrics输出到Loggie本身的日志中 | -| logger.enabled | bool | 非必填 | false | 是否开启 | -| logger.period | time.Duration | 非必填 | 10s | 指标打印的时间间隔，数据量较大时建议将间隔延长，如30s、5m | -| logger.pretty | bool | 非必填 | false | 打印的指标json是否需要友好展示 | -| logger.additionLogEnabled | bool | 非必填 | false | 是否需要将打印的指标单独输出到另外的日志文件中，在数据量比较多的情况下，如果我们配置的打印时间间隔较短，可以打开该开关，避免太多的metrics日志干扰 | -| logger.additionLogConfig | | 非必填 | | 额外输出的日志配置参数 | -| logger.additionLogConfig.directory | bool | 非必填 | /data/loggie/log | 额外输出的日志目录 | -| logger.additionLogConfig.maxBackups | int | 非必填 | metrics.log | 日志轮转最多保留的文件个数，默认为3 | -| logger.additionLogConfig.maxSize | int | 非必填 | 1024 | 日志轮转的时候，最大的文件大小，单位为MB | -| logger.additionLogConfig.maxAge | int | 非必填 | 14 | 日志轮转最大保留的天数 | -| logger.additionLogConfig.timeFormat | string | 非必填 | 2006-01-02 15:04:05 | 每行日志输出的时间格式 | - - -## listeners - -### filesource - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| filesource | | 非必填 | | file source实时文件采集的监控指标处理，包括文件的名称、采集进度、文件大小、qps等 | - - -### filewatcher - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| filewatcher | | 非必填 | | 对文件采集情况的定时检查并暴露指标，包括文件名称、ackOffset、修改时间、大小等 | -| filewatcher.period | time.Duration | 非必填 | 5m | 定时检查间隔时间 | -| filewatcher.checkUnFinishedTimeout | time.Duration | 非必填 | 24h | 检查文件是否采集完毕的超时时间，如果检测到文件的最近修改时间为`checkUnFinishedTimeout`之前，同时文件的并未采集完毕，则会在metrics中被标记为unfinished状态 | - - -### sink - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| sink | | 非必填 | | sink发送端的监控指标处理，包括发送成功的event数量、发送失败的event数量、event qps等 | - - -### reload - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| reload | | 非必填 | | reload的指标处理，目前为总的reload次数 | - - -### logAlert - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| logAlert | | 非必填 | | 日志报警 | -| logAlert.alertManagerAddress | string数组 | 必填 | | alertManager地址 | -| logAlert.bufferSize | int | 非必填 | 100 | 日志报警发送的buffer大小，单位为报警事件个数 | -| logAlert.batchTimeout | time.Duration | 非必填 | 10s | 每个报警发送batch的最大发送时间 | -| logAlert.batchSize | int | 非必填 | 10 | 每个报警发送batch的最大包含报警请求个数 | \ No newline at end of file + ``` \ No newline at end of file diff --git a/docs/reference/global/system.md b/docs/reference/global/system.md deleted file mode 100644 index 365bf66..0000000 --- a/docs/reference/global/system.md +++ /dev/null @@ -1,51 +0,0 @@ -启动参数中使用`-config.system`指定全局系统YAML格式的配置，包含如下： - -- [**monitor**](monitor.md): 监控相关的配置 -- [**discovery**](discovery.md): 服务发现与配置下发 -- [**reload**](reload.md): 动态配置热加载 -- [**defaults**](defaults.md): 全局默认配置 -- [**http**](http.md): 管理和监控使用的http端口 - - -???+ example "全局配置示例" - - ``` yaml - # loggie.yml - loggie: - monitor: - logger: - period: 30s - enabled: true - listeners: - filesource: ~ - filewatcher: ~ - reload: ~ - sink: ~ - - discovery: - enabled: true - kubernetes: - fields: - container.name: containername - logConfig: logconfig - namespace: namespace - node.name: nodename - pod.name: podname - - reload: - enabled: true - period: 10s - - defaults: - sink: - type: dev - sources: - - type: file - watcher: - cleanFiles: - maxHistory: 1 - http: - enabled: true - port: 9196 - - ``` \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index 2cbf480..784c7d8 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,8 +1,90 @@ ## 配置 +Loggie的配置主要分为两类： +### 系统配置 +全局的系统配置，启动参数中使用`-config.system`指定，包含如下： + +- [**monitor**](global/monitor.md): 监控相关的配置 +- [**discovery**](global/discovery.md): 服务发现与配置下发 +- [**reload**](global/reload.md): 动态配置热加载 +- [**defaults**](global/defaults.md): 全局默认配置 +- [**http**](global/http.md): 管理和监控使用的http端口 + +???+ example "loggie.yml" + + ``` yaml + # loggie.yml + loggie: + monitor: + logger: + period: 30s + enabled: true + listeners: + filesource: ~ + filewatcher: ~ + reload: ~ + sink: ~ + + discovery: + enabled: true + kubernetes: + fields: + container.name: containername + logConfig: logconfig + namespace: namespace + node.name: nodename + pod.name: podname + + reload: + enabled: true + period: 10s + + defaults: + sink: + type: dev + sources: + - type: file + watcher: + cleanFiles: + maxHistory: 1 + http: + enabled: true + port: 9196 + + ``` + +### Pipeline配置 +Pipeline的配置，通过启动参数`-config.pipeline`指定。表示队列使用的Source、Sink、Queue和Interceptor。 + +- [**Source**](pipelines/source/overview.md): 每个Pipeline可配置多个Source +- [**Interceptor**](pipelines/interceptor/normalize.md): 每个Pipeline可配置多个Interceptor +- [**Sink**](pipelines/sink/overview.md): 每个Pipeline可配置一个Sink +- [**Queue**](pipelines/queue/channel.md): 默认为channel队列，一般无需配置 + +???+ example "pipeline.yml" + + ``` yaml + pipelines: + - name: demo # pipeline name必填 + sources: + - type: ${sourceType} + name: access # source中name必填 + ... + interceptors: + - type: ${interceptorType} + ... + sink: + type: ${sinkType} + ... + ``` ## Kubernetes CRD +Loggie定义了以下几个CRD用于在Kubernetes集群环境里下发配置： -## API +- [**LogConfig**](discovery/kubernetes/logconfig.md)：namespace级别，表示一个Pipeline配置，可用于采集Pods的容器日志。 -## Metrics \ No newline at end of file +- [**ClusterLogConfig**](discovery/kubernetes/clusterlogconfig.md)：cluster级别，表示一个Pipeline配置，包括集群级别的跨Namespace采集Pod容器日志，采集Node节点上的日志，以及为某个Loggie集群下发通用的pipeline配置。 + +- [**Sink**](discovery/kubernetes/sink.md)：cluster级别，表示一个sink配置，可以在LogConfig/ClusterLogConfig中引用该Sink。 + +- [**Interceptors**](discovery/kubernetes/interceptors.md)：cluster级别，表示一个interceptors组，可以在LogConfig中引用该interceptors组。 diff --git a/docs/reference/monitor/filesource.md b/docs/reference/monitor/filesource.md new file mode 100644 index 0000000..a25b68d --- /dev/null +++ b/docs/reference/monitor/filesource.md @@ -0,0 +1,62 @@ +# filesource listener + +实时文件采集的监控，表示当前日志采集的进度与状态，包括文件的名称、采集进度、QPS等。 + +## 配置 +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| period | time.Duration | 非必填 | 10s | listener消费处理数据的时间间隔 | + +## Metrics + +* LABELS: + * pipeline: 表示所在的pipeline名称 + * source: 表示所在的source名称 + * filename: 表示文件名 + +#### file_size + +``` +# HELP file size +# TYPE loggie_filesource_file_size gauge +loggie_filesource_file_size{pipeline="xxx", source="access", filename="/var/log/a.log"} 2048 +``` + +* HELP: 表示当前某个日志文件被采集时的文件大小 +* TYPE: gauge + + +#### file_offset + +``` +# HELP file offset +# TYPE loggie_filesource_file_offset gauge +loggie_filesource_file_offset{pipeline="xxx", source="access", filename="/var/log/a.log"} 1024 +``` + +* HELP: 表示当前某个日志文件被采集的进度，当前读取文件的offset +* TYPE: gauge + + +#### line_number + +``` +# HELP current read line number +# TYPE loggie_filesource_line_number gauge +loggie_filesource_line_number{pipeline="xxx", source="access", filename="/var/log/a.log"} 20 +``` + +* HELP: 表示当前某个日志文件被采集时的当前读取的行数 +* TYPE: gauge + + +#### line_qps + +``` +# HELP current read line qps +# TYPE loggie_filesource_line_qps gauge +loggie_filesource_line_qps{pipeline="xxx", source="access", filename="/var/log/a.log"} 48 +``` + +* HELP: 表示当前某个日志文件被采集时每秒读取的行数 +* TYPE: gauge diff --git a/docs/reference/monitor/filewatcher.md b/docs/reference/monitor/filewatcher.md new file mode 100644 index 0000000..078f664 --- /dev/null +++ b/docs/reference/monitor/filewatcher.md @@ -0,0 +1,86 @@ +# filewatcher listener + +对文件采集情况的定时检查并暴露指标，包括文件名称、ackOffset、修改时间、大小等。 + +## 配置 + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| period | time.Duration | 非必填 | 5m | 定时检查间隔时间 | +| checkUnFinishedTimeout | time.Duration | 非必填 | 24h | 检查文件是否采集完毕的超时时间，如果检测到文件的最近修改时间为`checkUnFinishedTimeout`之前，同时文件的并未采集完毕，则会在metrics中被标记为unfinished状态，可用于检查是否有长时间未被采集的日志文件 | + + +## Metrics + +### 全局级别 +#### total_file_count + +``` +# HELP file count total +# TYPE loggie_filewatcher_total_file_count gauge +loggie_filewatcher_total_file_count{} 20 +``` + +* HELP: 表示当前被Loggie检测到活跃的文件个数总和 +* TYPE: gauge + +#### inactive_file_count + +``` +# HELP inactive file count +# TYPE loggie_filewatcher_inactive_file_count gauge +loggie_filewatcher_inactive_file_count{} 20 +``` + +* HELP: 表示当前被Loggie检测到的不活跃的文件个数总和 +* TYPE: gauge + +### 文件级别 + +文件级别包括了以下prometheus labels: + +* LABELS: + * pipeline: 表示所在的pipeline名称 + * source: 表示所在的source名称 + * filename: 表示文件名 + * status: 表示文件状态。 + * pending: 已被检测到，可能采集中或者采集完毕 + * unfinished: 文件的modify time距当前时间已经超过`checkUnFinishedTimeout`时间 + * ignored: 文件被忽略，可能超过`ignore_older`时间 + +由于定时扫描的时间间隔`period`默认为5min，以下指标可能存在一定程度的延迟。 + +#### file_size + +``` +# HELP file size +# TYPE loggie_filewatcher_file_size gauge +loggie_filewatcher_file_size{pipeline="xxx", source="access", filename="/var/log/a.log", status="pending"} 2048 +``` + +* HELP: 表示该文件的总大小 +* TYPE: gauge + + +#### file_ack_offset + +``` +# HELP file ack offset +# TYPE loggie_filewatcher_file_ack_offset gauge +loggie_filewatcher_file_ack_offset{pipeline="xxx", source="access", filename="/var/log/a.log", status="pending"} 1024 +``` + +* HELP: 表示该文件被采集后，并且已经接收到ack的offset，可被理解为已经发送成功的文件offset进度 +* TYPE: gauge + +#### file_last_modify + +``` +# HELP file last modify timestamp +# TYPE loggie_filewatcher_file_last_modify gauge +loggie_filewatcher_file_last_modify{pipeline="xxx", source="access", filename="/var/log/a.log", status="pending"} 2343214422 +``` + +* HELP: 文件的最新被修改时间 +* TYPE: gauge + diff --git a/docs/reference/monitor/logalert.md b/docs/reference/monitor/logalert.md new file mode 100644 index 0000000..4569bcd --- /dev/null +++ b/docs/reference/monitor/logalert.md @@ -0,0 +1,13 @@ +# logAlert listener + +用于日志报警的发送。 + +## 配置 + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| alertManagerAddress | string数组 | 必填 | | alertManager地址 | +| bufferSize | int | 非必填 | 100 | 日志报警发送的buffer大小，单位为报警事件个数 | +| batchTimeout | time.Duration | 非必填 | 10s | 每个报警发送batch的最大发送时间 | +| batchSize | int | 非必填 | 10 | 每个报警发送batch的最大包含报警请求个数 | + diff --git a/docs/reference/monitor/overview.md b/docs/reference/monitor/overview.md new file mode 100644 index 0000000..6e74e80 --- /dev/null +++ b/docs/reference/monitor/overview.md @@ -0,0 +1,37 @@ +# Monitor +监控事件总线，所有的组件都可以发出自己的metrics指标数据，由listeners消费处理。 + +!!! example + + ```yaml + monitor: + logger: + period: 30s + enabled: true + listeners: + filesource: ~ + filewatcher: ~ + reload: ~ + sink: ~ + ``` + +## logger +Loggie支持将metrics指标输出到日志中，可以通过logger配置。 + + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| logger.enabled | bool | 非必填 | false | 是否开启 | +| logger.period | time.Duration | 非必填 | 10s | 指标打印的时间间隔，数据量较大时建议将间隔延长，如30s、5m | +| logger.pretty | bool | 非必填 | false | 打印的指标json是否需要友好展示 | +| logger.additionLogEnabled | bool | 非必填 | false | 是否需要将打印的指标单独输出到另外的日志文件中，在数据量比较多的情况下，如果我们配置的打印时间间隔较短，可以打开该开关，避免太多的metrics日志干扰 | +| logger.additionLogConfig | | 非必填 | | 额外输出的日志配置参数 | +| logger.additionLogConfig.directory | bool | 非必填 | /data/loggie/log | 额外输出的日志目录 | +| logger.additionLogConfig.maxBackups | int | 非必填 | metrics.log | 日志轮转最多保留的文件个数，默认为3 | +| logger.additionLogConfig.maxSize | int | 非必填 | 1024 | 日志轮转的时候，最大的文件大小，单位为MB | +| logger.additionLogConfig.maxAge | int | 非必填 | 14 | 日志轮转最大保留的天数 | +| logger.additionLogConfig.timeFormat | string | 非必填 | 2006-01-02 15:04:05 | 每行日志输出的时间格式 | + +## listeners +表示具体启动的listeners。 +配置不填写即为关闭，不启动该Listener，相关的的指标也不会被处理和暴露。 \ No newline at end of file diff --git a/docs/reference/monitor/queue.md b/docs/reference/monitor/queue.md new file mode 100644 index 0000000..9872178 --- /dev/null +++ b/docs/reference/monitor/queue.md @@ -0,0 +1,45 @@ +# queue listener + +## 配置 +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| period | time.Duration | 非必填 | 10s | listener消费处理数据的时间间隔 | + +## Metrics + +* LABELS: + * pipeline: 表示所在的pipeline名称 + * type: queue队列的类型 + +#### capacity + +``` +# HELP queue capacity +# TYPE loggie_queue_capacity gauge +loggie_queue_capacity{pipeline="xxx", type="channel"} 2048 +``` + +* HELP: 当前队列的容量 +* TYPE: gauge + +#### size + +``` +# HELP queue size +# TYPE loggie_queue_size gauge +loggie_queue_size{pipeline="xxx", type="channel"} 2048 +``` + +* HELP: 当前队列被使用的长度 +* TYPE: gauge + +#### fill_percentage + +``` +# HELP how full is queue +# TYPE loggie_queue_fill_percentage gauge +loggie_queue_fill_percentage{pipeline="xxx", type="channel"} 50 +``` + +* HELP: 当前队列使用的百分比 +* TYPE: gauge \ No newline at end of file diff --git a/docs/reference/monitor/reload.md b/docs/reference/monitor/reload.md new file mode 100644 index 0000000..f013ca4 --- /dev/null +++ b/docs/reference/monitor/reload.md @@ -0,0 +1,18 @@ +# reload listener + +reload的指标，总的reload次数。 + + +## Metrics + +#### total + +``` +# HELP Loggie reload total count +# TYPE loggie_reload_total gauge +loggie_reload_total{} 10 +``` + +* HELP: 表示当前reload的总次数 +* TYPE: counter + diff --git a/docs/reference/monitor/sink.md b/docs/reference/monitor/sink.md new file mode 100644 index 0000000..ebfbc78 --- /dev/null +++ b/docs/reference/monitor/sink.md @@ -0,0 +1,48 @@ +# sink listener + +sink发送端的监控指标处理，包括发送成功的event数量、发送失败的event数量、event qps等 + +## 配置 +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| period | time.Duration | 非必填 | 10s | listener消费处理数据的时间间隔 | + + +## Metrics + +* LABELS: + * pipeline: 表示所在的pipeline名称 + * source: 表示所在的source名称 + +#### success_event + +``` +# HELP send event success count +# TYPE loggie_sink_success_event gauge +loggie_sink_success_event{pipeline="xxx", source="access"} 2048 +``` + +* HELP: 在`period`时间段内，发送成功的event个数 +* TYPE: gauge + +#### failed_event + +``` +# HELP send event failed count +# TYPE loggie_sink_failed_event gauge +loggie_sink_failed_event{pipeline="xxx", source="access"} 2048 +``` + +* HELP: 在`period`时间段内，发送失败的event个数 +* TYPE: gauge + +#### event_qps + +``` +# HELP send success event failed count +# TYPE loggie_sink_event_qps gauge +loggie_sink_event_qps{pipeline="xxx", source="access"} 2048 +``` + +* HELP: 在`period`时间段内，发送的event QPS +* TYPE: gauge \ No newline at end of file diff --git a/docs/reference/pipelines/interceptor/addk8smeta.md b/docs/reference/pipelines/interceptor/addk8smeta.md new file mode 100644 index 0000000..63f84f2 --- /dev/null +++ b/docs/reference/pipelines/interceptor/addk8smeta.md @@ -0,0 +1,63 @@ +# addK8sMeta + +用于从event中的某些字段（比如日志文件的路径中），提取到： + +- `pod.uid` +- `namespace`与`pod.name` +- `container.id` + +以上3种任意其一，此时Loggie可索引到具体的Pod信息，并添加`${node.name}`、`${namespace}`、`${pod.uid}`、`${pod.name}`等元信息作加入到event中，用于后续的分析处理。 +属于source interceptor。 + +!!! example + + ```yaml + interceptors: + - type: addK8sMeta + pattern: "/var/log/${pod.uid}/${pod.name}/" + addFields: + nodename: "${node.name}" + namespace: "${namespace}" + podname: "${pod.name}" + ``` + +## patternFields + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| patternFields | string | 非必填 | 默认会从event中获取系统字段里的filename | 用于提取的字段 | + +## pattern + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| pattern | string | 必填 | | 提取字段的匹配模型 | + +必须包含有： + +- `pod.uid` +- `namespace与pod.name` +- `container.id` + +其中之一。 + +比如：`/var/log/${pod.uid}/${pod.name}/` + +## fieldsName + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| fieldsName | string | 非必填 | kubernetes | 添加元信息的字段 | + +## addFields + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| addFields | map | 非必填 | | 需要添加的元信息 | + +目前支持添加的元信息字段有： + +- `${node.name}` +- `${namespace}` +- `${pod.uid}` +- `${pod.name}` \ No newline at end of file diff --git a/docs/reference/pipelines/interceptor/normalize.md b/docs/reference/pipelines/interceptor/normalize.md index 339fb17..e32a3f9 100644 --- a/docs/reference/pipelines/interceptor/normalize.md +++ b/docs/reference/pipelines/interceptor/normalize.md @@ -10,7 +10,44 @@ | ---------- | ----------- | ----------- | --------- | -------- | | processors | 数组 | 必填 | 无 | 所有的处理processor列表 | -配置的processor将按照顺序依次执行。包括： +配置的processor将按照顺序依次执行。 + +!!! tips + + Loggie支持使用`a.b`的形式引用嵌套的字段。 + 比如数据为: + ```json + { + "fields": { + "hello": "world" + } + } + ``` + 下面的processor配置中均可以使用`fields.hello`指定嵌套在`fields`里的`hello: world`。 + +### addMeta +默认情况下，Loggie不会添加任何的系统内部信息到原始数据中。 +可通过addMeta添加系统内置字段发送给下游。 + +!!! note + 请注意，在pipeline中配置addMeta，只会影响该pipeline发送的所有数据，如果需要全局生效，请在[defaults](../../global/defaults.md)中配置normalize.addMeta。 + + ``` + loggie: + defaults: + interceptors: + - type: normalize + name: global + processors: + addMeta: ~ + + ``` + + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| target | string | 非必填 | meta | 系统内置字段添加到event中的字段名 | + ### regex 将指定字段进行正则提取。 @@ -122,7 +159,7 @@ | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | -| drop.target | string数组 | 必填 | 无 | drop的字段 | +| drop.targets | string数组 | 必填 | 无 | drop的字段 | !!! example ```yaml @@ -130,7 +167,7 @@ - type: normalize processors: - drop: - target: ["id", "body"] + targets: ["id", "body"] ``` @@ -139,9 +176,9 @@ | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | -| rename.target | 数组 | 必填 | 无 | | -| rename.target[n].from | string | 必填 | 无 | rename的目标 | -| rename.target[n].to | string | 必填 | 无 | rename后的名称 | +| rename.convert | 数组 | 必填 | 无 | | +| rename.convert[n].from | string | 必填 | 无 | rename的目标 | +| rename.convert[n].to | string | 必填 | 无 | rename后的名称 | !!! example ```yaml @@ -149,7 +186,7 @@ - type: normalize processors: - rename: - target: + convert: - from: "hello" to: "world" ``` @@ -159,7 +196,7 @@ | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | -| add.target | map | 必填 | 无 | 新增的key:value值 | +| add.fields | map | 必填 | 无 | 新增的key:value值 | !!! example ```yaml @@ -167,20 +204,82 @@ - type: normalize processors: - add: - target: + fields: hello: world ``` +### convert + +字段类型转换。 + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| convert.convert | 数组 | 必填 | 无 | | +| convert.convert[n].from | string | 必填 | 无 | 需要转换的字段名 | +| convert.convert[n].to | string | 必填 | 无 | 转换后的类型，可为："bool", "integer", "float" | + +!!! example + ```yaml + interceptors: + - type: normalize + processors: + - convert: + convert: + - from: count + to: float + ``` + +### copy + +字段复制。 + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| copy.convert | 数组 | 必填 | 无 | | +| copy.convert[n].from | string | 必填 | 无 | 需要复制的字段名 | +| copy.convert[n].to | string | 必填 | 无 | 复制后的字段名 | + +!!! example + ```yaml + interceptors: + - type: normalize + processors: + - copy: + convert: + - from: hello + to: world + ``` + +### underRoot + +将字段中的所有`key:value`放到event最外层。 + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| underRoot.keys | string数组 | 必填 | 无 | 需要underRoot的字段名 | + +!!! example + ```yaml + interceptors: + - type: normalize + processors: + - copy: + convert: + - from: hello + to: world + ``` + + ### timestamp 转换时间格式。 | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | -| timestamp.target | 数组 | 必填 | 无 | | -| timestamp.target[n].from | string | 必填 | 无 | 指定转换时间格式的字段 | -| timestamp.target[n].fromLayout | string | 必填 | 无 | 指定字段的时间格式(golang形式) | -| timestamp.target[n].toLayout | string | 必填 | 无 | 转换后的时间格式(golang形式)，另外可为`unix`和`unix_ms` | -| timestamp.target[n].toType | string | 非必填 | 无 | 转换后的时间字段类型 | +| timestamp.convert | 数组 | 必填 | 无 | | +| timestamp.convert[n].from | string | 必填 | 无 | 指定转换时间格式的字段 | +| timestamp.convert[n].fromLayout | string | 必填 | 无 | 指定字段的时间格式(golang形式) | +| timestamp.convert[n].toLayout | string | 必填 | 无 | 转换后的时间格式(golang形式)，另外可为`unix`和`unix_ms` | +| timestamp.convert[n].toType | string | 非必填 | 无 | 转换后的时间字段类型 | !!! example ```yaml @@ -188,7 +287,7 @@ - type: normalize processors: - timestamp: - target: + convert: - from: logtime fromLayout: "2006-01-02T15:04:05Z07:00" toLayout: "unix" diff --git a/docs/reference/pipelines/interceptor/overview.md b/docs/reference/pipelines/interceptor/overview.md new file mode 100644 index 0000000..de6773c --- /dev/null +++ b/docs/reference/pipelines/interceptor/overview.md @@ -0,0 +1,31 @@ +# Overview + +interceptors字段为数组，一个Pipeline中可填写多个interceptor组件配置。 + +目前，interceptor分为两种类型： + +- source interceptor：运行在source发送数据到queue的过程中，`source -> source interceptor -> queue`。 +- sink interceptor：运行在queue到sink的过程中，`queue -> sink interceptor -> sink`。 + +一个interceptor只属于其中一种。大部分组件为source interceptor类型，可支持配置belongTo被部分source使用。少数通用性质的比如retry interceptor为sink interceptor类型。 + +## Interceptor通用配置 + +### name + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| name | string | 非必填 | | 表示interceptor的名称。当pipeline里配置相同type interceptor的情况下，必填，用于区分标识 | + +### belongTo + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| belongTo | string数组 | 非必填 | | 仅source interceptor可用，用于指定该interceptor仅被哪些source使用 | + + +### order + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| order | int | 非必填 | | interceptor的排列顺序权重 | diff --git a/docs/reference/pipelines/queue/channel.md b/docs/reference/pipelines/queue/channel.md index 275a7f9..68743cd 100644 --- a/docs/reference/pipelines/queue/channel.md +++ b/docs/reference/pipelines/queue/channel.md @@ -16,12 +16,6 @@ channel queue,是基于go chan实现的内存缓冲queue。 | ---------- | ----------- | ----------- | --------- | -------- | | batchSize | int | 不必填 | 2048 | 一个批次包含的event数量 | -## batchBufferFactor - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| batchBufferFactor | int | 不必填 | 2 | queue缓冲区的大小(channel的容量)=batchSize*batchBufferFactor | - ## batchBytes | `字段` | `类型` | `是否必填` | `默认值` | `含义` | diff --git a/docs/reference/pipelines/sink/codec.md b/docs/reference/pipelines/sink/codec.md deleted file mode 100644 index 440cfc2..0000000 --- a/docs/reference/pipelines/sink/codec.md +++ /dev/null @@ -1,147 +0,0 @@ -# codec - -codec主要为sink发送时根据需求进行格式的转换。 - -!!! example - ```yaml - codec: - type: json - codec: - type: json - beatsFormat: true - transformer: - - rename: - target: - - from: systemState - to: meta - - drop: - target: ["systemPipelineName", "systemSourceName", "meta.collectTime"] - ``` - - -## type: json - -### pretty - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.pretty | bool | 否 | false | 是否将json格式日志展示成便于阅读的形式 | - - -### beatsFormat - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.beatsFormat | bool | 否 | false | 是否将json格式日志展示成便于阅读的形式 | - - -### prune -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.prune | bool | 否 | false | 是否为精简模式，精简模式下将不发送system开头的系统保留字段 | - -!!! example - ```yaml - sink: - type: dev - printEvents: true - codec: - type: json - pretty: false - beatsFormat: true - prune: true - ``` - -### transformer - -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer | 数组 | 否 | 无 | 日志格式转换transformer | - -transformer会按配置顺序执行。 -字段名称支持通过`.`来引用多层级。比如使用`fields.hostname`来引用在`fields`结构里的`hostname`字段。 - -!!! example - ```yaml - sink: - type: dev - printEvents: true - codec: - type: json - transformer: - - add: - target: - agent: loggie - drop: - target: ["unUsedKey"] - rename: - target: - - from: fields.host_name - to: fields.hostname - ``` - - -#### add -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.add.target | map | 否 | 无 | 增加字段 | - -#### drop -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.add.target | string数组 | 否 | 无 | 删除不用的字段 | - -#### move -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.move.target | 数组 | 否 | 无 | 移动字段 | -| codec.transformer.move.target[n].from | string | 必填 | 无 | 移动字段的来源 | -| codec.transformer.move.target[n].to | string | 必填 | 无 | 移动字段的去向 | - -#### copy -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.copy | 数组 | 否 | 无 | 复制字段 | -| codec.transformer.copy.target[n].from | string | 必填 | 无 | 复制字段的来源 | -| codec.transformer.copy.target[n].to | string | 必填 | 无 | 复制字段的去向 | - -#### rename -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.rename | 数组 | 否 | 无 | 重命名字段 | -| codec.transformer.rename.target[n].from | string | 必填 | 无 | 重命名字段的来源 | -| codec.transformer.rename.target[n].to | string | 必填 | 无 | 重命名字段的去向 | - -#### timestamp -| `字段` | `类型` | `是否必填` | `默认值` | `含义` | -| ---------- | ----------- | ----------- | --------- | -------- | -| codec.transformer.timestamp | 数组 | 否 | 无 | 格式化转换时间 | -| codec.transformer.timestamp[n].from | string | 必填 | 无 | 格式化转换时间的字段 | -| codec.transformer.timestamp[n].fromLayout | string | 必填 | 无 | 格式化转换前时间字段格式(golang layout形式) | -| codec.transformer.timestamp[n].toLayout | string | 必填 | 无 | 格式化转换时间后时间字段格式(golang layout形式) | - -以上的layout参数需要填写golang形式，可参考： -``` -const ( - Layout = "01/02 03:04:05PM '06 -0700" // The reference time, in numerical order. - 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" -) -``` -还可以根据实际情况修改。 - - diff --git a/docs/reference/pipelines/sink/file.md b/docs/reference/pipelines/sink/file.md new file mode 100644 index 0000000..bacf0e3 --- /dev/null +++ b/docs/reference/pipelines/sink/file.md @@ -0,0 +1,66 @@ +# file + +将接收到的数据以文件的形式写入到本地。 + +!!! example + + ```yaml + sink: + type: file + workerCount: 1024 + baseDirs: + - /data0 + - /data1 + - /data2 + dirHashKey: ${namespace}-${deployName} + filename: /${namespace}/${deployName}/${podName}/${filename} + maxSize: 500 + maxAge: 7 + maxBackups: 50 + compress: true + ``` + +## workerCount +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| workerCount | int | 非必填 | 1 | 写文件的并发数 | + +## baseDirs +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| baseDirs | string数组 | 非必填 | | 文件的基础目录，可以按某个key做哈希，然后存储到对应的基础目录上 | + +## dirHashKey +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| baseDirs | string | 非必填 | | 按指定Key做哈希，支持变量 | + +## filename +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| filename | string | 必填 | | 文件名，支持变量 | + +## maxSize +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxSize | int | 非必填 | 1 | 文件大小，单位为MiB | + +## maxAge +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxAge | int | 非必填 | | 旧文件保留天数，单位「天」，默认不删除 | + +## maxBackups +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxBackups | int | 非必填 | 1 | 最大保留的备份文件数，默认不删除（如果maxAge配置了，那么文件依旧会被删除） | + +## localTime +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| localTime | bool | 非必填 | false | 是否用本地时间格式化备份文件，默认使用UTC时间 | + +## compress +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| compress | bool | 非必填 | false | 是否压缩，使用gzip，默认不压缩 | diff --git a/docs/reference/pipelines/sink/kafka.md b/docs/reference/pipelines/sink/kafka.md index 3fdb28a..ef9a323 100644 --- a/docs/reference/pipelines/sink/kafka.md +++ b/docs/reference/pipelines/sink/kafka.md @@ -23,6 +23,31 @@ | ---------- | ----------- | ----------- | --------- | -------- | | topic | string | 非必填 | loggie | 发送日志至Kafka的topic | +可使用`${a.b}`的方式，获取event里的字段值作为具体的topic名称。 + +比如，一个event为： + +```json +{ + "topic": "loggie", + "hello": "world" +} +``` +可配置`topic: ${topic}`，此时该event发送到Kafka的topic为"loggie"。 + +同时支持嵌套的选择方式： + +```json +{ + "fields": { + "topic": "loggie" + }, + "hello": "world" +} +``` +可配置`topic: ${fields.topic}`，同样也会发送到topic "loggie"。 + + ## balance | `字段` | `类型` | `是否必填` | `默认值` | `含义` | diff --git a/docs/reference/pipelines/sink/overview.md b/docs/reference/pipelines/sink/overview.md new file mode 100644 index 0000000..f8d49c4 --- /dev/null +++ b/docs/reference/pipelines/sink/overview.md @@ -0,0 +1,36 @@ +# Overview + +一个Pipeline对应一个Sink。 + +## Sink通用配置 + +!!! example + + ```yaml + sink: + type: "dev" + codec: + type: json + pretty: true + + ``` + +### parallelism + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| parallelism | int | 非必填 | 1 | sink客户端的并发度，可同时启动多个增大发送吞吐量 | + +### codec + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| codec | | 非必填 | | sink发送数据给下游时，数据使用的格式 | +| codec.type | string | 非必填 | json | 使用json格式发送 | + +#### type: json + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| codec.pretty | | 非必填 | false | 是否进行json格式美化 | +| codec.beatsFormat | | 非必填 | false | 日志转成类filebeats格式：增加`@timestamp`字段，同时body字段命名为`message` | diff --git a/docs/reference/pipelines/source/dev.md b/docs/reference/pipelines/source/dev.md new file mode 100644 index 0000000..d614ba1 --- /dev/null +++ b/docs/reference/pipelines/source/dev.md @@ -0,0 +1,25 @@ +# dev + +用于开发或者压测场景下，自动生成数据。 + +!!! example + + ```yaml + sources: + - type: dev + name: benchmark + qps: 100 + ``` + + +## qps + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| qps | int | 非必填 | 1000 | 生成event的QPS | + +## byteSize + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| byteSize | int | 非必填 | 1024 | 单条event的字节数 | diff --git a/docs/reference/pipelines/source/grpc.md b/docs/reference/pipelines/source/grpc.md index 7beabce..1cd53d5 100644 --- a/docs/reference/pipelines/source/grpc.md +++ b/docs/reference/pipelines/source/grpc.md @@ -1,7 +1,7 @@ # grpc Grpc source用于接收Loggie Grpc格式的数据请求。 -一般用在[中转机](../../../user-guide/use-in-kubernetes/aggregator.md)场景，接收其他Loggie集群发送的日志。 +一般用在[中转机](../../../user-guide/best-practice/aggregator.md)场景，接收其他Loggie集群发送的日志。 !!! example @@ -32,9 +32,6 @@ Grpc source用于接收Loggie Grpc格式的数据请求。 | ---------- | ----------- | ----------- | --------- | -------- | | timeout | time.Duration | 非必填 | 20s | 超时时间 | -## maintenanceInterval - - diff --git a/docs/reference/pipelines/source/kafka.md b/docs/reference/pipelines/source/kafka.md index c933e69..9cbe954 100644 --- a/docs/reference/pipelines/source/kafka.md +++ b/docs/reference/pipelines/source/kafka.md @@ -1,4 +1,4 @@ -# Kafka source +# kafka Kafka source用于接收Kafka数据。 @@ -30,12 +30,59 @@ Kafka source用于接收Kafka数据。 | ---------- | ----------- | ----------- | --------- | -------- | | groupId | string | 非必填 | loggie | Loggie消费kafka的groupId | +## queueCapacity + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| queueCapacity | int | 非必填 | 100 | 内部发送的队列容量 | + +## minAcceptedBytes + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| minAcceptedBytes | int | 非必填 | 1 | 最小接收的batch字节数 | + +## maxAcceptedBytes + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxAcceptedBytes | int | 非必填 | 1e6 | 最大接收的batch字节数 | + +## readMaxAttempts + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| readMaxAttempts | int | 非必填 | 3 | 最大的重试次数 | + +## maxPollWait + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxPollWait | time.Duration | 非必填 | 10s | 接收的最长等待时间 | + +## readBackoffMin + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| readBackoffMin | time.Duration | 非必填 | 100ms | 在接收新的消息前，最小的时间间隔 | + +## readBackoffMax + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| readBackoffMax | time.Duration | 非必填 | 1s | 在接收新的消息前，最大的时间间隔 | + +## enableAutoCommit + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| enableAutoCommit | bool | 非必填 | false | 是否开启autoCommit | ## autoCommitInterval | `字段` | `类型` | `是否必填` | `默认值` | `含义` | | ---------- | ----------- | ----------- | --------- | -------- | -| autoCommitInterval | int | 非必填 | 0 | autoCommit的间隔时间 | +| autoCommitInterval | time.Duration | 非必填 | 1s | autoCommit的间隔时间 | ## autoOffsetReset diff --git a/docs/reference/pipelines/source/kubeEvent.md b/docs/reference/pipelines/source/kube-event.md similarity index 100% rename from docs/reference/pipelines/source/kubeEvent.md rename to docs/reference/pipelines/source/kube-event.md diff --git a/docs/reference/pipelines/source/overview.md b/docs/reference/pipelines/source/overview.md new file mode 100644 index 0000000..1ad1856 --- /dev/null +++ b/docs/reference/pipelines/source/overview.md @@ -0,0 +1,103 @@ +# Overview + +sources字段为数组，一个Pipeline中可填写多个source组件配置。 + +因此，请注意所有的source中`name`必填，作为pipeline中source的唯一标识。 + +## Source通用配置 + +所有Source均可以使用以下配置。 + +### name + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| name | string | 必填 | | 表示source的名称，建议填写有标识意义的词 | + +### fields + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| fields | map | 非必填 | | 自定义额外添加到event中的字段 | + +比如如下配置: + +!!! example + + ``` + sources: + - type: file + name: access + paths: + - /var/log/*.log + fields: + service: demo + ``` + +会给采集的所有日志上，都加上`service: demo`字段。 + +### fieldsFromEnv + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| fieldsFromEnv | map | 非必填 | | 额外添加到event中的字段，value为env环境变量的key | + +比如如下配置: + +!!! example + + ``` + sources: + - type: file + name: access + paths: + - /var/log/*.log + fieldsFromEnv: + service: SVC_NAME + ``` + +会从Loggie所在的环境变量中，获取`SVC_NAME`的值`${SVC_NAME}`，然后给所有的日志event上添加字段：`service: ${SVC_NAME}`。 + +### fieldsUnderRoot + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| fieldsUnderRoot | bool | 非必填 | false | 额外添加的fields是否放在event的根部 | + +比如，默认情况下，输出的日志格式为： + +```json +{ + "body": "hello world", + "fields": { + "service": "demo" + } +} +``` + +如果设置fieldsUnderRoot=true，输出的日志格式为： + +```json +{ + "body": "hello world", + "service": "demo" +} +``` + + +### fieldsUnderKey + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| fieldsUnderKey | string | 非必填 | fields | 当`fieldsUnderRoot=false`时，字段的名称 | + +比如可以修改默认的字段`fields`为`tag`，输出的日志为： + +```json +{ + "body": "hello world", + "tag": { + "service": "demo" + } +} +``` diff --git a/docs/reference/pipelines/source/prometheus-exporter.md b/docs/reference/pipelines/source/prometheus-exporter.md new file mode 100644 index 0000000..a077497 --- /dev/null +++ b/docs/reference/pipelines/source/prometheus-exporter.md @@ -0,0 +1,37 @@ +# prometheusExporter + +采集Prometheus Metrics的指标数据。 + +!!! example + ```yaml + sources: + - type: prometheusExporter + name: metric + endpoints: + - "127.0.0.1:9196/metrics" + ``` + +## endpoints + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| endpoints | string数组 | 必填 | | 抓取的远端exporter地址，请注意Loggie不会默认在请求路径中添加/metrics | + + +## interval + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| interval | time.Duration | 非必填 | 30s | 定时抓取远端exporter的时间间隔 | + +## timeout + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| timeout | time.Duration | 非必填 | 5s | 抓取请求的超时时间 | + +## toJson + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| toJson | bool | 非必填 | false | 是否将抓取到的prometheus原生指标，转换成JSON格式 | diff --git a/docs/reference/pipelines/source/unix.md b/docs/reference/pipelines/source/unix.md new file mode 100644 index 0000000..7152f45 --- /dev/null +++ b/docs/reference/pipelines/source/unix.md @@ -0,0 +1,44 @@ +# unix + +通过unix socket接收数据。 + +!!! example + ```yaml + sources: + - type: unix + name: demo + path: + - "/tmp/loggie.sock" + ``` + +## path + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| path | string | 必填 | | 接收的路径名 | + +## maxBytes + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxBytes | int | 非必填 | 40960 | 接收的最大字节数 | + +## maxConnections + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| maxConnections | int | 非必填 | 512 | 同时保持最多的连接数 | + +## timeout + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| timeout | time.Duration | 非必填 | 5m | 连接超时时间 | + +## mode + +| `字段` | `类型` | `是否必填` | `默认值` | `含义` | +| ---------- | ----------- | ----------- | --------- | -------- | +| mode | string | 非必填 | 0755 | | 路径path的权限，这里请加上双引号""，避免被识别成数字类型 + + diff --git a/docs/user-guide/architecture/advantages.md b/docs/user-guide/architecture/advantages.md index a67a0bf..bcdd66d 100644 --- a/docs/user-guide/architecture/advantages.md +++ b/docs/user-guide/architecture/advantages.md @@ -8,8 +8,8 @@ Loggie支持多个Pipeline，每个Pipeline都基于简单直观的source->inter 多Pipeline设计，减少互相干扰。比如我们可以将重要的业务日志放在一个Pipeline中，其他的不重要的日志配置为另外的Pipeline，不重要的日志配置变动、发生下游堵塞时，不会影响重要日志的采集和发送。 ## 通用性更好 -在一些场景下，我们可能会将不同类型的服务混合部署在一个节点上，很可能他们的日志会发送到不同的Kafka集群中，如果是类似Filebeat等只有一个全局的输出源的时候，需要在节点上部署两个Agent，如果使用Loggie则只需要使用不同的Pipeline即可，每个Pipeline配置不同的Sink，减少部署成本。 -我们甚至可以采集相同的日志，发送到不同的后端输出源，可以根据实际需求灵活配置。 +在一些场景下，我们可能会将不同类型的服务混合部署在一个节点上，很可能他们的日志会发送到不同的Kafka集群中，如果只有一个全局的输出源，需要在节点上部署两个Agent，如果使用Loggie则只需要使用不同的Pipeline即可，每个Pipeline配置不同的Sink，减少部署成本。 +我们甚至可以采集相同的日志，发送到不同的后端输出源，根据实际需求灵活配置。 ## 灵活、热插拔、可扩展 本质上source->interceptor->sink架构是一个数据流式的设计，不同类型的source/interceptor/sink的排列组合，可以满足日志的不同需求， @@ -29,7 +29,7 @@ Loggie并没有将interceptor更细化的分类成比如Filter/Formater等类型 ## 可快速方便的写一个组件 Loggie基于微内核的架构，所有的source/interceptor/sink/queue都被抽象成component，只需要在代码中实现Golang接口，即可方便的研发一个component。 -如果Loggie在某些特异化场景下，无法满足你的需求，可以尝试写一个自己的component。 +如果Loggie在某些场景下，无法满足你的需求，可以尝试写一个自己的component。 比如需要Loggie转换成特定的日志格式，可以写一个interceptor去处理；需要Loggie将采集的日志发送至尚未支持的服务，可以写一个sink。 当然，Loggie使用Golang编写，所以你目前需要用Golang来写component。Golang和Java或者C/C++相比，在性能和研发效率上有一个折中，更适合类似日志Agent的场景。 @@ -44,7 +44,7 @@ Loggie基于微内核的架构，所有的source/interceptor/sink/queue都被抽 如果你使用Loggie，你可以： 1. 快速部署，支持各种部署架构 -2. 只需要使用LogConfig CRD配置管理日志配置，更方便的接入各类容器云平台，对业务无侵入，无需关心Pod迁移等，无需手动在节点上操作配置日志文件，同时可配置注入Namespace/PodName/NodeName等元信息供查询使用 +2. 只需要使用ClusterLogConfig/LogConfig CRD配置管理日志配置，更方便的接入各类容器云平台，对业务无侵入，无需关心Pod迁移等，无需手动在节点上操作配置日志文件，同时可配置注入Namespace/PodName/NodeName等元信息供查询使用 ## 更好的稳定性、更详细的监控指标、更方便的排障方式 @@ -53,12 +53,10 @@ Loggie可配置限流interceptor，在日志量太大时，可以避免发送日 Loggie有合理的文件句柄处理机制，避免fd被占用的各种异常场景导致节点不稳定。 另外，Loggie结合我们在各种环境中遇到的各种问题，针对性的检测暴露出相应的指标。 -比如指标支持采集和发送延迟检测。 -比如针对文件size增长太快，或者文件size太大等场景，支持该类metric上报。 +比如指标支持采集和发送延迟检测。比如针对文件size增长太快，或者文件size太大等场景，支持该类metric上报。 -同时Loggie已支持原生Prometheus metric，可避免额外部署exporter带来的部署成本和资源消耗。Loggie还提供了完善的Grafana监控图表，可以方便快速接入使用。 +同时Loggie支持原生Prometheus metric，可避免额外部署exporter带来的部署成本和资源消耗。Loggie还提供了完善的Grafana监控图表，可以方便快速接入使用。 ## 更低的资源占用，更好的性能 -Loggie基于Golang，基于极少的资源占用，可提供强大的吞吐性能。 - +Loggie基于Golang编写，在代码层面我们有很多优化，在较少资源占用的同时，还可提供强大的吞吐性能。 diff --git a/docs/user-guide/architecture/background.md b/docs/user-guide/architecture/background.md index 0db861e..9d442ba 100644 --- a/docs/user-guide/architecture/background.md +++ b/docs/user-guide/architecture/background.md @@ -36,12 +36,15 @@ Filebeat的metrics比较有限，很多时候我们想要排查诸如常见的 ## 二、为什么现有的其他开源日志项目不能满足需求？ **Fluentd/Fluent-bit** + Fluentd基于Ruby性能一般，单线程；Fluent-bit基于C，对于我们的技术栈来说，Ruby和C的维护和二次开发成本比较大。 **Logstash** + Logstash性能较差，基于JRuby的资源占用和损耗都比较大。 **Flume** + 资源占用较大，性能一般，之前有内部部门使用过Flume，对比的压测结论证实确实不如Filebeat。 最重要的是，目前所有的开源Agent，均没有对K8s有很好的原生支持，个别支持的也只能采集stdout的日志。 @@ -51,35 +54,18 @@ Logstash性能较差，基于JRuby的资源占用和损耗都比较大。 **整体的目标：** 高性能、资源占用低、高可用、稳定性强、可扩展性强、更适合云原生。 -**性能与资源** -性能相同的情况下，CPU比社区Filebeat少一半以上，吞吐量上限要远高于Filebeat。 +**性能与资源：** +性能相同的情况下，CPU比社区Filebeat大大降低，吞吐量上限要远高于Filebeat。 -**高可用、稳定性强**： +**高可用、稳定性强：** 资源隔离，作为基础设施一定要稳定可靠，同时默认支持大量监控指标，对常见的运维类问题有良好的支撑，减少运维负担。 -**可扩展性**： -采集日志agent，不仅仅是采集日志，本质上可以抽象成输入-队列处理转发-输出的一个模型。 -整体设计上，微内核、可插拔，用户可以方便的实现包括source、sink、interceptor（过滤、路由、编码、增强等）。 -方便用户扩展，比如可以很快速的写一个处理逻辑，就可以进行数据处理。 - -**功能**： - -- 服务发现与配置中心：默认支持k8s service discovery，支持CRD的方式下发配置（与Kubernetes更原生的结合）；可对接其他例如consul、zk、apollo等外部配置中心 -- 多个sink，sink配置可动态更新 -- 支持数据流pipeline管理和路由 -- 自身可作为中转机使用，支持分流、转发，支撑更大规模数据量 -- 支持动态可定义的日志切分功能，自定义的日志过滤、聚合、运算能力 -- 可直接支持报警接入 -- 支持限流、背压 -- 默认提供更完善的promethues监控metrics -- 完善的可观测性保障 -- 提供k8s operator，可以自动化部署，方便用户配置 -- 更多的想象力：比如监听Kubernetes event，可以写一个source，就可以把kubernetes事件发送到报警，或者发送到Kafka/Elasticsearch等存储；可以写个拦截器interceptor插件，定时从Elasticsearch拉取数据到数仓备份，满足定时投递需求； - +**可扩展性：** +整体设计上，方便用户扩展，实现过滤、路由、编码等能力。比如可以很快速的写一个处理逻辑，就可以进行数据处理。 总结一下，我们理想中的日志Agent是一个： 1. 开箱即用：可快速部署容器化场景下的日志采集服务；有完善的文档与经验介绍； 2. 高性能：比原生Filebeat性能高，资源占用少； -3. 高可靠：隔离性稳定性更强；默认集成更多的prometheus监控指标，方便运维排障； +3. 高可靠：隔离性稳定性更强；默认集成更多的监控指标，方便运维排障； 4. 可扩展：基于微内核的架构，用户可方便快捷的写自己的插件，满足各种定制化需求； diff --git a/docs/user-guide/architecture/compare.md b/docs/user-guide/architecture/compare.md index 38f8ec7..d449234 100644 --- a/docs/user-guide/architecture/compare.md +++ b/docs/user-guide/architecture/compare.md @@ -3,16 +3,64 @@ | | Loggie | Filebeat | Fluentd | Logstash | Flume | | ---------------------- | ------------------------------------------------------------ | ----------------------------------------------- | ---------------- | -------- | -------- | -| 开发语言 | Golang | Golang | Ruby | Ruby | Java | +| 开发语言 | Golang | Golang | Ruby | JRuby | Java | | 多Pipeline | 支持 | 单队列 | 单队列 | 支持 | 支持 | -| 多输出源 | 支持 | 不支持，仅能一个Output | | 支持 | 支持 | +| 多输出源 | 支持 | 不支持，仅一个Output | 配置copy | 支持 | 支持 | | 中转机 | 支持 | 不支持 | 支持 | 支持 | 支持 | -| 日志处理 | 支持正则、分隔符等 | | | | | | 日志报警 | 支持 | 不支持 | 不支持 | 不支持 | 不支持 | | Kubernetes容器日志采集 | 支持容器的stdout和容器内部日志文件 | 只支持容器stdout | 只支持容器stdout | 不支持 | 不支持 | -| 配置下发 | Kubernetes下支持通过CRD的方式配置，后续非容器环境会支持其他配置中心 | 手动配置 | 手动配置 | 手动配置 | 手动配置 | -| 监控 | 原生支持Prometheus metrics，同时可配置API、发送metrics等方式 | API接口暴露，接入Prometheus需使用额外的exporter | | | | +| 配置下发 | Kubernetes下可通过CRD配置，主机场景配置中心陆续支持中 | 手动配置 | 手动配置 | 手动配置 | 手动配置 | +| 监控 | 原生支持Prometheus metrics，同时可配置单独输出指标日志文件、发送metrics等方式 | API接口暴露，接入Prometheus需使用额外的exporter | 支持API和Prometheus metrics | 需使用额外的exporter | 需使用额外的exporter | | 资源占用 | 低 | 低 | 一般 | 较高 | 较高 | ## 基准性能测试与对比 + +**测试环境：** + +- 物理机 48C，256G +- Kafka 3 Broker，挂载SSD盘 +- Filebeat v7.8版本，无配置processor等处理；Loggie默认包含cost、retry、metric interceptor； + +**测试目的：** + +Filebeat和Loggie的性能对比 + +**测试思路：** + +Filebeat和Loggie，均采集日志发送至Kafka，观察相应的资源占用和发送吞吐量 + +**测试详情：** + +单文件自动生成5000000行日志，每行内容如下所示： + +``` +[13/May/2021:10:20:29 +0800] 0.015 10.200.170.107 "GET /static/3tJHS3Ubrf.html?activity_channel_id=22=1_00000&fromMiniapp=1&miniapp_uuid=uEd93lG2eG8Qj5fRXuiJwNt4bmiylkmg HTTP/1.1" 200 138957 "110.183.45.54, 10.200.151.37" act.you.163.com "" "Mozilla/5.0 (Linux; Android 8.1.0; PADM00Build/O11019; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/67.0.3396.87 XWEB/568 MMWEBSDK/190102 Mobile Safari/537.36 MMWEBID/6881 MicroMessenger/7.0.3.1400(0x2700033B) Process/appbrand0 NetType/WIFI Language/zh_CN miniProgram" "" [127.0.0.1:8990] [0.014] [] [] immsg={"st":1553307293614,"sb":138963,"rc":200,"cf":{"sr":1},"if":"default","ut":14,"sv":"static","pd":"activity","qb":764} +``` + +配置Filebeat和Loggie采集日志，并发送至Kafka某个Topic，不使用客户端压缩，Kafka Topic配置Partition为3。 + +在保证Agent规格资源充足的情况下，修改采集的文件个数、发送客户端并发度（配置Filebeat worker和Loggie parallelism)，观察各自的CPU、Memory和Pod网卡发送速率。 + +测试得到如下数据： + +| Agent | 文件大小 | 日志文件数 | 发送并发度 | CPU | MEM (rss) | 网卡发包速率 | +| -------- | -------- | ---------- | ---------- | -------- | ----------- | ------------------- | +| Filebeat | 3.2G | 1 | 3 | 7.5~8.5c | 63.8MiB | 75.9MiB/s | +| Filebeat | 3.2G | 1 | 8 | 10c | 65MiB | 70MiB/s | +| Filebeat | 3.2G | 10 | 8 | 11c | 65MiB | 80MiB/s | +| | | | | | | | | +| Loggie | 3.2G | 1 | 3 | 2.1c | 60MiB | 120MiB/s | +| Loggie | 3.2G | 1 | 8 | 2.4c | 68.7MiB | 120MiB/s | +| Loggie | 3.2G | 10 | 8 | 3.5c | 70MiB | 210MiB/s | + +**测试结论：** + +相同压测条件和场景下： + +- Loggie和Filebeat消耗的CPU相比，大概仅为后者的1/4，同时发送吞吐量为后者的1.6～2.6倍。 + +- Memory相当，均处于较低的水准。 + +- Filebeat的极限吞吐量存在瓶颈，80MB/s后很难提升，而Loggie则可以达到200MiB/s以上。 + diff --git a/docs/user-guide/architecture/config.md b/docs/user-guide/architecture/config.md deleted file mode 100644 index 5a7c8bb..0000000 --- a/docs/user-guide/architecture/config.md +++ /dev/null @@ -1,3 +0,0 @@ -# 配置设计 - - diff --git a/docs/user-guide/architecture/core-arch.md b/docs/user-guide/architecture/core-arch.md index 31d8810..09994af 100644 --- a/docs/user-guide/architecture/core-arch.md +++ b/docs/user-guide/architecture/core-arch.md @@ -1,7 +1,7 @@ -# 核心架构 +# 设计架构 ## 内部设计 -详细的设计如下图所示： +Loggie详细的设计如下图所示： ![](imgs/loggie-full-arch.png) @@ -25,10 +25,10 @@ 除了日志采集，很多涉及到数据传输、转换的场景，都可以考虑使用Loggie，即使Loggie没有你想要的组件，你也可以快速开发一个source、sink或interceptor，同时复用Loggie的很多能力，避免重复的开发工作，比如： -- 配置中心，灵活的配置手段，避免手动下发配置，在Kubernetes集群中可以使用CRD，并且支持自动reload、支持指定Loggie集群 -- 稳定性和可靠性，多输入输出源的隔离性，保证at-least-once，重试机制，避免传输过程中的数据丢失，避免数据量过多或过大造成的隐患 -- 完整的监控指标，比如队列占有、传输延迟、发送qps等，可快速接入Prometheus，同时提供一些快速排障的手段和接口 -- 可插拔的interceptor可用于数据处理、格式转换等 +- 在Kubernetes集群中可方便、直接的使用CRD下发配置，并且支持自动reload、支持指定Loggie集群，无需考虑部署、配置更新等问题 +- 依赖Loggie提供传输过程的稳定性和可靠性，保证at-least-once和重试机制，避免数据丢失，以及数据量过多或过大造成的隐患 +- 使用Loggie提供的一系列监控指标，比如队列长度、传输延迟、发送QPS等，可快速接入Prometheus，同时还可使用一些系统内置的快速排障的接口与能力 +- 使用可插拔的Interceptor可用于自定义的数据处理、格式转换等，避免过多的定制化代码开发 ... ## 应用场景 diff --git a/docs/user-guide/architecture/schema.md b/docs/user-guide/architecture/schema.md index 4905cab..3875388 100644 --- a/docs/user-guide/architecture/schema.md +++ b/docs/user-guide/architecture/schema.md @@ -4,61 +4,20 @@ 了解Loggie内部数据格式的设计，能帮助我们配置合适的日志处理和日志格式转换 ## 结构设计 -在Loggie内部的日志数据，会被存储为如下`key:value`的格式： +在Loggie内部的日志数据，包括： -!!! example - ```json - "body": "xxxxxxx", - "key1": "value1", - "key2": "value2" - - ``` +- **body**: source接收的原始数据。比如使用file source采集的日志文件里的一行日志数据 +- **header**: 用户使用的字段。比如用户自己添加到source里的fields字段，用户切分日志后得到的字段等 +- **meta**: Loggie系统内置的元信息，默认不会发送给下游 -其中`body`为source接收到的原始内容，比如日志采集source，这里的`body`为文件采集到的原始日志数据。 -其他的字段，在Loggie内部被统一称为header。header里一般包括： - -- 系统保留字段。统一system开头，比如systemPipelineName、systemSourceName、systemState等 -- 用户使用的字段。比如用户自己添加到source里的fields字段，用户切分日志后得到的字段等 - -默认Json格式输出示例如下： - -!!! example - ```json - { - "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", - "fields": { - "test": "demo" - }, - "systemPipelineName": "svcA", - "systemSourceName": "accesslog", - "systemState": { - "nextOffset": 2790, - "filename": "/tmp/log/a.log", - "collectTime": "2021-12-12T11:58:12.141267+08:00", - "contentBytes": 160, - "jobUid": "39100914-16777234", - "lineNumber": 39, - "offset": 2630 - } - } - ``` ## 格式转换 -如果以上的格式不满足需求，可以使用sink里的 **codec** 修改输出的字段： +如果以上的格式不满足需求，可以参考： -- [配置](../../reference/pipelines/sink/codec.md) -- [使用示例](../best-practice/log-format.md) +- [日志格式转换](../best-practice/log-format.md) ## 日志切分 -对于原始日志数据的切分与处理，请使用 **normalize interceptor**： +对于原始日志数据的切分与处理，请使用 **normalize interceptor**，请参考： -- [配置](../../reference/pipelines/interceptor/normalize.md) -- [使用示例](../best-practice/log-process.md) - - -!!! caution - 格式转换和日志切分两者区别： - - - normalize interceptor除了可以drop `body`字段外，无法修改系统保留的字段（修改可能影响内部逻辑）。codec.transformer可以任意修改字段，但存在反序列化的性能开销。 - - normalize interceptor可以通过配置`belongTo`指定关联source使用，codec.transformer则为pipeline级别，同时可以在系统配置中使用defaults来全局生效。 \ No newline at end of file +- [日志切分处理](../best-practice/log-process.md) \ No newline at end of file diff --git a/docs/user-guide/use-in-kubernetes/aggregator.md b/docs/user-guide/best-practice/aggregator.md similarity index 86% rename from docs/user-guide/use-in-kubernetes/aggregator.md rename to docs/user-guide/best-practice/aggregator.md index f5d9143..7825524 100644 --- a/docs/user-guide/use-in-kubernetes/aggregator.md +++ b/docs/user-guide/best-practice/aggregator.md @@ -28,7 +28,7 @@ Loggie可以部署为Agent，同时支持独立部署，进行聚合、转发和 如果仅仅修改`sink`或者`interceptor` CR本身不会立即同步到已经使用的LogConfig里，只有等待某些事件触发后（LogConfig本身被修改、关联Pod有重建等）才会被刷新配置。如果需要立刻更新，可以考虑重启Loggie本身。 -被采集的容器创建以及匹配的LogConfig，请参考[Loggie采集容器日志](./collect-container-logs.md)。 +被采集的容器创建以及匹配的LogConfig，请参考[Loggie采集容器日志](../use-in-kubernetes/collect-container-logs.md)。 这里我们将其中的sink修改为以下示例： @@ -68,7 +68,7 @@ Loggie可以部署为Agent，同时支持独立部署，进行聚合、转发和 ```yaml apiVersion: loggie.io/v1beta1 - kind: LogConfig + kind: ClusterLogConfig metadata: name: aggre namespace: default @@ -111,7 +111,6 @@ Loggie可以部署为Agent，同时支持独立部署，进行聚合、转发和 ```json 2021-12-20 09:58:50 INF go/src/loggie.io/loggie/pkg/sink/dev/sink.go:98 > event: { "body": "14-Dec-2021 06:19:58.306 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [141] milliseconds", - "systemSourceName": "rec1", "fields": { "podname": "tomcat-684c698b66-gkrfs", "containername": "tomcat", @@ -119,15 +118,5 @@ Loggie可以部署为Agent，同时支持独立部署，进行聚合、转发和 "namespace": "default", "nodename": "kind-control-plane" }, - "systemState": { - "collectTime": "2021-12-20T09:58:46.346170897Z", - "contentBytes": 117, - "jobUid": "1320468-64769", - "lineNumber": 43, - "offset": 6028, - "nextOffset": 6145, - "filename": "/var/lib/kubelet/pods/89772369-2fd6-4b64-909f-aa10d81326c5/volumes/kubernetes.io~empty-dir/log/catalina.2021-12-14.log" - }, - "systemPipelineName": "default/aggregator/" } ``` diff --git a/docs/user-guide/best-practice/log-clean.md b/docs/user-guide/best-practice/log-clean.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/user-guide/best-practice/log-format.md b/docs/user-guide/best-practice/log-format.md index ed85878..a003c1d 100644 --- a/docs/user-guide/best-practice/log-format.md +++ b/docs/user-guide/best-practice/log-format.md @@ -1,42 +1,183 @@ # 日志格式转换 -> 在sink的[codec](../../reference/pipelines/sink/codec.md)中对输出的日志格式进行配置。 > 建议先了解Loggie内部日志数据[schema设计](../architecture/schema.md)。 + +日志格式转换，主要是对Loggie内置的一些字段进行处理和转换，一般会依赖[日志切分处理](log-process.md)。 + ## 需求场景 -默认情况下，Loggie输出的日志字段格式类似如下所示： -!!! example "Event" +Loggie部署在不同的环境中，如果需要兼容已有的格式，可以参考如下的办法。 + +### 示例1: 发送原始数据 +正常情况，Loggie仅将原始数据发送给下游。 + +如果你配置： + +!!! config "pipelines.yml" + + ```yaml + pipelines: + - name: local + sources: + - type: file + name: demo + paths: + - /tmp/log/*.log + sink: + type: dev + printEvents: true + codec: + pretty: true ``` + +sink输出的数据仅为原始数据： + +```json { - "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", - "fields": { - "test": "demo" - }, - "systemPipelineName": "svcA", - "systemSourceName": "accesslog", - "systemState": { - "nextOffset": 2790, - "filename": "/tmp/log/a.log", - "collectTime": "2021-12-12T11:58:12.141267+08:00", - "contentBytes": 160, - "jobUid": "39100914-16777234", - "lineNumber": 39, - "offset": 2630 - } + "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]" + } +``` + +### 示例2: 添加fields自定义元信息 + +如果我们在source上配置了一些自定义的fields。 + +!!! config "pipelines.yml" + + ```yaml + pipelines: + - name: local + sources: + - type: file + name: demo + paths: + - /tmp/log/*.log + fields: + topic: "loggie" + + sink: + type: dev + printEvents: true + codec: + pretty: true + ``` + +那么sink输出的为： + +```json + { + "fields": { + "topic": "loggie", + }, + "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]" + } +``` + +当然我们也可以配置`fieldsUnderRoot: true`，让fields里的`key:value`和body同一层级。 + +```yaml + fields: + topic: "loggie" + fieldsUnderRoot: true +``` + +```json + { + "topic": "loggie", + "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]" + } +``` + +### 示例3: 添加meta系统内置元信息 + +有一些Loggie系统内置的元信息，我们也希望发送给下游，这个时候，需要使用normalize interceptor中的addMeta processors。 + +!!! config "pipelines.yml" + + ```yaml + pipelines: + - name: local + sources: + - type: file + name: demo + paths: + - /tmp/log/*.log + fields: + topic: "loggie" + interceptors: + - type: normalize + processors: + - addMeta: ~ + + sink: + type: dev + printEvents: true + codec: + pretty: true + + ``` + +配置了addMeta processor之后，默认会把所有的系统内置元信息输出。 + +默认Json格式输出示例如下： + +!!! example + + ```json + { + "fields": { + "topic": "loggie" + }, + "meta": { + "systemState": { + "nextOffset": 720, + "filename": "/tmp/log/a.log", + "collectTime": "2022-03-08T11:33:47.369813+08:00", + "contentBytes": 90, + "jobUid": "43772050-16777231", + "lineNumber": 8, + "offset": 630 + }, + "systemProductTime": "2022-03-08T11:33:47.370166+08:00", + "systemPipelineName": "local", + "systemSourceName": "demo" + }, + "body": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]" } ``` -如果需要兼容现有的格式，可以参考如下的办法。 +当然，我们可能会觉得这些数据太多了，或者想对字段进行修改。我们就可以使用[normalize interceptor](../../reference/pipelines/interceptor/normalize.md)里的其他processor，进行drop、rename、copy、timestamp转换等操作。 -## 功能与配置 +另外，这里的normalize interceptor配置在某个Pipeline中，如果希望全局生效，避免每个pipeline都配置该interceptor，可以在defaults中配置： -以下默认配置的sink codec是pipeline级别，如果你需要整体替换，请在系统配置defaults中进行全局修改。 +!!! config "loggie.yml" -### 1. 常规样式 + ```yaml + defaults: + interceptors: + - type: normalize + name: global # 用于区分pipelines中的normalize，避免pipeline中定义了normalize会覆盖这里的defaults + order: 500 # 默认normalize的order值为900，这里定义一个相对较小值，可控制先执行defaults中的normalize + processor: + - addMeta: ~ + ``` -codec可以配置: + +### 示例4：beatsFormat快速转换 + +如果你期望的格式为类似： + +```json +{ + "@timestamp": "2021-12-12T11:58:12.141267", + "message": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", +} +``` + +Loggie提供了一个内置的转换方式，可以在sink codec中设置[beatsFormat](../../reference/pipelines/sink/overview.md)如下: !!! config + ```yaml sink: type: dev @@ -44,133 +185,6 @@ codec可以配置: codec: type: json beatsFormat: true - prune: true ``` -#### # codec.beatsFormat -将默认的`body`改为`message`，同时增加`@timestamp`时间字段。 - -此时日志格式为： - -!!! example "Event" - ```json - { - "@timestamp": "2021-12-12T11:58:12.141267", - "message": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", - "fields": { - "test": "demo" - }, - "systemPipelineName": "svcA", - "systemSourceName": "accesslog", - "systemState": { - "nextOffset": 2790, - "filename": "/tmp/log/a.log", - "collectTime": "2021-12-12T11:58:12.141267+08:00", - "contentBytes": 160, - "jobUid": "39100914-16777234", - "lineNumber": 39, - "offset": 2630 - } - } - ``` - -#### # codec.prune -精简模式，不发送system开头系统保留字段。 - -!!! example "Event" - ```json - { - "@timestamp": "2021-12-12T11:58:12.141267", - "message": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", - "fields": { - "test": "demo" - } - } - ``` - - -以上配置在sink端无额外性能开销，可放心使用。 - -### 2. 自定义转换 - -和`normalize interceptor`类似，codec可配置transformer可以用于字段的格式化修改。 - -假设我们需要将原始日志，转换成以下的日志格式： -!!! example - ```json - { - "@timestamp": "2021-12-12T11:58:12.141267", - "message": "01-Dec-2021 03:13:58.298 INFO [main] Starting service [Catalina]", - "test": "demo" - "meta": { - "nextOffset": 2790, - "filename": "/tmp/log/a.log", - "collectTime": "2021-12-12T11:58:12.141267+08:00", - "contentBytes": 160, - "jobUid": "39100914-16777234", - "lineNumber": 39, - "offset": 2630 - } - } - ``` - -相比原始日志格式，需要做如下的几个变动： - -**1. body重命名为message** - -配置： -!!! config - ```yaml - codec: - type: json - beatsFormat: true - ``` - -**2. 将fields字段的内容放在最外层** - -建议直接在source里配置`fieldsUnderRoot`: - -!!! config - ```yaml - sources: - - type: file - fields: - test: demo - fieldsUnderRoot: true - ``` - - -**3. 将systemState改名为meta** -!!! config - ```yaml - codec: - type: json - codec: - type: json - beatsFormat: true - transformer: - - rename: - target: - - from: systemState - to: meta - ``` - -**4. 去掉systemPipelineName和systemSourceName字段和meta.collectTime字段** -!!! config - ```yaml - codec: - type: json - codec: - type: json - beatsFormat: true - transformer: - - rename: - target: - - from: systemState - to: meta - - drop: - target: ["systemPipelineName", "systemSourceName", "meta.collectTime"] - - ``` -其中嵌套的字段名称支持通过`.`来引用。 - +会将默认的`body`改为`message`，同时增加`@timestamp`时间字段。 \ No newline at end of file diff --git a/docs/user-guide/best-practice/log-process.md b/docs/user-guide/best-practice/log-process.md index e5cb43b..e496945 100644 --- a/docs/user-guide/best-practice/log-process.md +++ b/docs/user-guide/best-practice/log-process.md @@ -1,10 +1,7 @@ -# 日志切分与处理 +# 日志切分处理 > Loggie可使用[normalize interceptor](../../reference/pipelines/interceptor/normalize.md)来进行日志的切分和处理，将日志数据进行结构化的提取，同时可以对提取后的字段进行处理。 > 建议先了解Loggie内部日志数据[schema设计](../architecture/schema.md)。 -!!! caution - normalize interceptor只用于用户日志的处理，并不能转换system开头的系统保留字段，系统保留字段请参考[日志格式转换](./log-format.md)。 - ## 需求场景 最主要的是对日志进行切分解析提取和处理。 @@ -34,7 +31,8 @@ - regex: 正则切分提取日志 - jsonDecode: 解析提取json格式的日志 - split: 通过分隔符来提取日志 -- add/rename/drop指定字段 +- add/rename/drop/copy/underRoot指定字段 +- convert类型转换 - timestamp: 转换指定字段的时间格式 normalize可以配置内部的processor顺序执行。 @@ -86,9 +84,9 @@ normalize可以配置内部的processor顺序执行。 processors: - jsonDecode: ~ - drop: - target: ["stream", "time", "body"] + targets: ["stream", "time", "body"] - rename: - target: + convert: - from: "log" to: "message" - type: normalize @@ -117,7 +115,7 @@ normalize可以配置内部的processor顺序执行。 max: 4 keys: ["time", "std", "F", "message"] - drop: - target: ["time", "std", "F", "body"] + targets: ["time", "std", "F", "body"] - type: normalize name: accproc belongTo: ["access"] @@ -141,11 +139,10 @@ normalize可以配置内部的processor顺序执行。 使用filesource采集后，在Loggie里的原始格式为： ``` "body": '"log":"I0610 08:29:07.698664 Waiting for caches to sync\n","stream":"stderr", "time":"2021-06-10T08:29:07.698731204Z"' -"systemXXX": xxx ... ``` -在normalize interceptors里，使用: +可在normalize interceptors里，配置以下processor: 1. **`jsonDecode`**: 解析并提取字段，将Loggie里存储的日志格式变成： @@ -154,7 +151,6 @@ normalize可以配置内部的processor顺序执行。 "log": "I0610 08:29:07.698664 Waiting for caches to sync\n" "stream":"stderr" "time":"2021-06-10T08:29:07.698731204Z" -"systemXXX": xxx ... ``` @@ -167,7 +163,6 @@ normalize可以配置内部的processor顺序执行。 最终发送的日志格式变成： ``` "message": "I0610 08:29:07.698664 Waiting for caches to sync\n" -"systemXXX": xxx ... ``` diff --git a/docs/user-guide/enterprise-practice/enterprise-log-practice.md b/docs/user-guide/enterprise-practice/enterprise-log-practice.md deleted file mode 100644 index 800c42a..0000000 --- a/docs/user-guide/enterprise-practice/enterprise-log-practice.md +++ /dev/null @@ -1,7 +0,0 @@ -# 日志使用方式 - -### 日志分类 - - -### 日志切分 - diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 256e524..43e831e 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -5,7 +5,8 @@ ## 落地一套日志系统会遇到哪些问题？ 在企业中，我们需要怎么去构建一套完整的日志系统？如何根据实际情况选型，其中又会碰到哪些问题？ -搭建完日志系统后，如何根据业务来推广和使用？最佳实践有哪些？ +在不同的业务类型、不同的使用场景、不同的日志规模下，我们可以采用哪些日志系统架构？ + 请看「[企业实战](enterprise-practice/architecture-and-evolution.md)」。 在我们对落地一套功能完善、架构完整的日志系统有初步了解后，想要知道： @@ -26,8 +27,3 @@ Loggie和其他的开源日志Agent区别是什么？ 如何配置整体的监控和报警，保证Loggie正常运行？如何监控是否采集到ERROR日志？ 请看「[监控报警](monitor/loggie-monitor.md)」。 - -使用Loggie遇到问题，如何排查？ -请看「[Troubleshot](troubleshot/general-problems.md)」。 - - diff --git a/docs/user-guide/monitor/loggie-monitor.md b/docs/user-guide/monitor/loggie-monitor.md index efee626..c27287f 100644 --- a/docs/user-guide/monitor/loggie-monitor.md +++ b/docs/user-guide/monitor/loggie-monitor.md @@ -6,7 +6,7 @@ Loggie的monitor eventbus被设计为发布和订阅模式，各个组件发送m 组件和topic以及listener之间是松耦合关系，比如`file source`还会定时将全量匹配的日志文件指标发送至`filewatcher topic`，`filewatcher listener`会处理和暴露指标。 -## monitor配置 +## Monitor配置 monitor eventbus配置在全局的系统配置中，示例如下： !!! config @@ -89,11 +89,7 @@ spec: instance: loggie ``` -同时，我们需要在Grafana中添加如下的json来展示Loggie的监控控制台。 - -```url -https://github.com/loggie-io/installation/tree/main/prometheus/grafana-dashboard -``` +同时，我们需要在Grafana中添加install工程中的[json](https://github.com/loggie-io/installation/tree/main/prometheus/grafana-dashboard)来展示Loggie的监控控制台。 !!! note Kubernetes版本和Grafana版本不同，可能导致图表展示不兼容，需要根据情况进行修改。 diff --git a/docs/user-guide/monitor/service-log-alarm.md b/docs/user-guide/monitor/service-log-alarm.md index 24be10c..3b1c9d2 100644 --- a/docs/user-guide/monitor/service-log-alarm.md +++ b/docs/user-guide/monitor/service-log-alarm.md @@ -44,7 +44,7 @@ port: 9196 ``` -增加`logAlert interceptor`，同时在logConfig中引用： +增加`logAlert interceptor`，同时在ClusterLogConfig/LogConfig中引用： !!! config diff --git a/docs/user-guide/troubleshot/FAQ.md b/docs/user-guide/troubleshot/FAQ.md deleted file mode 100644 index 4514b4c..0000000 --- a/docs/user-guide/troubleshot/FAQ.md +++ /dev/null @@ -1 +0,0 @@ -# FAQ diff --git a/docs/user-guide/troubleshot/general-problems.md b/docs/user-guide/troubleshot/general-problems.md deleted file mode 100644 index 129cf37..0000000 --- a/docs/user-guide/troubleshot/general-problems.md +++ /dev/null @@ -1 +0,0 @@ -# 一般问题排查思路 \ No newline at end of file diff --git a/docs/user-guide/use-in-kubernetes/collect-container-logs.md b/docs/user-guide/use-in-kubernetes/collect-container-logs.md index 3f1e8b0..2c1917b 100644 --- a/docs/user-guide/use-in-kubernetes/collect-container-logs.md +++ b/docs/user-guide/use-in-kubernetes/collect-container-logs.md @@ -22,9 +22,10 @@ Loggie会感知到Pod和CRD的事件，进行配置的动态更新。同时，Lo ## CRD使用说明 Loggie目前有三种CRD： -- **[LogConfig](../../reference/discovery/kubernetes/logconfig.md)**：表示一个日志采集任务，其中主要填写采集的source配置，以及关联的sink和interceptor。 -- **[Sink](../../reference/discovery/kubernetes/sink.md)**：表示一个sink后端，需要在LogConfig中被关联。 -- **[Interceptor](../../reference/discovery/kubernetes/interceptors.md)**：表示一个interceptors组，需要在LogConfig中被关联。 +- **[LogConfig](../../reference/discovery/kubernetes/logconfig.md)**：namespace级别CRD，用于采集Pod容器日志，其中主要填写采集的source配置，以及关联的sink和interceptor。 +- **[ClusterLogConfig](../../reference/discovery/kubernetes/clusterlogconfig.md)**：cluster级别CRD，表示集群级别的采集Pod容器日志，采集Node节点上的日志，以及为某个Loggie集群下发通用的pipeline配置。 +- **[Sink](../../reference/discovery/kubernetes/sink.md)**：表示一个sink后端，需要在ClusterLogConfig/LogConfig中被关联。 +- **[Interceptor](../../reference/discovery/kubernetes/interceptors.md)**：表示一个interceptors组，需要在ClusterLogConfig/LogConfig中被关联。 ## 准备工作 @@ -37,7 +38,7 @@ Loggie目前有三种CRD： 3. Loggie Agent发送至Kafka，Loggie Aggregator消费Kafka再发送至后端 ... -本文仅关注采集端，如果需要使用部署Loggie Aggregator，请参考[Loggie中转机](../use-in-kubernetes/aggregator.md)。 +本文仅关注采集端，如果需要使用部署Loggie Aggregator，请参考[Loggie中转机](../best-practice/aggregator.md)。 在采集容器日志之前，请确保已经在Kubernetes中部署了Loggie DaemonSet。[如何在Kubernetes中部署Loggie？](../../getting-started/install/kubernetes.md) @@ -169,7 +170,7 @@ kubectl port-forward service/kibana-kibana 5601:http 为了表明我们即将采集日志发送到的Elasticsearch，需要配置对应的Sink。 这里有两种方式： -1. 如果整个集群只会有一个存储后端，我们可以在全局的配置文件configMap里，配置defaults参数，具体可[参考](../../reference/global/system.md#defaults)。 +1. 如果整个集群只会有一个存储后端，我们可以在全局的配置文件configMap里，配置defaults参数，具体可[参考](../../reference/global/defaults.md)。 2. 使用Sink CRD，并在logConfig中引用。这种方式可以扩展为多个后端，不同的logConfig可以配置使用不同的后端存储，大多数情况下，我们建议使用该方式。 @@ -298,16 +299,6 @@ Events: 发送成功后，我们可以在Kibana上查询到采集到的日志。 -## 更多 -虽然Loggie已经采集到了日志到Elasticsearch中，我们肯定还有更多的疑问和需求，比如： - -1. stdout日志输出的格式被多加了一层封装，如何只发送原始的日志内容？ -2. Loggie默认的日志字段和现有使用不一致，如何修改Loggie发送的日志格式与字段？ -3. 如何将日志发送到Kafka，然后通过Kafka再转发至Elasticsearch？ -4. 如何配置Loggie的监控？ - - - diff --git a/docs/user-guide/use-in-kubernetes/collect-node-logs.md b/docs/user-guide/use-in-kubernetes/collect-node-logs.md index 57a997a..0d81914 100644 --- a/docs/user-guide/use-in-kubernetes/collect-node-logs.md +++ b/docs/user-guide/use-in-kubernetes/collect-node-logs.md @@ -4,7 +4,7 @@ ## 配置说明 -和采集容器不同的是，节点日志采集的logConfig类型是ClusterLogConfig，selector使用`type: node`，并且填写`nodeSelector`用于选择下发配置到哪些节点，Node上需要包含这些labels。 +和采集容器不同的是，节点日志采集需使用集群级别的ClusterLogConfig，selector使用`type: node`，并且填写`nodeSelector`用于选择下发配置到哪些节点，同时需确保Node上包含这些labels。 示例如下： !!! example @@ -28,5 +28,5 @@ interceptorRef: default ``` -另外需要注意的是，如果需要采集Node节点上某路径的日志，需要Loggie同样挂载相同的路径，否则由于容器隔离性Loggie无法获取到节点的日志。 +另外应注意的是，如果需要采集Node节点上某路径的日志，需要Loggie同样挂载相同的路径，否则由于容器隔离性Loggie无法获取到节点的日志。 比如采集Node上`/var/log/`路径下的日志，需要Loggie Agent增加挂载该路径。 \ No newline at end of file diff --git a/docs/user-guide/use-in-kubernetes/kube-event-source.md b/docs/user-guide/use-in-kubernetes/kube-event-source.md index 818288e..b42e4fa 100644 --- a/docs/user-guide/use-in-kubernetes/kube-event-source.md +++ b/docs/user-guide/use-in-kubernetes/kube-event-source.md @@ -10,18 +10,17 @@ Kubernetes Events是由Kubernetes本身组件和一些控制器产生的事件 ## 配置示例 -配置kubeEvents source，并且使用`type: loggie`下发配置到Aggregator集群即可。 +配置kubeEvents source，并且使用`type: cluster`下发配置到Aggregator集群即可。 !!! config ```yaml apiVersion: loggie.io/v1beta1 - kind: LogConfig + kind: ClusterLogConfig metadata: name: kubeevent - namespace: default spec: selector: - type: loggie + type: cluster cluster: aggregator pipeline: sources: | @@ -63,16 +62,15 @@ Kubernetes Events是由Kubernetes本身组件和一些控制器产生的事件 target: ["body"] ``` - === "logConfig" + === "clusterLogConfig" ```yaml apiVersion: loggie.io/v1beta1 - kind: LogConfig + kind: ClusterLogConfig metadata: name: kubeevent - namespace: default spec: selector: - type: loggie + type: cluster cluster: aggregator pipeline: sources: | @@ -150,7 +148,6 @@ Kubernetes Events是由Kubernetes本身组件和一些控制器产生的事件 ] }, "reportingComponent": "", - "systemPipelineName": "default/kubeevent/", "type": "Normal", "message": "Created pod: loggie-aggregator-pbkjk", "reason": "SuccessfulCreate", @@ -170,7 +167,6 @@ Kubernetes Events是由Kubernetes本身组件和一些控制器产生的事件 "apiVersion": "apps/v1", "resourceVersion": "2975170" }, - "systemSourceName": "event" } ``` diff --git a/docs/user-guide/use-in-kubernetes/sidecar.md b/docs/user-guide/use-in-kubernetes/sidecar.md index a2373a4..fe2c3b9 100644 --- a/docs/user-guide/use-in-kubernetes/sidecar.md +++ b/docs/user-guide/use-in-kubernetes/sidecar.md @@ -121,8 +121,3 @@ data: !!! info Loggie后续会支持自动Sidecar注入和通过LogConfig自动生成ConfigMap挂载的方式，从而达到和使用DaemonSet一致的体验。 - - -## - - diff --git a/nav.yml b/nav.yml index 23caa45..5d8af41 100644 --- a/nav.yml +++ b/nav.yml @@ -19,7 +19,6 @@ nav: - 架构与特性: - 诞生背景: user-guide/architecture/background.md - 设计架构: user-guide/architecture/core-arch.md - - 配置设计: user-guide/architecture/config.md - 数据格式: user-guide/architecture/schema.md - 优势与特性: user-guide/architecture/advantages.md - 开源项目对比: user-guide/architecture/compare.md @@ -28,14 +27,13 @@ nav: - Kubernetes下的日志采集: user-guide/use-in-kubernetes/general-usage.md - Loggie采集容器日志: user-guide/use-in-kubernetes/collect-container-logs.md - Loggie采集Node日志: user-guide/use-in-kubernetes/collect-node-logs.md - - Loggie中转机: user-guide/use-in-kubernetes/aggregator.md - Sidecar方式采集日志: user-guide/use-in-kubernetes/sidecar.md - 采集Kubernetes Events: user-guide/use-in-kubernetes/kube-event-source.md - 最佳实践: - 日志格式转换: user-guide/best-practice/log-format.md - - 日志切分与处理: user-guide/best-practice/log-process.md - - 日志定时清理: user-guide/best-practice/log-clean.md + - 日志切分处理: user-guide/best-practice/log-process.md + - 使用Loggie中转机: user-guide/best-practice/aggregator.md - 监控报警: - Loggie的监控与报警: user-guide/monitor/loggie-monitor.md @@ -43,18 +41,11 @@ nav: - 企业实战: - 日志系统架构与演进: user-guide/enterprise-practice/architecture-and-evolution.md - - 企业日志使用实践: user-guide/enterprise-practice/enterprise-log-practice.md - - - TroubleShot: - - 一般问题排查思路: user-guide/troubleshot/general-problems.md - - FAQ: user-guide/troubleshot/FAQ.md - - 组件配置: - Overview: reference/index.md - 启动参数: reference/global/args.md - 系统配置: - - Overview: reference/global/system.md - monitor: reference/global/monitor.md - discovery: reference/global/discovery.md - reload: reference/global/reload.md @@ -62,20 +53,29 @@ nav: - http: reference/global/http.md - Source: + - Overview: reference/pipelines/source/overview.md - file: reference/pipelines/source/file.md - kafka: reference/pipelines/source/kafka.md - - kubeEvent: reference/pipelines/source/kubeEvent.md + - kubeEvent: reference/pipelines/source/kube-event.md - grpc: reference/pipelines/source/grpc.md + - prometheusExporter: reference/pipelines/source/prometheus-exporter.md + - unix: reference/pipelines/source/unix.md + - dev: reference/pipelines/source/dev.md + - Sink: + - Overview: reference/pipelines/sink/overview.md - elasticsearch: reference/pipelines/sink/elasticsearch.md - kafka: reference/pipelines/sink/kafka.md - - dev: reference/pipelines/sink/dev.md - grpc: reference/pipelines/sink/grpc.md - - codec: reference/pipelines/sink/codec.md + - file: reference/pipelines/sink/file.md + - dev: reference/pipelines/sink/dev.md + - Interceptor: + - Overview: reference/pipelines/interceptor/overview.md - normalize: reference/pipelines/interceptor/normalize.md - - limit: reference/pipelines/interceptor/limit.md - - logalert: reference/pipelines/interceptor/logalert.md + - rateLimit: reference/pipelines/interceptor/limit.md + - addK8sMeta: reference/pipelines/interceptor/addk8smeta.md + - logAlert: reference/pipelines/interceptor/logalert.md - metrics: reference/pipelines/interceptor/metrics.md - retry: reference/pipelines/interceptor/retry.md - maxbytes: reference/pipelines/interceptor/maxbytes.md @@ -83,16 +83,24 @@ nav: - Queue: - channel: reference/pipelines/queue/channel.md - memeory: reference/pipelines/queue/memory.md + + - Monitor: + - Overview: reference/monitor/overview.md + - filesource: reference/monitor/filesource.md + - filewatcher: reference/monitor/filewatcher.md + - reload: reference/monitor/reload.md + - sink: reference/monitor/sink.md + - queue: reference/monitor/queue.md + - logAlert: reference/monitor/logalert.md + - Kubernetes CRD: - - Overview: reference/discovery/kubernetes/overview.md - - logConfig: reference/discovery/kubernetes/logconfig.md - - clusterLogConfig: reference/discovery/kubernetes/clusterlogconfig.md - - sink: reference/discovery/kubernetes/sink.md - - interceptor: reference/discovery/kubernetes/interceptors.md + - LogConfig: reference/discovery/kubernetes/logconfig.md + - ClusterLogConfig: reference/discovery/kubernetes/clusterlogconfig.md + - Sink: reference/discovery/kubernetes/sink.md + - Interceptor: reference/discovery/kubernetes/interceptors.md - 开发手册: - 代码贡献: developer-guide/contributing.md - 本地开发: developer-guide/development.md - 代码规范: developer-guide/code/coding-guide.md - 组件开发: developer-guide/component/component-guide.md - - metric上报: developer-guide/metric/metric-guide.md