From 82b2fb2b87b8c90d31dadeac18c3b21ee0c2b7e3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 9 Apr 2024 09:25:52 -0700 Subject: [PATCH] Process: replace constraints with requirement levels and note (#863) --- .chloggen/863.yaml | 4 ++++ docs/resource/process.md | 33 +++++++++++++++++++++------------ model/resource/process.yaml | 17 +++++------------ 3 files changed, 30 insertions(+), 24 deletions(-) create mode 100644 .chloggen/863.yaml diff --git a/.chloggen/863.yaml b/.chloggen/863.yaml new file mode 100644 index 0000000000..6dc53c5dcf --- /dev/null +++ b/.chloggen/863.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: process +note: Replace constraints with requirement_level in process attributes. +issues: [ 863 ] diff --git a/docs/resource/process.md b/docs/resource/process.md index aa9ccea63f..8b5c5f9619 100644 --- a/docs/resource/process.md +++ b/docs/resource/process.md @@ -7,6 +7,7 @@ - [Process](#process) + - [Selecting process attributes](#selecting-process-attributes) - [Process runtimes](#process-runtimes) - [Erlang Runtimes](#erlang-runtimes) - [Go Runtimes](#go-runtimes) @@ -27,32 +28,40 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`process.command`](../attributes-registry/process.md) | 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` | `Conditionally Required` See alternative attributes below. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.command_args`](../attributes-registry/process.md) | 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]` | `Conditionally Required` See alternative attributes below. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.command_line`](../attributes-registry/process.md) | 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"` | `Conditionally Required` See alternative attributes below. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.executable.name`](../attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Conditionally Required` See alternative attributes below. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`process.executable.path`](../attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Conditionally Required` See alternative attributes below. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.command`](../attributes-registry/process.md) | 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` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.command_args`](../attributes-registry/process.md) | 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]` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.command_line`](../attributes-registry/process.md) | 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"` | `Conditionally Required` [3] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.name`](../attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Conditionally Required` [4] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`process.executable.path`](../attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Conditionally Required` [5] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.owner`](../attributes-registry/process.md) | string | The username of the user that owns the process. | `root` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.parent_pid`](../attributes-registry/process.md) | int | Parent Process identifier (PPID). | `111` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`process.pid`](../attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**Additional attribute requirements:** At least one of the following sets of attributes is required: +**[1]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[2]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[3]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[4]:** See [Selecting process attributes](#selecting-process-attributes) for details. + +**[5]:** See [Selecting process attributes](#selecting-process-attributes) for details. + + +### Selecting process attributes + +At least one of the following attributes is required: * [`process.executable.name`](../attributes-registry/process.md) * [`process.executable.path`](../attributes-registry/process.md) * [`process.command`](../attributes-registry/process.md) * [`process.command_line`](../attributes-registry/process.md) * [`process.command_args`](../attributes-registry/process.md) - Between `process.command_args` and `process.command_line`, usually `process.command_args` should be preferred. On Windows and other systems where the native format of process commands is a single string, `process.command_line` can additionally (or instead) be used. -For backwards compatibility with older versions of this semantic convention, -it is possible but deprecated to use an array as type for `process.command_line`. -In that case it MUST be interpreted as if it was `process.command_args`. - ## Process runtimes **type:** `process.runtime` @@ -94,7 +103,7 @@ Go Runtimes SHOULD fill in the as follows: ```go import "runtime" - + func getRuntimeName() string { if runtime.Compiler == "gc" { return "go" diff --git a/model/resource/process.yaml b/model/resource/process.yaml index 61223d61ce..36becc7606 100644 --- a/model/resource/process.yaml +++ b/model/resource/process.yaml @@ -9,27 +9,20 @@ groups: - ref: process.parent_pid - ref: process.executable.name requirement_level: - conditionally_required: See alternative attributes below. + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.executable.path requirement_level: - conditionally_required: See alternative attributes below. + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.command requirement_level: - conditionally_required: See alternative attributes below. + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.command_line requirement_level: - conditionally_required: See alternative attributes below. + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.command_args requirement_level: - conditionally_required: See alternative attributes below. + conditionally_required: See [Selecting process attributes](#selecting-process-attributes) for details. - ref: process.owner - constraints: - - any_of: - - process.executable.name - - process.executable.path - - process.command - - process.command_line - - process.command_args - id: process.runtime prefix: process.runtime