add namespace to jvm metric attributes (#20)

2023-08-14 22:35:25 +02:00 · 2023-08-14 22:35:25 +02:00 · 2927d5809b
parent a0143da118
commit 2927d5809b
7 changed files with 82 additions and 27 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -26,6 +26,25 @@ release.
  clients invoking them.
 - BREAKING: Rename all JVM metrics from `process.runtime.jvm.*` to `jvm.*`
  ([#241](https://github.com/open-telemetry/semantic-conventions/pull/241))
+- BREAKING: Add namespaces to JVM metric attributes ([#20](https://github.com/open-telemetry/semantic-conventions/pull/20)).
+  - Rename attributes `type` to `jvm.memory.type`, `pool` to `jvm.memory.pool.name`
+  - Applies to metrics:
+    - `jvm.memory.usage`
+    - `jvm.memory.init`
+    - `jvm.memory.committed`
+    - `jvm.memory.limit`
+    - `jvm.memory.usage_after_last_gc`
+  - Rename attributes `gc` to `jvm.gc.name`, `action` to `jvm.gc.action`
+  - Applies to metrics:
+    - `jvm.gc.duration`
+  - Rename attribute `daemon` to `thread.daemon`
+  - Applies to metrics:
+    - `jvm.threads.count`
+  - Rename attribute `pool` to `jvm.buffer.pool.name`
+  - Applies to metrics:
+    - `jvm.buffer.usage`
+    - `jvm.buffer.limit`
+    - `jvm.buffer.count`

 ## v1.21.0 (2023-07-13)

--- a/docs/general/attributes.md
+++ b/docs/general/attributes.md
@ -368,6 +368,7 @@ a thread that started a span.
 |---|---|---|---|---|
 | `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended |
 | `thread.name` | string | Current thread name. | `main` | Recommended |
+| `thread.daemon` | boolean | Whether the thread is daemon or not. |  | Recommended |
 <!-- endsemconv -->

 Examples of where `thread.id` and `thread.name` can be extracted from:
--- a/docs/system/runtime-environment-metrics.md
+++ b/docs/system/runtime-environment-metrics.md
@ -91,12 +91,12 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
 <!-- semconv metric.jvm.memory.usage(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
-| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |
+| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
+| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |

 **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).

-`type` MUST be one of the following:
+`jvm.memory.type` MUST be one of the following:

 | Value  | Description |
 |---|---|
@ -118,12 +118,12 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
 <!-- semconv metric.jvm.memory.committed(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
-| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |
+| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
+| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |

 **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).

-`type` MUST be one of the following:
+`jvm.memory.type` MUST be one of the following:

 | Value  | Description |
 |---|---|
@ -145,12 +145,12 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
 <!-- semconv metric.jvm.memory.limit(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
-| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |
+| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
+| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |

 **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).

-`type` MUST be one of the following:
+`jvm.memory.type` MUST be one of the following:

 | Value  | Description |
 |---|---|
@ -172,12 +172,12 @@ This metric is obtained from [`MemoryPoolMXBean#getCollectionUsage()`](https://d
 <!-- semconv metric.jvm.memory.usage_after_last_gc(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
-| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |
+| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
+| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |

 **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).

-`type` MUST be one of the following:
+`jvm.memory.type` MUST be one of the following:

 | Value  | Description |
 |---|---|
@ -204,8 +204,8 @@ of `[]` (single bucket histogram capturing count, sum, min, max).
 <!-- semconv metric.jvm.gc.duration(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `gc` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended |
-| `action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended |
+| `jvm.gc.name` | string | Name of the garbage collector. [1] | `G1 Young Generation`; `G1 Old Generation` | Recommended |
+| `jvm.gc.action` | string | Name of the garbage collector action. [2] | `end of minor GC`; `end of major GC` | Recommended |

 **[1]:** Garbage collector name is generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()).

@ -228,7 +228,7 @@ Note that this is the number of platform threads (as opposed to virtual threads)
 <!-- semconv metric.jvm.threads.count(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `daemon` | boolean | Whether the thread is daemon or not. |  | Recommended |
+| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. |  | Recommended |
 <!-- endsemconv -->

 ### Metric: `jvm.classes.loaded`
@ -325,12 +325,12 @@ This metric is obtained from [`MemoryPoolMXBean#getUsage()`](https://docs.oracle
 <!-- semconv metric.jvm.memory.init(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
-| `pool` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |
+| `jvm.memory.type` | string | The type of memory. | `heap`; `non_heap` | Recommended |
+| `jvm.memory.pool.name` | string | Name of the memory pool. [1] | `G1 Old Gen`; `G1 Eden space`; `G1 Survivor Space` | Recommended |

 **[1]:** Pool names are generally obtained via [MemoryPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()).

-`type` MUST be one of the following:
+`jvm.memory.type` MUST be one of the following:

 | Value  | Description |
 |---|---|
@ -385,7 +385,7 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o
 <!-- semconv metric.jvm.buffer.usage(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |
+| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |

 **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
 <!-- endsemconv -->
@ -404,7 +404,7 @@ This metric is obtained from [`BufferPoolMXBean#getTotalCapacity()`](https://doc
 <!-- semconv metric.jvm.buffer.limit(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |
+| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |

 **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
 <!-- endsemconv -->
@ -423,7 +423,7 @@ This metric is obtained from [`BufferPoolMXBean#getCount()`](https://docs.oracle
 <!-- semconv metric.jvm.buffer.count(full) -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `pool` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |
+| `jvm.buffer.pool.name` | string | Name of the buffer pool. [1] | `mapped`; `direct` | Recommended |

 **[1]:** Pool names are generally obtained via [BufferPoolMXBean#getName()](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html#getName()).
 <!-- endsemconv -->
--- a/model/metrics/process-runtime-jvm-metrics-experimental.yaml
+++ b/model/metrics/process-runtime-jvm-metrics-experimental.yaml
@ -34,8 +34,11 @@ groups:
  - id: attributes.jvm.buffer
    type: attribute_group
    brief: "Describes JVM buffer metric attributes."
+    prefix: jvm.buffer
    attributes:
-      - ref: pool
+      - id: pool.name
+        type: string
+        requirement_level: recommended
        brief: Name of the buffer pool.
        examples: [ "mapped", "direct" ]
        note: >
--- a/model/metrics/process-runtime-jvm-metrics.yaml
+++ b/model/metrics/process-runtime-jvm-metrics.yaml
@ -2,6 +2,7 @@ groups:
  - id: attributes.jvm.memory
    type: attribute_group
    brief: "Describes JVM memory metric attributes."
+    prefix: jvm.memory
    attributes:
      - id: type
        type:
@ -16,7 +17,7 @@ groups:
        requirement_level: recommended
        brief: The type of memory.
        examples: ["heap", "non_heap"]
-      - id: pool
+      - id: pool.name
        type: string
        requirement_level: recommended
        brief: Name of the memory pool.
@ -63,8 +64,9 @@ groups:
    brief: "Duration of JVM garbage collection actions."
    instrument: histogram
    unit: "s"
+    prefix: jvm.gc
    attributes:
-      - id: gc
+      - id: name
        type: string
        requirement_level: recommended
        brief: Name of the garbage collector.
@ -88,9 +90,7 @@ groups:
    instrument: updowncounter
    unit: "{thread}"
    attributes:
-      - id: daemon
-        brief: "Whether the thread is daemon or not."
-        type: boolean
+      - ref: thread.daemon
        requirement_level: recommended

  - id: metric.jvm.classes.loaded
--- a/model/trace/general.yaml
+++ b/model/trace/general.yaml
@ -215,6 +215,9 @@ groups:
        brief: >
          Current thread name.
        examples: main
+      - id: daemon
+        brief: "Whether the thread is daemon or not."
+        type: boolean
  - id: code
    prefix: code
    type: span
--- a/schema-next.yaml
+++ b/schema-next.yaml
@ -27,6 +27,35 @@ versions:
            process.runtime.jvm.buffer.usage: jvm.buffer.usage
            process.runtime.jvm.buffer.limit: jvm.buffer.limit
            process.runtime.jvm.buffer.count: jvm.buffer.count
+        # https://github.com/open-telemetry/semantic-conventions/pull/20
+        - rename_attributes:
+            attribute_map:
+              type: jvm.memory.type
+              pool: jvm.memory.pool.name
+            apply_to_metrics:
+              - jvm.memory.usage
+              - jvm.memory.committed
+              - jvm.memory.limit
+              - jvm.memory.usage_after_last_gc
+              - jvm.memory.init
+        - rename_attributes:
+            attribute_map:
+              name: jvm.gc.name
+              action: jvm.gc.action
+            apply_to_metrics:
+              - jvm.gc.duration
+        - rename_attributes:
+            attribute_map:
+              daemon: thread.daemon
+            apply_to_metrics:
+              - jvm.threads.count
+        - rename_attributes:
+            attribute_map:
+              pool: jvm.buffer.pool.name
+            apply_to_metrics:
+              - jvm.buffer.usage
+              - jvm.buffer.limit
+              - jvm.buffer.count
  1.21.0:
    spans:
      changes: