feat(components): add management to observability services

Ref CAMEL-21462

components/camel-observability-services/pom.xml

@@ -49,6 +49,10 @@
             <groupId>org.apache.camel</groupId>
             <artifactId>camel-health</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.apache.camel</groupId>
+            <artifactId>camel-management</artifactId>
+        </dependency>
     </dependencies>
 
 </project>

components/camel-observability-services/src/main/docs/observability-services.adoc

@@ -28,6 +28,7 @@ WARNING: the customization of the configuration for this component is not availa
 The presence of this dependency will provide the following components:
 
 * camel-health
+* camel-management
 * camel-micrometer-prometheus
 * camel-opentelemetry
 
@@ -59,8 +60,24 @@ docker run -p 4318:4318 otel/opentelemetry-collector-contrib:0.113.0
 
 This service will expose the port `4318` to `localhost` which is the default setting expected by the agent. You can change this configuration accordingly.
 
-=== Agent configuration
+=== OpenTelemetry Agent configuration
 
-In order to collect the metrics exposed by the application, and, depending on the runtime of choice, you will need to start your Camel application with a Java agent, whose goal is to push those metrics to the OpenTelemetry compatible collector server. Follow the instructions provided in xref:others:opentelemetry.adoc#OpenTelemetry-JavaAgent[Opentelemetry Java Agent configuration]
+In order to collect the metrics exposed by the application, and, depending on the runtime of choice, you will need to start your Camel application with a Java agent, whose goal is to push those metrics to the OpenTelemetry compatible collector server. Follow the instructions provided in xref:others:opentelemetry.adoc#OpenTelemetry-JavaAgent[Opentelemetry Java Agent configuration].
 
-WARNING: due to https://issues.apache.org/jira/browse/CAMEL-21460[a flaw in the alignment of Opentelemetry dependencies in Spring Boot] runtime you may hit a runtime error until the Spring Boot BOM dependencies is aligning the Opentelemetry dependencies. Be mindful of the required workaround required for this to work until the issue is fixed.
+WARNING: due to https://issues.apache.org/jira/browse/CAMEL-21460[a flaw in the alignment of Opentelemetry dependencies in Spring Boot] runtime you may hit a runtime error until the Spring Boot BOM dependencies is aligning the Opentelemetry dependencies. Be mindful of the required workaround required for this to work until the issue is fixed.
+
+== JMX configuration
+
+The presence of this component implies the presence of `camel-management` component. This is in charge to include information about Camel application status in JMX format.
+
+NOTE: the presence of this components automatically enable the collection of the JMX metrics. This should be negligible from performance point of view, however, you may want to disable that running the application with `-Dorg.apache.camel.jmx.disabled=true` JVM option.
+
+=== Testing JMX
+
+An easy way to test the JMX configuration is to run a JMX client such as `jconsole`. Just execute it from the same machine where the Camel application you want to monitor is running and you can quickly verify the status of the application (selecting the local process). There is the possibility to https://docs.oracle.com/javase/tutorial/jmx/remote/jconsole.html[expose the JMX remotely as well].
+
+Exposing remote JMX would require some security setting in place to avoid disclosing sensitive information. Also mind that it may not be suitable for cloud development (ie, Kubernetes) due to possible limitations within the binary protocols used by the JMX technology. In this case it is recommended the usage of a JSR 160 compatible Java agent.
+
+=== JMX Agent configuration
+
+When dealing with JMX you may want to expose the information available via HTTP(S) protocol which would make JMX more suitable to cloud based development. A possible way to expose the information is to use a JSR 160 compatible Java agent, whose goal is to interact as an adapter interface towards JMX, exposing an HTTP based service instead. Follow the instructions provided in xref:manual:jmx.adoc#_how_to_use_a_java_agent[JMX Java Agent configuration].

docs/user-manual/modules/ROOT/pages/jmx.adoc

@@ -1,14 +1,14 @@
 = JMX
 
-Camel has optional support for JMX management, which is 
+Camel has optional support for JMX management, which is
 part of the `camel-management` and `camel-management-api` JARs.
 
 == Using JMX to manage Apache Camel
 
 The JMX instrumentation agent is enabled in Camel when the `camel-management`
 JAR is included in the classpath. Once enabled, the Camel runtime creates and
-registers MBean management objects with a `MBeanServer` instance in the VM. 
-This allows Camel users to instantly obtain insights into how Camel routes 
+registers MBean management objects with a `MBeanServer` instance in the VM.
+This allows Camel users to instantly obtain insights into how Camel routes
 perform down to the individual processor level.
 
 The high level supported types of management objects are:
@@ -29,7 +29,7 @@ addition to performance counter-attributes.
 == Disabling or enabling Camel JMX
 
 JMX is only enabled in Camel when the `camel-management` JAR is included on the
-classpath. To quickly enable or disable JMX, simply add or remove this JAR 
+classpath. To quickly enable or disable JMX, simply add or remove this JAR
 from the classpath.
 
 It is also possible to enable or disable JMX via configuration as documented below.
@@ -334,3 +334,55 @@ declared that the `EndpointUri` JMX attribute is masked:
 String getEndpointUri();
 ----
 
+== Expose JMX metrics remotely
+
+When you're running the application locally, you can use any JMX client (ie, `jconsole`) to access to the process and the the statistics exposed. However, you may want to expose these metrics remotely in order to be accessed by any remote process: https://docs.oracle.com/javase/tutorial/jmx/remote/jconsole.html[expose the JMX metrics remotely].
+
+NOTE: make sure to properly secure the access to JMX services for production workloads.
+
+== How to use a Java Agent
+
+Exposing the JMX metrics with its native protocol may not always be possible (ie, for firewall limitations, security, etc). In this case you may recur to the availability of JSR 160 compatible Java Agents (for instance, https://jolokia.org/reference/html/manual/agents.html#agents-jvm[Jolokia]), which goal is to adapt the JMX interface with HTTP based protocol. With this approach you can run you application attaching a Java Agent whose goal will be to take care of exposing JMX via HTTP. As an example:
+```
+java -javaagent:jsr160-javaagent.jar -jar my-camel-app.jar
+```
+will expose certain endpoints (depending on the implementation) which would let you interact with JMX.
+
+Depending on the implementation you will need to provide to a different set of agent configuration. For example, if you're running Jolokia agent, then, you will need to run this configuration to expose a plain HTTP unsecure service:
+```
+java -javaagent:jolokia-agent-jvm-2.1.1-javaagent.jar=protocol=http,useSslClientAuthentication=false,discoveryEnabled=false,host=*,extendedClientCheck=false -jar my-camel-app.jar
+```
+From that moment onward you will be able to access the service via:
+
+```
+
+$ curl http://localhost:8778/jolokia/list/org.apache.camel | jq | more
+{
+  "request": {
+    "path": "org.apache.camel",
+    "type": "list"
+  },
+  "value": {
+    "context=camel-1,name=\"platform-http\",type=components": {
+      "op": {
+        "getCamelId": {
+          "args": [],
+          "ret": "java.lang.String",
+          "desc": "CamelId"
+        },
+        "isHealthCheckSupported": {
+          "args": [],
+          "ret": "boolean",
+          "desc": "HealthCheckSupported"
+        },
+        "getComponentName": {
+          "args": [],
+          "ret": "java.lang.String",
+          "desc": "ComponentName"
+        },
+...
+```
+
+Each agent implementation may provide a different way to get and execute actions on the various endpoint.
+
+WARNING: make sure to properly secure the access to the HTTP services for production workloads checking the specific agent configuration documentation.