From a68c4d0fe99a98a98b3cd26c9dbc9c0c07a10506 Mon Sep 17 00:00:00 2001
From: ethfoo <ethfoo@163.com>
Date: Sun, 24 Apr 2022 17:07:18 +0800
Subject: [PATCH] Feat log context (#48)

* Feat: update log-format to log-enrich
---
 docs/reference/pipelines/source/file.md       |  9 +++
 docs/user-guide/architecture/schema.md        |  2 +-
 .../{log-format.md => log-enrich.md}          | 58 ++++++++++++++++---
 docs/user-guide/index.md                      |  2 +-
 nav.yml                                       |  4 +-
 5 files changed, 63 insertions(+), 12 deletions(-)
 rename docs/user-guide/best-practice/{log-format.md => log-enrich.md} (72%)

diff --git a/docs/reference/pipelines/source/file.md b/docs/reference/pipelines/source/file.md
index 0e1d2e2..111affb 100644
--- a/docs/reference/pipelines/source/file.md
+++ b/docs/reference/pipelines/source/file.md
@@ -77,6 +77,15 @@ file source用于日志采集。
     }
     ```
 
+state含义解释：
+- pipeline: 所在的pipeline名称
+- source: 所在的source名称
+- filename: 采集的文件名称
+- timestamp: 采集时刻的时间戳
+- offset: 采集的数据在文件的offset偏移量
+- bytes: 采集的数据字节数
+- hostname: 所在节点名称
+
 ## workerCount
 
 | `字段`      | `类型` | `是否必填` | `默认值` | `含义`                                                       |
diff --git a/docs/user-guide/architecture/schema.md b/docs/user-guide/architecture/schema.md
index 3875388..e7e93f1 100644
--- a/docs/user-guide/architecture/schema.md
+++ b/docs/user-guide/architecture/schema.md
@@ -15,7 +15,7 @@
 ## 格式转换
 如果以上的格式不满足需求，可以参考：
 
-- [日志格式转换](../best-practice/log-format.md)
+- [日志元信息](../best-practice/log-enrich.md)
 
 ## 日志切分
 对于原始日志数据的切分与处理，请使用 **normalize interceptor**，请参考：
diff --git a/docs/user-guide/best-practice/log-format.md b/docs/user-guide/best-practice/log-enrich.md
similarity index 72%
rename from docs/user-guide/best-practice/log-format.md
rename to docs/user-guide/best-practice/log-enrich.md
index a003c1d..c85fac6 100644
--- a/docs/user-guide/best-practice/log-format.md
+++ b/docs/user-guide/best-practice/log-enrich.md
@@ -1,14 +1,12 @@
-# 日志格式转换
+# 日志增加加元信息
 
 > 建议先了解Loggie内部日志数据[schema设计](../architecture/schema.md)。  
 
 
-日志格式转换，主要是对Loggie内置的一些字段进行处理和转换，一般会依赖[日志切分处理](log-process.md)。
-
 ## 需求场景
-Loggie部署在不同的环境中，如果需要兼容已有的格式，可以参考如下的办法。
+Loggie部署在不同的环境中，如果需要在原始的日志数据里，增加一些元信息，同时兼容已有的格式，可以参考如下的办法。
 
-### 示例1: 发送原始数据
+### 场景1: 发送原始数据
 正常情况，Loggie仅将原始数据发送给下游。
 
 如果你配置：
@@ -38,7 +36,7 @@ sink输出的数据仅为原始数据：
     }
 ```
 
-### 示例2: 添加fields自定义元信息
+### 场景2: 添加fields自定义元信息
 
 如果我们在source上配置了一些自定义的fields。
 
@@ -88,7 +86,51 @@ sink输出的数据仅为原始数据：
     }
 ```
 
-### 示例3: 添加meta系统内置元信息
+### 场景3: 添加日志采集file source的状态信息
+在我们使用file source时，可能希望自动在日志原始数据里，增加一些日志采集的状态，比如采集的文件名称、采集的文件offsest等，file source提供了一个`addonMeta`配置，可快速enable。
+
+示例：添加如下`addonMeta`，并设置为true。
+
+!!! config "file source"
+
+    ```yaml
+    sources:
+    - type: file
+      paths:
+      - /var/log/*.log
+      addonMeta: true
+    ```
+    
+此时，采集的event会变成类似如下：
+
+!!! example 
+
+    ```json
+    {
+      "body": "this is test",
+      "state": {
+        "pipeline": "local",
+        "source": "demo",
+        "filename": "/var/log/a.log",
+        "timestamp": "2006-01-02T15:04:05.000Z",
+        "offset": 1024,
+        "bytes": 4096,
+        "hostname": "node-1"
+      }
+    }
+    ```
+
+具体字段含义可参考[file source](../../reference/pipelines/source/file.md)
+
+
+### 场景4: 增加Kubernetes元信息
+在Kubernetes的场景中，采集的容器日志，为了在查询的时候，使用namespace/podName等信息进行检索，往往需要增加相关的元数据。
+
+我们可以在系统配置的discovery.kubernetes中，配置fields字段。
+
+可参考[discovery](../../reference/global/discovery.md)。
+
+### 场景5: 添加meta系统内置元信息
 
 有一些Loggie系统内置的元信息，我们也希望发送给下游，这个时候，需要使用normalize interceptor中的addMeta processors。
 
@@ -163,7 +205,7 @@ sink输出的数据仅为原始数据：
     ```
 
 
-### 示例4：beatsFormat快速转换
+### 场景6：beatsFormat快速转换
 
 如果你期望的格式为类似：
 
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
index 43e831e..e7af2fa 100644
--- a/docs/user-guide/index.md
+++ b/docs/user-guide/index.md
@@ -23,7 +23,7 @@ Loggie和其他的开源日志Agent区别是什么？
 请看「[Kubernetes](use-in-kubernetes/general-usage.md)」。  
 
 如何配置各种不同的日志架构？如何接入现有的服务？如何配置日志的处理和切分？Loggie还提供了哪些有用又好用的功能？  
-请看「[最佳实践](best-practice/log-format.md)」。  
+请看「[最佳实践](best-practice/log-enrich.md)」。  
 
 如何配置整体的监控和报警，保证Loggie正常运行？如何监控是否采集到ERROR日志？  
 请看「[监控报警](monitor/loggie-monitor.md)」。  
diff --git a/nav.yml b/nav.yml
index 25f17a0..62e663f 100644
--- a/nav.yml
+++ b/nav.yml
@@ -31,7 +31,7 @@ nav:
         - 采集Kubernetes Events: user-guide/use-in-kubernetes/kube-event-source.md
 
       - 最佳实践:
-        - 日志格式转换: user-guide/best-practice/log-format.md
+        - 日志增加元信息: user-guide/best-practice/log-enrich.md
         - 日志切分处理: user-guide/best-practice/log-process.md
         - 使用Loggie中转机: user-guide/best-practice/aggregator.md
 
@@ -83,7 +83,7 @@ nav:
 
       - Queue:
         - channel: reference/pipelines/queue/channel.md
-        - memeory: reference/pipelines/queue/memory.md
+        - memory: reference/pipelines/queue/memory.md
 
       - Monitor:
         - Overview: reference/monitor/overview.md