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.

Sign up for GitHub

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

Jump to bottom

Overhaul process command-line resource conventions. #1137

Merged
merged 6 commits into from
Nov 3, 2020
Merged

Overhaul process command-line resource conventions. #1137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4787372
Clean up process resource conventions.
Oberon00 Oct 23, 2020
ac2d626
Update CHANGELOG.
Oberon00 Oct 23, 2020
4251ea0
Add backwards compatiblity note.
Oberon00 Oct 23, 2020
78fd429
Update specification/resource/semantic_conventions/process.md
Oberon00 Oct 23, 2020
de9b8ec
Fix duplicated process.runtime attributes.
Oberon00 Oct 23, 2020
45146b9
Update specification/resource/semantic_conventions/process.md
Oberon00 Oct 28, 2020
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
5 changes: 4 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ New:

Updates:

- Make `process.pid` optional, split `process.command_args` from `command_line`
([#1137](https://github.com/open-telemetry/opentelemetry-specification/pull/1137))
- Renamed `CorrelationContext` to `Baggage`:
([#857](https://github.com/open-telemetry/opentelemetry-specification/pull/857))
- Add semantic convention for NGINX custom HTTP 499 status code.
Expand Down Expand Up @@ -91,7 +93,8 @@ Updates:
- Version attributes no longer have a prefix such as semver:
([#873](https://github.com/open-telemetry/opentelemetry-specification/pull/873))
- Add semantic conventions for process runtime
([#882](https://github.com/open-telemetry/opentelemetry-specification/pull/882))
([#882](https://github.com/open-telemetry/opentelemetry-specification/pull/882),
[#1137](https://github.com/open-telemetry/opentelemetry-specification/pull/1137))
- Use hex encoding for trace id and span id fields in OTLP JSON encoding:
([#911](https://github.com/open-telemetry/opentelemetry-specification/pull/911))
- Explicitly specify the SpanContext APIs IsValid and IsRemote as required
Expand Down
26 changes: 22 additions & 4 deletions specification/resource/semantic_conventions/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member Author

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.

Comment on lines +20 to +23
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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`.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The 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).

Copy link
Contributor

Choose a reason for hiding this comment

The 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 command_line being a string or a list. I really wish I knew how people plan on using this information such that the this distinction matters. 😁

Copy link
Member Author

Choose a reason for hiding this comment

The 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.

Expand Down