finish jetty 12 support + doc

Author: SylvainJuge

instrumentation/jmx-metrics/library/jetty.md

@@ -8,7 +8,7 @@ The metrics captured and their respective attributes depend on the Jetty version
 
 ## Jetty 12 and later
 
-Those metrics require the following Jetty modules to be enabled : `jmx`, `http` and `statistics`.
+Those metrics require the following Jetty modules to be enabled : `jmx`, `http`, `statistics`, `sessions` and at least one of `ee8-deploy`, `ee9-deploy` or `ee10-deploy`.
 
 | Metric Name             | Type          | Attributes                                 | Description                               |
 |-------------------------|---------------|--------------------------------------------|-------------------------------------------|
@@ -17,17 +17,37 @@ Those metrics require the following Jetty modules to be enabled : `jmx`, `http`
 | jetty.thread.busy.count | UpDownCounter | jetty.thread.pool.id, jetty.thread.context | The current number of busy threads        |
 | jetty.thread.idle.count | UpDownCounter | jetty.thread.pool.id, jetty.thread.context | The current number of idle threads        |
 | jetty.thread.queue.size | UpDownCounter | jetty.thread.pool.id, jetty.thread.context | The current job queue size                |
-| jetty.io.select.count   | Counter       | jetty.selector.resource, jetty.selector.id | The number of select calls                |
+| jetty.io.select.count   | Counter       | jetty.selector.context, jetty.selector.id  | The number of select calls                |
+| jetty.session.count     | UpDownCounter | jetty.context, jetty.session.cache.id      | Current number of active sessions         |
+| jetty.session.count.max | Gauge         | jetty.context, jetty.session.cache.id      | Maximum number of active sessions         |
+
+- `jetty.context` corresponds to the deployed application subfolder in `webapps` folder.
+- `jetty.selector.context` is a technical string identifier, high cardinality with values like `HTTP_1_1@7674f035` but stable per Jetty process instance
+- `jetty.selector.id` is a technical numeric identifier, usually with low cardinality between `0` and `9`.
+- `jetty.session.cache.id` is a technical numeric identifier, usually single `0` value is used
+- `jetty.thread.context` is a technical string identifier, high cardinality with values like `Server@5a411614` but stable per Jetty process instance
+- `jetty.thread.pool.id` is a technical numeric identifier, usually single `0` value is used
 
 ## Jetty 9 to 11
 
 Those metrics require the following Jetty modules to be enabled : `jmx`, `http` and `stats`.
 
-| Metric Name             | Type          | Attributes                                 | Description                               |
-|-------------------------|---------------|--------------------------------------------|-------------------------------------------|
-| jetty.thread.count      | UpDownCounter | jetty.thread.pool.id                       | The current number of threads             |
-| jetty.thread.limit      | UpDownCounter | jetty.thread.pool.id                       | The maximum number of threads in the pool |
-| jetty.thread.busy.count | UpDownCounter | jetty.thread.pool.id                       | The current number of busy threads        |
-| jetty.thread.idle.count | UpDownCounter | jetty.thread.pool.id                       | The current number of idle threads        |
-| jetty.thread.queue.size | UpDownCounter | jetty.thread.pool.id                       | The current job queue size                |
-| jetty.io.select.count   | Counter       | jetty.selector.resource, jetty.selector.id | The number of select calls                |
+| Metric Name                 | Type          | Attributes                                | Description                               |
+|-----------------------------|---------------|-------------------------------------------|-------------------------------------------|
+| jetty.thread.count          | UpDownCounter | jetty.thread.pool.id                      | The current number of threads             |
+| jetty.thread.limit          | UpDownCounter | jetty.thread.pool.id                      | The maximum number of threads in the pool |
+| jetty.thread.busy.count     | UpDownCounter | jetty.thread.pool.id                      | The current number of busy threads        |
+| jetty.thread.idle.count     | UpDownCounter | jetty.thread.pool.id                      | The current number of idle threads        |
+| jetty.thread.queue.size     | UpDownCounter | jetty.thread.pool.id                      | The current job queue size                |
+| jetty.io.select.count       | Counter       | jetty.selector.context, jetty.selector.id | The number of select calls                |
+| jetty.session.created.count | Counter       | jetty.context, jetty.session.handler.id   | The total number of created sessions      |
+| jetty.session.duration.sum  | Gauge         | jetty.context, jetty.session.handler.id   | The cumulated session duration            |
+| jetty.session.duration.max  | Gauge         | jetty.context, jetty.session.handler.id   | The maximum session duration              |
+| jetty.session.duration.mean | Gauge         | jetty.context, jetty.session.handler.id   | The mean session duration                 |
+
+- `jetty.context` corresponds to the deployed application subfolder in `webapps` folder.
+- `jetty.selector.context` is a technical string identifier, high cardinality with values like `HTTP_1_1@7674f035` but stable per Jetty process instance
+- `jetty.selector.id` is a technical numeric identifier, usually with low cardinality between `0` and `9`.
+- `jetty.session.cache.id` is a technical numeric identifier, usually single `0` value is used
+- `jetty.thread.pool.id` is a technical numeric identifier, usually single `0` value is used
+- `jetty.session.handler.id` is a technical numeric identifier, usually single `0` value is used

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

@@ -66,10 +66,10 @@ rules:
 
   - bean: org.eclipse.jetty.io:context=*,type=managedselector,id=*
     metricAttribute:
-      # 'id' is a numerical value in [0,9] by default
-      jetty.selector.context: param(context)
       # 'context' is a high cardinality value like 'HTTP_1_1@7674f035' but likely stable for the
       # duration of the jetty process lifecycle
+      jetty.selector.context: param(context)
+      # 'id' is a numerical value in [0,9] by default
       jetty.selector.id: param(id)
     mapping:
       # jetty.select.count
@@ -81,7 +81,6 @@ rules:
 
   # Session metrics for Jetty 12
   - bean: org.eclipse.jetty.session:context=*,type=defaultsessioncache,id=*
-    # org.eclipse.jetty.session:context=ROOT,type=defaultsessioncache,id=0
     prefix: jetty.session.
     unit: "{session}"
     metricAttribute:

instrumentation/jmx-metrics/library/src/test/java/io/opentelemetry/instrumentation/jmx/rules/JettyIntegrationTest.java

@@ -41,7 +41,12 @@ void testCollectedMetrics(int jettyMajorVersion) {
     Set<String> jettyModules = new HashSet<>(Arrays.asList("jmx", "http"));
     if (jettyMajorVersion >= 12) {
       jettyModules.add("statistics");
+      // required for session management
+      jettyModules.add("sessions");
+      // required for deployment support in 'webapps' folder
+      jettyModules.add("ee10-deploy");
     } else {
+      // with older versions deployment and session management are available by default
       jettyModules.add("stats");
     }
     String addModulesArg = "--add-to-startd=" + String.join(",", jettyModules);
@@ -152,7 +157,7 @@ private static MetricsVerifier createMetricsVerifier(int jettyMajorVersion) {
               "jetty.session.count.max",
               metric ->
                   metric
-                      .isUpDownCounter()
+                      .isGauge()
                       .hasDescription("Maximum number of active sessions")
                       .hasUnit("{session}")
                       .hasDataPointsWithAttributes(