Document feature in journald user-level filtering (#13713)

* Document feature in #11398 * Apply suggestions from code review Co-authored-by: Kari Halsted <[email protected]> * Update example config * Apply suggestions from code review Co-authored-by: Ursula Chen <[email protected]> Co-authored-by: Kari Halsted <[email protected]> Co-authored-by: Ursula Chen <[email protected]>
DataDog · Jan 19, 2023 · 61abb5e · 61abb5e
1 parent b51104b
commit 61abb5e
Show file tree

Hide file tree

Showing 3 changed files with 133 additions and 9 deletions.
diff --git 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
@@ -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:
+            - '*'
diff --git 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:
+    #   - '*'