Fix yaml lint errors

open-telemetry · Jun 9, 2023 · 78f03af · 78f03af
1 parent 30fef93
commit 78f03af
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 38 deletions.
diff --git a/Makefile b/Makefile
@@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
 # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
-SEMCONVGEN_VERSION=0.18.0
+SEMCONVGEN_VERSION=0.19.0
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
 .PHONY: all

diff --git a/semantic_conventions/metrics/system-metrics.yaml b/semantic_conventions/metrics/system-metrics.yaml
@@ -1,20 +1,20 @@
 groups:
-# General system attributes
+  # General system attributes
   - id: system
     prefix: system
     type: attribute_group
-    brief: Describes System metric attributes
+    brief: "Describes System metric attributes"
     attributes:
       - id: device
         type: string
-        brief: The device identifier
+        brief: "The device identifier"
         examples: ["(identifier)"]
 
-# sytem.cpu.* metrics and attribute group
+  # sytem.cpu.* metrics and attribute group
   - id: system.cpu
     prefix: system.cpu
     type: attribute_group
-    brief: Describes System CPU metric attributes
+    brief: "Describes System CPU metric attributes"
     attributes:
       - id: state
         type:
@@ -28,11 +28,11 @@ groups:
               value: 'system'
             - id: interrupt
               value: 'interrupt'
-        brief: The state of the CPU
+        brief: "The state of the CPU"
         examples: ["idle", "interrupt"]
       - id: cpu
         type: int
-        brief: The CPU number [0..n-1]
+        brief: "The CPU number [0..n-1]"
         examples: [1]
 
   - id: metric.system.cpu.time
@@ -48,18 +48,18 @@ groups:
   - id: metric.system.cpu.utilization
     type: metric
     metric_name: system.cpu.utilization
-    brief: Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of CPUs
+    brief: "Difference in system.cpu.time since the last measurement, divided by the elapsed time and number of CPUs"
     instrument: gauge
     unit: "1"
     attributes:
       - ref: system.cpu.state
       - ref: system.cpu.cpu
 
-# sytem.memory.* metrics and attribute group
+  # sytem.memory.* metrics and attribute group
   - id: system.memory
     prefix: system.memory
     type: attribute_group
-    brief: Describes System Memory metric attributes
+    brief: "Describes System Memory metric attributes"
     attributes:
       - id: state
         type:
@@ -71,7 +71,7 @@ groups:
               value: 'free'
             - id: cached
               value: 'cached'
-        brief: The memory state
+        brief: "The memory state"
         examples: ["free", "cached"]
 
   - id: metric.system.memory.usage
@@ -92,11 +92,11 @@ groups:
     attributes:
       - ref: system.memory.state
 
-# system.paging.* metrics and attribute group
+  # system.paging.* metrics and attribute group
   - id: system.paging
     prefix: system.paging
     type: attribute_group
-    brief: Describes System Memory Paging metric attributes
+    brief: "Describes System Memory Paging metric attributes"
     attributes:
       - id: state
         type:
@@ -106,7 +106,7 @@ groups:
               value: 'used'
             - id: free
               value: 'free'
-        brief: The memory paging state
+        brief: "The memory paging state"
         examples: ["free"]
       - id: type
         type:
@@ -116,7 +116,7 @@ groups:
               value: 'major'
             - id: minor
               value: 'minor'
-        brief: The memory paging type
+        brief: "The memory paging type"
         examples: ["minor"]
       - id: direction
         type:
@@ -126,12 +126,12 @@ groups:
               value: 'in'
             - id: out
               value: 'out'
-        brief: The paging access direction
+        brief: "The paging access direction"
         examples: ["in"]
   - id: metric.system.paging.usage
     type: metric
     metric_name: system.paging.usage
-    brief: Unix swap or windows pagefile usage
+    brief: "Unix swap or windows pagefile usage"
     instrument: updowncounter
     unit: "By"
     attributes:
@@ -165,11 +165,11 @@ groups:
       - ref: system.paging.type
       - ref: system.paging.direction
 
-# system.disk.* metrics and attribute group
+  # system.disk.* metrics and attribute group
   - id: system.disk
     prefix: system.disk
     type: attribute_group
-    brief: Describes System Disk metric attributes
+    brief: "Describes System Disk metric attributes"
     attributes:
       - id: direction
         type:
@@ -179,7 +179,7 @@ groups:
               value: 'read'
             - id: write
               value: 'write'
-        brief: The disk operation direction
+        brief: "The disk operation direction"
         examples: ["read"]
 
   - id: metric.system.disk.io
