diff --git a/.chloggen/993.yaml b/.chloggen/993.yaml new file mode 100755 index 0000000000..a4a55ace39 --- /dev/null +++ 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 index 922286f11d..58e3b1e07e 100644 --- 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 index 54f5a61672..6912ec1a93 100644 --- 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) @@ -472,6 +473,44 @@ This metric is [recommended][MetricRecommended]. + + + + + +### Metric: `process.uptime` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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 + + + + + + + + + + + + + + + + diff --git a/model/metrics/process-metrics.yaml b/model/metrics/process-metrics.yaml index 9b174de0e0..9df5139e51 100644 --- 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 index 596972a3b1..7824d0ffbb 100644 --- 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: