Docs updates (#779)

* Update rename plugin docs

* Update pipeline docs

* Update docs sidebar

_sidebar.idoc.md

@@ -20,8 +20,11 @@
 @global-contents-table-plugin-output|links-list
 
 - **Pipeline**
-  - [Match modes](pipeline/README.md#match-modes)
-  - [Experimental: Do If rules](pipeline/doif/README.md#experimental-do-if-rules)
+  - [About](/pipeline/README.md)
+  - [Settings](/pipeline/README.md#settings)
+  - [Datetime parse formats](/pipeline/README.md#datetime-parse-formats)
+  - [Match modes](/pipeline/README.md#match-modes)
+  - [Experimental: Do If rules](/pipeline/doif/README.md#experimental-do-if-rules)
 
 - **Other**
   - [Contributing](/docs/contributing.md)

_sidebar.md

@@ -63,8 +63,11 @@
 
 
 - **Pipeline**
-  - [Match modes](pipeline/README.md#match-modes)
-  - [Experimental: Do If rules](pipeline/doif/README.md#experimental-do-if-rules)
+  - [About](/pipeline/README.md)
+  - [Settings](/pipeline/README.md#settings)
+  - [Datetime parse formats](/pipeline/README.md#datetime-parse-formats)
+  - [Match modes](/pipeline/README.md#match-modes)
+  - [Experimental: Do If rules](/pipeline/doif/README.md#experimental-do-if-rules)
 
 - **Other**
   - [Contributing](/docs/contributing.md)

pipeline/README.idoc.md

@@ -118,7 +118,7 @@ Type of `EventPool`. `std` pool is an original pool with the slice of `Event` po
 
 ## Datetime parse formats
 
-Most of the plugins which work with parsing datetime call `pipeline.ParseTime` function. It accepts datetime layouts the same way as Go `time.Parse` (in format of datetime like `2006-01-02T15:04:05.999999999Z07:00`) except unix timestamp formats, they can only be specified via aliases.
+Most of the plugins which work with parsing datetime call `pipeline.ParseTime` function. It accepts datetime layouts the same way as Go [time.Parse](https://pkg.go.dev/time#Parse) (in format of datetime like `2006-01-02T15:04:05.999999999Z07:00`) except unix timestamp formats, they can only be specified via aliases.
 
 For the comfort of use there are aliases to some datetime formats:
 

pipeline/README.md

@@ -118,7 +118,7 @@ Type of `EventPool`. `std` pool is an original pool with the slice of `Event` po
 
 ## Datetime parse formats
 
-Most of the plugins which work with parsing datetime call `pipeline.ParseTime` function. It accepts datetime layouts the same way as Go `time.Parse` (in format of datetime like `2006-01-02T15:04:05.999999999Z07:00`) except unix timestamp formats, they can only be specified via aliases.
+Most of the plugins which work with parsing datetime call `pipeline.ParseTime` function. It accepts datetime layouts the same way as Go [time.Parse](https://pkg.go.dev/time#Parse) (in format of datetime like `2006-01-02T15:04:05.999999999Z07:00`) except unix timestamp formats, they can only be specified via aliases.
 
 For the comfort of use there are aliases to some datetime formats:
 

plugin/README.md

@@ -531,7 +531,12 @@ It renames the fields of the event. You can provide an unlimited number of confi
 When `override` is set to `false`, the field won't be renamed in the case of field name collision.
 Sequence of rename operations isn't guaranteed. Use different actions for prioritization.
 
-**Example:**
+**Note**: if the renamed field name starts with underscore "_", it should be escaped with preceding underscore. E.g.
+if the renamed field is "_HOSTNAME", in config it should be "___HOSTNAME". Only one preceding underscore is needed.
+Renamed field names with only one underscore in config are considered as without preceding underscore:
+if there is "_HOSTNAME" in config the plugin searches for "HOSTNAME" field.
+
+**Example common:**
 ```yaml
 pipelines:
   example_pipeline:
@@ -543,14 +548,59 @@ pipelines:
     ...
 ```
 
-The resulting event could look like:
-```yaml
+Input event:
+
+```
 {
   "my_object": {
     "field": {
-      "new_sub_field":"value"
+      "subfield":"value"
     }
-  },
+  }
+}
+```
+
+Output event:
+
+```
+{
+  "my_object": {
+    "field": {
+      "new_sub_field":"value"  # renamed
+    }
+  }
+}
+```
+
+**Example journalctl:**
+```yaml
+pipelines:
+  example_pipeline:
+    ...
+    actions:
+    - type: rename
+      override: false
+      __HOSTNAME: host
+      ___REALTIME_TIMESTAMP: ts
+    ...
+```
+
+Input event:
+
+```
+{
+  "_HOSTNAME": "example-host",
+  "__REALTIME_TIMESTAMP": "1739797379239590"
+}
+```
+
+Output event:
+
+```
+{
+  "host": "example-host",   # renamed
+  "ts": "1739797379239590"  # renamed
+}
 ```
 
 [More details...](plugin/action/rename/README.md)

plugin/action/README.md

@@ -374,7 +374,12 @@ It renames the fields of the event. You can provide an unlimited number of confi
 When `override` is set to `false`, the field won't be renamed in the case of field name collision.
 Sequence of rename operations isn't guaranteed. Use different actions for prioritization.
 
-**Example:**
+**Note**: if the renamed field name starts with underscore "_", it should be escaped with preceding underscore. E.g.
+if the renamed field is "_HOSTNAME", in config it should be "___HOSTNAME". Only one preceding underscore is needed.
+Renamed field names with only one underscore in config are considered as without preceding underscore:
+if there is "_HOSTNAME" in config the plugin searches for "HOSTNAME" field.
+
+**Example common:**
 ```yaml
 pipelines:
   example_pipeline:
@@ -386,14 +391,59 @@ pipelines:
     ...
 ```
 
-The resulting event could look like:
-```yaml
+Input event:
+
+```
 {
   "my_object": {
     "field": {
-      "new_sub_field":"value"
+      "subfield":"value"
     }
-  },
+  }
+}
+```
+
+Output event:
+
+```
+{
+  "my_object": {
+    "field": {
+      "new_sub_field":"value"  # renamed
+    }
+  }
+}
+```
+
+**Example journalctl:**
+```yaml
+pipelines:
+  example_pipeline:
+    ...
+    actions:
+    - type: rename
+      override: false
+      __HOSTNAME: host
+      ___REALTIME_TIMESTAMP: ts
+    ...
+```
+
+Input event:
+
+```
+{
+  "_HOSTNAME": "example-host",
+  "__REALTIME_TIMESTAMP": "1739797379239590"
+}
+```
+
+Output event:
+
+```
+{
+  "host": "example-host",   # renamed
+  "ts": "1739797379239590"  # renamed
+}
 ```
 
 [More details...](plugin/action/rename/README.md)

plugin/action/rename/README.md

@@ -3,7 +3,12 @@ It renames the fields of the event. You can provide an unlimited number of confi
 When `override` is set to `false`, the field won't be renamed in the case of field name collision.
 Sequence of rename operations isn't guaranteed. Use different actions for prioritization.
 
-**Example:**
+**Note**: if the renamed field name starts with underscore "_", it should be escaped with preceding underscore. E.g.
+if the renamed field is "_HOSTNAME", in config it should be "___HOSTNAME". Only one preceding underscore is needed.
+Renamed field names with only one underscore in config are considered as without preceding underscore:
+if there is "_HOSTNAME" in config the plugin searches for "HOSTNAME" field.
+
+**Example common:**
 ```yaml
 pipelines:
   example_pipeline:
@@ -15,14 +20,59 @@ pipelines:
     ...
 ```
 
-The resulting event could look like:
-```yaml
+Input event:
+
+```
+{
+  "my_object": {
+    "field": {
+      "subfield":"value"
+    }
+  }
+}
+```
+
+Output event:
+
+```
 {
   "my_object": {
     "field": {
-      "new_sub_field":"value"
+      "new_sub_field":"value"  # renamed
     }
-  },
+  }
+}
+```
+
+**Example journalctl:**
+```yaml
+pipelines:
+  example_pipeline:
+    ...
+    actions:
+    - type: rename
+      override: false
+      __HOSTNAME: host
+      ___REALTIME_TIMESTAMP: ts
+    ...
+```
+
+Input event:
+
+```
+{
+  "_HOSTNAME": "example-host",
+  "__REALTIME_TIMESTAMP": "1739797379239590"
+}
+```
+
+Output event:
+
+```
+{
+  "host": "example-host",   # renamed
+  "ts": "1739797379239590"  # renamed
+}
 ```
 
 <br>*Generated using [__insane-doc__](https://github.com/vitkovskii/insane-doc)*

plugin/action/rename/rename.go

@@ -11,7 +11,12 @@ It renames the fields of the event. You can provide an unlimited number of confi
 When `override` is set to `false`, the field won't be renamed in the case of field name collision.
 Sequence of rename operations isn't guaranteed. Use different actions for prioritization.
 
-**Example:**
+**Note**: if the renamed field name starts with underscore "_", it should be escaped with preceding underscore. E.g.
+if the renamed field is "_HOSTNAME", in config it should be "___HOSTNAME". Only one preceding underscore is needed.
+Renamed field names with only one underscore in config are considered as without preceding underscore:
+if there is "_HOSTNAME" in config the plugin searches for "HOSTNAME" field.
+
+**Example common:**
 ```yaml
 pipelines:
   example_pipeline:
@@ -23,14 +28,59 @@ pipelines:
     ...
 ```
 
-The resulting event could look like:
-```yaml
+Input event:
+
+```
+{
+  "my_object": {
+    "field": {
+      "subfield":"value"
+    }
+  }
+}
+```
+
+Output event:
+
+```
 {
   "my_object": {
     "field": {
-      "new_sub_field":"value"
+      "new_sub_field":"value"  # renamed
     }
-  },
+  }
+}
+```
+
+**Example journalctl:**
+```yaml
+pipelines:
+  example_pipeline:
+    ...
+    actions:
+    - type: rename
+      override: false
+      __HOSTNAME: host
+      ___REALTIME_TIMESTAMP: ts
+    ...
+```
+
+Input event:
+
+```
+{
+  "_HOSTNAME": "example-host",
+  "__REALTIME_TIMESTAMP": "1739797379239590"
+}
+```
+
+Output event:
+
+```
+{
+  "host": "example-host",   # renamed
+  "ts": "1739797379239590"  # renamed
+}
 ```
 }*/