Release v1.2 (#67)

* Feat: add release v1.2 docs
2022-06-16 17:23:55 +08:00 · 2022-06-16 17:23:55 +08:00 · 8df0093942
parent bf3910fc6f
commit 8df0093942
24 changed files with 646 additions and 35 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,67 @@
+# Copyright (c) 2016-2021 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Node, TypeScript, Python
+# -----------------------------------------------------------------------------
+
+# Dependencies
+/node_modules
+/__pycache__
+/venv
+/.venv
+
+# Build files
+/build
+/MANIFEST
+/site
+
+# Distribution files
+/dist
+/mkdocs_material.egg-info
+
+# Caches and logs
+*.cpuprofile
+*.log
+*.tsbuildinfo
+.cache
+.eslintcache
+
+# -----------------------------------------------------------------------------
+# General
+# -----------------------------------------------------------------------------
+
+# Never ignore .gitkeep files
+!**/.gitkeep
+
+# Husky hooks
+.husky/.gitignore
+.husky/_
+
+# macOS internals
+.DS_Store
+
+# Temporary files
+TODO
+tmp
+
+# IDEs
+.vscode
+.idea
--- a/docs/developer-guide/release.md
+++ b/docs/developer-guide/release.md
@ -0,0 +1,83 @@
+# 版本和Release发布流程
+
+## 版本发布涉及工程
+- Loggie 主工程
+- Loggie-installation 部署脚本工程
+- Loggie docs 文档项目（暂时为最新的版本文档，后续会支持多版本）
+
+## 代码分支策略
+- 版本参考[Semantic语义](https://semver.org/)
+- 使用main主分支为开发分支，日常所有代码PR均合入main分支
+- 新版本使用release分支，格式为`release-vA.B`，例如`release-v1.1`，这里只使用版本前两位
+- 基于release分支打上tag表示具体版本，例如`v1.1.0`
+- bugfix 除了肯定会合入main分支外，根据严重情况cherry-pick至具体的release分支，同时打上tag，需要升级最小版本，例如`v1.1.1`
+
+## 发布新版本步骤
+
+#### 1. 创建新的release分支
+
+确认版本需要的所有功能已经合入，main分支为最新提交：
+
+``` bash
+git checkout main
+git pull upstream main -r
+```
+
+基于main分支创建新的release分支，例如`release-v1.1`：
+```bash
+git checkout -b release-v${A.B}
+```
+
+#### 2. 填写CHANGELOG
+基于该分支填写CHANGELOG，提交至工程中合入
+
+```bash
+git add .
+git commit -m'Release: add v${A.B.C} changelog'
+git push upstream release-v${A.B.C}
+```
+
+#### 3. release Loggie-installation
+release Loggie-installationation部署脚本工程，和上述1，2步骤相同
+
+请注意：
+
+- 请勿忘记修改Chart.yaml中的版本号
+
+#### 4. 回归测试
+基于release分支进行回归测试。  
+release分支push至Github后，会触发action进行镜像构建，使用该镜像进行回归测试。  
+这里的测试会使用loggie-installationation部署脚本里相应的release分支，同时回归验证部署脚本正确性。  
+如果测试发现Bug，提交PR合入release分支，重新进行回归。  
+
+#### 5. 打上版本tag
+
+测试通过后，基于该release分支打上相应的版本tag，比如`v1.1.0`
+```bash
+git pull upstream release-v${A.B.C}
+git tag v${A.B.C}
+git push v${A.B.C}
+```
+注意Loggie工程和Loggie-installationation部署脚本均需要。
+
+#### 6. 在Github上发布release
+
+- Loggie工程复制项目中的CHANGELOG即可
+- Loggie installation工程需要提供`loggie-linux-amd64`二进制和`loggie-v${A.B.C}.tgz` helm chart包。
+  - 二进制需要找台linux amd64机器进行`make build`
+  - helm chart包需要基于对应版本的loggie installation项目，执行`helm package ./helm-chart`即可。
+
+#### 7. 更新Loggie docs文档
+
+- 更新Loggie docs文档，并提PR合入
+- 注意修改Loggie镜像和版本号等
+
+
+#### 8. 将release分支合入main
+提PR将release分支合入main，可等稳定一段时间后再合入，注意Loggie工程和Loggie-installation部署脚本均需要。
+
+
+## 有BugFix时
+
+- 如果是不重要的bug，基于main分支提交修改即可，可以不合入release分支
+- 如果为重要的bug，需要修复，确定需要修复的版本release分支（可为最近一个或者多个），除了提交至main分支外，还需要cherry-pick至指定release分支，同时打上tag，新增最小版本号，同时需要确认Loggie-installation和docs是否同步修改。
--- a/docs/getting-started/install/kubernetes.md
+++ b/docs/getting-started/install/kubernetes.md
@ -10,7 +10,7 @@
 ### 下载helm-chart包

 ```bash
-helm pull https://github.com/loggie-io/installation/releases/download/v1.1.0/loggie-v1.1.0.tgz && tar xvzf loggie-v1.1.0.tgz
+helm pull https://github.com/loggie-io/installation/releases/download/v1.2.0/loggie-v1.2.0.tgz && tar xvzf loggie-v1.2.0.tgz
 ```

 ### 修改配置
@ -25,7 +25,7 @@ cd installation/helm-chart

 #### 镜像
 ```yaml
-image: hub.c.163.com/loggie/loggie:v1.1.0
+image: hub.c.163.com/loggie/loggie:v1.2.0
 ```
 loggie的镜像。

--- a/docs/getting-started/install/node.md
+++ b/docs/getting-started/install/node.md
@ -13,7 +13,7 @@ Loggie使用Golang编译成二进制，可根据自身需求对接各类部署
 ## 下载二进制

 ```
-mkdir /opt/loggie && curl https://github.com/loggie-io/installation/releases/download/v1.1.0/loggie-linux-amd64 -o /opt/loggie/loggie && chmod +x /opt/loggie/loggie
+mkdir /opt/loggie && curl https://github.com/loggie-io/installation/releases/download/v1.2.0/loggie-linux-amd64 -o /opt/loggie/loggie && chmod +x /opt/loggie/loggie
 ```

 ## 添加配置文件
--- a/docs/getting-started/quick-start/kubernetes.md
+++ b/docs/getting-started/quick-start/kubernetes.md
@ -22,7 +22,7 @@
 #### 下载chart再部署

 ```bash
-helm pull https://github.com/loggie-io/installation/releases/download/v1.1.0/loggie-v1.1.0.tgz && tar xvzf loggie-v1.1.0.tgz
+helm pull https://github.com/loggie-io/installation/releases/download/v1.2.0/loggie-v1.2.0.tgz && tar xvzf loggie-v1.2.0.tgz
 ```
 尝试修改一下其中的values.yaml。

@ -40,7 +40,7 @@ helm install loggie ./loggie -nloggie --create-namespace
 #### 直接部署：

 ```bash
-helm install loggie -nloggie --create-namespace https://github.com/loggie-io/installation/releases/download/v1.1.0/loggie-v1.1.0.tgz
+helm install loggie -nloggie --create-namespace https://github.com/loggie-io/installation/releases/download/v1.2.0/loggie-v1.2.0.tgz
 ```


@ -107,6 +107,35 @@ spec:
 EOF
 ```

+可以看到，上面使用了sinkRef引用了刚才创建的`sink default CR`。当然，我们还可以直接在Logconfig中使用sink字段，示例如下：
+
+```yaml
+cat << EOF | kubectl apply -f -
+apiVersion: loggie.io/v1beta1
+kind: LogConfig
+metadata:
+  name: nginx
+  namespace: default
+spec:
+  selector:
+    type: pod
+    labelSelector:
+      app: nginx
+  pipeline:
+    sources: |
+      - type: file
+        name: mylog
+        paths:
+        - stdout
+    sink: |
+      type: dev
+      printEvents: true
+      codec:
+        type: json
+        pretty: true
+EOF
+```
+
 创建完之后，我们可以使用`kubectl get lgc`查看到创建的CRD实例。

 同时，我们还可以通过`kubectl describe lgc nginx`查看LogConfig的事件，以获取最新的状态。
--- a/docs/getting-started/quick-start/node.md
+++ b/docs/getting-started/quick-start/node.md
@ -5,7 +5,7 @@
 ### 1. 下载可执行文件
 请找一台Linux服务器节点，下载Loggie二进制可执行文件
 ```shell
-curl -LJ https://github.com/loggie-io/installation/releases/download/v1.1.0/loggie-linux-amd64 -o loggie
+curl -LJ https://github.com/loggie-io/installation/releases/download/v1.2.0/loggie-linux-amd64 -o loggie
 ```
 ### 2. 添加配置文件

--- a/docs/reference/discovery/kubernetes/logconfig.md
+++ b/docs/reference/discovery/kubernetes/logconfig.md
@ -107,9 +107,10 @@ namespace级别CRD，表示一个日志采集任务，用于采集Pod容器日
 | 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存在不一致的场景。 |
-| matchFields.annotationKey | string数组  |    非必填    |      | 和上面labelKey类似，注入的为Pod Annoatation的值 |
-| matchFields.env | string数组  |    非必填    |      | 和上面labelKey类似，注入的为Pod Env环境变量的值 |
+| matchFields.labelKey | string数组  |    非必填    |      | 指定增加的Pod上的Label Key值，比如Pod上包含Label: `app: demo`，此处填写`labelKey: app`，此时会将Pod上的`app: demo` label增加到file source fields中，采集到的日志会被加上该label信息。适用于匹配的Pod的label存在不一致的场景。支持配置为"*"的方式获取所有的label |
+| matchFields.annotationKey | string数组  |    非必填    |      | 和上面labelKey类似，注入的为Pod Annoatation的值，支持配置为"*"的方式获取所有的annotation |
+| matchFields.env | string数组  |    非必填    |      | 和上面labelKey类似，注入的为Pod Env环境变量的值，支持配置为"*"的方式获取所有的env |
+

 !!! example

--- a/docs/reference/global/args.md
+++ b/docs/reference/global/args.md
@ -14,7 +14,7 @@
 ## 日志参数:  

 - `-log.level`: 日志级别，默认为info，可配置为debug、info、warn和error
- `-log.jsonFormat`: 是否将日志输出为json格式，默认为true
+- `-log.jsonFormat`: 是否将日志输出为json格式，默认为false
 - `-log.enableStdout`: 是否输出标准输出日志，默认为true
 - `-log.enableFile`: 是否输出日志文件，默认为false，即不输出日志文件，默认打印到标准输出
 - `-log.directory`: 日志文件的路径，默认为/var/log，当log.enableFile=true时生效
@ -23,6 +23,7 @@
 - `-log.maxBackups`: 日志轮转最多保留的文件个数，默认为3
 - `-log.maxAge`: 日志轮转最大保留的天数，默认为7
 - `-log.timeFormat`: 每行日志输出的时间格式，默认格式为`2006-01-02 15:04:05`
+- `-log.noColor`: 输出是否有颜色美化，默认为false，即有颜色美化，对于从标准输出查看日志比较方便。如果输出到日志文件中，建议设置为true，避免引入额外的格式。

 !!! info
    Loggie的日志轮转使用[lumberjack](`https://github.com/natefinch/lumberjack`)库
--- a/docs/reference/global/discovery.md
+++ b/docs/reference/global/discovery.md
@ -8,12 +8,13 @@
      enabled: true
      kubernetes:
        cluster: aggregator
-        fields:
-          container.name: containername
-          logConfig: logconfig
-          namespace: namespace
-          node.name: nodename
-          pod.name: podname
+        containerRuntime: containerd
+        k8sFields: 
+          logconfig: "${_k8s.logconfig}"
+          namespace: "${_k8s.pod.namespace}"
+          nodename: "${_k8s.node.name}"
+          podname: "${_k8s.pod.name}"
+          containername: "${_k8s.pod.container.name}"

    ```

@ -32,14 +33,21 @@
 | kubeconfig | string  |    非必填    |     |  指定请求Kubernetes集群API的kubeconfig文件。通常在Loggie部署到Kubernetes集群中无需填写，此时为inCluster模式。如果Loggie部署在Kubernetes集群外（例如本地调试时），需要指定该kubeconfig文件。 |
 | master | string  |    非必填    |     | 指定请求Kubernetes集群API的master地址，inCluster模式一般无需填写 |
 | containerRuntime | string  |    非必填    |  docker   | 容器运行时，可选`docker`和`containerd` |
-| dockerDataRoot | string  |    非必填    |  /var/lib/docker   | docker的rootfs路径 |
+| rootFsCollectionEnabled | bool  |    非必填    |  false   | 是否开启采集root filesystem里的日志，用于不挂载日志volume的场景 |
+| parseStdout | bool  |    非必填    |  false   | 是否开启自动提取容器标准输出原始内容 |
 | kubeletRootDir | string  |    非必填    |  /var/lib/kubelet   | kubelet的root路径 |
 | podLogDirPrefix | string  |    非必填    |  /var/log/pods   | kubernetes默认放置的pod标准输出路径 |
-| fields | map  |    非必填    |    | 自动添加的元信息 |
-| fields.node.name | string  |    非必填    |  node.name  | 添加所在节点node name作为元信息，同时使用该值为key |
-| fields.node.ip | string  |    非必填    |  node.ip  | 添加所在节点node ip作为元信息，同时使用该值为key |
-| fields.namespace | string  |    非必填    |  namespace  | 添加namespace作为元信息，同时使用该值为key |
-| fields.pod.name | string  |    非必填    |  pod.name  | 添加pod name作为元信息，同时使用该值为key |
-| fields.pod.ip | string  |    非必填    |  pod.ip  | 添加pod ip作为元信息，同时使用该值为key |
-| fields.container.name | string  |    非必填    |  container.name  | 添加container name作为元信息，同时使用该值为key |
-| fields.logConfig | string  |    非必填    |  logConfig  | 添加logConfig name作为元信息，同时使用该值为key |
+| k8sFields | map  |    非必填    |    | 自动添加的kubernetes相关元信息，key即为添加的元信息key，value请使用${_k8s.XX}的方式指定 |
+
+
+"${_k8s.XX}"的方式可填写以下参数：
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| ${_k8s.node.name} | string  |    非必填    |  node.name  | 添加所在节点node name作为元信息 |
+| ${_k8s.node.ip} | string  |    非必填    |  node.ip  | 添加所在节点node ip作为元信息 |
+| ${_k8s.pod.namespace} | string  |    非必填    |  namespace  | 添加namespace作为元信息 |
+| ${_k8s.logconfig}| string  |    非必填    |  logConfig  | 添加logConfig name作为元信息 |
+| ${_k8s.pod.name} | string  |    非必填    |  pod.name  | 添加pod name作为元信息 |
+| ${_k8s.pod.ip} | string  |    非必填    |  pod.ip  | 添加pod ip作为元信息 |
+| ${_k8s.pod.container.name} | string  |    非必填    |  container.name  | 添加container name作为元信息 |
--- a/docs/reference/monitor/sys.md
+++ b/docs/reference/monitor/sys.md
@ -0,0 +1,35 @@
+# sys listener
+
+Loggie本身的CPU和Memory指标
+
+## 配置
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| period | time.Duration  |    非必填    |   10s   |  listener消费处理数据的时间间隔 |
+
+
+## Metrics
+
+#### cpu_percent
+
+```
+# HELP loggie_sys_cpu_percent Loggie cpu percent
+# TYPE loggie_sys_cpu_percent gauge
+loggie_sys_cpu_percent 0.37
+```
+
+* HELP: Loggie的cpu使用率
+* TYPE: gauge
+
+
+#### mem_rss
+
+```
+# HELP loggie_sys_mem_rss Loggie memory rss bytes
+# TYPE loggie_sys_mem_rss gauge
+loggie_sys_mem_rss 2.5853952e+07
+```
+
+* HELP: Loggie的内存占用字节数
+* TYPE: gauge
+
--- a/docs/reference/pipelines/interceptor/addk8smeta.md
+++ b/docs/reference/pipelines/interceptor/addk8smeta.md
@ -1,12 +1,12 @@
 # addK8sMeta

-用于从event中的某些字段（比如日志文件的路径中），提取到：
+用于从event中的某些字段（比如日志文件的路径中），获取到：

 - `pod.uid`
 - `namespace`与`pod.name`
 - `container.id`

-以上3种任意其一，此时Loggie可索引到具体的Pod信息，并添加`${node.name}`、`${namespace}`、`${pod.uid}`、`${pod.name}`等元信息作加入到event中，用于后续的分析处理。  
+以上3种任意其一的索引信息，此时Loggie可根据该索引查询到具体的Pod，并添加额外的kubernetes`${node.name}`、`${namespace}`、`${pod.uid}`、`${pod.name}`等元信息作加入到event中，用于后续的分析处理。  
 属于source interceptor。

 !!! example
@ -21,12 +21,6 @@
        podname: "${pod.name}"
    ```

-## patternFields
-
-|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
-| ---------- | ----------- | ----------- | --------- | -------- |
-| patternFields | string  |    非必填    |  默认会从event中获取系统字段里的filename    | 用于提取的字段 |
-
 ## pattern

 |    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
@ -43,6 +37,12 @@

 比如：`/var/log/${pod.uid}/${pod.name}/`

+## patternFields
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| patternFields | string  |    非必填    |  默认会从event中获取系统字段里的filename，此时需要使用file source    | 从event中用于提取的pattern的字段 |
+
 ## fieldsName

 |    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
@ -57,7 +57,10 @@

 目前支持添加的元信息字段有：

+- `${cluster}`：集群信息，为系统配置中`discovery.kubernetes.cluster`字段。
 - `${node.name}`
 - `${namespace}`
+- `${workload.kind}`：Deployment/StatefulSet/DaemonSet/Job等
+- `${workload.name}`：工作负载的名称
 - `${pod.uid}`
 - `${pod.name}`
--- a/docs/reference/pipelines/interceptor/normalize.md
+++ b/docs/reference/pipelines/interceptor/normalize.md
@ -55,6 +55,7 @@
 | ---------- | ----------- | ----------- | --------- | -------- |
 | regex.pattern | string  |    必填    |  无    | 正则解析规则 |
 | regex.target | string  |    非必填    |  body    | 正则解析的目标字段 |
+| regex.ignoreError | bool  |    非必填    |  false    | 是否忽略错误 |

 !!! example
    ```yaml
@ -88,6 +89,8 @@
 |    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
 | ---------- | ----------- | ----------- | --------- | -------- |
 | jsonDecode.target | string  |    非必填    |  body    | json decode的目标字段 |
+| jsonDecode.ignoreError | bool  |    非必填    |  false    | 是否忽略错误 |
+

 !!! example
    ```yaml
@ -107,6 +110,7 @@
 | split.separator | string  |    必填    |  无    | 分隔符 |
 | split.max | int  |    非必填    |  -1    | 通过分割符分割后得到的最多的字段数 |
 | split.keys | string数组  |    必填    |  无   | 分割后字段对应的key |
+| split.ignoreError | bool  |    非必填    |  false    | 是否忽略错误 |

 !!! example
    === "base"
--- a/docs/reference/pipelines/sink/overview.md
+++ b/docs/reference/pipelines/sink/overview.md
@ -26,7 +26,7 @@
 |    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
 | ---------- | ----------- | ----------- | --------- | -------- |
 | codec |   |    非必填    |    | sink发送数据给下游时，数据使用的格式 |
-| codec.type | string  |    非必填    |   json | 使用json格式发送 |
+| codec.type | string  |    非必填    |   json | codec类型 |

 #### type: json

--- a/docs/reference/pipelines/sink/sls.md
+++ b/docs/reference/pipelines/sink/sls.md
@ -0,0 +1,61 @@
+# sls
+
+sls sink用于将日志发送至阿里云SLS存储。  
+
+!!! example
+
+    ```yaml
+    sink:
+      type: sls
+      name: demo
+      endpoint: cn-hangzhou.log.aliyuncs.com
+      accessKeyId: ${id}
+      accessKeySecret: ${secret}
+      project: test
+      logstore: test1
+      topic: myservice
+    ```
+
+## endpoint
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| endpoint | string  |    必填    |      | sls存储的访问域名 |
+
+你可以在具体project页面的项目概览中查看到。
+
+## accessKeyId
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| accessKeyId | string  |    必填    |      | 访问的accessKeyId，请查看阿里云账号的访问凭证管理 |
+
+建议使用阿里云的子账号，子账号需要有对应project、logstore的权限。
+
+## accessKeySecret
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| accessKeySecret | string  |    必填    |      | 访问的accessKeySecret，请查看阿里云账号的访问凭证管理 |
+
+## project
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| project | string  |    必填    |      | SLS存储的project名称 |
+
+## logstore
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| logstore | string  |    必填    |      | SLS存储的logstore名称 |
+
+## topic
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| topic | string  |    非必填    |      | 日志主题（Topic）是日志服务的基础管理单元。您可在采集日志时指定Topic，用于区分日志  |
+
+
+
+
--- a/docs/reference/pipelines/source/overview.md
+++ b/docs/reference/pipelines/source/overview.md
@ -108,3 +108,77 @@ sources字段为数组，一个Pipeline中可填写多个source组件配置。
    }
 }
 ```
+
+### codec
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| codec |   |    非必填    |    | source接收到数据的时候用于解析预处理 |
+| codec.type | string  |    非必填    |   无 |  |
+
+请注意：目前仅`file source`支持source codec。
+
+#### type: json
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| codec.bodyFields |   |    必填    |    | 使用解析读取到的json数据中的该字段作为`body` |
+
+配置示例：
+!!! example "type: json"
+
+    ```yaml
+      sources:
+      - type: file
+        name: nginx
+        paths:
+        - /var/log/*.log
+        codec:
+          type: json
+          bodyFields: log
+    ```
+
+如果采集到的日志为：
+```json
+{"log":"I0610 08:29:07.698664 Waiting for caches to sync\n", "stream":"stderr", "time:"2021-06-10T08:29:07.698731204Z"}
+```
+则codec后得到的event为：
+```
+body: "I0610 08:29:07.698664 Waiting for caches to sync"
+```
+
+请注意：目前非bodyFields的字段均会被丢弃。
+
+
+#### type: regex
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| codec.pattern |   |    必填    |    | 正则表达式 |
+| codec.bodyFields |   |    必填    |    | 使用正则提取到的该字段作为`body` |
+
+配置示例：
+!!! example "type: regex"
+
+    ```yaml
+      sources:
+      - type: file
+        name: nginx
+        paths:
+        - /var/log/*.log
+        codec:
+          type: regex
+          pattern: ^(?P<time>[^ ^Z]+Z) (?P<stream>stdout|stderr) (?P<logtag>[^ ]*) (?P<log>.*)$
+          bodyFields: log
+    ```
+
+如果采集到的日志为：
+```
+2021-12-01T03:13:58.298476921Z stderr F INFO [main] Starting service [Catalina]
+```
+则codec后得到的event为：
+```
+body: "INFO [main] Starting service [Catalina]"
+```
+
+请注意：目前非bodyFields的字段均会被丢弃。
--- a/docs/reference/pipelines/source/prometheus-exporter.md
+++ b/docs/reference/pipelines/source/prometheus-exporter.md
@ -35,3 +35,25 @@
 |    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
 | ---------- | ----------- | ----------- | --------- | -------- |
 | toJson | bool  |    非必填    |  false   | 是否将抓取到的prometheus原生指标，转换成JSON格式 |
+
+## labels
+
+|    `字段`   |    `类型`    |  `是否必填`  |  `默认值`  |  `含义`  |
+| ---------- | ----------- | ----------- | --------- | -------- |
+| labels | map  |    非必填    |     | 给所有metrics指标增加额外的label |
+
+labels支持配置${_env.XX}的方式获取环境变量。
+例如，配置：
+!!! example "labels"
+
+    ```yaml
+        sources:
+        - type: prometheusExporter
+          name: metric
+          endpoints:
+          - "http://127.0.0.1:9196/metrics"
+          labels:
+            svc: ${_env.SVC}
+    
+    ```
+假设环境变量SVC=test，会将所有的metrics加上svc=test的label。
--- a/docs/user-guide/best-practice/log-process.md
+++ b/docs/user-guide/best-practice/log-process.md
@ -25,6 +25,9 @@
 这种结构化的数据，存储的时候便于过滤查询，或者根据日志里的时间来排序，而不是采集的时间戳，或者根据日志级别进行一些过滤，可以方便查询到ERROR级别的日志等等。  
 当然不仅仅是像以上tomcat的运维类日志，还有诸如业务的一些订单等等日志，都有类似的需求和使用场景。  

+!!! caution "关于stdout日志的解析提取"
+    以下示例仅提供日志切分处理的参考思路，如果你需要提取容器标准输出的原始日志，请参考[采集容器日志](../use-in-kubernetes/collect-container-logs.md#_5)。
+
 ## 功能
 目前已经支持的功能有：

--- a/docs/user-guide/enterprise-practice/imgs/sls-crd.png
+++ b/docs/user-guide/enterprise-practice/imgs/sls-crd.png
--- a/docs/user-guide/enterprise-practice/imgs/sls-project.png
+++ b/docs/user-guide/enterprise-practice/imgs/sls-project.png
--- a/docs/user-guide/enterprise-practice/imgs/sls-searchlog.png
+++ b/docs/user-guide/enterprise-practice/imgs/sls-searchlog.png
--- a/docs/user-guide/enterprise-practice/sls.md
+++ b/docs/user-guide/enterprise-practice/sls.md
@ -0,0 +1,115 @@
+# 使用阿里云SLS日志存储
+
+不管你的服务部署在阿里云还是使用混合云的架构，Loggie同样支持采集日志数据至阿里云SLS日志存储。
+而你只需要使用`sls sink`即可。
+
+
+## 准备：创建SLS日志存储Project
+
+为了使用阿里云SLS日志存储，我们需要先创建一个对应的Project。
+如下所示，在阿里云SLS页面中，点击`创建Project`，填入project名称和对应的地域，创建完之后同步创建相应的Logstore。
+![sls-project](imgs/sls-project.png)
+
+然后我们可以准备一下`sls sink`的配置，示例如下所示，具体可参考[sls sink 配置参数](../../reference/pipelines/sink/sls.md)：
+
+!!! example "sls sink"
+
+    ```yaml
+        sink:
+          type: sls
+          name: demo
+          endpoint: cn-hangzhou.log.aliyuncs.com
+          accessKeyId: xxxx
+          accessKeySecret: xxxx
+          project: test
+          logstore: test1
+          topic: myservice
+    ```
+
+## 采集ECS上的日志
+
+参考[主机部署](../../getting-started/install/node.md)的方式，我们可以修改pipeline.yml，加上sls sink的配置即可。
+
+Pipeline配置参考示例如下：
+
+!!! example "sls pipeline"
+
+    ```yaml
+    pipelines:
+      - name: test
+        sources:
+          - type: file
+            name: demo
+            addonMeta: true
+            paths:
+              - /tmp/log/*.log
+        sink:
+          type: sls
+          endpoint: cn-hangzhou.log.aliyuncs.com
+          accessKeyId: ${accessKeyId}
+          accessKeySecret: ${accessKeySecret}
+          project: loggietest
+          logstore: demo1
+          topic: myservice
+    ```
+
+## 采集ACK Kubernetes集群的日志
+
+和自建Kubernetes集群一样，Loggie同样可以部署在阿里云ACK的Kubernetes集群中。
+我们可以根据ACK提供的kubeconfig文件，使用kubectl或者helm来部署。可参考[Kubernetes部署](../../getting-started/install/kubernetes.md)。
+
+请注意：
+
+- 如果希望采集未挂载emptyDir/hostPath的Pod日志，请确保values.yaml里系统配置中`discovery.kubernetes.rootFsCollectionEnabled`设置为true。
+- 配置`discovery.kubernetes.containerRuntime`为匹配的Kubernetes集群的容器运行时，默认配置为containerd。
+
+部署完之后，和常规的Kubernetes集群下的使用姿势类似，同样可以使用ClusterLogConfig/LogConfig/Interceptor/Sink CR的方式。
+
+ACK提供了CRD的使用页面，我们可以直接在该页面中进行创建和修改。
+![sls-crd](imgs/sls-crd.png)
+
+采集某个服务的日志示例参考如下，只需使用`sls sink`即可。当然也可以使用单独创建一个sink CR存储`sls sink`配置，在LogConfig中通过sinkRef引用。
+
+!!! example "logconfig"
+
+    ```yaml
+    apiVersion: loggie.io/v1beta1
+    kind: LogConfig
+    metadata:
+      name: tomcat
+      namespace: default
+    spec:
+      selector:
+        labelSelector:
+          app: tomcat
+        type: pod
+    
+      pipeline:
+        sources: |
+          - type: file
+            name: stdout
+            paths:
+              - stdout
+          - type: file
+            name: access
+            ignoreOlder: 3d
+            paths:
+              - /usr/local/tomcat/logs/*.log
+    
+        sink: |
+          type: sls
+          endpoint: cn-hangzhou.log.aliyuncs.com
+          accessKeyId: ${accessKeyId}
+          accessKeySecret: ${accessKeySecret} 
+          project: loggietest
+          logstore: demo1
+          topic: myservice
+    ```
+
+## 查看日志
+
+我们可以在SLS具体的Project中查看采集的日志，如下图所示：
+![sls-searchlog.png](imgs/sls-searchlog.png)
+
+具体的元信息的添加和日志字段修改，可参考[日志切分处理](../best-practice/log-process.md)以及[日志增加元信息](../best-practice/log-enrich.md)。
+
--- a/docs/user-guide/use-in-kubernetes/collect-container-logs.md
+++ b/docs/user-guide/use-in-kubernetes/collect-container-logs.md
@ -301,7 +301,102 @@ Events:

 发送成功后，我们可以在Kibana上查询到采集到的日志。  

-
+## 自动解析容器标准输出原始日志
+
+正常情况下，我们采集到的标准输出并不是打印的日志内容，而是被容器运行时增加了一层封装。  
+
+例如docker的标准输出为json形式：
+```json
+{"log":"I0610 08:29:07.698664 Waiting for caches to sync\n", "stream":"stderr", "time:"2021-06-10T08:29:07.698731204Z"}
+```
+业务打印的原始日志内容存储在log字段里。
+
+containerd的标准输出形式类似如下：
+```
+2021-12-01T03:13:58.298476921Z stderr F INFO [main] Starting service [Catalina]
+```
+前面`2021-12-01T03:13:58.298476921Z stderr F `为运行时增加的前缀内容，后面则为原始的日志。
+
+特别是如果我们配置了日志采集多行配置，因为采集到的日志内容和业务输出的日志不一致，会导致采集标准输出日志匹配多行有问题。
+
+所以，Loggie提供了一键开关配置，在系统配置中，将`parseStdout`参数设置为true即可。
+
+!!! example "parseStdout"
+
+    ```yaml
+    config:
+      loggie:
+        discovery:
+          enabled: true
+          kubernetes:
+            parseStdout: true
+    ```
+
+Loggie会在渲染LogConfig的时候自动增加source codec解析出原始的业务日志。
+
+需要注意的是：
+
+- 仅当LogConfig配置里的paths单独为`stdout`时有效：  
+  【有效】
+    ```yaml
+            sources: |
+              - type: file
+                name: common
+                paths:
+                  - stdout
+    ```
+  【无效】
+  ```yaml
+          sources: |
+            - type: file
+              name: common
+              paths:
+                - stdout
+                - /usr/local/tomcat/logs/*.log
+  ```
+  上面需要改成两个source：  
+  【有效】
+  ```yaml
+          sources: |
+            - type: file
+              name: stdout
+              paths:
+                - stdout
+            - type: file
+              name: tomcat
+              paths:
+                - /usr/local/tomcat/logs/*.log
+  ```
+
+- 目前只会保留原始的日志内容到`body`中，其余运行时附加的字段会被丢弃。
+- 自动解析stdout实际上是在LogConfig渲染成Pipeline配置时自动增加source codec来实现。
+
+
+## 无需挂载volume的容器日志采集
+
+虽然我们建议使用挂载volume(emptyDir/hostPath+subPathExpr)的方式将日志文件挂出给Loggie采集，但仍然存在很多情况我们没办法将业务的Pod统一挂载出日志路径。  
+比如一些基础组件无法配置独立的日志volume，或者业务单纯的不愿意改部署配置。
+
+Loggie提供了无需挂载即可采集容器日志的能力，可自动识别并采集容器root filesystem里的日志文件。
+
+你只需要将部署的helm chart中values.yml里的配置`rootFsCollectionEnabled`设置为true，
+同时填上实际环境的容器运行时（docker/containerd），如下所示：
+
+!!! example "rootFsCollectionEnabled"
+
+    ```yaml
+    config:
+      loggie:
+        discovery:
+          enabled: true
+          kubernetes:
+            containerRuntime: containerd
+            rootFsCollectionEnabled: false
+    ```
+
+修改完成后，重新helm upgrade即可。  
+helm模版会自动渲染增加额外的一些挂载路径和配置，如果你从低版本升级，需要额外修改部署的Daemonset yaml。
+具体原理请参考issues [#208](https://github.com/loggie-io/loggie/issues/208)。



--- a/docs/user-guide/use-in-kubernetes/general-usage.md
+++ b/docs/user-guide/use-in-kubernetes/general-usage.md
@ -202,6 +202,12 @@ Pv的访问模式包括：

 另外，鉴于一些Agent对采集docker stdout有一定的支持，所以还存在一些使用上变种，比如利用webhook注入一个sidecar，读取Pod里的日志文件，转换成sidecar的stdout，然后采集sidecar的stdout日志，这里不再详述。  

+**（4）不挂载**
+
+很多情况下，用户都疏于挂载日志路径volume，或者对接一个已经存在的系统，往往业务方不愿意更改，这个时候能采集容器里的日志文件吗？
+
+Loggie尝试解决了这个问题，可以通过配置开启，不过这种方式仍然需要更多长期生产实践的检验。欢迎试用，具体开关请参考下一节。
+

 #### Sidecar + Stdout/日志文件
 如果需要采用sidecar的方式，需要将日志Agent同时挂载相同的日志路径，Agent的配置文件也一般使用ConfigMap挂载出来。
--- a/nav.yml
+++ b/nav.yml
@ -41,6 +41,7 @@ nav:

      - 企业实战:
        - 日志系统架构与演进: user-guide/enterprise-practice/architecture-and-evolution.md
+        - 使用阿里云SLS日志存储: user-guide/enterprise-practice/sls.md

      - 运维排障:
        - 日志采集快速排障指南: user-guide/troubleshot/log-collection.md
@ -73,6 +74,7 @@ nav:
        - grpc: reference/pipelines/sink/grpc.md
        - file: reference/pipelines/sink/file.md
        - dev: reference/pipelines/sink/dev.md
+        - sls: reference/pipelines/sink/sls.md

      - Interceptor:
        - Overview: reference/pipelines/interceptor/overview.md
@ -96,6 +98,7 @@ nav:
        - sink: reference/monitor/sink.md
        - queue: reference/monitor/queue.md
        - logAlert: reference/monitor/logalert.md
+        - sys: reference/monitor/sys.md

      - Kubernetes CRD: 
        - LogConfig: reference/discovery/kubernetes/logconfig.md
@ -108,3 +111,4 @@ nav:
      - 本地开发: developer-guide/development.md
      - 代码规范: developer-guide/code/coding-guide.md
      - 组件开发: developer-guide/component/component-guide.md
+      - 版本发布流程: developer-guide/release.md