Use JConsole with Wowza Streaming Engine

Wowza Streaming Engine™ media server software can be managed and monitored through a Java Management Extensions (JMX) interface.

JMX is a standards-based technology that exposes Java application components through a unified object interface. This interface can then be consumed by open-source and commercial monitoring tools such as HP OpenView, OpenNMS, JConsole, and VisualVM. This article describes how to enable the JMX interface for Wowza Streaming Engine and manage the server software using JConsole.

About JConsole

JConsole is a general-purpose tool for managing a Java-based server. JConsole communicates with Java servers using the Java Management Extensions (JMX) protocol. Wowza Streaming Engine exposes a rich set of objects for monitoring the server. The Java virtual machine also exposes a set of JMX objects that can be used to monitor the virtual machine.

The easiest way to view these objects is to use the JConsole applet that ships with the Java Development Kit (JDK) of most popular VMs. This tool is usually located in the [java-install-dir]/bin folder that's created by the JDK installation. This location differs based on platform:

• Windows – C:\Program Files\Java\[jdk-version]\bin
• Linux – /usr/java/[jdk-version]/bin

Because JConsole is a general-purpose tool, much of the functionality is focused on monitoring and managing Java itself. Wowza Streaming Engine items are exposed in the WowzaStreamingEngine section under the MBeans tab.

The data follows the Wowza Streaming Engine object hierarchy of Server, VHost, Application, ApplicationInstance, Client, MediaStream. Each object in this hierarchy exposes three panels: Attributes, Operations, and Notifications. In most cases, only the Attributes and Operations sections are used.

The Attributes panel has attributes that are attached to this object. Some values are read-only, and others are read-write. If you double-click on a read-write value, you can change its value in a live running server. Read-only integer values can be graphed by double-clicking on them.

The Operations panel has methods that are attached to this object that use normal parameters (string, int, long). You can execute methods by entering values for the parameters and clicking that operations button.

Local management using JConsole

By default, the Wowza Streaming Engine files [install-dir]/bin/startup.bat and [install-dir]/bin/startup.sh are configured to expose the JMX object interface to a locally running copy of JConsole. To view the JMX interface, start Wowza Streaming Engine, and then run JConsole. In JConsole, you should see a list of the running Java virtual machines that expose a JMX interface. The Wowza Streaming Engine server is listed as com.wowza.wms.bootstrap.Bootstrap start. Select this item, and then click Connect.

You can then explore the different tab panels that are included in JConsole. The Wowza Streaming Engine management objects are located under the MBeans tab in the WowzaStreamingEngine group.

JMX object organization is based on the configured virtual hosts, applications, and applications instances. Monitoring objects are created and deleted on the fly as applications, application instances, client connections, and streams are created and deleted from the server.

Remote JMX interface configuration

By default, the startup and service scripts are configured to only expose the JMX interface to a locally running monitoring application. You can also configure a remote JMX interface for monitoring Wowza Streaming Engine from a remote computer. Both the JVM and Wowza Streaming Engine include remote JMX interfaces. It's only necessary to configure one of these remote interfaces to enable remote monitoring. We recommend you use the Wowza Streaming Engine remote interface because it's easier to configure and can be properly exposed through hardware-based and software-based firewalls.

The remote JMX interface built into Wowza Streaming Engine can be configured through the JMXRemoteConfiguration and AdminInterface containers in the [install-dir]/conf/Server.xml file. This section describes the configuration settings.

JMXRemoteConfiguration - Enable, IpAddress, RMIServerHostName, RMIConnectionPort, RMIRegistryPort

The Enable setting enables and disables the remote JMX interface. The default value is false. Setting this value to true (with no further modifications to the other settings) enables the remote JMX interface with authentication. The default user name/password is admin/admin. The URL for invocation in JConsole is:

service:jmx:rmi://localhost:8084/jndi/rmi://localhost:8085/jmxrmi

