HawtIO Diagnostic Console Guide

1. In the settings.xml file, add repository elements for the Red Hat repositories as shown in this example:

   <?xml version="1.0"?>
   <settings>
   
     <profiles>
       <profile>
         <id>extra-repos</id>
         <activation>
           <activeByDefault>true</activeByDefault>
         </activation>
         <repositories>
          <repository>
            <id>redhat-ga-repository</id>
            <url>https://maven.repository.redhat.com/ga</url>
            <releases>
              <enabled>true</enabled>
            </releases>
            <snapshots>
              <enabled>false</enabled>
            </snapshots>
           </repository>
           <repository>
             <id>redhat-ea-repository</id>
             <url>https://maven.repository.redhat.com/earlyaccess/all</url>
             <releases>
               <enabled>true</enabled>
             </releases>
             <snapshots>
               <enabled>false</enabled>
             </snapshots>
           </repository>
         </repositories>
         <pluginRepositories>
           <pluginRepository>
             <id>redhat-ga-repository</id>
             <url>https://maven.repository.redhat.com/ga</url>
             <releases>
               <enabled>true</enabled>
             </releases>
             <snapshots>
               <enabled>false</enabled>
             </snapshots>
           </pluginRepository>
           <pluginRepository>
             <id>redhat-ea-repository</id>
             <url>https://maven.repository.redhat.com/earlyaccess/all</url>
             <releases>
               <enabled>true</enabled>
             </releases>
             <snapshots>
               <enabled>false</enabled>
             </snapshots>
           </pluginRepository>
         </pluginRepositories>
       </profile>
     </profiles>
   
     <activeProfiles>
       <activeProfile>extra-repos</activeProfile>
     </activeProfiles>
   
   </settings>

   Copy to Clipboard Toggle word wrap

Procedure:

1. Install the latest HawtIO on your machine using the jbang command:

   $ jbang app install -Dhawtio.jbang.version=4.0.0.redhat-00040 hawtio@hawtio/hawtio

   Copy to Clipboard Toggle word wrap
   Note

   This installation method is available only with jbang>=0.115.0.

2. It will install the HawtIO command. Launch a HawtIO instance with the following command:

   $ hawtio

   Copy to Clipboard Toggle word wrap

3. The command will automatically open the console at http://0.0.0.0:8080/hawtio/. To change the port number, run the following command:

   $ hawtio --port 8090

   Copy to Clipboard Toggle word wrap

4. For more information on the configuration options of the CLI, run the following code:

   $ hawtio --help
   Usage: hawtio [-hjoV] [-c=<contextPath>] [-d=<plugins>] [-e=<extraClassPath>]
                 [-H=<host>] [-k=<keyStore>] [-l=<warLocation>] [-p=<port>]
                 [-s=<keyStorePass>] [-w=<war>]
   Run Hawtio
     -c, --context-path=<contextPath>
                         Context path.
     -d, --plugins-dir=<plugins>
                         Directory to search for .war files to install as 3rd
                           party plugins.
     -e, --extra-class-path=<extraClassPath>
                         Extra class path.
     -h, --help          Print usage help and exit.
     -H, --host=<host>   Hostname to listen to.
     -j, --join          Join server thread.
     -k, --key-store=<keyStore>
                         JKS keyStore with the keys for https.
     -l, --war-location=<warLocation>
                         Directory to search for .war files.
     -o, --open-url      Open the web console automatic in the web browser.
     -p, --port=<port>   Port number.
     -s, --key-store-pass=<keyStorePass>
                         Password for the JKS keyStore with the keys for https.
     -V, --version       Print Hawtio version
     -w, --war=<war>     War file or directory of the hawtio web application.

   Copy to Clipboard Toggle word wrap

Procedure:

1. Add io.hawt:hawtio-quarkus and the supporting Camel Quarkus extensions to the dependencies in pom.xml:

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>io.hawt</groupId>
         <artifactId>hawtio-bom</artifactId>
         <version>4.0.0.redhat-00040</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
     <!-- ... other BOMs or dependencies ... -->
   </dependencyManagement>
   
   <dependencies>
     <dependency>
       <groupId>io.hawt</groupId>
       <artifactId>hawtio-quarkus</artifactId>
     </dependency>
   
      <!-- Mandatory for enabling Camel management via JMX / Hawtio -->
     <dependency>
       <groupId>org.apache.camel.quarkus</groupId>
       <artifactId>camel-management-starter</artifactId>
     </dependency>
   
     <!-- (Optional) Required for Hawtio Camel route diagram tab -->
     <dependency>
       <groupId>org.apache.camel.quarkus</groupId>
       <artifactId>camel-quarkus-jaxb</artifactId>
     </dependency>
   
     <!-- ... other dependencies ... -->
   </dependencies>

   Copy to Clipboard Toggle word wrap

