From d2a5612e0e4611245ba2017c1a2ae38e644c7854 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 23 Oct 2023 01:22:29 -0700 Subject: [PATCH] Introduce `jvm.thread.daemon` and `jvm.thread.state` attributes (#297) Co-authored-by: Joao Grassi --- CHANGELOG.md | 3 +++ docs/general/attributes.md | 1 - docs/runtime/jvm-metrics.md | 23 ++++++++++++++++++++--- model/general.yaml | 3 --- model/metrics/jvm-metrics.yaml | 29 ++++++++++++++++++++++++++++- schema-next.yaml | 8 ++++++++ 6 files changed, 59 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f943bf69..2e286d80d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,9 @@ release. ([#410](https://github.com/open-telemetry/semantic-conventions/pull/410)) - BREAKING: Factor in `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`. ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411)) +- Remove `thread.daemon`, and introduce `jvm.thread.daemon` instead. + Introduce `jvm.thread.state` attribute and add it to `jvm.thread.count` metric. + ([#297](https://github.com/open-telemetry/semantic-conventions/pull/297)) ### Features diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 1b082c164..047ae0274 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -358,7 +358,6 @@ a thread that started a span. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | | `thread.id` | int | Current "managed" thread ID (as opposed to OS thread ID). | `42` | Recommended | | `thread.name` | string | Current thread name. | `main` | Recommended | diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md index 2ec4231fc..f36246c65 100644 --- a/docs/runtime/jvm-metrics.md +++ b/docs/runtime/jvm-metrics.md @@ -189,8 +189,13 @@ of `[]` (single bucket histogram capturing count, sum, min, max). ### Metric: `jvm.thread.count` This metric is [recommended][MetricRecommended]. -This metric is obtained from [`ThreadMXBean#getDaemonThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getDaemonThreadCount--) and -[`ThreadMXBean#getThreadCount()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadCount--). +This metric is obtained from a combination of + +* [`ThreadMXBean#getAllThreadIds()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getAllThreadIds--) +* [`ThreadMXBean#getThreadInfo()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadMXBean.html#getThreadInfo-long:A-) +* [`ThreadInfo#getThreadState()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/ThreadInfo.html#getThreadState--) +* [`ThreadInfo#isDaemon()`](https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/ThreadInfo.html#isDaemon()) (requires Java 9+) + Note that this is the number of platform threads (as opposed to virtual threads). @@ -202,7 +207,19 @@ Note that this is the number of platform threads (as opposed to virtual threads) | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`thread.daemon`](../general/attributes.md) | boolean | Whether the thread is daemon or not. | | Recommended | +| `jvm.thread.daemon` | boolean | Whether the thread is daemon or not. | | Recommended | +| `jvm.thread.state` | string | State of the thread. | `runnable`; `blocked` | Recommended | + +`jvm.thread.state` MUST be one of the following: + +| Value | Description | +|---|---| +| `new` | A thread that has not yet started is in this state. | +| `runnable` | A thread executing in the Java virtual machine is in this state. | +| `blocked` | A thread that is blocked waiting for a monitor lock is in this state. | +| `waiting` | A thread that is waiting indefinitely for another thread to perform a particular action is in this state. | +| `timed_waiting` | A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state. | +| `terminated` | A thread that has exited is in this state. | ## JVM Classes diff --git a/model/general.yaml b/model/general.yaml index 4f387bac6..5994c16ff 100644 --- a/model/general.yaml +++ b/model/general.yaml @@ -52,9 +52,6 @@ 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 diff --git a/model/metrics/jvm-metrics.yaml b/model/metrics/jvm-metrics.yaml index 4306fc239..c837145a8 100644 --- a/model/metrics/jvm-metrics.yaml +++ b/model/metrics/jvm-metrics.yaml @@ -90,8 +90,35 @@ groups: instrument: updowncounter unit: "{thread}" attributes: - - ref: thread.daemon + - id: jvm.thread.daemon + type: boolean requirement_level: recommended + brief: "Whether the thread is daemon or not." + - id: jvm.thread.state + requirement_level: recommended + type: + allow_custom_values: false + members: + - id: new + value: 'new' + brief: 'A thread that has not yet started is in this state.' + - id: runnable + value: 'runnable' + brief: 'A thread executing in the Java virtual machine is in this state.' + - id: blocked + value: 'blocked' + brief: 'A thread that is blocked waiting for a monitor lock is in this state.' + - id: waiting + value: 'waiting' + brief: 'A thread that is waiting indefinitely for another thread to perform a particular action is in this state.' + - id: timed_waiting + value: 'timed_waiting' + brief: 'A thread that is waiting for another thread to perform an action for up to a specified waiting time is in this state.' + - id: terminated + value: 'terminated' + brief: 'A thread that has exited is in this state.' + brief: "State of the thread." + examples: ["runnable", "blocked"] - id: metric.jvm.class.loaded type: metric diff --git a/schema-next.yaml b/schema-next.yaml index 8fe76165a..4c3647ce4 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,14 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + metrics: + changes: + # https://github.com/open-telemetry/semantic-conventions/pull/20 + - rename_attributes: + attribute_map: + thread.daemon: jvm.thread.daemon + apply_to_metrics: + - jvm.thread.count 1.22.0: spans: changes: