• How to use JConsole with Wowza media server software

    Wowza media server software can be managed and monitored through a Java Management Extensions (JMX) interface. JMX is a standards-based technology for exposing 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 media server software and manage it using JConsole.

    Notes:

    Contents


    About JConsole
    Local Management Using JConsole
    Remote JMX Interface Configuration
    Remote Management Using JConsole
    Object Overview

    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. The Wowza media server 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
    OSX: /Library/Java/Home/bin

    Notes:
    • JDK version 6 (or later) is required to work with Wowza media server software. We recommend installing the most recent version of the Java JDK for your platform.
    • Most Java Runtime Environment (JRE or JVM) vendors require that you install the full JDK to get the JConsole management and monitoring application. See your vendor's documentation for more information.
    Because JConsole is a general-purpose tool, much of the functionality is focused around monitoring and managing Java itself. Wowza media server items are exposed in the WowzaMediaServerPro section under the MBeans tab.
    Note: If you're running Wowza Streaming Engine™ software, the server items are exposed in the WowzaStreamingEngine section under the MBeans tab.
    Here the data is organized following the Wowza Pro object heirarchy of Server, VHost, Application, ApplicationInstance, Client, MediaStream. Each object in this heirarchy exposes three panels: Attributes, Operations, and Notifications. In most cases it's only the Attributes and Operations sections that 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 media server 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 the Wowza media server, and then run JConsole. In JConsole, you should see a list of the running Java virtual machines that expose a JMX interface. The Wowza media 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 media server management objects are located under the MBeans tab in the WowzaMediaServerPro group.
    Note: As noted above, if you're running Wowza Streaming Engine, your server items are exposed in the WowzaStreamingEngine section under the MBeans tab.
    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.

    Note: In Windows, for security reasons, local monitoring and management is only supported if your default Windows temporary directory is on a file system that supports setting permissions on files and directories (for example, on an NTFS file system). It's not supported on a FAT file system that provides insufficient access controls. The workaround is to configure remote monitoring. For more information about how to configure the remote JMX interface, see Remote Management Using JConsole.

    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 the Wowza media server from a remote computer. Both the JVM and Wowza media server include remote JMX interfaces. It's only necessary to configure one of these remote interfaces to enable remote monitoring. We recommend that you use the Wowza media server remote interface because it's easier to configure and can be properly exposed through hardware-based and software-based firewalls.

    The remote JMX interface that's built-in with the Wowza media server 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 is a Boolean value that can be either true or false. It's the "switch" to enable and disable 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 username/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, the IpAddress value should be set to the internal IP address of the Wowza media server and the RMIServerHostName value should be set to the external IP address or domain name of the computer. For example, if the Wowza media server 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 as follows:
    <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. These values should only be changed if the Wowza media server 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 effect the connection URL in the following way:
    service:jmx:rmi://[RMIServerHostName]:[RMIConnectionPort]/jndi/rmi://[RMIServerHostName]:[RMIRegistryPort]/jmxrmi
    If the remote JMX interface is enabled, the Wowza media server 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 is a Boolean value that can be either true or false. It's the "switch" to enable and disable remote JMX interface authentication. The PasswordFile and AccessFile settings are the full path to the JMX password and access files respectively.
    The password file is a text file with one line per user. Each line contains a username followed by a space followed by a password. The access file contains one line per user. Each line contains a username followed by the readwrite or readonly access permission identifier. A sample password file (jmxremote.password) and a sample access file (jmxremote.access) can be found in the conf directory of the Wowza media server installation.

    These files define three named users:
    admin (password admin)		- access readwrite
    monitorRole (password admin)	- access readonly
    controlRole (password admin)	- access readwrite
    Note: Some Java Runtime Environments (JREs) require that both the password and access files have read-only privileges. On Linux operating systems, this can be achieved by setting the permissions on both files to 600:
    chmod 600 conf/jmxremote.access
    chmod 600 conf/jmxremote.password

    JMXRemoteConfiguration - SSLSecure

    The SSLSecure setting is a Boolean value that can be either true or false. It's the "switch" to enable and disable the remote JMX interface over Secure Sockets Layer (SSL). SSL configuration can be quite involved. For more information about how to enable SSL with JMX, see Using SSL.

    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)
    Client			- Details of each connected Flash session
    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 Client, MediaStream, and/or SharedObject information can add significant load to the server and to the JMX interface. You'll most likely want to turn off this level of detail in your deployed solution.

    Note: When running the Wowza media server software as a Windows service, the JMX interface isn't available unless the service is running as a named user. To configure the service to run as a named user, do the following:

    1. Open the Services console (Start > Control Panel > Administrative Tools > Services).

    2. Right-click the Wowza media server service, and then select Properties.

    3. On the Log On tab, change the Log on as option to This account, and then enter a username and password for a local user.

    Remote Management Using JConsole


    JConsole can be used to monitor a remote Wowza media server. 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 the Wowza media server 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.

    Note: VisualVM is another great tool for monitoring a Wowza media server over JMX. After you get VisualVM installed and running, it's best to install the MBean plugin. To do this, select the Plugins command from the Tools menu. Then on the Available Plugins tab, put a checkmark next to the VisualVM-MBean plugin and click Install. The MBean plugin provides similar information to JConsole. You can select Add JMX Connection from the File menu to add your Wowza media server to the Applications list.

    Object Overview


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

    Server: The server object contains information about when the server was started and how long it has been running.

    VHosts: The VHosts collection includes information about each of the running virtual hosts. From here, you get access to each of the running applications and applications 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 different 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 particular virtual host.

    Connections: The Server exposes Connections objects at many different 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 particular 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. You can 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 the Wowza media server. The Wowza media server 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 WowzaMediaServer 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.

    Originally Published: 10-02-2010.
    Updated: 10-31-2014.

    If you're having problems or want to discuss this article, post in our forum.