Add remaining ECS attributes for file namespace (#914)

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
open-telemetry · Sep 23, 2024 · b780f48 · b780f48
1 parent ee435c0
commit b780f48
Show file tree

Hide file tree

Showing 3 changed files with 157 additions and 9 deletions.
diff --git a/.chloggen/file_leftovers.yaml b/.chloggen/file_leftovers.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: file
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add additional attributes from ECS to the `file` namespace.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [914]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
diff --git a/docs/attributes-registry/file.md b/docs/attributes-registry/file.md
@@ -10,12 +10,38 @@
 
 Describes file attributes.
 
-| Attribute        | Type   | Description                                                                                           | Examples                                                      | Stability                                                        |
-| ---------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `file.directory` | string | Directory where the file is located. It should include the drive letter, when appropriate.            | `/home/user`; `C:\Program Files\MyApp`                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `file.extension` | string | File extension, excluding the leading dot. [1]                                                        | `png`; `gz`                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `file.name`      | string | Name of the file including the extension, without the directory.                                      | `example.png`                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `file.path`      | string | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `file.size`      | int    | File size in bytes.                                                                                   |                                                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-
-**[1]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz").
+| Attribute                        | Type     | Description                                                                                           | Examples                                                      | Stability                                                        |
+| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `file.accessed`                  | string   | Time when the file was last accessed, in ISO 8601 format. [1]                                         | `2021-01-01T12:00:00Z`                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.attributes`                | string[] | Array of file attributes. [2]                                                                         | `["readonly", "hidden"]`                                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.changed`                   | string   | Time when the file attributes or metadata was last changed, in ISO 8601 format. [3]                   | `2021-01-01T12:00:00Z`                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.created`                   | string   | Time when the file was created, in ISO 8601 format. [4]                                               | `2021-01-01T12:00:00Z`                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.directory`                 | string   | Directory where the file is located. It should include the drive letter, when appropriate.            | `/home/user`; `C:\Program Files\MyApp`                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.extension`                 | string   | File extension, excluding the leading dot. [5]                                                        | `png`; `gz`                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.fork_name`                 | string   | Name of the fork. A fork is additional data associated with a filesystem object. [6]                  | `Zone.Identifer`                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.group.id`                  | string   | Primary Group ID (GID) of the file.                                                                   | `1000`                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.group.name`                | string   | Primary group name of the file.                                                                       | `users`                                                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.inode`                     | string   | Inode representing the file in the filesystem.                                                        | `256383`                                                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.mode`                      | string   | Mode of the file in octal representation.                                                             | `0640`                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.modified`                  | string   | Time when the file content was last modified, in ISO 8601 format.                                     | `2021-01-01T12:00:00Z`                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.name`                      | string   | Name of the file including the extension, without the directory.                                      | `example.png`                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.owner.id`                  | string   | The user ID (UID) or security identifier (SID) of the file owner.                                     | `1000`                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.owner.name`                | string   | Username of the file owner.                                                                           | `root`                                                        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.path`                      | string   | Full path to the file, including the file name. It should include the drive letter, when appropriate. | `/home/alice/example.png`; `C:\Program Files\MyApp\myapp.exe` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.size`                      | int      | File size in bytes.                                                                                   |                                                               | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `file.symbolic_link.target_path` | string   | Path to the target of a symbolic link. [7]                                                            | `/usr/bin/python3`                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+
+**[2]:** Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`.
+
+**[3]:** `file.changed` captures the time when any of the file's properties or attributes (including the content) are changed, while `file.modified` captures the timestamp when the file content is modified.
+
+**[4]:** This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+
+**[5]:** When the file name has multiple extensions (example.tar.gz), only the last one should be captured ("gz", not "tar.gz").
+
+**[6]:** On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at least one fork for the data portion, and additional forks may exist.
+On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name.
+
+**[7]:** This attribute is only applicable to symbolic links.
diff --git a/model/file/registry.yaml b/model/file/registry.yaml
@@ -4,6 +4,41 @@ groups:
     display_name: File Attributes
     brief: "Describes file attributes."
     attributes:
+      - id: file.accessed
+        type: string
+        brief: >
+          Time when the file was last accessed, in ISO 8601 format.
+        note: >
+          This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+        stability: experimental
+        examples: ['2021-01-01T12:00:00Z']
+      - id: file.attributes
+        type: string[]
+        brief: >
+          Array of file attributes.
+        note: >
+          Attributes names depend on the OS or file system. Here’s a non-exhaustive list of values expected for this
+          attribute: `archive`, `compressed`, `directory`, `encrypted`, `execute`, `hidden`, `immutable`, `journaled`, `read`, `readonly`, `symbolic link`, `system`, `temporary`, `write`.
+        stability: experimental
+        examples: ['readonly', 'hidden']
+      - id: file.created
+        type: string
+        brief: >
+          Time when the file was created, in ISO 8601 format.
+        note: >
+          This attribute might not be supported by some file systems — NFS, FAT32, in embedded OS, etc.
+        stability: experimental
+        examples: ['2021-01-01T12:00:00Z']
+      - id: file.changed
+        type: string
+        brief: >
+          Time when the file attributes or metadata was last changed, in ISO 8601 format.
+        note: >
+          `file.changed` captures the time when any of the file's properties or attributes
+          (including the content) are changed, while `file.modified` captures the timestamp
+          when the file content is modified.
+        stability: experimental
+        examples: ['2021-01-01T12:00:00Z']
       - id: file.directory
         type: string
         brief: >
@@ -19,12 +54,69 @@ groups:
         note: >
           When the file name has multiple extensions (example.tar.gz), only the last one should
           be captured ("gz", not "tar.gz").
+      - id: file.fork_name
+        type: string
+        brief: >
+          Name of the fork. A fork is additional data associated with a filesystem object.
+        note: >
+          On Linux, a resource fork is used to store additional data with a filesystem object. A file always has at
+          least one fork for the data portion, and additional forks may exist.
+
+          On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is
+          just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet.
+          An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the
+          value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension`
+          should populate `file.extension`. The full path, `file.path`, will include the fork name.
+        stability: experimental
+        examples: ['Zone.Identifer']
+      - id: file.group.id
+        type: string
+        brief: >
+          Primary Group ID (GID) of the file.
+        stability: experimental
+        examples: ["1000"]
+      - id: file.group.name
+        type: string
+        brief: >
+          Primary group name of the file.
+        stability: experimental
+        examples: ['users']
+      - id: file.inode
+        type: string
+        brief: >
+          Inode representing the file in the filesystem.
+        stability: experimental
+        examples: ['256383']
+      - id: file.mode
+        type: string
+        brief: >
+          Mode of the file in octal representation.
+        stability: experimental
+        examples: ['0640']
+      - id: file.modified
+        type: string
+        brief: >
+          Time when the file content was last modified, in ISO 8601 format.
+        stability: experimental
+        examples: ['2021-01-01T12:00:00Z']
       - id: file.name
         type: string
         brief: >
           Name of the file including the extension, without the directory.
         stability: experimental
         examples: ['example.png']
+      - id: file.owner.id
+        type: string
+        brief: >
+          The user ID (UID) or security identifier (SID) of the file owner.
+        stability: experimental
+        examples: ["1000"]
+      - id: file.owner.name
+        type: string
+        brief: >
+          Username of the file owner.
+        stability: experimental
+        examples: ['root']
       - id: file.path
         type: string
         brief: >
@@ -36,3 +128,11 @@ groups:
         brief: >
           File size in bytes.
         stability: experimental
+      - id: file.symbolic_link.target_path
+        type: string
+        brief: >
+          Path to the target of a symbolic link.
+        note: >
+          This attribute is only applicable to symbolic links.
+        stability: experimental
+        examples: ['/usr/bin/python3']