Add additional process fields from ECS (#993)

Co-authored-by: Alexandra Konrad <[email protected]> Co-authored-by: Alexandra Konrad <[email protected]> Co-authored-by: Liudmila Molkova <[email protected]>
open-telemetry · Aug 3, 2024 · 18b3555 · 18b3555
1 parent e9c09e8
commit 18b3555
Show file tree

Hide file tree

Showing 5 changed files with 90 additions and 2 deletions.
diff --git a/.chloggen/993.yaml b/.chloggen/993.yaml
@@ -0,0 +1,4 @@
+change_type: enhancement
+component: process
+note: Add additional process fields from ECS
+issues: [993]
diff --git a/docs/attributes-registry/process.md b/docs/attributes-registry/process.md
@@ -15,6 +15,7 @@ An operating system process.
 
 | Attribute                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                 | Examples                                            | Stability                                                        |
 | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- |
+| `args_count`                  | int      | Length of the process.command_args array [1]                                                                                                                                                                                                                                                                                                                | `4`                                                 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.command`             | string   | The command used to launch the process (i.e. the command name). On Linux based systems, can be set to the zeroth string in `proc/[pid]/cmdline`. On Windows, can be set to the first parameter extracted from `GetCommandLineW`.                                                                                                                            | `cmd/otelcol`                                       | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.command_args`        | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]`            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.command_line`        | string   | The full command used to launch the process as a single string representing the full command. On Windows, can be set to the result of `GetCommandLineW`. Do not set this if you have to assemble it just for monitoring; use `process.command_args` instead.                                                                                                | `C:\cmd\otecol --config="my directory\config.yaml"` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -40,9 +41,15 @@ An operating system process.
 | `process.session_leader.pid`  | int      | The PID of the process's session leader. This is also the session ID (SID) of the process.                                                                                                                                                                                                                                                                  | `14`                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.user.id`             | int      | The effective user ID (EUID) of the process.                                                                                                                                                                                                                                                                                                                | `1001`                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `process.user.name`           | string   | The username of the effective user of the process.                                                                                                                                                                                                                                                                                                          | `root`                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `process.vpid`                | int      | Virtual process identifier. [1]                                                                                                                                                                                                                                                                                                                             | `12`                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `process.vpid`                | int      | Virtual process identifier. [2]                                                                                                                                                                                                                                                                                                                             | `12`                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `title`                       | string   | Process title (proctitle) [3]                                                                                                                                                                                                                                                                                                                               | `cat /etc/hostname`; `xfce4-session`; `bash`        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `working_directory`           | string   | The working directory of the process.                                                                                                                                                                                                                                                                                                                       | `/root`                                             | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-**[1]:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within.
+**[1]:** This field can be useful for querying or performing bucket analysis on how many arguments were provided to start a process. More arguments may be an indication of suspicious activity.
+
+**[2]:** The process ID within a PID namespace. This is not necessarily unique across all processes on the host but it is unique within the process namespace that the process exists within.
+
+**[3]:** In many Unix-like systems, process title (proctitle), is the string that represents the name or command line of a running process, displayed by system monitoring tools like ps, top, and htop.
 
 `process.context_switch_type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 

diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
@@ -30,6 +30,7 @@ metrics](/docs/runtime/README.md#metrics).
   - [Metric: `process.open_file_descriptor.count`](#metric-processopen_file_descriptorcount)
   - [Metric: `process.context_switches`](#metric-processcontext_switches)
   - [Metric: `process.paging.faults`](#metric-processpagingfaults)
+  - [Metric: `process.uptime`](#metric-processuptime)
 
 <!-- tocstop -->
 
@@ -472,6 +473,44 @@ This metric is [recommended][MetricRecommended].
 
 
 
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `process.uptime`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.process.uptime(metric_table) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `process.uptime` | Counter | `s` | The time the process has been running. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+**[1]:** Instrumentations SHOULD use counter with type `double` and measure uptime with at least millisecond precision
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+<!-- semconv metric.process.uptime(full) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml
@@ -92,6 +92,7 @@ groups:
     unit: "{count}"
     attributes:
       - ref: process.context_switch_type
+
   - id: metric.process.paging.faults
     type: metric
     metric_name: process.paging.faults
@@ -101,3 +102,12 @@ groups:
     unit: "{fault}"
     attributes:
       - ref: process.paging.fault_type
+
+  - id: metric.process.uptime
+    type: metric
+    metric_name: process.uptime
+    stability: experimental
+    brief: "The time the process has been running."
+    instrument: counter
+    unit: "s"
+    note: "Instrumentations SHOULD use counter with type `double` and measure uptime with at least millisecond precision"
diff --git a/model/registry/process.yaml b/model/registry/process.yaml
@@ -84,6 +84,18 @@ groups:
           null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based
           executables, this would be the full argv vector passed to `main`.
         examples: ['cmd/otecol', '--config=config.yaml']
+      - id: args_count
+        type: int
+        stability: experimental
+        brief: >
+          Length of the process.command_args array
+        note: >
+          This field can be useful for querying or performing bucket analysis on how many
+          arguments were provided to start a process. More arguments may be an indication
+          of suspicious activity.
+        requirement_level:
+          recommended: if `process.command_args` is populated.
+        examples: [4]
       - id: process.owner
         type: string
         stability: experimental
@@ -146,6 +158,16 @@ groups:
           An additional description about the runtime of the process, for example
           a specific vendor customization of the runtime environment.
         examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0'
+      - id: title
+        type: string
+        stability: experimental
+        brief: >
+          Process title (proctitle)
+        note: >
+          In many Unix-like systems, process title (proctitle), is the string
+          that represents the name or command line of a running process,
+          displayed by system monitoring tools like ps, top, and htop.
+        examples: ["cat /etc/hostname", "xfce4-session", "bash"]
       - id: process.creation.time
         type: string
         stability: experimental
@@ -169,6 +191,12 @@ groups:
         stability: experimental
         brief: >
           Whether the process is connected to an interactive shell.
+      - id: working_directory
+        type: string
+        stability: experimental
+        brief: >
+          The working directory of the process.
+        examples: ["/root"]
       - id: process.context_switch_type
         brief: "Specifies whether the context switches for this data point were voluntary or involuntary."
         type: