From 4ed438544308ae08a703512bc15c4dbf6223698e Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 18 Apr 2023 13:03:44 -0400 Subject: [PATCH 1/7] Move semantic convention CODEOWNERS to new semconv-approvers team. (#3398) We're formalizing the semantic convention codeowners team, and elevating it to the same status as trace/metrics/logs approvers. The new team is created, and previous `inst-wg` team members are being asked to commit to Approver responsibilities before being added to the new team. Co-authored-by: Reiley Yang --- .github/CODEOWNERS | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index fbbc5fe8f19..d1bfc690008 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -27,9 +27,9 @@ specification/metrics/ @open-telemetry/technical-committee @open-telemetry/spec experimental/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers specification/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers -# Semantic Conventions owners (global + trace/metrics/logs + instr-wg) -semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/instr-wg -specification/trace/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers @open-telemetry/instr-wg -specification/metrics/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers @open-telemetry/instr-wg -specification/logs/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers @open-telemetry/instr-wg -specification/resource/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/instr-wg +# Semantic Conventions owners (global + trace/metrics/logs/semconv) +semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers +specification/trace/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers @open-telemetry/specs-semconv-approvers +specification/metrics/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers @open-telemetry/specs-semconv-approvers +specification/logs/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers @open-telemetry/specs-semconv-approvers +specification/resource/semantic_conventions/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-semconv-approvers From 5443e963b6e0d4bbf202896fd165d9349aa4cabb Mon Sep 17 00:00:00 2001 From: Matthew Wear Date: Tue, 18 Apr 2023 14:21:28 -0700 Subject: [PATCH 2/7] add k8s.cluster.uid resource attribute semconv (#3267) Fixes #3266 ## Changes Kubernetes doesn't have a formal way to identify a cluster, but a pseudo-id can be derived by taking the `uid` of the `kube-system` namespace. This PR adds a convention for `k8s.cluster.uid` to be set to the `kube-system` namespace uid. --- CHANGELOG.md | 2 ++ semantic_conventions/resource/k8s.yaml | 29 +++++++++++++++++++ .../resource/semantic_conventions/k8s.md | 24 +++++++++++++++ 3 files changed, 55 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52188613a7c..f0765df35b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -101,6 +101,8 @@ release. ### Semantic Conventions +- Add k8s.cluster.uid semantic convention + ([#3267](https://github.com/open-telemetry/opentelemetry-specification/pull/3267)) - Clarify that attribute requirement levels apply to the instrumentation library ([#3289](https://github.com/open-telemetry/opentelemetry-specification/pull/3289)) - Fix grammatical number of metric units. diff --git a/semantic_conventions/resource/k8s.yaml b/semantic_conventions/resource/k8s.yaml index 1513f201663..32a9716dbe6 100644 --- a/semantic_conventions/resource/k8s.yaml +++ b/semantic_conventions/resource/k8s.yaml @@ -10,6 +10,35 @@ groups: brief: > The name of the cluster. examples: ['opentelemetry-cluster'] + - id: uid + type: string + brief: > + A pseudo-ID for the cluster, set to the UID of the `kube-system` + namespace. + note: | + K8s does not have support for obtaining a cluster ID. If this is ever + added, we will recommend collecting the `k8s.cluster.uid` through the + official APIs. In the meantime, we are able to use the `uid` of the + `kube-system` namespace as a proxy for cluster ID. Read on for the + rationale. + + Every object created in a K8s cluster is assigned a distinct UID. The + `kube-system` namespace is used by Kubernetes itself and will exist + for the lifetime of the cluster. Using the `uid` of the `kube-system` + namespace is a reasonable proxy for the K8s ClusterID as it will only + change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are + UUIDs as standardized by + [ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). + Which states: + + > If generated according to one of the mechanisms defined in Rec. + ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be + different from all other UUIDs generated before 3603 A.D., or is + extremely likely to be different (depending on the mechanism chosen). + + Therefore, UIDs between clusters should be extremely unlikely to + conflict. + examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d'] - id: k8s.node prefix: k8s.node diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/semantic_conventions/k8s.md index 2b2387c54c6..25dfe2e3781 100644 --- a/specification/resource/semantic_conventions/k8s.md +++ b/specification/resource/semantic_conventions/k8s.md @@ -25,6 +25,30 @@ Kubernetes object, but "name" is usually more user friendly so can be also set. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended | +| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended | + +**[1]:** K8s does not have support for obtaining a cluster ID. If this is ever +added, we will recommend collecting the `k8s.cluster.uid` through the +official APIs. In the meantime, we are able to use the `uid` of the +`kube-system` namespace as a proxy for cluster ID. Read on for the +rationale. + +Every object created in a K8s cluster is assigned a distinct UID. The +`kube-system` namespace is used by Kubernetes itself and will exist +for the lifetime of the cluster. Using the `uid` of the `kube-system` +namespace is a reasonable proxy for the K8s ClusterID as it will only +change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are +UUIDs as standardized by +[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html). +Which states: + +> If generated according to one of the mechanisms defined in Rec. + ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be + different from all other UUIDs generated before 3603 A.D., or is + extremely likely to be different (depending on the mechanism chosen). + +Therefore, UIDs between clusters should be extremely unlikely to +conflict. ## Node From c210cf5884cf2c06dc1d1a6a34a4ea76c542841f Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Wed, 19 Apr 2023 11:48:46 -0500 Subject: [PATCH 3/7] Move configuration schema to separate repository (#3412) --- CHANGELOG.md | 2 ++ specification/configuration/file-configuration.md | 4 ++-- .../schema/opentelemetry_configuration.json | 15 --------------- 3 files changed, 4 insertions(+), 17 deletions(-) delete mode 100644 specification/configuration/schema/opentelemetry_configuration.json diff --git a/CHANGELOG.md b/CHANGELOG.md index f0765df35b7..1961e9131b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,8 @@ release. - Lay initial groundwork for file configuration ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360)) +- Move file configuration schema to `opentelemetry-configuration`. + ([#3412](https://github.com/open-telemetry/opentelemetry-specification/pull/3412)) ### Telemetry Schemas diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index dbe949b2c7b..802512710d9 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -31,8 +31,8 @@ interpreted to produce configured OpenTelemetry components. ## Configuration Model The configuration model is defined -in [./schema/](./schema/opentelemetry_configuration.json) using -the [JSON Schema](https://json-schema.org/). +in [opentelemetry-configuration](https://github.com/open-telemetry/opentelemetry-configuration) +using the [JSON Schema](https://json-schema.org/). ### Stability Definition diff --git a/specification/configuration/schema/opentelemetry_configuration.json b/specification/configuration/schema/opentelemetry_configuration.json deleted file mode 100644 index 2dc9cb04f8a..00000000000 --- a/specification/configuration/schema/opentelemetry_configuration.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "$id": "https://opentelemetry.io/otelconfig/OpenTelemetryConfiguration", - "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "OpenTelemetryConfiguration", - "type": "object", - "additionalProperties": false, - "properties": { - "file_format": { - "type": "number" - } - }, - "required": [ - "file_format" - ] -} From 85810dbb6a6b5f339aad38adb776321cce17cbde Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 20 Apr 2023 11:56:48 -0700 Subject: [PATCH 4/7] Converts JVM metrics to yaml (#3413) Converts JVM metrics to yaml --- .../metrics/process-runtime-jvm-metrics.yaml | 185 +++++++++ .../runtime-environment-metrics.md | 359 +++++++++++++++--- 2 files changed, 499 insertions(+), 45 deletions(-) create mode 100644 semantic_conventions/metrics/process-runtime-jvm-metrics.yaml diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml new file mode 100644 index 00000000000..aab4f788bc9 --- /dev/null +++ b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @@ -0,0 +1,185 @@ +groups: + - id: attributes.process.runtime.jvm.memory + type: attribute_group + brief: "Describes JVM memory metric attributes." + attributes: + - id: type + type: + allow_custom_values: false + members: + - id: heap + value: 'heap' + brief: 'Heap memory.' + - id: non_heap + value: 'non_heap' + brief: 'Non-heap memory' + requirement_level: recommended + brief: The type of memory. + examples: ["heap", "non_heap"] + - id: pool + type: string + requirement_level: recommended + brief: Name of the memory pool. + examples: ["G1 Old Gen", "G1 Eden space", "G1 Survivor Space"] + note: > + 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()). + + - id: metric.process.runtime.jvm.memory.usage + type: metric + metric_name: process.runtime.jvm.memory.usage + extends: attributes.process.runtime.jvm.memory + brief: "Measure of memory used." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.memory.init + type: metric + metric_name: process.runtime.jvm.memory.init + extends: attributes.process.runtime.jvm.memory + brief: "Measure of initial memory requested." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.memory.committed + type: metric + metric_name: process.runtime.jvm.memory.committed + extends: attributes.process.runtime.jvm.memory + brief: "Measure of memory committed." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.memory.limit + type: metric + metric_name: process.runtime.jvm.memory.limit + extends: attributes.process.runtime.jvm.memory + brief: "Measure of max obtainable memory." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.memory.usage_after_last_gc + type: metric + metric_name: process.runtime.jvm.memory.usage_after_last_gc + extends: attributes.process.runtime.jvm.memory + brief: "Measure of memory used, as measured after the most recent garbage collection event on this pool." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.gc.duration + type: metric + metric_name: process.runtime.jvm.gc.duration + brief: "Duration of JVM garbage collection actions." + instrument: histogram + unit: "ms" + attributes: + - id: gc + type: string + requirement_level: recommended + brief: Name of the garbage collector. + examples: ["G1 Young Generation", "G1 Old Generation"] + note: > + 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()). + - id: action + type: string + requirement_level: recommended + brief: Name of the garbage collector action. + examples: ["end of minor GC", "end of major GC"] + note: > + Garbage collector action is generally obtained via + [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + + - id: metric.process.runtime.jvm.threads.count + type: metric + metric_name: process.runtime.jvm.threads.count + brief: "Number of executing threads." + instrument: updowncounter + unit: "{thread}" + attributes: + - id: daemon + brief: "Whether the thread is daemon or not." + type: boolean + requirement_level: recommended + + - id: metric.process.runtime.jvm.classes.loaded + type: metric + metric_name: process.runtime.jvm.classes.loaded + brief: "Number of classes loaded since JVM start." + instrument: counter + unit: "{class}" + + - id: metric.process.runtime.jvm.classes.unloaded + type: metric + metric_name: process.runtime.jvm.classes.unloaded + brief: "Number of classes unloaded since JVM start." + instrument: counter + unit: "{class}" + + - id: metric.process.runtime.jvm.classes.current_loaded + type: metric + metric_name: process.runtime.jvm.classes.current_loaded + brief: "Number of classes currently loaded." + instrument: updowncounter + unit: "{class}" + + - id: metric.process.runtime.jvm.cpu.utilization + type: metric + metric_name: process.runtime.jvm.cpu.utilization + brief: "Recent CPU utilization for the process." + note: > + This utilization is not defined as being for the specific interval since last measurement + (unlike `system.cpu.utilization`). + instrument: gauge + unit: "1" + + - id: metric.process.runtime.jvm.system.cpu.utilization + type: metric + metric_name: process.runtime.jvm.system.cpu.utilization + brief: "Recent CPU utilization for the whole system." + note: > + This utilization is not defined as being for the specific interval since last measurement + (unlike `system.cpu.utilization`). + instrument: gauge + unit: "1" + + - id: metric.process.runtime.jvm.system.cpu.load_1m + type: metric + metric_name: process.runtime.jvm.system.cpu.load_1m + brief: "Average CPU load of the whole system for the last minute." + instrument: gauge + unit: "1" + + - id: attributes.process.runtime.jvm.buffer + type: attribute_group + brief: "Describes JVM buffer metric attributes." + attributes: + - ref: pool + brief: Name of the memory pool. + examples: [ "mapped", "direct" ] + note: > + 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()). + + - id: metric.process.runtime.jvm.buffer.usage + type: metric + metric_name: process.runtime.jvm.buffer.usage + extends: attributes.process.runtime.jvm.buffer + brief: "Measure of memory used by buffers." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.buffer.limit + type: metric + metric_name: process.runtime.jvm.buffer.limit + extends: attributes.process.runtime.jvm.buffer + brief: "Measure of total memory capacity of buffers." + instrument: updowncounter + unit: "By" + + - id: metric.process.runtime.jvm.buffer.count + type: metric + metric_name: process.runtime.jvm.buffer.count + extends: attributes.process.runtime.jvm.buffer + brief: "Number of buffers in the pool." + instrument: updowncounter + unit: "{buffer}" diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index 84a1eaa4ba2..e7d9d975d82 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -20,6 +20,22 @@ semantic conventions when instrumenting runtime environments. * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) - [Attributes](#attributes) - [JVM Metrics](#jvm-metrics) + * [Metric: `process.runtime.jvm.memory.usage`](#metric-processruntimejvmmemoryusage) + * [Metric: `process.runtime.jvm.memory.init`](#metric-processruntimejvmmemoryinit) + * [Metric: `process.runtime.jvm.memory.committed`](#metric-processruntimejvmmemorycommitted) + * [Metric: `process.runtime.jvm.memory.limit`](#metric-processruntimejvmmemorylimit) + * [Metric: `process.runtime.jvm.memory.usage_after_last_gc`](#metric-processruntimejvmmemoryusage_after_last_gc) + * [Metric: `process.runtime.jvm.gc.duration`](#metric-processruntimejvmgcduration) + * [Metric: `process.runtime.jvm.threads.count`](#metric-processruntimejvmthreadscount) + * [Metric: `process.runtime.jvm.classes.loaded`](#metric-processruntimejvmclassesloaded) + * [Metric: `process.runtime.jvm.classes.unloaded`](#metric-processruntimejvmclassesunloaded) + * [Metric: `process.runtime.jvm.classes.current_loaded`](#metric-processruntimejvmclassescurrent_loaded) + * [Metric: `process.runtime.jvm.cpu.utilization`](#metric-processruntimejvmcpuutilization) + * [Metric: `process.runtime.jvm.system.cpu.utilization`](#metric-processruntimejvmsystemcpuutilization) + * [Metric: `process.runtime.jvm.system.cpu.load_1m`](#metric-processruntimejvmsystemcpuload_1m) + * [Metric: `process.runtime.jvm.buffer.usage`](#metric-processruntimejvmbufferusage) + * [Metric: `process.runtime.jvm.buffer.limit`](#metric-processruntimejvmbufferlimit) + * [Metric: `process.runtime.jvm.buffer.count`](#metric-processruntimejvmbuffercount) @@ -59,48 +75,301 @@ consider, for example pthreads vs green thread implementations. **Description:** Java Virtual Machine (JVM) metrics captured under `process.runtime.jvm.` -All JVM metric attributes are required unless otherwise indicated. - -| Name | Description | Unit | Unit ([UCUM](README.md#instrument-units)) | Instrument Type ([*](README.md#instrument-types)) | Value Type | Attribute Key | Attribute Values | -|------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------|-------------------------------------------|---------------------------------------------------|------------|---------------|-----------------------| -| process.runtime.jvm.memory.usage | Measure of memory used | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"non_heap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.init | Measure of initial memory requested | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"non_heap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.committed | Measure of memory committed | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"non_heap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.limit | Measure of max obtainable memory | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"non_heap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.memory.usage_after_last_gc | Measure of memory used, as measured after the most recent garbage collection event on this pool | Bytes | `By` | UpDownCounter | Int64 | type | `"heap"`, `"non_heap"` | -| | | | | | | pool | Name of pool [1] | -| process.runtime.jvm.threads.count | Number of executing threads | threads | `{thread}` | UpDownCounter | Int64 | daemon | `true`, `false` | -| process.runtime.jvm.classes.loaded | Number of classes loaded since JVM start | classes | `{class}` | Counter | Int64 | | | -| process.runtime.jvm.classes.unloaded | Number of classes unloaded since JVM start | classes | `{class}` | Counter | Int64 | | | -| process.runtime.jvm.classes.current_loaded | Number of classes currently loaded | classes | `{class}` | UpDownCounter | Int64 | | | -| process.runtime.jvm.cpu.utilization | Recent CPU utilization for the process [2] | 1 | 1 | Asynchronous Gauge | Double | | | -| process.runtime.jvm.system.cpu.utilization | Recent CPU utilization for the whole system [2] | 1 | 1 | Asynchronous Gauge | Double | | | -| process.runtime.jvm.system.cpu.load_1m | Average CPU load of the whole system for the last minute | 1 | 1 | Asynchronous Gauge | Double | | | -| process.runtime.jvm.buffer.usage | Measure of memory used by buffers | Bytes | `By` | UpDownCounter | Int64 | pool | Name of pool[3] | -| process.runtime.jvm.buffer.limit | Measure of total memory capacity of buffers | Bytes | `By` | UpDownCounter | Int64 | pool | Name of pool[3] | -| process.runtime.jvm.buffer.count | Number of buffers in the pool | buffers | `{buffer}` | UpDownCounter | Int64 | pool | Name of pool[3] | -| process.runtime.jvm.gc.duration | Duration of JVM garbage collection actions | Milliseconds | `ms` | Histogram | Int64 | gc | Name of gc[4] | -| | | | | | | action | The gc action[4] | - -**[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()). -Examples include `G1 Old Gen`, `G1 Eden space`, `G1 Survivor Space`, `Metaspace`, etc. - -**[2]**: These utilizations are not defined as being for the specific interval since last measurement (unlike `system.cpu.utilization`). - -**[3]**: 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()). - -**[4]**: Garbage collector name and action are generally obtained via [GarbageCollectionNotificationInfo#getGcName()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcName()) and [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()) respectively. The following is an incomplete list of names and actions for several popular garbage collectors: - -* G1 Garbage Collector - * Names: `G1 Young Generation`, `G1 Old Generation` - * Actions: `end of minor GC`, `end of major GC` -* Shenandoah Garbage Collector - * Names: `Shenandoah Cycles`, `Shenandoah Pauses` - * Actions: `end of GC cycle`, `end of GC pause` -* Z Garbage Collector - * Names: `ZGC Cycles`, `ZGC Pauses` - * Actions: `end of GC cycle`, `end of GC pause` +### Metric: `process.runtime.jvm.memory.usage` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.usage` | UpDownCounter | `By` | Measure of memory used. | + + + +| 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 | + +**[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: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `process.runtime.jvm.memory.init` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.init` | UpDownCounter | `By` | Measure of initial memory requested. | + + + +| 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 | + +**[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: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `process.runtime.jvm.memory.committed` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.committed` | UpDownCounter | `By` | Measure of memory committed. | + + + +| 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 | + +**[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: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `process.runtime.jvm.memory.limit` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.limit` | UpDownCounter | `By` | Measure of max obtainable memory. | + + + +| 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 | + +**[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: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `process.runtime.jvm.memory.usage_after_last_gc` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.memory.usage_after_last_gc` | UpDownCounter | `By` | Measure of memory used, as measured after the most recent garbage collection event on this pool. | + + + +| 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 | + +**[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: + +| Value | Description | +|---|---| +| `heap` | Heap memory. | +| `non_heap` | Non-heap memory | + + +### Metric: `process.runtime.jvm.gc.duration` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.gc.duration` | Histogram | `ms` | Duration of JVM garbage collection actions. | + + + +| 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 | + +**[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()). + +**[2]:** Garbage collector action is generally obtained via [GarbageCollectionNotificationInfo#getGcAction()](https://docs.oracle.com/en/java/javase/11/docs/api/jdk.management/com/sun/management/GarbageCollectionNotificationInfo.html#getGcAction()). + + +### Metric: `process.runtime.jvm.threads.count` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.threads.count` | UpDownCounter | `{thread}` | Number of executing threads. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `daemon` | boolean | Whether the thread is daemon or not. | | Recommended | + + +### Metric: `process.runtime.jvm.classes.loaded` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.classes.loaded` | Counter | `{class}` | Number of classes loaded since JVM start. | + + + + + +### Metric: `process.runtime.jvm.classes.unloaded` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.classes.unloaded` | Counter | `{class}` | Number of classes unloaded since JVM start. | + + + + + +### Metric: `process.runtime.jvm.classes.current_loaded` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.classes.current_loaded` | UpDownCounter | `{class}` | Number of classes currently loaded. | + + + + + +### Metric: `process.runtime.jvm.cpu.utilization` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the process. | + + + + + +### Metric: `process.runtime.jvm.system.cpu.utilization` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.system.cpu.utilization` | Gauge | `1` | Recent CPU utilization for the whole system. | + + + + + +### Metric: `process.runtime.jvm.system.cpu.load_1m` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| 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. | + + + + + +### Metric: `process.runtime.jvm.buffer.usage` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.buffer.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool` | string | Name of the memory 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()). + + +### Metric: `process.runtime.jvm.buffer.limit` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.buffer.limit` | UpDownCounter | `By` | Measure of total memory capacity of buffers. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool` | string | Name of the memory 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()). + + +### Metric: `process.runtime.jvm.buffer.count` + +This metric is [recommended](../metric-requirement-level.md#recommended). + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `process.runtime.jvm.buffer.count` | UpDownCounter | `{buffer}` | Number of buffers in the pool. | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `pool` | string | Name of the memory 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()). + From 227e5bf061905bfb1256e5bc84fd7ef0c66a8257 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Fri, 21 Apr 2023 08:48:06 -0500 Subject: [PATCH 5/7] Mark logs bridge API / SDK as stable (#3376) All items in #2911 have been completed and I believe logs can now be marked stable. --- specification/logs/bridge-api.md | 2 +- specification/logs/sdk.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 66b4932739c..dff8555b7d9 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -1,6 +1,6 @@ # Logs Bridge API -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 515668404f4..fba6391949f 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -1,6 +1,6 @@ # Logs SDK -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents From 773ee656f92c7f591f2fd9c38df82c264a15184d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 21 Apr 2023 07:59:59 -0700 Subject: [PATCH 6/7] Fix JVM buffer pool attribute description (#3423) Follow-up to #3413 --------- Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- .../metrics/process-runtime-jvm-metrics.yaml | 2 +- .../semantic_conventions/runtime-environment-metrics.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml index aab4f788bc9..19978463eaa 100644 --- a/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml +++ b/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml @@ -154,7 +154,7 @@ groups: brief: "Describes JVM buffer metric attributes." attributes: - ref: pool - brief: Name of the memory pool. + brief: Name of the buffer pool. examples: [ "mapped", "direct" ] note: > Pool names are generally obtained via diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index e7d9d975d82..61dc41501b4 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -333,7 +333,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `pool` | string | Name of the memory pool. [1] | `mapped`; `direct` | Recommended | +| `pool` | 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()). @@ -351,7 +351,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `pool` | string | Name of the memory pool. [1] | `mapped`; `direct` | Recommended | +| `pool` | 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()). @@ -369,7 +369,7 @@ This metric is [recommended](../metric-requirement-level.md#recommended). | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `pool` | string | Name of the memory pool. [1] | `mapped`; `direct` | Recommended | +| `pool` | 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()). From 11e28edeaae2b70d803697882a8c9daf3bb809b8 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Mon, 24 Apr 2023 14:13:37 -0500 Subject: [PATCH 7/7] Add log documents to specification README.md (#3435) --- CHANGELOG.md | 3 +++ specification/README.md | 5 +++++ 2 files changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1961e9131b6..deb54bb3e4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,9 @@ release. ### Common +- Add log entries to specification README.md contents. + ([#3435](https://github.com/open-telemetry/opentelemetry-specification/pull/3435)) + ## v1.20.0 (2023-04-07) ### Context diff --git a/specification/README.md b/specification/README.md index 7cdde2b5c42..60deab9e11d 100644 --- a/specification/README.md +++ b/specification/README.md @@ -25,9 +25,13 @@ cascade: - [Baggage](baggage/api.md) - [Tracing](trace/api.md) - [Metrics](metrics/api.md) + - Logs + - [Bridge API](logs/bridge-api.md) + - [Event API](logs/event-api.md) - SDK Specification - [Tracing](trace/sdk.md) - [Metrics](metrics/sdk.md) + - [Logs](logs/sdk.md) - [Resource](resource/sdk.md) - [Configuration](sdk-configuration.md) - Data Specification @@ -39,6 +43,7 @@ cascade: - [OpenCensus](compatibility/opencensus.md) - [OpenTracing](compatibility/opentracing.md) - [Prometheus and OpenMetrics](compatibility/prometheus_and_openmetrics.md) + - [Trace Context in non-OTLP Log Formats](compatibility/logging_trace_context.md) ## Notation Conventions and Compliance