@@ -205,22 +205,23 @@ groups:
   - id: metric.system.disk.io_time
     type: metric
     metric_name: system.disk.io_time
-    brief: Time disk spent activated
+    brief: "Time disk spent activated"
     instrument: counter
     unit: "s"
     note: |
        The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as:
 
        - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats)
-       - Windows: The complement of ["Disk\% IdleTime"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).)
-         performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`
+       - Windows: The complement of
+         ["Disk\% IdleTime"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained)
+         %20to%200%20(meaning%20always%20busy).) performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`
     attributes:
       - ref: system.device
 
   - id: metric.system.disk.operation_time
     type: metric
     metric_name: system.disk.operation_time
-    brief: Sum of the time each operation took to complete
+    brief: "Sum of the time each operation took to complete"
     instrument: counter
     unit: "s"
     note: |
@@ -241,11 +242,11 @@ groups:
       - ref: system.device
       - ref: system.disk.direction
 
-# system.filesystem.* metrics and attribute group
+  # system.filesystem.* metrics and attribute group
   - id: system.filesystem
     prefix: system.filesystem
     type: attribute_group
-    brief: Describes Filesystem metric attributes
+    brief: "Describes Filesystem metric attributes"
     attributes:
       - id: state
         brief: "The filesystem state"
@@ -312,11 +313,11 @@ groups:
       - ref: system.filesystem.mode
       - ref: system.filesystem.mountpoint
 
-# system.network.* metrics and attribute group
+  # system.network.* metrics and attribute group
   - id: system.network
     prefix: system.network
     type: attribute_group
-    brief: Describes Network metric attributes
+    brief: "Describes Network metric attributes"
     attributes:
       - id: direction
         type:
@@ -420,12 +421,11 @@ groups:
       - ref: system.network.state
       - ref: network.transport
 
-# system.processes.* metrics and attribute group
-
+  # system.processes.* metrics and attribute group
   - id: metric.system.processes.count
     type: metric
     metric_name: system.processes.count
-    brief: Total number of processes in each state
+    brief: "Total number of processes in each state"
     instrument: updowncounter
     unit: "{process}"
     attributes:
@@ -448,6 +448,6 @@ groups:
   - id: metric.system.processes.created
     type: metric
     metric_name: system.processes.created
-    brief: Total number of processes created over uptime of the host
+    brief: "Total number of processes created over uptime of the host"
     instrument: counter
     unit: "{process}"
diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md
@@ -307,7 +307,9 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getProcessCpuLoad()`](https:
 <!-- semconv metric.process.runtime.jvm.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the process. |
+| `process.runtime.jvm.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the process. [1] |
+
+**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getProcessCpuLoad()).
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.cpu.utilization(full) -->
@@ -322,7 +324,9 @@ and [`com.ibm.lang.management.OperatingSystemMXBean#getSystemCpuLoad()`](https:/
 <!-- semconv metric.process.runtime.jvm.system.cpu.utilization(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system. |
+| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system. [1] |
+
+**[1]:** The value range is [0.0,1.0]. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html#getCpuLoad()).
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.system.cpu.utilization(full) -->
@@ -336,7 +340,9 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht
 <!-- semconv metric.process.runtime.jvm.system.cpu.load_1m(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute. |
+| `process.runtime.jvm.system.cpu.load_1m` | Gauge | `1` | Average CPU load of the whole system for the last minute. [1] |
+
+**[1]:** The value range is [0,n], where n is the number of CPU cores - or a negative number of the value is not available. This utilization is not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). [Reference](https://docs.oracle.com/en/java/javase/17/docs/api/java.management/java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()).
 <!-- endsemconv -->
 
 <!-- semconv metric.process.runtime.jvm.system.cpu.load_1m(full) -->

diff --git a/specification/metrics/semantic_conventions/system-metrics.md b/specification/metrics/semantic_conventions/system-metrics.md
@@ -325,8 +325,9 @@ This metric is [recommended][MetricRecommended].
 **[1]:** The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as:
 
 - Linux: Field 13 from [procfs-diskstats](https://www.kernel.org/doc/Documentation/ABI/testing/procfs-diskstats)
-- Windows: The complement of ["Disk\% IdleTime"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).)
-  performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`
+- Windows: The complement of
+  ["Disk\% IdleTime"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained)
+  %20to%200%20(meaning%20always%20busy).) performance counter: `uptime * (100 - "Disk\% Idle Time") / 100`
 <!-- endsemconv -->
 
 <!-- semconv metric.system.disk.io_time(full) -->