Chapter 3. Agents

WAR agent是目前最流行的变种，就像任何其他的JEE Web应用程序可以部署在一个servlet容器中。

通常情况下，安装仅仅是简单的复制agent WAR到部署目录下。在其他平台上可以通过Web GUI或命令行工具来部署。每一个servlet容器安装的详细说明不在本文档的范围内。

servlet本身可以通过两种方式配置：

Jolokia has various detectors which can detect the brand and version of an application server it is running in. This version is revealed with the version command. With the configuration parameter detectorOptions extra options can be passed to the detectors. These options take the form of a JSON object, where the keys are productnames and the values other JSON objects containing the specific configuration. This configuration is feed to a successful detector which can do some extra initialization on agent startup. Currently the following extra options are supported:

In order use JEE security within the war, some extrat configuration steps are required within web.xml.

There is a commented section which can serve as an example. All current client libraries are able to use BASIC HTTP authentication with user and password. The <login-config> should be set accordingly. The <security-constraint> specifies the URL pattern (which is in the default setup specify all resources provided by the Jolokia servlet) and a role name which is used to find the proper authentication credentials. This role must be referenced outside the agent WAR within the servlet container, e.g. for Tomcat the role definition can be found in $TOMCAT/config/tomcat-users.xml.

Jolokia agent servlet也可以被集成到自己的Web应用中。只需要添加org.jolokia.http.AgentServlet类到我们自己的web.xml文件中。下面的示例映射agent的context/jolokia：

    <servlet>
      <servlet-name>jolokia-agent</servlet-name>
      <servlet-class>org.jolokia.http.AgentServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
      <servlet-name>jolokia-agent</servlet-name>
      <url-pattern>/jolokia/*</url-pattern>
    </servlet-mapping>
    

当然， 表格 3.1, “Servlet init parameters”中所描述的任何初始化参数，也可以用在这里。

In order for this servlet definition to find the referenced Java class, the JAR jolokia-core.jar must be included. This jar can be found in Jolokia's maven resository. Maven users will can declare a dependency on this jar artifact:

    <project>
      <!-- ....  --> 
      <dependencies>
        <dependency>
          <groupId>org.jolokia</groupId>
          <artifactId>jolokia-core</artifactId>
          <version>0.90</version>
        </dependency>
      </dependencies>

      <!-- Maven repository hosting Jolokia -->
      <repositories>
        <repository>
          <id>labs-consol-release</id>
          <name>ConSol* Labs Repository (Releases)</name>
          <url>http://labs.consol.de/maven/repository</url>
        </repository>
      </repositories>
    </project>

The org.jolokia.http.Agent can be subclassed, too in order to provide a custom restrictor or a custom log handler. See Section 4.2, “Jolokia Restrictors” for details.^[5]

Also, multiple Jolokia agents can be deployed in the same JVM without problem. However, since the agent deploys some Jolokia-specific MBeans on the single PlatformMBeansServer, for multi-agent deployments it is important to use the mbeanQualifier init parameter to distinguish multiple Jolokia MBeans by adding an extra propery to those MBeans' names. This also needs to be done if multiple webapps containing Jolokia agents are deployed on the same JEE server.

This bundle depends mostly on a running OSGi HttpService which it uses for registering the agent servlet.

All package imports of this bundle are listed in Table 3.3, “Package Imports of jolokia-osgi.jar (SB: exported by system bundle)”. Note that the org.osgi.framework.* and javax.* packages are typically exported by the system bundle, so no extra installation effort is required here. Whether the org.osgi.service.* interfaces are available depends on your OSGi container. If they are not provided, they can be easily fetched and installed from e.g. maven central. Often the LogService interface is exported out of the box, but not the HttpService. You will notice any missing package dependency during the resolve phase while installing jolokia-osgi.jar.

This agent bundle consumes two services by default: As stated above, an org.osgi.service.http.HttpService which is used to register (deregister) the Jolokia agent as a servlet under the context /jolokia by default as soon as the HttpService becomes available (unavailable). Secondly, an org.osgi.service.log.LogService is used for logging, if available. If such a service is not registered, the Jolokia bundle uses the standard HttpServlet.log() method for its logging needs.

The Jolokia OSGi bundle can be configured via the properties which typically can be configured in a global configuration file of the OSGi container. All properties start with the prefix org.jolokia and are listed in Table 3.4, “Jolokia Bundle Properties”. They are mostly the same as the init-param options for a Jolokia servlet when used in a JEE WAR artifact.

This bundle also exports the service org.jolokia.osgi.servlet.JolokiaContext which can be used to obtain context information of the registered agent like the context path under which this servlet can be reached. Additionally, it exports org.osgi.service.http.HttpContext, which is used for authentication. Note that this service is only available when the agent servlet is active (i.e. when an HttpService is registered).

You have a couple of choices when running jolokia on Glassfish v3 and up, since Glassfish is a both a fully fledged JEE container and an OSGi container. If you choose to run the Section 3.1, “JEE Agent (WAR)” then it is completely straight forward just deploy the war in the normal way. If you choose to deploy the Section 3.2, “OSGi Agents” then you will need to configure the org.jolokia.httpServiceFilter option with a filter to select either the Admin HttpService (4848 by default) or the Default HttpService which is where WAR files are deployed to.

In Glassfish 3.1.2 the OSGi bundle configuration is done in glassfish/conf/osgi.properties in version's prior to this the configuration is by default in glassfish/osgi/felix/conf/config.properties or if you are using Equinox glassfish/osgi/equinox/configuration/config.ini

# Restrict the jolokia http service selection to the admin host
org.jolokia.httpServiceFilter=(VirtualServer=__asadmin)
# Or alternatively to the normal http service use : (VirtualServer=server)

Deploying the bundle can be either be done by coping the jolokia-osgi.jar into the domain glassfish/domains/<domain>/autodeploy/bundles directory or it can be added to all instances by copying the jar to glassfish/modules/autostart

By default the agent will be available on http://localhost:<port>/osgi/jolokia rather than http://localhost:<port>/jolokia as with WAR deployment.

The all-in-one bundle includes an implementation of org.osgi.service.http.HttpService, i.e. the Felix implementation. The HttpService will be registered as OSGi service during startup, so it is available for other bundles as well. The only package import requirement for this bundle is org.osgi.service.LogService, since the Felix Webservice requires this during startup. As mentioned above, normally the LogService interface gets exported by default in the standard containers, but if not, you need to install it e.g. from the OSGi compendium definitions.

This bundle can be configured the same way as the pure bundle as described in Section 3.2.1, “jolokia-osgi.jar”. Additionally, the embedded Felix HttpService can be configured as described in its documentation. e.g. setting the port to 9090 instead of the default port 8080, a property org.osgi.service.http.port=9090 needs to be set. This might be useful, if this bundle is used within containers which already occupy the default port (Glassfish, Eclipse Virgo) but don't expose an OSGi HttpService.

It is also possible to register the Jolokia agent servlet manually instead of relying of the OSGi bundle activator which comes with the agents. For this use case jolokia-osgi.jar should be used. This bundle exports the package org.jolokia.osgi.servlet which includes the servlet class JolokiaServlet. This class has three constructors: A default constructor without arguments, one with a single BundleContext argument and finally one with an additional Restrictor (see Section 4.2, “Jolokia Restrictors” for details how access restrictions can be applied). The constructor with a BundleContext as its argument has the advantage that it will use an OSGi LogService if available and adds various OSGi server detectors which adds server information like product name and version to the version command. Refer to Section 6.2.6, “Getting the agent version (version)” for details about the server infos provided.

Please note that for this use case the bundle org.jolokia.osgi should not be started but left in the state resolved. Otherwise, as soon as an OSGi HttpService registers, this bundle will try to add yet another agent servlet to this service, which is probably not what you want. Alternatively, the bundle property org.jolokia.listenForHttpService can be set to false in which case there will be never an automatic servlet registration to an HttpService.

As described in Section 4.2, “Jolokia Restrictors”, the Jolokia agent can use custom restrictors implementing the interface org.jolokia.restrictor.Restrictor. If the bundle property org.jolokia.useRestrictorService is set to true and no restrictor is configured by other means, the agent will use one or more OSGi service which register under the name org.jolokia.restrictor.Restrictor. If no such service is available, access to the agent is always denied. If one such restrictor service is available, the access decision is delegated to this service. When more than one restrictor service is available, access is ony granted if all of them individually grant access. A sample restrictor service as a maven project can be found in the Jolokia source at agent/osgi/restrictor-sample.

The JVM agent uses the JVM Agent interface for linking into any JVM. Under the hood it uses an HTTP-Server, which is available on every Oracle/Sun JVM from verion 1.6 upwards.

java -javaagent:agent.jar=port=7777,host=localhost

A Jolokia agent can be attached to any running Java process as long as the user has sufficient access privileges for accessing the process. This agent uses the Java attach API for dynamically attaching and detaching to and from the process. It works similar to JConsole connecting to a local process. The Jolokia advantage is, that after the start of the agent, it can be reached over the network.

The JAR containing the JVM agent also contains a client application which can be reached via the -jar option. Call it with --help to get a short usage information:

$ java -jar jolokia-jvm-1.0.1-agent.jar --help

Jolokia Agent Launcher
======================

Usage: java -jar jolokia-jvm-1.0.1-SNAPSHOT-agent.jar [options] <command> <pid/regexp>

where <command> is one of
    start     -- Start a Jolokia agent for the process specified
    stop      -- Stop a Jolokia agent for the process specified
    status    -- Show status of an (potentially) attached agent
    toggle    -- Toggle between start/stop (default when no command is given)
    list      -- List all attachable Java processes (default when no argument is given at all)

[options] are used for providing runtime information for attaching the agent:

    --host <host>                 Hostname or IP address to which to bind on
                                  (default: InetAddress.getLocalHost())
    --port <port>                 Port to listen on (default: 8778)
    --agentContext <context>      HTTP Context under which the agent is reachable (default: /jolokia)
    --user <user>                 User used for Basic-Authentication
    --password <password>         Password used for Basic-Authentication
    --quiet                       No output. "status" will exit with code 0 if the agent is running, 1 otherwise
    --verbose                     Verbose output
    --executor <executor>         Executor policy for HTTP Threads to use (default: single)
                                  "fixed"  -- Thread pool with a fixed number of threads (default: 5)
                                  "cached" -- Cached Thread Pool, creates threads on demand
                                  "single" -- Single Thread
    --threadNr <nr threads>       Number of fixed threads if "fixed" is used as executor
    --backlog <backlog>           How many request to keep in the backlog (default: 10)
    --protocol <http|https>       Protocol which must be either "http" or "https" (default: http)
    --keystore <keystore>         Path to keystore (https only)
    --keystorePassword <pwd>      Password to the keystore (https only)
    --useSslClientAuthentication  Use client certificate authentication (https only)
    --debug                       Switch on agent debugging
    --debugMaxEntries <nr>        Number of debug entries to keep in memory which can be fetched from the Jolokia MBean
    --maxDepth <depth>            Maximum number of levels for serialization of beans (default: null)
    --maxCollectionSize <size>    Maximum number of element in collections to keep when serializing the response (default: null)
    --maxObjects <nr>             Maximum number of objects to consider for serialization (default: maxObjects)
    --policyLocation <url>        Location of a Jolokia policy file
    --mbeanQualifier <qualifier>  Qualifier to use when registering Jolokia internal MBeans
    --config <configfile>         Path to a property file from where to read the configuration
    --help                        This help documentation

<pid/regexp> can be either a numeric process id or a regular expression. A regular expression is matched
against the processes' names (ignoring case) and must be specific enough to select exactly one process.

If no <command> is given but only a <pid> the state of the Agent will be toggled
between "start" and "stop"

If neither <command> nor <pid> is given, a list of Java processes along with their IDs
is printed

For more documentation please visit www.jolokia.org

Every option described in Table 3.6, “JVM agent configuration options” is reflected by a command line option for the launcher. Additionally, the option --quiet can be used to keep the launcher silent and --verbose for adding some extra logging.

The launcher knows various operational modes, which needs to be provided as a non-option argument and possibly require an extra argument.

The launcher is especially suitable for one-shot, local queries. For example, a simple shell script for printing out the memory usage of a local Java process, including (temporarily) attaching an Jolokia agent looks simply like in the following example. With a complete client library like Jmx4Perl even more one shot scripts are possible^[6].

#!/bin/sh

url=`java -jar agent.jar start $1 | tail -1`

memory_url="${url}read/java.lang:type=Memory/HeapMemoryUsage"
used=`wget -q -O - "${memory_url}/used" | sed 's/^.*"value":\([0-9]*\).*$/\1/'`
max=`wget -q -O - "${memory_url}/max" | sed 's/^.*"value":\([0-9]*\).*$/\1/'`
usage=$((${used}*100/${max}))
echo "Memory Usage: $usage %"

java -jar agent.jar --quiet stop $1