About

The Diffusion Monitoring Console is an optional publisher, provided as console.dar. It is deployed by default, and can be undeployed in the same manner as any DAR file. It exists to give operational staff using a web browser accessible visibility over the operations of a Diffusion solution

To manage a Diffusion server and make changes to it, use Java Management Extensions (JMX) tools such as JConsole. Unless you have to stop the Diffusion server, and stop and restart a publisher.

Dependencies

The console depends on the Diffusion publisher to mirror JMX MBeans as topics. The console also makes use of the statistics controlled by etc/Statistics.xml

The live graphing feature mandates a web browser that supports Scalar Vector Graphics (SVG). Most modern web browsers implement the features required by the Console however Internet Explorer^® v9 is the recommended minimum for Microsoft^® users.

Logging in

The console is secured by a username and password. The username you use to login must have permissions to view and act on information on the Diffusion server, for example by having the ADMINISTRATOR role.

The default configuration of the Diffusion server, provides a user 'admin' with the password 'password'. This user has the appropriate permissions to use all of the console capabilities. For more information, see Pre-defined users.

Figure 1. Logging in the monitoring console

Features: Overview tab

By default the console is deployed as part of Diffusion. It is available in a fresh installation at http://localhost:8080/console.

Default layout

By default, the console consists of six panels, each focusing on a key feature of the server.

Figure 2. The default console layout

• Diffusion Details: the server version; the server up time, the server start date and time and the time and which the current license expires.
• Server details: the name and version of the underlying operating system; the total memory available (physical and virtual) and the amount of free memory.
• Java™ Details: the name, vendor and version of the Java Virtual Machine (JVM).

Instead of tabular data the second row show live line graphs.

• Memory pool usage: the values over time of the memory used by the JVM process.
• Clients: the value over time of the number of clients connected.
• Topics: the value over time of the number of topics on your Diffusion server.

Publishers table

At the bottom of the Overview is the publishers table. At a glance this shows the installed publishers and their vital statistics: the number of topics created, client connected, messages sent, bytes sent and finally publisher status

Figure 3. The table of publishers

Using the pull-down menu on the Details button publishers can be stopped and restarted. The Details button itself reveals the publisher statistics: clients, topics, average messages per second and average bytes per second.

Figure 4. Publisher statistics graphs

Features: Topics tab

The Topics tab brings to the web browser the ability to browse and interact with the Diffusion topic tree.

Figure 5. The table of topics

Users can intuitively browse the live topic tree, fetch and subscribe to topics. If the server is so configured the table also shows the number of subscribed clients, messages sent and bytes sent. Enable individual topic statistics through etc/Statistics.xml, for example,

<!-- Enable global topic statistics -->

  <topic-statistics enabled="true">

  <!-- Enable individual topic instance statistics -->

  <monitor-instances>true</monitor-instances>

</topic-statistics>

Once a set of topics is selected using its checkbox the Subscribe and Unsubscribe work intuitively, and each button has an recursive alternative available through the drop-down menu-button.

The details button shows more detail on the topic in question, as well as offering to fetch the topic value

Figure 6. Details of the topic publishing the CPU load of the host server

Features: Clients tab

The Client tab shows a live list of the clients connected to the Diffusion server. Additionally it shows the number of messages to and from the server, the client IP address, connection type and connection time.

Figure 7. The table of clients

Configure the Diffusion server to provide live client statistics through etc/Statistics.xml

<!-- Enable global client statistics -->
<client-statistics enabled="true">
		<!-- Definition of the log in Logs.xml -->
		<log-name>stats</log-name>
		<!-- Specifies the output frequency of the log, this is one entry per frequency -->

		<output-frequency>1h</output-frequency>
		<!-- Enable individual client instance statistics -->
		<monitor-instances>true</monitor-instances>
</client-statistics>

Features: Logs tab

The Logs tab shows a live color-coded display of log entries emitted by the server at the levels of INFO, WARN, and ERROR.

Figure 8. The table of log entries

Users can also perform client-side simple filtering on log entries. Unlike other monitoring metrics the Diffusion server retains up to 250 log entries in memory.

Features: Security tab

The Security tab shows a live list of security principals and roles that are configured on the Diffusion server.

For more information about security, see Security.

Figure 9. Security tables

Create, edit, or delete principals: The Principals table shows a list of the principals that the system authentication handler is configured to allow to connect to the Diffusion server. The table also shows the roles that are assigned to any client session that authenticates with the principal.

Click the New Principal button to add a new principal and define its associated password and roles.

Click the spanner icon next to an existing principal to edit that its password or roles.

Click the trashcan icon next to an existing principal to delete that principal.

Edit authentication policy and roles for anonymous users: The Anonymous Users table shows the authentication decision for client session that connect anonymously to the Diffusion server. You can choose to ALLOW or DENY anonymous connections or to ABSTAIN from the authentication decision, which then passes to the next configured authentication handler.

Click the spanner icon to edit the authentication decision for anonymous connections and, if that decision is ALLOW, edit any roles that are assigned to anonymous sessions.

Create, edit, or delete roles: The Roles table shows a list of roles that have been configured in the security store of the Diffusion server. These are the roles that you can choose to assign to any principals that connect to the Diffusion server.

Click the New Role button to add a new role and define its permissions and any roles it inherits from.

Click the spanner icon next to an existing role to edit its permissions and any roles it inherits from.

Click the trashcan icon next to an existing role to delete that role.

Advanced

Saving the console layout

Users can save changes made to their console layout with the “Save Overview layout” button. This persists a file on the server side, making it shared amongst all Console users.

White & Blacklist editing

The Console optionally maintains a blacklist or whitelist of IP addresses that are allowed to make use of it. Users can specify discrete IP addresses or use syntax supported by etc/SubscriptionValidationPolicy.xml to cover subnets. In order to make these changes active, after editing the whitelist or blacklist and clicking the "Save settings" button, you must restart the server.

Figure 10. Editing the Access Policy

Stop Diffusion

Required permissions: control_server

The Stop Diffusion menu item stops the server when clicked upon.

Figure 11. Notification that the Diffusion server has stopped

Going further

Changing the console layout

The console is designed to be extensible and flexible. Users can reorder, edit, create and remove panels. Grab the panel header and drag it to a new location as desired. Click the trash-can icon to remove the icon – with verification

Figure 12. The default Diffusion Details panel

Click on the spanner or wrench icon to configure the panel.

Figure 13. Editing the properties of the Diffusion Details panel

Panel name’ and ‘Header color’ are self explanatory. ‘View type’ is a choice of data renderings.

• Table: As seen already, this option shows one or more monitoring metrics in a table of textual values.
• Line: Renders one or more numeric metrics as a line graph.
• Area: Renders one or more numeric metrics as an overlapping area graph.
• Single: Used to visualize a single metric in large text, for metrics that are worth the screen real-estate.

Line and area graphs have an extra two configuration fields: ‘Refresh rate (ms)’ and ‘Max data points’. The latter configures how much data is retained for rendering the graph. The former governs the frequency with which the graph is updated and does not influence the frequency of updates from the server. Historic data is only stored in the browser and refreshing the page loses the stored set of data points.

Hovering the mouse over a graph panel shows the detail of the underlying data point

Figure 14. Visualizing the CPU load on a server at a specific time.

Sourcing monitoring metrics

Clicking the ‘Edit fields’ button presents the user with a Topic Data Fields dialog, where the user nominates one or more topics from where metrics are drawn.

Figure 15. Editing and adding to the set of topics for this panel

Users of the Topics tab have already seen the Add to Overview button in the Topic details dialog that can shortcut this process.

The default Console layout draws metrics from topics in the Diffusion/MBeans topic tree, however this is not mandatory and solution implementers are free to draw on any suitable topic to reflect their own monitoring needs – including 3rd party topics implemented as part of the solution.

The Diffusion/MBeans topic tree is populated by the JMX adapter which reflects all JMX MBeans as topics. Solution implementers that build custom MBeans to manage their solution can re-use the same MBeans for monitoring purposes.

The Console can draw on features that are themselves optional (Topic and client statistics, for example). If they are disabled, the Console points this out, and request they be enabled in etc/Statistics.xml

Production deployment notes

Securing the Diffusion/ topics

The topics in the Diffusion/ tree convey a great deal of power and it is highly probable that bringing a Diffusion based solution to production requires limiting their access to suitable users: for example, users with an IP address in a specific range. Solution implementers can achieve this by implementing an authentication handler.

The default configuration for the console allows users to stop and restart publishers as well as stop the Diffusion server itself. This feature is configured using the properties console.control.server and console.control.publishers on the Diffusion publisher in etc/Publishers.xml.