Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Process: replace constraints with requirement levels and note #863

Merged
merged 4 commits into from
Apr 9, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .chloggen/863.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
change_type: enhancement
component: process
note: Replace constraints with requirement_level in process attributes.
issues: [ 863 ]
33 changes: 21 additions & 12 deletions docs/resource/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
<!-- toc -->

- [Process](#process)
- [Selecting process attributes](#selecting-process-attributes)
- [Process runtimes](#process-runtimes)
- [Erlang Runtimes](#erlang-runtimes)
- [Go Runtimes](#go-runtimes)
Expand All @@ -27,32 +28,40 @@
<!-- semconv process -->
| 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.
<!-- endsemconv -->

### 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)
<!-- endsemconv -->

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,
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
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`
Expand Down Expand Up @@ -94,7 +103,7 @@ Go Runtimes SHOULD fill in the as follows:

```go
import "runtime"

func getRuntimeName() string {
if runtime.Compiler == "gc" {
return "go"
Expand Down
17 changes: 5 additions & 12 deletions model/resource/process.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading