add process.name attribute and adapt process.executable.name #1737
+58
−13
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # 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: process | ||
|
|
||
| # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). | ||
| note: Added new attribute `process.name`, adjusted guidance for `process.executable.name` | ||
|
|
||
| # 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: [1736] | ||
|
|
||
| # (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: | | ||
| The new `process.name` attribute uses the original guidance for `process.executable.name`, | ||
| suggesting use of `/proc/[pid]/comm` or the `Name` field from `/proc/[pid]/status` on Linux. | ||
| `process.executable.name` guidance now suggests using the base name from the `/proc/[pid]/exe` | ||
| symlink's target path. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,12 +25,13 @@ An operating system process. | |
| | <a id="process-executable-build-id-gnu" href="#process-executable-build-id-gnu">`process.executable.build_id.gnu`</a> | string | The GNU build ID as found in the `.note.gnu.build-id` ELF section (hex string). | `c89b11207f6479603b0d49bf291c092c2b719293` |  | | ||
| | <a id="process-executable-build-id-go" href="#process-executable-build-id-go">`process.executable.build_id.go`</a> | string | The Go build ID as retrieved by `go tool buildid <go executable>`. | `foh3mEXu7BLZjsN9pOwG/kATcXlYVCDEFouRMQed_/WwRFB1hPo9LBkekthSPG/x8hMC8emW2cCjXD0_1aY` |  | | ||
| | <a id="process-executable-build-id-htlhash" href="#process-executable-build-id-htlhash">`process.executable.build_id.htlhash`</a> | string | Profiling specific build ID for executables. See the OTel specification for Profiles for more information. | `600DCAFE4A110000F2BF38C493F5FB92` |  | | ||
| | <a id="process-executable-name" href="#process-executable-name">`process.executable.name`</a> | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` |  | | ||
| | <a id="process-executable-path" href="#process-executable-path">`process.executable.path`</a> | 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` |  | | ||
| | <a id="process-exit-code" href="#process-exit-code">`process.exit.code`</a> | int | The exit code of the process. | `127` |  | | ||
| | <a id="process-exit-time" href="#process-exit-time">`process.exit.time`</a> | string | The date and time the process exited, in ISO 8601 format. | `2023-11-21T09:26:12.315Z` |  | | ||
| | <a id="process-group-leader-pid" href="#process-group-leader-pid">`process.group_leader.pid`</a> | int | The PID of the process's group leader. This is also the process group ID (PGID) of the process. | `23` |  | | ||
| | <a id="process-interactive" href="#process-interactive">`process.interactive`</a> | boolean | Whether the process is connected to an interactive shell. | |  | | ||
| | <a id="process-name" href="#process-name">`process.name`</a> | string | The name of the process. On Linux based systems, this SHOULD be set to the value of `/proc/[pid]/comm` or to the `Name` field in `proc/[pid]/status` (these values are equivalent). On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. [2] | `otelcol` |  | | ||
| | <a id="process-owner" href="#process-owner">`process.owner`</a> | string | The username of the user that owns the process. | `root` |  | | ||
| | <a id="process-paging-fault-type" href="#process-paging-fault-type">`process.paging.fault_type`</a> | string | The type of page fault for this data point. Type `major` is for major/hard page faults, and `minor` is for minor/soft page faults. | `major`; `minor` |  | | ||
| | <a id="process-parent-pid" href="#process-parent-pid">`process.parent_pid`</a> | int | Parent Process identifier (PPID). | `111` |  | | ||
|
|
@@ -43,17 +44,19 @@ An operating system process. | |
| | <a id="process-saved-user-id" href="#process-saved-user-id">`process.saved_user.id`</a> | int | The saved user ID (SUID) of the process. | `1002` |  | | ||
| | <a id="process-saved-user-name" href="#process-saved-user-name">`process.saved_user.name`</a> | string | The username of the saved user. | `operator` |  | | ||
| | <a id="process-session-leader-pid" href="#process-session-leader-pid">`process.session_leader.pid`</a> | int | The PID of the process's session leader. This is also the session ID (SID) of the process. | `14` |  | | ||
| | <a id="process-title" href="#process-title">`process.title`</a> | string | Process title (proctitle) [3] | `cat /etc/hostname`; `xfce4-session`; `bash` |  | | ||
| | <a id="process-user-id" href="#process-user-id">`process.user.id`</a> | int | The effective user ID (EUID) of the process. | `1001` |  | | ||
| | <a id="process-user-name" href="#process-user-name">`process.user.name`</a> | string | The username of the effective user of the process. | `root` |  | | ||
| | <a id="process-vpid" href="#process-vpid">`process.vpid`</a> | int | Virtual process identifier. [4] | `12` |  | | ||
| | <a id="process-working-directory" href="#process-working-directory">`process.working_directory`</a> | string | The working directory of the process. | `/root` |  | | ||
|
|
||
| **[1] `process.args_count`:** 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] `process.name`:** The value of this attribute will be equivalent to `process.executable.name` on Windows, but may not be on Linux. On Linux, the process name from `/proc/[pid]/comm` is truncated if its name is longer than `TASK_COMM_LEN`-1, and it can be manually changed by the process itself via [`prctl(2)`](https://man7.org/linux/man-pages/man2/prctl.2.html). On Windows, it won't be necessary to have both `process.name` and `process.executable.name`, but it may be on Linux depending on your use case. | ||
|
|
||
| **[3] `process.title`:** 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. | ||
|
|
||
| **[4] `process.vpid`:** 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. | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -79,9 +82,9 @@ Describes Linux Process attributes | |
|
|
||
| | Attribute | Type | Description | Examples | Stability | | ||
| |---|---|---|---|---| | ||
| | <a id="process-linux-cgroup" href="#process-linux-cgroup">`process.linux.cgroup`</a> | string | The control group associated with the process. [5] | `1:name=systemd:/user.slice/user-1000.slice/session-3.scope`; `0::/user.slice/user-1000.slice/[email protected]/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope` |  | | ||
|
|
||
| **[5] `process.linux.cgroup`:** Control groups (cgroups) are a kernel feature used to organize and manage process resources. This attribute provides the path(s) to the cgroup(s) associated with the process, which should match the contents of the [/proc/\[PID\]/cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) file. | ||
|
|
||
| ## Deprecated Process Attributes | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -40,7 +40,7 @@ | |
| | [`process.command`](/docs/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] |  | | ||
| | [`process.command_args`](/docs/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] |  | | ||
| | [`process.command_line`](/docs/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] |  | | ||
| | [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Conditionally Required` [4] |  | | ||
| | [`process.executable.path`](/docs/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] |  | | ||
| | [`process.linux.cgroup`](/docs/attributes-registry/process.md) | string | The control group associated with the process. [6] | `1:name=systemd:/user.slice/user-1000.slice/session-3.scope`; `0::/user.slice/user-1000.slice/[email protected]/tmux-spawn-0267755b-4639-4a27-90ed-f19f88e53748.scope` | `Recommended` |  | | ||
| | [`process.owner`](/docs/attributes-registry/process.md) | string | The username of the user that owns the process. | `root` | `Recommended` |  | | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -11,6 +11,22 @@ groups: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brief: > | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Process identifier (PID). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| examples: [1234] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| - id: process.name | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type: string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stability: experimental | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brief: > | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| The name of the process. On Linux based systems, this SHOULD be set to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| the value of `/proc/[pid]/comm` or to the `Name` field in `proc/[pid]/status` | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| (these values are equivalent). On Windows, this SHOULD be set to the | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| base name of `GetProcessImageFileNameW`. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| note: > | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| The value of this attribute will be equivalent to `process.executable.name` | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| on Windows, but may not be on Linux. On Linux, the process name from `/proc/[pid]/comm` | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is truncated if its name is longer than `TASK_COMM_LEN`-1, and it can be manually | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| changed by the process itself via [`prctl(2)`](https://man7.org/linux/man-pages/man2/prctl.2.html). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| On Windows, it won't be necessary to have both `process.name` and `process.executable.name`, but | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| it may be on Linux depending on your use case. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Comment on lines
+17
to
+28
There was a problem hiding this comment. a suggestion for #1737 (comment)
Suggested change
There was a problem hiding this comment. I think we should avoid calling anything the "general process name", or that it belongs in
It's better to ensure the correct field is used for the correct data, and not suggest it's optional which information goes into the different fields. I think part of the confusion before this change is because the differences between these weren't clear. Which one is the most important might also depend on the use case. Sometimes the executable file name might be considered more important than the process name. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| examples: ['otelcol'] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| - id: process.parent_pid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type: int | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stability: experimental | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
@@ -64,9 +80,9 @@ groups: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type: string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stability: experimental | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brief: > | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| The name of the process executable. On Linux based systems, this SHOULD be | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| set to the base name of the target of `/proc/[pid]/exe`. On Windows, | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| this SHOULD be set to the base name of `GetProcessImageFileNameW`. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| examples: ['otelcol'] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
There was a problem hiding this comment. would it be possible to have an example that's different between There was a problem hiding this comment. Where would be the best place for that? As part of this description? There was a problem hiding this comment. Added it as a note on There was a problem hiding this comment. I meant if we could have realistic example that's different on linux in There was a problem hiding this comment.
For Linux, one example where the process name isn't changed programmatically is using a symbolic link, for example A real example for this is Unfortunate, there are other examples where
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| - id: process.executable.path | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type: string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How should a backend operate if one of the fields is omitted? Take the value from the other field? What if one of the names isn't available for some reason?
What if on Linux both fields have the same value (a common case), is it OK to just send one of the two fields?
Also, is Windows the only OS where both fields are always the same? Can we have a completely list? If not, should we better not mention "Windows" here as the only affected OS?
Even if we say something like "In cases where
process.nameandprocess.executable.nameare identical, only one of the fields is required.", there is room for interpretation. Why not drop the last sentence, which may lead to confusion?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In Linux, when using memfd, there can be processes created with no executable file.
So I don't think the backend/SDKs should be copying the fields when missing or omitting an existent field, since it could cause confusion as to whether
process.executable.namereally existed or not.On the other hand, I agree the fields would commonly be duplicated, so it would be nice have a way to only send one and reduce data volumes. Especially since some workloads can create very large number of processes, so the data volume involving process telemetry can be very large.