From 61abb5e22c4b975dcba53b10c2ec961190213b8e Mon Sep 17 00:00:00 2001
From: Ian Bucad <ian.bucad@datadoghq.com>
Date: Fri, 20 Jan 2023 08:24:26 +1100
Subject: [PATCH] Document feature in journald user-level filtering (#13713)

* Document feature in #11398

* Apply suggestions from code review

Co-authored-by: Kari Halsted <12926135+kayayarai@users.noreply.github.com>

* Update example config

* Apply suggestions from code review

Co-authored-by: Ursula Chen <58821586+urseberry@users.noreply.github.com>

Co-authored-by: Kari Halsted <12926135+kayayarai@users.noreply.github.com>
Co-authored-by: Ursula Chen <58821586+urseberry@users.noreply.github.com>
---
 journald/README.md                            | 24 ++++++-
 journald/assets/configuration/spec.yaml       | 69 ++++++++++++++++++-
 .../journald/data/conf.yaml.example           | 49 ++++++++++++-
 3 files changed, 133 insertions(+), 9 deletions(-)

diff --git a/journald/README.md b/journald/README.md
index b70121aa70667..98c27d21d789c 100644
--- a/journald/README.md
+++ b/journald/README.md
@@ -83,10 +83,11 @@ If your journal is located elsewhere, add a `path` parameter with the correspond
 
 ##### Filter journal units
 
-It's possible to filter in and out specific units by using these parameters:
+You can filter specific _system-level_ units by using these parameters:
+
+- `include_units`: Includes all system-level units specified.
+- `exclude_units`: Excludes all system-level units specified.
 
-- `include_units`: Includes all units specified.
-- `exclude_units`: Excludes all units specified.
 
 Example:
 
@@ -99,6 +100,23 @@ logs:
           - sshd.service
 ```
 
+In Datadog Agent version `7.37.0`+, you can filter _user-level_ units by using these parameters:
+
+- `include_user_units`: Includes all user-level units specified.
+- `exclude_user_units`: Excludes all user-level units specified.
+
+**Note**: Use the `*` wildcard in `exclude_units` or `exclude_user_units` to specify a particular Journald log.
+
+Example:
+
+```yaml
+logs:
+    # Collect all system-level unit logs.
+    - type: journald
+      exclude_user_units:
+          - '*'
+```
+
 ##### Tailing the same journal multiple times
 
 If you want to report units with different source or service tags, these must appear in separate journald configs.
diff --git a/journald/assets/configuration/spec.yaml b/journald/assets/configuration/spec.yaml
index 17003ff233d6b..62cd78da93790 100644
--- a/journald/assets/configuration/spec.yaml
+++ b/journald/assets/configuration/spec.yaml
@@ -3,6 +3,69 @@ files:
 - name: journald.yaml
   options:
   - template: logs
-    example:
-    - type: journald
-      container_mode: true
+    enabled: true
+    multiple: true
+    options:
+      - name: type
+        description: ''
+        required: true
+        enabled: true
+        value:
+          type: string
+          example: journald
+          display_default: journald
+      - name: container_mode
+        description: |
+          Automatically sets the source attribute to the corresponding short image
+            name of the container for logs coming from Docker containers.
+
+          Available from Datadog Agent 7.17.0 and above.
+        value:
+          type: boolean
+          display_default: false
+          example: true
+      - name: include_units
+        description: |
+          List of system-level service units to include from log collection.
+        value:
+          type: array
+          items:
+            type: string
+          example:
+            - docker.service
+            - sshd.service
+      - name: exclude_units
+        description: |
+          List of system-level service units to exclude from log collection.
+          Note: The excluded units will take precedence over include_units.
+
+          From Datadog Agent 7.37.0+, a wildcard can be used to exclude all
+            system-level unit logs, thereby collecting only user-level unit logs.
+        value:
+          type: array
+          items:
+            type: string
+          example:
+            - '*'
+      - name: include_user_units
+        description: |
+          List of user-level service units to include from log collection.
+        value:
+          type: array
+          items:
+            type: string
+          example:
+            - linger-example.service
+      - name: exclude_user_units
+        description: |
+          List of user-level service units to exclude from log collection.
+          Note: The excluded units will take precedence over include_user_units.
+
+          From Datadog Agent 7.37.0+, a wildcard can be used to exclude all
+            user-level unit logs, thereby collecting only system-level unit logs.
+        value:
+          type: array
+          items:
+            type: string
+          example:
+            - '*'
\ No newline at end of file
diff --git a/journald/datadog_checks/journald/data/conf.yaml.example b/journald/datadog_checks/journald/data/conf.yaml.example
index f26ee9015029c..8b56d79c428e9 100644
--- a/journald/datadog_checks/journald/data/conf.yaml.example
+++ b/journald/datadog_checks/journald/data/conf.yaml.example
@@ -13,6 +13,49 @@
 ##
 ## Discover Datadog log collection: https://docs.datadoghq.com/logs/log_collection/
 #
-# logs:
-#   - type: journald
-#     container_mode: true
+logs:
+
+    ## @param type - string - required
+    #
+  - type: journald
+
+    ## @param container_mode - boolean - optional - default: false
+    ## Automatically sets the source attribute to the corresponding short image
+    ##   name of the container for logs coming from Docker containers.
+    ##
+    ## Available from Datadog Agent 7.17.0 and above.
+    #
+    # container_mode: true
+
+    ## @param include_units - list of strings - optional
+    ## List of system-level service units to include from log collection.
+    #
+    # include_units:
+    #   - docker.service
+    #   - sshd.service
+
+    ## @param exclude_units - list of strings - optional
+    ## List of system-level service units to exclude from log collection.
+    ## Note: The excluded units will take precedence over include_units.
+    ##
+    ## From Datadog Agent 7.37.0+, a wildcard can be used to exclude all
+    ##   system-level unit logs, thereby collecting only user-level unit logs.
+    #
+    # exclude_units:
+    #   - '*'
+
+    ## @param include_user_units - list of strings - optional
+    ## List of user-level service units to include from log collection.
+    #
+    # include_user_units:
+    #   - linger-example.service
+
+    ## @param exclude_user_units - list of strings - optional
+    ## List of user-level service units to exclude from log collection.
+    ## Note: The excluded units will take precedence over include_user_units.
+    ##
+    ## From Datadog Agent 7.37.0+, a wildcard can be used to exclude all
+    ##   user-level unit logs, thereby collecting only system-level unit logs.
+    #
+    # exclude_user_units:
+    #   - '*'