Release notes changes related to Tomcat metrics updates (#13973)

Co-authored-by: Sylvain Juge <[email protected]>
Co-authored-by: Trask Stalnaker <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+### Migration notes
+- Tomcat metrics definitions provided by JMX Metric Insight subsystem
+  - metric `http.server.tomcat.errorCount` --> `tomcat.error.count`
+    - attribute: `name` --> `tomcat.request.processor.name`
+    - type: Gauge --> Counter
+  - metric `http.server.tomcat.requestCount` --> `tomcat.request.count`
+    - attribute: `name` --> `tomcat.request.processor.name`
+    - type: Gauge --> Counter
+  - metric `http.server.tomcat.maxTime` --> `tomcat.request.duration.max`
+    - attribute: `name` --> `tomcat.request.processor.name`
+    - unit: `ms` --> `s`
+  - metric `http.server.tomcat.processingTime` --> `tomcat.request.duration.sum`
+    - attribute: `name` --> `tomcat.request.processor.name`
+    - unit: `ms` --> `s`
+  - metric `http.server.tomcat.traffic` --> `tomcat.network.io`
+    - attribute: `name` --> `tomcat.request.processor.name`, `direction` --> `network.io.direction`
+  - metric `http.server.tomcat.sessions.activeSessions` --> `tomcat.session.active.count`
+    - attribute: `context` --> `tomcat.context`
+  - metric `http.server.tomcat.threads` split into two metrics: `tomcat.thread.count` and `tomcat.thread.busy.count`
+    - attribute: `name` --> `tomcat.thread.pool.name`, `state` removed
+
+### 📈 Enhancements
+
+- **JMX Metric Insight**: improved Tomcat metrics alignment to semconv (see Migration notes above for details) and added new Tomcat metrics: `tomcat.session.active.limit`, `tomcat.thread.limit`
+  ([#13650](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/13650))
+
+
 ## Version 2.16.0 (2025-05-15)
 
 ### ⚠️⚠️ Breaking changes ⚠️⚠️
@@ -11,7 +38,6 @@
 - Remove deprecated property for disabling kafka metrics
   ([#13803](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/13803))
 
-
 ### 🌟 New javaagent instrumentation
 
 - Add Avaje Jex Instrumentation