Yaml files for process semantic convention (#1227)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
2020-11-24 14:18:10 +01:00 · 2020-11-24 14:18:10 +01:00 · 85daff3954
parent 4a6610e5fb
commit 85daff3954
2 changed files with 105 additions and 14 deletions
--- a/semantic_conventions/resource/process.yaml
+++ b/semantic_conventions/resource/process.yaml
@ -0,0 +1,87 @@
+groups:
+  - id: process
+    prefix: process
+    brief: >
+        An operating system process.
+    attributes:
+      - id: pid
+        type: number
+        brief: >
+          Process identifier (PID).
+        examples: [1234]
+      - id: executable.name
+        type: string
+        required:
+          conditional: "See below"
+        brief: >
+          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`.
+        examples: ['otelcol']
+      - id: executable.path
+        type: string
+        required:
+          conditional: "See below"
+        brief: >
+          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`.
+        examples: ['/usr/bin/cmd/otelcol']
+      - id: command
+        type: string
+        required:
+          conditional: "See below"
+        brief: >
+          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`.
+        examples: ['cmd/otelcol']
+      - id: command_line
+        type: string
+        required:
+          conditional: "See below"
+        brief: >
+          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.
+        examples: ['C:\cmd\otecol --config="my directory\config.yaml"']
+      - id: command_args
+        type: string[]
+        required:
+          conditional: "See below"
+        brief: >
+          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`.
+        examples: ['cmd/otecol', '--config=config.yaml']
+      - id: owner
+        type: string
+        brief: >
+          The username of the user that owns the process.
+        examples: 'root'
+  - id: process.runtime
+    prefix: process.runtime
+    brief: >
+      The single (language) runtime instance which is monitored.
+    attributes:
+      - id: name
+        type: string
+        brief: >
+          The name of the runtime of this process. For compiled native binaries,
+          this SHOULD be the name of the compiler.
+        examples: ['OpenJDK Runtime Environment']
+      - id: version
+        type: string
+        brief: >
+          The version of the runtime of this process, as returned by the runtime
+          without modification.
+        examples: '14.0.2'
+      - id: description
+        type: string
+        brief: >
+          An additional description about the runtime of the process, for example
+          a specific vendor customization of the runtime environment.
+        examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0'
--- a/specification/resource/semantic_conventions/process.md
+++ b/specification/resource/semantic_conventions/process.md
@ -22,15 +22,17 @@

 **Description:** An operating system process.

-| Attribute  | Description  | Example  | Required |
-|---|---|---|--|
-| 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 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 |
+<!-- semconv process -->
+| Attribute  | Type | Description  | Example  | Required |
+|---|---|---|---|---|
+| `process.pid` | number | Process identifier (PID). | `1234` | No |
+| `process.executable.name` | 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` | Conditional<br>See below |
+| `process.executable.path` | 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` | Conditional<br>See below |
+| `process.command` | 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` | Conditional<br>See below |
+| `process.command_line` | 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"` | Conditional<br>See below |
+| `process.command_args` | 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`<br>`--config=config.yaml` | Conditional<br>See below |
+| `process.owner` | string | The username of the user that owns the process. | `root` | No |
+<!-- 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,
@ -48,11 +50,13 @@ At least one of `process.executable.name`, `process.executable.path`, `process.c

 **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 Eclipse OpenJ9 VM openj9-0.21.0` | No |
+<!-- semconv process.runtime -->
+| Attribute  | Type | Description  | Example  | Required |
+|---|---|---|---|---|
+| `process.runtime.name` | string | 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` | string | The version of the runtime of this process, as returned by the runtime without modification. | `14.0.2` | No |
+| `process.runtime.description` | string | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. | `Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0` | No |
+<!-- endsemconv -->

 How to set these attributes for particular runtime kinds is described in the following subsections.