-
Notifications
You must be signed in to change notification settings - Fork 889
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
Overhaul process command-line resource conventions. #1137
Changes from all commits
4787372
ac2d626
4251ea0
78fd429
de9b8ec
45146b9
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -6,18 +6,36 @@ | |||||||||
|
||||||||||
| Attribute | Description | Example | Required | | ||||||||||
|---|---|---|--| | ||||||||||
| process.pid | Process identifier (PID). | `1234` | Yes | | ||||||||||
| process.pid | Process identifier (PID). | `1234` | No | | ||||||||||
| process.executable.name | 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` | See below | | ||||||||||
| process.executable.path | 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` | See below | | ||||||||||
| process.command | 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` | See below | | ||||||||||
| process.command_line | The full command used to launch the process. The value can be either a list of strings representing the ordered list of arguments, or a single string representing the full command. On Linux based systems, can be set to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. On Windows, can be set to the result of `GetCommandLineW`. | Linux: `[ cmd/otecol, --config=config.yaml ]`, Windows: `cmd/otecol --config=config.yaml` | See below | | ||||||||||
| process.command_line | 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"` | See below | | ||||||||||
| process.command_args | 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 ]` | See below | | ||||||||||
| process.owner | The username of the user that owns the process. | `root` | No | | ||||||||||
|
||||||||||
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`. | ||||||||||
Comment on lines
+20
to
+23
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
I'm not sure if we want to keep backwards compatibility here since the previous solution was a bit unclean IMHO. We don't have multiple types (string and array of strings in this case) for the same attribute anywhere else, which is also why we weren't able to pour these into YAML definitions for the markdown and constants generator tool yet. While not making interpretation impossible, I think it would still be easier for consumers and overall cleaner if we can stick to one well-defined type per attribute. I would be +1 for a breaking change here if we can settle on this before GA (which I hope we can). The strict trace spec freeze does not apply to semantic conventions as far as I know. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we would still declare command_line as non-array string in the YAML and have this text just there in the markdown as prose. We should clarify that the MUST only applies for those that choose to support this at at all (which should be a MAY). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I will register that I don't understand why it matters if a value can take on more than one type. I didn't see a problem with There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For one, this is not supported by the current semantic convention tool, which is why this file has no corresponding YAML yet. |
||||||||||
|
||||||||||
At least one of `process.executable.name`, `process.executable.path`, `process.command`, `process.command_line` or `process.command_args` is required to allow back ends to identify the executable. | ||||||||||
|
||||||||||
## Process runtimes | ||||||||||
|
||||||||||
**type:** `process.runtime` | ||||||||||
|
||||||||||
**Description:** The single (language) runtime instance which is monitored. | ||||||||||
|
||||||||||
| Attribute | Description | Example | Required | | ||||||||||
|---|---|---|--| | ||||||||||
| process.runtime.name | The name of the runtime of this process. For compiled native binaries, this SHOULD be the name of the compiler. | `OpenJDK Runtime Environment` | No | | ||||||||||
| process.runtime.version | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | No | | ||||||||||
| process.runtime.description | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 openj9-0.21.0` | No | | ||||||||||
|
||||||||||
At least one of `process.executable.name`, `process.executable.path`, `process.command`, or `process.command_line` is required. | ||||||||||
|
||||||||||
`process.runtime.name` SHOULD be set to one of the values listed below, unless more detailed instructions are provided. | ||||||||||
If none of the listed values apply, a custom value best describing the runtime CAN be used. | ||||||||||
|
||||||||||
|
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.
I added this paragraph to keep the change non-breaking but I would be happy to remove it if deemed unnecessary.