Skip to content

Commit ed69672

Browse files
SylvainJugeSylvainJuge
committed
add jvm yaml + some docs
fix some markdown fix yaml link fix another link add test dependencies + path to agent jar fix jvm metrics definitions add jvm rules to library add test infrastructure + jvm metrics tests work around checkstyle rules add missing jvm.memory.type attribute add comment for jvm memory type on heap only remove duplicated yaml fix typo in readme add jvm.memory.type in jvm metrics docs add test for jvm.cpu.time reformat fix jvm.cpu.time metric name
1 parent 680da24 commit ed69672

File tree

12 files changed

+1271
-1
lines changed

12 files changed

+1271
-1
lines changed

‎instrumentation/jmx-metrics/javaagent/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,7 +302,7 @@ rules:
302302
unit: By
303303
metricAttribute:
304304
jvm.memory.pool.name : param(name)
305-
jvm.memory.type: lowercase(beanattr(type))
305+
jvm.memory.type: lowercase(beanattr(Type))
306306
```
307307

308308
For now, only the `lowercase` transformation is supported, other additions might be added in the future if needed.

‎instrumentation/jmx-metrics/library/build.gradle.kts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
2+
13
plugins {
24
id("otel.library-instrumentation")
35
}
@@ -6,4 +8,28 @@ dependencies {
68
implementation("org.snakeyaml:snakeyaml-engine")
79

810
testImplementation(project(":testing-common"))
11+
testImplementation("org.testcontainers:testcontainers")
12+
13+
testImplementation("org.testcontainers:junit-jupiter")
14+
testImplementation("com.linecorp.armeria:armeria-junit5:1.31.3")
15+
testImplementation("com.linecorp.armeria:armeria-junit5:1.31.3")
16+
testImplementation("com.linecorp.armeria:armeria-grpc:1.31.3")
17+
testImplementation("io.opentelemetry.proto:opentelemetry-proto:1.5.0-alpha")
18+
}
19+
20+
tasks {
21+
test {
22+
// get packaged agent jar for testing
23+
val shadowTask = project(":javaagent").tasks.named<ShadowJar>("shadowJar").get()
24+
25+
dependsOn(shadowTask)
26+
27+
inputs.files(layout.files(shadowTask))
28+
.withPropertyName("javaagent")
29+
.withNormalizer(ClasspathNormalizer::class)
30+
31+
doFirst {
32+
jvmArgs("-Dio.opentelemetry.javaagent.path=${shadowTask.archiveFile.get()}")
33+
}
34+
}
935
}

‎instrumentation/jmx-metrics/library/jvm.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# JVM Metrics
2+
3+
Here is the list of metrics based on MBeans exposed by the JVM and that are defined in [`jvm.yaml`](./src/main/resources/jmx/rules/jvm.yaml).
4+
5+
Those metrics are defined in the [JVM runtime metrics semantic conventions](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/).
6+
7+
| Metric Name | semconv maturity | Type | Attributes | Description |
8+
|---------------------------------------------------------------------------------------------------------------------------------------|:-----------------|---------------|---------------------------------------|----------------------------------------------------|
9+
| [jvm.memory.used](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmmemoryused) | stable | UpDownCounter | jvm.memory.pool.name, jvm.memory.type | Used memory |
10+
| [jvm.memory.committed](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmmemorycommitted) | stable | UpDownCounter | jvm.memory.pool.name, jvm.memory.type | Committed memory |
11+
| [jvm.memory.limit](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmmemorylimit) | stable | UpDownCounter | jvm.memory.pool.name, jvm.memory.type | Max obtainable memory |
12+
| [jvm.memory.init](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmmemoryinit) | experimental | UpDownCounter | jvm.memory.pool.name, jvm.memory.type | Initial memory requested |
13+
| [jvm.memory.used_after_last_gc](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmmemoryused_after_last_gc) | stable | UpDownCounter | jvm.memory.pool.name, jvm.memory.type | Memory used after latest GC |
14+
| [jvm.thread.count](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmthreadcount) | stable | UpDownCounter | [^1] | Threads count |
15+
| [jvm.class.loaded](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmclassloaded) | stable | Counter | | Classes loaded since JVM start |
16+
| [jvm.class.unloaded](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmclassunloaded) | stable | Counter | | Classes unloaded since JVM start |
17+
| [jvm.class.count](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmclasscount) | stable | UpDownCounter | | Classes currently loaded count |
18+
| [jvm.cpu.count](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmcpucount) | stable | UpDownCounter | | Number of CPUs available |
19+
| [jvm.cpu.recent_utilization](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmcpurecent_utilization) | stable | Gauge | | Recent CPU utilization for process reported by JVM |
20+
| [jvm.system.cpu.load_1m](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmsystemcpuload_1m) | experimental | Gauge | | Average CPU load reported by JVM |
21+
| [jvm.system.cpu.recent_utilization](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmcpurecent_utilization) | experimental | Gauge | | Recent CPU utilization reported by JVM |
22+
| [jvm.buffer.memory.used](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmbuffermemoryused) | experimental | UpDownCounter | jvm.buffer.pool.name | Memory used by buffers |
23+
| [jvm.buffer.memory.limit](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmbuffermemorylimit) | experimental | UpDownCounter | jvm.buffer.pool.name | Maximum memory usage for buffers |
24+
| [jvm.buffer.memory.count](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmbuffermemorycount) | experimental | UpDownCounter | jvm.buffer.pool.name | Buffers count |
25+
26+
## Limitations and unsupported metrics
27+
28+
There are a few limitations to the JVM metrics that are captured through the JMX interface with declarative YAML.
29+
Using the [runtime-telemetry](../../runtime-telemetry) modules with instrumentation allow to capture metrics without those limitations.
30+
31+
[^1]: `jvm.thread.daemon` and `jvm.thread.state` attributes are not supported.
32+
33+
- [jvm.gc.duration](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmgcduration) metric is not supported as it is only exposed through JMX notifications which are not supported with YAML.
34+
- [jvm.cpu.time](https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/#metric-jvmcputime) metric is not supported yet due to lack of unit conversion, see [#13369](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/13369) for details.

‎instrumentation/jmx-metrics/library/src/main/resources/jmx/rules/jvm.yaml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
3+
rules:
4+
5+
- bean: java.lang:type=MemoryPool,name=*
6+
prefix: jvm.memory.
7+
type: updowncounter
8+
unit: By
9+
metricAttribute:
10+
jvm.memory.pool.name: param(name)
11+
jvm.memory.type: lowercase(beanattr(Type))
12+
mapping:
13+
# jvm.memory.used
14+
Usage.used:
15+
metric: used
16+
desc: Measure of memory used.
17+
# jvm.memory.committed
18+
Usage.committed:
19+
metric: committed
20+
desc: Measure of memory committed.
21+
# jvm.memory.limit
22+
Usage.max:
23+
metric: limit
24+
desc: Measure of max obtainable memory.
25+
# jvm.memory.init (experimental)
26+
Usage.init:
27+
metric: init
28+
desc: Measure of initial memory requested.
29+
# jvm.memory.used_after_last_gc
30+
# note: metric attribute "jvm.memory.type" will always be "heap" as GC only manages heap
31+
CollectionUsage.used:
32+
metric: used_after_last_gc
33+
desc: Measure of memory used, as measured after the most recent garbage collection event on this pool.
34+
35+
- bean: java.lang:type=Threading
36+
prefix: jvm.thread.
37+
mapping:
38+
# jvm.thread.count
39+
# limitation: 'jvm.thread.daemon' and 'jvm.thread.state' metric attributes are not provided
40+
ThreadCount:
41+
metric: count
42+
type: updowncounter
43+
unit: "{thread}"
44+
desc: Number of executing platform threads.
45+
46+
- bean: java.lang:type=ClassLoading
47+
prefix: jvm.class.
48+
type: updowncounter
49+
unit: "{class}"
50+
mapping:
51+
# jvm.class.loaded
52+
TotalLoadedClassCount:
53+
metric: loaded
54+
desc: Number of classes loaded since JVM start.
55+
# jvm.class.unloaded
56+
UnloadedClassCount:
57+
metric: unloaded
58+
desc: Number of classes unloaded since JVM start.
59+
# jvm.class.count
60+
LoadedClassCount:
61+
metric: count
62+
desc: Number of classes currently loaded.
63+
64+
- bean: java.lang:type=OperatingSystem
65+
prefix: jvm.
66+
# TODO: drop negative values once https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/13589 is merged
67+
# dropNegativeValues: true
68+
mapping:
69+
# jvm.cpu.count
70+
AvailableProcessors:
71+
metric: cpu.count
72+
type: updowncounter
73+
unit: "{cpu}"
74+
desc: Number of processors available to the Java virtual machine.
75+
# jvm.cpu.time
76+
ProcessCpuTime:
77+
metric: cpu.time
78+
type: counter
79+
sourceUnit: ns
80+
unit: s
81+
desc: CPU time used by the process as reported by the JVM.
82+
# jvm.cpu.recent_utilization
83+
ProcessCpuLoad:
84+
metric: cpu.recent_utilization
85+
type: gauge
86+
unit: '1'
87+
desc: Recent CPU utilization for the process as reported by the JVM.
88+
# jvm.system.cpu.load_1m (experimental)
89+
SystemLoadAverage:
90+
metric: system.cpu.load_1m
91+
type: gauge
92+
unit: "{run_queue_item}"
93+
desc: Average CPU load of the whole system for the last minute as reported by the JVM.
94+
# jvm.system.cpu.utilization (experimental)
95+
SystemCpuLoad:
96+
metric: system.cpu.utilization
97+
type: gauge
98+
unit: '1'
99+
desc: Recent CPU utilization for the whole system as reported by the JVM.
100+
101+
- bean: java.nio:name=*,type=BufferPool
102+
prefix: jvm.buffer.
103+
type: updowncounter
104+
metricAttribute:
105+
jvm.buffer.pool.name: param(name)
106+
mapping:
107+
# jvm.buffer.memory.used (experimental)
108+
MemoryUsed:
109+
metric: memory.used
110+
unit: By
111+
desc: Measure of memory used by buffers.
112+
# jvm.buffer.memory.limit (experimental)
113+
TotalCapacity:
114+
metric: memory.limit
115+
unit: By
116+
desc: Measure of total memory capacity of buffers.
117+
# jvm.buffer.count (experimental)
118+
Count:
119+
metric: count
120+
unit: "{buffer}"
121+
desc: Number of buffers in the pool.

0 commit comments

Comments
 (0)