Update otel metrics for jvm-observ-lib

jvm-observ-lib/README.md

@@ -1,15 +1,17 @@
-# JVM observability lib
+# JVM observability library
 
-This lib can be used to generate dashboards, rows, panels, and alerts for JVM monitoring.
+This library can be used to generate dashboards, rows, panels, and alerts for JVM monitoring.
 
 Supports the following sources:
 
 - `prometheus` (https://prometheus.github.io/client_java/instrumentation/jvm/#jvm-memory-metrics). This also works for jmx_exporter (javaagent mode) starting from 1.0.1 release.
-- `otel` (https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/jmx-metrics/docs/target-systems/jvm.md)
-- `otel_with_suffixes` same as otel with add_metric_suffixes=true in otelcollector
-- `java_micrometer` (springboot) (https://github.com/micrometer-metrics/micrometer/blob/main/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/jvm/JvmMemoryMetrics.java)
+- `otel_with_suffixes` OpenTelemetry JVM metrics following semantic conventions (https://opentelemetry.io/docs/specs/semconv/runtime/jvm-metrics/). Uses metric names like `jvm_memory_used_bytes`, `jvm_gc_duration_seconds`, etc. **Recommended for new deployments. Corresponds to semantic conventions v1.22.0 and later.**
+- `otel_old` Legacy OpenTelemetry JVM metrics (https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/jmx-metrics/docs/target-systems/jvm.md). Uses `process_runtime_jvm_*` metric names. **Corresponds to semantic conventions v1.21.0 and earlier.**
+- `otel_old_with_suffixes` Same as `otel_old` but with Prometheus suffixes added by the OTel collector (`add_metric_suffixes=true`). **Corresponds to semantic conventions v1.21.0 and earlier.**
+- `java_micrometer` (springboot) (https://github.com/micrometer-metrics/micrometer/blob/main/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/jvm/JvmMemoryMetrics.java). Can be seen when Micrometer to OTEL bridge is used.
+- `java_micrometer_with_suffixes` (springboot) same, but with prometheus suffixes
 - `prometheus_old` client_java instrumentation prior to 1.0.0 release: (https://github.com/prometheus/client_java/releases/tag/v1.0.0-alpha-4). This also works for jmx_exporter (javaagent mode) prior to 1.0.1 release.
-- `jmx_exporter`. Works with jmx_exporter (both http and javaagent modes) and the folllowing snippet:
+- `jmx_exporter`. Works with jmx_exporter (both http and javaagent modes) and the following snippet:
 
 ```yaml
 lowercaseOutputName: true
@@ -22,6 +24,43 @@ rules:
   - pattern : java.lang<type=(.*)>
 ```
 
+## OpenTelemetry sources
+
+The library supports multiple OpenTelemetry metric sources to accommodate different deployment scenarios:
+
+### Recommended: `otel_with_suffixes`
+Uses the latest OpenTelemetry JVM semantic conventions with metric names like:
+- `jvm_memory_used_bytes{jvm_memory_type="heap", jvm_memory_pool_name="G1 Eden Space"}`
+- `jvm_gc_duration_seconds_count{jvm_gc_name="G1 Young Generation", jvm_gc_action="end of minor GC"}`
+- `jvm_thread_count{jvm_thread_daemon="true", jvm_thread_state="runnable"}`
+
+### Legacy: `otel_old` and `otel_old_with_suffixes`
+For backward compatibility with existing OpenTelemetry deployments using:
+- `process_runtime_jvm_memory_usage{type="heap", pool="G1 Eden Space"}`
+- `process_runtime_jvm_gc_duration_count{gc="G1 Young Generation", action="end of minor GC"}`
+- `process_runtime_jvm_threads_count{daemon="true"}`
+
+### Migration path
+1. **Current users of `otel`** → migrate to `otel_old` (no functional change)
+2. **Current users of `otel_with_suffixes`** → migrate to `otel_old_with_suffixes` (no functional change)  
+3. **New deployments** → use `otel_with_suffixes` for semantic conventions compliance
+4. **Upgrade path** → `otel_old*` → `otel_with_suffixes` when updating instrumentation
+
+## OpenTelemetry Semantic Conventions Migration
+
+The OpenTelemetry project introduced breaking changes to JVM metric names in semantic conventions v1.22.0 (October 2023):
+
+- **v1.21.0 and earlier**: Used `process_runtime_jvm_*` metric names (supported by `otel_old` sources)
+- **v1.22.0 and later**: Changed to `jvm.*` metric names (supported by `otel_with_suffixes` sources)
+
+### When to use each source:
+
+- Use `otel_old*` sources if your instrumentation produces `process_runtime_jvm_*` metrics
+- Use `otel_with_suffixes` if your instrumentation produces `jvm.*` metrics  
+- Check your OpenTelemetry Java instrumentation version:
+  - **Before semantic conventions v1.22.0**: Use `otel_old*` sources
+  - **After semantic conventions v1.22.0**: Use `otel_with_suffixes` sources
+
 
 ## Import
 
@@ -45,7 +84,7 @@ local jvm =
         uid: 'jvm-sample',
         dashboardNamePrefix: 'JVM',
         dashboardTags: ['java', 'jvm'],
-        metricsSource: 'java_micrometer', // or java_otel, prometheus,
+        metricsSource: 'otel_with_suffixes', // or java_micrometer_with_suffixes, prometheus, etc.
     }
   );
 jvm.asMonitoringMixin()

jvm-observ-lib/config.libsonnet

@@ -6,7 +6,8 @@
   uid: 'jvm',
   dashboardNamePrefix: '',
   dashboardTags: ['java', 'jvm'],
-  metricsSource: ['java_micrometer', 'prometheus', 'prometheus_old', 'otel', 'otel_with_suffixes', 'jmx_exporter'],
+  // generate only popular by default. See others options in README.
+  metricsSource: ['java_micrometer', 'prometheus', 'otel_old_with_suffixes', 'otel_with_suffixes', 'jmx_exporter'],
   signals+:
     {
       memory: (import './signals/memory.libsonnet')(this),