2. Run HawtIO with your Quarkus application in development mode as follows:

   mvn compile quarkus:dev

   Copy to Clipboard Toggle word wrap
3. Open http://localhost:8080/hawtio to view the HawtIO console.

Procedure:

1. Add io.hawt:hawtio-springboot and the supporting Camel Spring Boot starters to the dependencies in pom.xml:

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>io.hawt</groupId>
         <artifactId>hawtio-bom</artifactId>
         <version>4.0.0.redhat-00040</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
       <!-- ... other BOMs or dependencies ... -->
     </dependencies>
   </dependencyManagement>
   
   <dependencies>
     <dependency>
       <groupId>io.hawt</groupId>
       <artifactId>hawtio-springboot</artifactId>
     </dependency>
   
      <!-- Mandatory for enabling Camel management via JMX / Hawtio -->
     <dependency>
       <groupId>org.apache.camel.springboot</groupId>
       <artifactId>camel-management-starter</artifactId>
     </dependency>
   
     <!-- (Optional) Required for Hawtio Camel route diagram tab -->
     <dependency>
       <groupId>org.apache.camel.springboot</groupId>
       <artifactId>camel-spring-boot-xml-starter</artifactId>
     </dependency>
   
     <!-- ... other dependencies ... -->
   </dependencies>

   Copy to Clipboard Toggle word wrap

2. Enable the HawtIO and Jolokia endpoints by adding the following lines to application.properties:

   spring.jmx.enabled = true
   management.endpoints.web.exposure.include = hawtio,jolokia

   Copy to Clipboard Toggle word wrap

3. Run HawtIO with your Spring Boot application in development mode as follows:

   mvn spring-boot:run

   Copy to Clipboard Toggle word wrap
4. Open http://localhost:8080/actuator/hawtio to view the HawtIO console.

1. Log in to the OpenShift console in the web browser as a user with cluster admin access.
2. Click Operators and then click OperatorHub.
3. In the search field window, type HawtIO to filter the list of operators. Click HawtIO Operator.

4. In the HawtIO Operator install window, click Install. The Create Operator Subscription form opens:

   1. For Update Channel, select stable-v1.

   2. For Installation Mode, accept the default (a specific namespace on the cluster).

      Note

      This mode determines what namespaces the operator will monitor for HawtIO CRs. This is different to what namespaces HawtIO will monitor when it is fully deployed. The latter can be configured via the HawtIO CR.

   3. For Installed Namespace, select the namespace in which you want to install HawtIO Operator.

   4. For the Update Approval, select Automatic or Manual to configure how OpenShift handles updates to HawtIO Operator.

      1. If the Automatic updates option is selected and a new version of HawtIO Operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of HawtIO without human intervention;
      2. If the Manual updates option is selected and a newer version of an Operator is available, the OLM only creates an update request. A Cluster Administrator must then manually approve the update request to have HawtIO Operator updated to the new version.
5. Click Install and OpenShift installs HawtIO Operator into the current namespace.
6. To verify the installation, click Operators and then click Installed Operators. HawtIO should be visible in the list of operators.

7. To deploy HawtIO by using the OpenShift web console:

   1. In the list of Installed Operators, under the Name column, click HawtIO Operator.
   2. On the Operator Details page under Provided APIs, click Create HawtIO.

   3. Accept the configuration default values or optionally edit them.

      1. For Replicas, to increase HawtIO performance (for example, in a high availability environment), the number of pods allocated to HawtIO can be increased;
      2. For RBAC (role-based access control), only specify a value in the Config Map field if you want to customize the default RBAC behaviour and if the ConfigMap file already exists in the namespace in which you installed HawtIO Operator
      3. For Nginx, see Performance tuning for HawtIO Operator installation

      4. For Type, specify either:

         1. Cluster: for HawtIO to monitor all namespaces on the OpenShift cluster for any HawtIO-enabled applications;
         2. Namespace: for HawtIO to monitor only the HawtIO-enabled applications that have been deployed in the same namespace.
   4. Click Create. The HawtIO Operator Details page opens and shows the status of the deployment.

8. To open HawtIO:

   1. For a namespace deployment: In the OpenShift web console, open the project in which the HawtIO operator is installed, and then select Overview. In the Project Overview page, scroll down to the Launcher section and click the HawtIO link.
   2. For a cluster deployment, in the OpenShift web console’s title bar, click the grid icon. In the popup menu, under Red Hat Applications, click the HawtIO URL link.
   3. Log into HawtIO. An Authorize Access page opens in the browser listing the required permissions.
   4. Click Allow selected permissions. HawtIO opens in the browser and shows any HawtIO-enabled application pods that are authorized for access.
9. Click Connect to view the monitored application. A new browser window opens showing the application in HawtIO.

1. admin: if a user can update a pod in OpenShift, then the user is conferred the admin role for HawtIO. The user can perform write MBean operations in HawtIO for the pod.
2. viewer: if a user can get a pod in OpenShift, then the user is conferred the viewer role for HawtIO. The user can perform read-only MBean operations in HawtIO for the pod.

1. In the Camel tab’s tree view, click Camel Contexts.
2. Check the box next to one or more contexts in the list.
3. Click Start or Suspend.

4. To delete a context:

   1. Stop the context.
   2. Click the ellipse icon and then select Delete from the dropdown menu.

1. In the Camel tab’s tree view, click a Camel application.
2. To view a list of application attributes and values, click Attributes.
3. To view a graphical representation of the application attributes, click Chart and then click Edit to select the attributes that you want to see in the chart.
4. To view inflight and blocked exchanges, click Exchanges.
5. To view application endpoints, click Endpoints. You can filter the list by URL, Route ID, and direction.
6. To view, enable, and disable statistics related to the Camel built-in type conversion mechanism that is used to convert message bodies and message headers to different types, click Type Converters.
7. To view and execute JMX operations, such as adding or updating routes from XML or finding all Camel components available in the classpath, click Operations.

1. To view a list of routes:

   1. Click the Camel tab.

   2. In the tree view, click the application’s routes folder:

      

      View larger image

      

2. To start, stop, or delete one or more routes:

   1. Check the box next to one or more routes in the list.
   2. Click Start or Stop.

   3. To delete a route, you must first stop it. Then click the ellipse icon and select Delete from the dropdown menu.

      

      View larger image

      
      Note
      • When you delete a route, you remove it from the deployed application.
      • You can also select a specific route in the tree view and then click the upper-right menu to start, stop, or delete it.
3. To view a graphical diagram of the routes, click Route Diagram.
4. To view inflight and blocked exchanges, click Exchanges.
5. To view endpoints, click Endpoints. You can filter the list by URL, Route ID, and direction.
6. Click Type Converters to view, enable, and disable statistics related to the Camel built-in type conversion mechanism, which is used to convert message bodies and message headers to different types.

7. To interact with a specific route:

   1. In the Camel tab’s tree view, select a route. To view a list of route attributes and values, click Attributes.
   2. To view a graphical representation of the route attributes, click Chart. You can click Edit to select the attributes that you want to see in the chart.
   3. To view inflight and blocked exchanges, click Exchanges.
   4. Click Operations to view and execute JMX operations on the route, such as dumping the route as XML or getting the route’s Camel ID value.

8. To trace messages through a route:

   1. In the Camel tab’s tree view, select a route.
   2. Select Trace, and then click Start tracing.

9. To send messages to a route:

   1. In the Camel tab’s tree view, open the context’s endpoints folder and then select an endpoint.
   2. Click the Send subtab.
   3. Configure the message in JSON or XML format.
   4. Click Send.
   5. Return to the route’s Trace tab to view the flow of messages through the route.

1. In the Camel tab’s tree view, select a route.
2. Select Debug, and then click Start debugging.

3. To add a breakpoint, select a node in the diagram and then click Add breakpoint. A red dot appears in the node:

   

   View larger image

   

4. The node is added to the list of breakpoints:

   

   View larger image

   

5. Click the down arrow to step to the next node or the Resume button to resume running the route.

   

   View larger image

   
6. Click the Pause button to suspend all threads for the route.
7. Click Stop debugging when you are done. All breakpoints are cleared.