The IpAddress and RMIServerHostName settings work together to expose the JMX interface to the network. In general, set the IpAddress value to the internal IP address of the Wowza Streaming Engine server and the RMIServerHostName value to the external IP address or domain name of the computer. For example, if Wowza Streaming Engine is behind a network-translated IP address (NAT), such that the internal IP address of the server is 192.168.1.7 and the external IP address is 40.128.7.4, the two settings should be:

<IpAddress>192.168.1.7</IpAddress>
<RMIServerHostName>40.128.7.4</RMIServerHostName>

With this configuration, you would use the following URL to connect to the JMX interface:

service:jmx:rmi://40.128.7.4:8084/jndi/rmi://40.128.7.4:8085/jmxrmi

The RMIConnectionPort and RMIRegistryPort settings control the TCP ports that are used to expose the RMI connection and RMI registry interfaces. You should only change these values if Wowza Streaming Engine reports port conflicts during startup. The default values for these settings are 8084 and 8085, respectively. The RMIConnectionPort corresponds to the first port number in the connection URL, and the RMIRegistryPort to the second.

The IpAddress, RMIConnectionPort, and RMIRegistryPort settings affect the connection URL in the following way:

service:jmx:rmi://[RMIServerHostName]:[RMIConnectionPort]/jndi/rmi://[RMIServerHostName]:[MIRegistryPort]/jmxrmi

If the remote JMX interface is enabled, Wowza Streaming Engine will log the URL of the currently configured JMX interface when it starts. This is probably the most reliable way to determine the JMX URL to use to connect to the server.

To enable remote JMX monitoring through software-based and hardware-based firewalls, open TCP communication for the two ports defined by the RMIConnectionPort and RMIRegistryPort settings.

JMXRemoteConfiguration - Authenticate, PasswordFile, AccessFile

The Authenticate setting enables and disables remote JMX interface authentication. The PasswordFile and AccessFile settings are the full path to the JMX password and access files, respectively. These files define three named users:

admin
monitorRole
controlRole

To be functional, a user must have an entry in both the password and the access files.

The password file is a text file with one line per user. Each line contains a username followed by a space and the password for that username (the default password is admin). For an example, see the [install-dir]/conf/jmxremote.password file.

The access file is a text file with one line per user. Each line contains a user name followed by a space and a value that defines the permitted access for that user name (the default value is readonly). For an example, see the [install-dir]/conf/jmxremote.access file. In the jmxremote.access file, acceptable values to define permitted access for a user are readonly and readwrite. To change the access permissions for any named user, open the jmxremote.access file in a text editor, change the value for the user, and then restart Wowza Streaming Engine to apply the changes.

Notes:

• Some  JREs require that both the password and access files have read-only privileges. On Linux systems, this can be achieved by setting the permissions on both files to 600:

  chmod 600 conf/jmxremote.access
  chmod 600 conf/jmxremote.password

• For more information about restricting permissions, see Password files and Access files.

JMXRemoteConfiguration - SSLSecure

The SSLSecure setting enables and disables the remote JMX interface over SSL. Do the following to configure SSLSecure:

1. Open your [install-dir]/conf/Tune.xml file in a text editor and add the following VMOption:

   <VMOption>-Dcom.sun.management.jmxremote.port=[port] -Djavax.net.ssl.keyStore=[yourKeyStore] -Djavax.net.ssl.keyStorePassword=[yourPassword] -Dcom.sun.management.jmxremote.password.file="[jmxremote.password]" -Dcom.sun.management.jmxremote.ssl.need.client.auth=true</VMOption>

   Where:

   • [port] is 9999 or another available port.
   • [yourKeyStore] is the full path and name of your keystore file.
   • [yourPassword] is the password for your keystore.
   • [jmxremote.password] is the full path and name of your jmxremote.password file.
2. Restrict permissions for JMX user roles and the operating system. To restrict JMX user permissions, update the jmxremote.password file as described in JMXRemoteConfiguration - Authenticate, PasswordFile, AccessFile. To restrict operating system permissions, set the owner's operating system permissions to readonly and remove all other permissions.
3. Launch the JConsole client with the following options:

   jconsole -J-Djavax.net.ssl.trustStore=[yourTrustStore] -J-Djavax.net.ssl.trustStorePassword=[yourPassword]

   Where:

   • [yourTrustStore] is the full path and name of your truststore file.
   • [yourPassword] is the password for your truststore.

Note: SSL configuration can be quite involved and additional configuration may be required. For more information about how to enable SSL with JMX, see Using SSL in the Oracle docs.

AdminInterface/ObjectList

The AdminInterface/ObjectList setting is a comma-separated list of object types that you can expose through the JMX interface. This list can contain any number of the following items:

Server			- Server-level connection and performance info and notifications
VHost			- Information about currently running virtual hosts
VHostItem		- Details of currently configured virtual hosts
Application		- Application-level connection and performance info
ApplicationInstance	- Application Instance-level connection and performance info
Module			- Details of currently loaded modules
MediaCaster		- Details of media caster object (live stream repeater)
MediaStream		- Details of each individual server-side NetStream object
SharedObject		- Details of currently loaded shared objects
Acceptor		- Details of currently running host ports or TCP ports
IdleWorker		- Details of currently running idle workers

Exposing MediaStream, and/or SharedObject information can add significant load to Wowza Streaming Engine and to the JMX interface. You'll most likely want to turn off this level of detail in your deployed solution.

Remote management using JConsole

JConsole can be used to monitor a remote instance of Wowza Streaming Engine. After you configure the remote JMX interface (see Remote JMX interface configuration), run JConsole and then enter the remote JMX interface URL in the Remote Process field. The default remote JMX interface URL for the JMX interface that's built-in with Wowza Streaming Engine is:

service:jmx:rmi://localhost:8084/jndi/rmi://localhost:8085/jmxrmi

Enter your username and password into the provided fields and then click Connect. This will enable you to connect to the remote server and view the JMX hierarchy.

Object overview

This section describes the more important top-level objects that can be used to monitor Wowza Streaming Engine performance and uptime. It doesn't cover every object exposed by the server. These objects are available under the WowzaStreamingEngine object in the MBeans section of JConsole.

• Server – Contains information about when the server was started and how long it has been running.
• VHosts – Includes information about each of the running virtual hosts. You can access each of the running applications and application instances. At each level of the hierarchy (Server, VHost, Application, ApplicationInstance), you can get detailed information about the number of connections (Connections object) and the input/output performance (IOPerformance object).
• IOPerformance – The Server exposes IOPerformance objects at many levels of the object hierarchy. These objects can be used to monitor server performance and throughput at that section of the server. For example, the IOPerformance object under a particular VHost displays the throughput of that virtual host.
• Connections – The Server exposes Connections objects at many levels of the object hierarchy. These objects can be used to monitor client connections at that section of the server. For example, the Connections object under a particular Application object displays the current number of clients that are connected to that application.
• VHost/[vHostName] - HandlerThreadPool, TransportThreadPool – The HandlerThreadPool and TransportThreadPool objects expose information about each of the worker thread pools that are owned by each of the virtual hosts. Use this object to monitor thread usage and load.
• ServerNotifications – The ServerNotifications object publishes notification events related to the connection limits and connection bursting capabilities of Wowza Streaming Engine. Wowza Streaming Engine can generate the following notification events:

com.wowza.wms.connect.WarningServerLicenseLimit	- connection accepted in bursting zone (warning)
com.wowza.wms.connect.ErrorServerLicenseLimit		- connection refused due to license limit
com.wowza.wms.connect.WarningVHostLimit			- connection refused due to virtual host limit

The body of the JMX notification message is a string with information about the virtual host, application, application instance, client ID, IP address, and referrer that generated the event. To view notification events in JConsole, navigate to the MBeans tab, open the WowzaStreamingEngine group, and then select the ServerNotification object. Then click Subscribe on the Notifications tab. All events are displayed as new rows in the Notifications list. Only events that occur after you subscribe to notifications are displayed.

More resources

• Monitoring and Management Using JMX Technology