6 Monitoring Using Web Services and JMX

You can extend Enterprise Manager Grid Control to monitor Web Services and JMX-instrumented applications for critical events, performance problems, error conditions, and statistics.

Enterprise Manager's ability to monitor WSDL and JMX-enabled targets enables you to consolidate monitoring and management operations. When added to the Enterprise Manager framework, Enterprise Manager functionality, such as notifications, jobs, and reporting, is automatically extended to these targets.

This chapter covers the following topics:

Note:

This chapter assumes knowledge of Management Plug-ins and the requisite target definition files. For information on Management Plug-in concepts, or developing and deploying Management Plug-ins, see Chapter 1, "Extending Monitoring" and Chapter 2, "Developing a Management Plug-in".

6.1 Overview

Using Enterprise Manager to monitor targets that expose a Web Services management interface, JMX-instrumented applications and servers, and standalone Java Virtual Machine (JVM) targets entails defining a new target type via Management Plug-ins.

Creating a new Management Plug-in consists of four basic steps:

  1. Generate the target metadata and default collection files to be added to the Management Plug-in.

  2. Create a Management Plug-in Archive containing the target definition files for one or more Management Plug-ins. A single archive may contain more than one Management Plug-in.

  3. Import the Management Plug-in into Enterprise Manager.

  4. Deploy the Management Plug-in to the appropriate Management Agent(s).

Procedural information for the monitoring targets can be found in the following sections:

  • Section 6.2 discusses software components exposing an external interface that communicate across a network using a standard messaging protocol.

  • Section 6.3 discusses J2EE applications running on an OC4J that are instrumented using JMX MBeans.

  • Section 6.4 discusses standalone Java applications running on J2SE5.0 or higher that are instrumented using JMX MBeans.

  • Section 6.5 discusses JMX applications running on Oracle WebLogic Application Servers 9.x or above.

Section 6.3 and Section 6.4 explain how to generate metadata and default collection files for your custom JMX-enabled application by guiding you through the MBeans for which you are interested in collecting data, and helping you define the MBeans as metrics in Enterprise Manager. Even if your standalone Java application is not instrumented through JMX, you can still monitor the JVMs it is running on by directly creating the built-in JVM target instances as defined in Section 6.9.3.

After the metadata and default collection files are created, you can follow the normal Management Plug-in mechanism to deploy your plug-in and create target instances of your Java application target type as discussed in Section 6.6 through Section 6.9.

6.2 Monitoring Using Web Services in Enterprise Manager

Web Services are loosely coupled software components that expose an external interface via the Web Service Definition Language (WSDL). These components communicate across a network using a standard messaging protocol called Simple Object Access Protocol (SOAP). The Management Agent's JMX/SOAP fetchlet supports SOAP communication.

Note:

For more information about the Web Services standard, see the World Wide Web Consortium (W3C) website:

HTTP://www.w3.org

Prerequisites

  • Enterprise Manager Grid Control Management Agent version 10.2.0.2 or greater installed on that host.

  • Enterprise Manager Grid Control Management Server (OMS) version 10.2.0.2 or greater with which the Management Agent communicates.

6.2.1 Creating Metadata and Default Collection Files

Defining a target type to be monitored via a Web Services interface entails creating the requisite target definition files, which are required to collect metrics from resources that support the WSDL interface:

  • Target Metadata

  • Default Collection

Enterprise Manager provides an easy-to-use Web Services wsperfcli command-line tool that simplifies creating new Management Plug-ins by automatically generating these requisite files. Information retrieval is achieved via the SOAP/JMX fetchlet that is integrated with the Management Agent.

The command-line tool works by parsing a specified WSDL file for all operations, and enables you to select one or more operations to be invoked. If multiple port types are specified in the WSDL file, the tool prompts you to select one of them. Operations are listed along with their parameters. A Web Service operation can be one of four types:

  • One Way

  • Request Response

  • Solicit Response

  • Notification

The Request Response operation type is particularly useful: The selected operation could have primitive or complex parameters and results. The result of Web Service invocation is displayed in a table (the tool prompts you to provide labels for the table columns). You can also filter result attributes by specifying an Xpath expression (see the columnOrder property in the generated target metadata, Example 6-3). Filter attributes can be useful for complex return types from which only few attributes are interesting.

The Web Services command-line tool supports Web Services with the following binding and encoding styles:

  • DOC/literal

  • RPC/encoded

6.2.1.1 Web Services Command-line Tool Syntax

The Web Services command-line tool syntax is as follows:

wsperfcli [OPTIONS] < WSDL File | URL to WSDL>

The wsperfcli command accepts the following options:

  • -useSOAP11 Use SOAP version 1.1 instead of default 1.2

  • -useWSIF Useful for WSDL with SOAP-type arrays

  • -usePROXY Use proxy to connect to the Web Service

  • -useSSL Use SSL to communicate with the Web Service

The command-line tool optionally accepts a WSDL file name or URL to locate the WSDL for a Web Service. For example, for a card-service Web Service, a WSDL URL would be as follows:

http://localhost:44861/card-service/card?WSDL

The command tool script requires access to the Enterprise Manager home directory (EM_HOME) to run. The tool defaults to ORACLE_HOME. The home directory setting can be set using the command-line argument -DEM_HOME. For example, -DEM_HOME=/myEMHome. Other optional arguments are -DSOAP11 and -DuseSSL, which allow metadata to be generated to use an older version of the SOAP protocol and SSL for communication with the Web Service. The option -useWSIF is used for WSDL that use the old SOAP-style arrays (rpc/encoded Web Services).

The tool parses specified WSDL for all the port types and binding (supported protocols such as HTTP get/post, SOAP) to list all the operations. If there are multiple port types in WSDL, you will first be prompted to choose a port type.

6.2.1.2 Web Services Command-line Tool Security

The command-line tool does not invoke the Web Service; it generates metadata required by Enterprise Manager for target monitoring purposes via the WSDL file. When you run this tool, you only need read permission on the WSDL file or URL and permission to save generated files to the appropriate directory.

6.2.1.3 Generating the Files

Example 6–1 shows a sample WSDL file passed to the command-line tool to generate the target metadata and collection files.

Example 6-1 Sample WSDL File TargetWithWSMgmtInterface

<?xml version="1.0" encoding="UTF-8" ?>
<definitions
     name="TargetWithWSMgmtInterface"
     targetNamespace="http://tempuri.org"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://tempuri.org"
     xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
     xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
     xmlns:ns1="http://mypackage3/MyProdMgmtInterface.wsdl/types"
     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    >
    <types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema"
 targetNamespace="http://tempuri.org" elementFormDefault="qualified"
             xmlns:tns="http://tempuri.org"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/"/>
        <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://mypackage3/MyProdMgmtInterface.wsdl/types"
             elementFormDefault="qualified" xmlns:tns="http://mypackage3/MyProdMgmtInterface.wsdl/types"
             xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/">
            <complexType name="ArrayOfstring">
                <complexContent>
                    <restriction base="soap11-enc:Array">
                        <attribute ref="soap11-enc:arrayType" wsdl:arrayType="string[]"/>
                    </restriction>
                </complexContent>
            </complexType>
        </schema>
    </types>
    <message name="TargetWithWSMgmtInterfaceSEI1_getNumActiveThreads"/>
    <message name="TargetWithWSMgmtInterfaceSEI1_getUserSessionID">
        <part name="user" type="xsd:string"/>
    </message>
    <message name="TargetWithWSMgmtInterfaceSEI1_getUserSessionIDResponse">
        <part name="result" type="xsd:string"/>
    </message>
    <message name="TargetWithWSMgmtInterfaceSEI1_getNumActiveThreadsResponse">
        <part name="result" type="xsd:long"/>
    </message>
    <message name="TargetWithWSMgmtInterfaceSEI1_getActiveUsers"/>
    <message name="TargetWithWSMgmtInterfaceSEI1_getActiveUsersResponse">
        <part name="result" type="ns1:ArrayOfstring"/>
    </message>
    <portType name="ManagementInterfaceWS">
        <operation name="getActiveUsers">
            <input message="tns:TargetWithWSMgmtInterfaceSEI1_getActiveUsers"/>
            <output message="tns:TargetWithWSMgmtInterfaceSEI1_getActiveUsersResponse"/>
        </operation>
        <operation name="getNumActiveThreads">
            <input message="tns:TargetWithWSMgmtInterfaceSEI1_getNumActiveThreads"/>
            <output message="tns:TargetWithWSMgmtInterfaceSEI1_getNumActiveThreadsResponse"/>
        </operation>
        <operation name="getUserSessionID" parameterOrder="user">
            <input message="tns:TargetWithWSMgmtInterfaceSEI1_getUserSessionID"/>
            <output message="tns:TargetWithWSMgmtInterfaceSEI1_getUserSessionIDResponse"/>
        </operation>
    </portType>
    <binding name="TargetWithWSMgmtInterfaceSoapHttp" type="tns:ManagementInterfaceWS">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="getActiveUsers">
            <soap:operation soapAction="http://tempuri.org:getActiveUsers"/>
            <input>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts=""/>
            </input>
            <output>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts="result"/>
            </output>
        </operation>
        <operation name="getNumActiveThreads">
            <soap:operation soapAction="http://tempuri.org:getNumActiveThreads"/>
            <input>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts=""/>
            </input>
            <output>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts="result"/>
            </output>
        </operation>
        <operation name="getUserSessionID">
            <soap:operation soapAction="http://tempuri.org:getUserSessionID"/>
            <input>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts="user"/>
            </input>
            <output>
                <soap:body use="encoded" namespace="http://tempuri.org" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                     parts="result"/>
            </output>
        </operation>
    </binding>
    <service name="ManagementInterfaceWS">
        <port name="TargetWithWSMgmtInterfacePort" binding="tns:TargetWithWSMgmtInterfaceSoapHttp">
            <soap:address location="http://144.25.119.190:8989/WS-MyProdMgmtIntf-context-root/ManagementInterfaceWS"/>
        </port>
    </service>
</definitions>

Example 6–2 uses the WSDL file shown in Example 6-1. First, the tool parses the WSDL for all port types and bindings (supported protocols such as HTTP get/post or SOAP) to list all the operations. If there are multiple port types in the WSDL, the tool first prompts you to select a port type.

Example 6-2 Sample Web Services Command-Line Tool Session




All port types for specified WSDL:
0 TargetWithWSMgmtInterfacePort
All operations for specified port type:
0   long getNumActiveThreads()
1   string getUserSessionID(string user)
2   string [] getActiveUsers()
>> Enter the index of operation to select.: 0



Next, the tool prompts you to select attributes from the return type to add to the metric.


Return value(s) for operation:
0 /tns:TargetWithWSMgmtInterfaceSEI1_getNumActiveThreadsResponse/result <long>
>> Enter the name for this metric column: ActiveThreads
>> Enter the label for this metric : ActiveThreadsLabel
>> Is this column a key <y/n> [n]: y
>> Do you want to add another metric <y/n>? [n] :
>> Enter value(s) for operation arguments:
>> Is this metric for periodic collection <y/n>? [n] : y
>> Enter the frequency of collections in seconds:12
>> Do you want to pick another operation to add <y/n>? [n] :n
>> Enter the metadata file name (metadata/TargetWithWSMgmtInterface.xml).:



The command-line tool generates the metadata required to monitor the target type TargetWithWSMgmtInterface as shown in Example 6-3.




Example 6-3 TargetWithWSMgmtInterface Target Metadata File


<?xml version='1.0'?><!DOCTYPE TargetMetadata SYSTEM "../dtds/TargetMetadata.dtd"><TargetMetadata META_VER="1.0" TYPE="TargetWithWSMgmtInterface" CATEGORY_PROPERTIES="versionCategory">
<Display>
<Label NLSID="TargetWithWSMgmtInterface">TargetWithWSMgmtInterface</Label>
<ShortName NLSID="TargetWithWSMgmtInterface">TargetWithWSMgmtInterface</ShortName>
<Description NLSID="TargetWithWSMgmtInterface">TargetWithWSMgmtInterface</Description>
</Display>
<Metric NAME="Threads" TYPE="TABLE">
<Display>
<Label NLSID="Threads">Threads</Label>
</Display>
<TableDescriptor>
<ColumnDescriptor NAME="activeThreads" TYPE="NUMBER">
<Display>
<Label NLSID="ActiveThreads">ActiveThreads</Label>
</Display>
</ColumnDescriptor>
</TableDescriptor>
<QueryDescriptor FETCHLET_ID="OJMX">
<Property NAME="machine" SCOPE="INSTANCE">HTTPMachine</Property>
<Property NAME="port" SCOPE="INSTANCE">HTTPPort</Property>
<Property NAME="metricType" SCOPE="GLOBAL" OPTIONAL="TRUE">GWS</Property>
<Property NAME="metric" SCOPE="GLOBAL">getNumActiveThreads</Property>
<Property NAME="requestBodyElement" SCOPE="GLOBAL" OPTIONAL="TRUE">tns:getNumActiveThreads</Property>
<Property NAME="authuser" SCOPE="INSTANCE" OPTIONAL="TRUE">authUser</Property>
<Property NAME="authpwd" SCOPE="INSTANCE" OPTIONAL="TRUE">authPasswd</Property>
<Property NAME="documentType" SCOPE="GLOBAL" OPTIONAL="TRUE">rpc/encoded</Property>
<Property NAME="soapVersion" SCOPE="GLOBAL" OPTIONAL="TRUE">SOAP1.1</Property>
<Property NAME="targetNamespace" SCOPE="GLOBAL" OPTIONAL="TRUE"><![CDATA[<namespace prefix="tns" uri="http://tempuri.org" />]]></Property>
<Property NAME="columnOrder" SCOPE="GLOBAL">/tns:getNumActiveThreadsResponse/result</Property>
<Property NAME="additionalNamespaces" SCOPE="GLOBAL" OPTIONAL="TRUE"><![CDATA[<namespaces><namespace prefix="tns" uri="http://tempuri.org" /><namespace prefix="mime" uri="http://schemas.xmlsoap.org/wsdl/mime/" /><namespace prefix="soap12" uri="http://schemas.xmlsoap.org/wsdl/soap12/" /><namespace prefix="ns1" uri="http://mypackage3/MyProdMgmtInterface.wsdl/types" /><namespace prefix="xsd" uri="http://www.w3.org/2001/XMLSchema" /><namespace prefix="soap" uri="http://schemas.xmlsoap.org/wsdl/soap/" /></namespaces>]]></Property>
<Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
<Property NAME="URI" SCOPE="GLOBAL">/WS-MyProdMgmtIntf-context-root/ManagementInterfaceWS</Property>
<Property NAME="soapAction" SCOPE="GLOBAL" OPTIONAL="TRUE">http://tempuri.org:getNumActiveThreads</Property>
<Property NAME="name" SCOPE="GLOBAL">getNumActiveThreads</Property>
<Property NAME="returnType" SCOPE="GLOBAL">long</Property>
<Property NAME="arguments" SCOPE="GLOBAL"><![CDATA[<arguments></arguments>]]></Property>
</QueryDescriptor>
</Metric>
<InstanceProperties>
<InstanceProperty NAME="HTTPMachine"><Display>
<Label NLSID="dms_HTTPMachine_iprop">Machine name</Label>
<ShortName NLSID="dms_HTTPMachine_iprop">Machine name</ShortName>
</Display>
</InstanceProperty>
<InstanceProperty NAME="HTTPPort"><Display>
<Label NLSID="dms_HTTPPort_iprop">Port</Label>
<ShortName NLSID="dms_HTTPPort_iprop">Port</ShortName>
</Display>
</InstanceProperty>
<InstanceProperty NAME="version" OPTIONAL="TRUE"><Display>
<Label NLSID="oc4j_version_iprop">Version of TargetWithWSMgmtInterface</Label>
<ShortName NLSID="oc4j_version_iprop">Version of TargetWithWSMgmtInterface</ShortName>
</Display>
</InstanceProperty>
<InstanceProperty NAME="authUser" OPTIONAL="TRUE"><Display>
<Label NLSID="dms_authUser_iprop">Username for basic authorization</Label>
<ShortName NLSID="dms_authUser_iprop">Username for basic authorization</ShortName>
</Display>
</InstanceProperty>
<InstanceProperty NAME="authPasswd" OPTIONAL="TRUE" CREDENTIAL="TRUE"><Display>
<Label NLSID="dms_authPasswd_iprop">Password for basic authorization</Label>
<ShortName NLSID="dms_authPasswd_iprop">Password for basic authorization</ShortName>
</Display>
</InstanceProperty>
</InstanceProperties>
</TargetMetadata>




The command-line tool also generates the requisite collection file as shown in Example 6-4.




Example 6-4 TargetWithWSMgmtInterface Default Collection File


<!DOCTYPE TargetMetadata SYSTEM "../dtds/TargetCollection.dtd"><!-- This file is generated by Collector at 2006-01-24 14:00:10 -->

<TargetCollection TYPE="TargetWithWSMgmtInterface" NAME="TargetWithWSMgmtInterface" INCLUDE_DEFAULT="TRUE">
        <CollectionItem NAME="Threads" UPLOAD="5">
                <Schedule>
                        <IntervalSchedule INTERVAL="12" TIME_UNIT="Sec"/>
                </Schedule>
        </CollectionItem>

</TargetCollection>




After the tool generates the target metadata and collection files, you can create the Management Plug-in archive. See Section 6.6, "Creating a Management Plug-in Archive".












6.3 Monitoring JMX Applications Deployed on Oracle Application Servers


The Java Management Extensions (JMX) framework improves manageability of your JMX-instrumented applications by enabling you to see what is happening inside. You gain insight into your applications and infrastructure through modular plug-ins called Managed Beans (MBeans). MBeans integrate with your application, components (such as Enterprise Java-Beans), or other resources to expose attributes (values) and operations.


The OJMX fetchlet, supplied with 10.2 Management Agents, enables you to monitor key metrics in your JMX-instrumented applications deployed on Oracle Application Server 10.1.3 or above. The fetchlet extends monitoring capabilities via JMX to the J2EE 1.4-compliant Oracle containers for J2EE (OC4J) servers themselves.


Monitoring JMX-instrumented applications/servers with Enterprise Manager entails defining a new target type that Enterprise Manager can monitor via Management Plug-ins. As with the Web Services wsperfcli command-line tool, Enterprise Manager provides an emjmxcli command-line tool to automate the generation of the target metadata and collection files.


Prerequisites


    

  • 

    Oracle Application Server 10.1.3 instance running on a specific host with a JMX-enabled application deployed on it that needs to be monitored as a target in Enterprise Manager Grid Control.
    

    • 

  • 

    Enterprise Manager Grid Control Management Agent version 10.2.0.2 or greater installed on that host.
    

    • 

  • 

    Enterprise Manager Grid Control Management Server (OMS) version 10.2.0.2 or greater with which the Management Agent communicates.
    

    • 



Known Limitations


    

  • 

    Currently, the emjmxcli tool and OJMX fetchlet only allow you to browse and monitor MBeans (system and application-defined) that are available on the default MBeanserver on the target OC4J instance. The emjmxcli tool primarily handles attributes and parameter and return values for operations that are OpenTypes. Examples: SimpleTypes, CompositeTypes, TabularTypes, and arrays of SimpleTypes.
    

    • 





6.3.1 Creating Metadata and Default Collection Files


As with Web Services, the JMX command-line tool (emjmxcli) simplifies creating the requisite target definition files: metadata and the default collection file. The tool is an offline configuration utility that connects you to an MBeanServer and enables you to browse available MBeans. It can also append metrics to an existing set of files during a subsequent invocation of the tool.


During a command-line tool session, you select specific MBeans and then choose the desired attributes/statistical values or operations Enterprise Manager needs to retrieve or invoke periodically on these MBeans to collect these values. The tool helps define packaging for these collected values as one or more Enterprise Manager metrics (with columns), and also enables you to specify a metric collection interval.




6.3.1.1 JMX Command-line Tool Syntax


The JMX command-line tool syntax is as follows for a JMX-enabled target on an OC4J:


emjmxcli <TARGET_HOME>
                [  -h <hostname>
                   -p <port>
                   -u <username>
                   -c <credential/password>
                   -w <work directory>
                   -e <true/false>
                   [-m <MBeanName> | -d <jmx_domain> | -s <mBeanPattern>]
                ]



<TARGET_HOME> is an Oracle Home directory 10.1.3 or greater Oracle Application Server Container for J2EE (OC4J).


The emjmxcli command accepts the following options:


    

  • 

    -h Hostname of the OC4J. Default: "localhost"
    

    • 

  • 

    -p RMI/RMIS port of the OC4J. Default: "23791" From the ORACLE_HOME/opmn/bin directory of your Application Server 10.1.3.0 or later instance, run opmnctl status -1 to determine the RMI port for the OC4J for which MBeans were deployed.
    

    • 

  • 

    -u Valid username for the OC4J. Default: "oc4jadmin"
    

    • 

  • 

    -c Password associated with the OC4J user specified by the -u option. Default: None. If you do not specify a password, you are prompted for the password.
    

    • 

  • 

    -w Directory where the metadata and default collection files created by the JMX command-line tool are placed. Default: Current directory. When invoking the command-line tool, you must have write permission on this directory to create subdirectories and add files. If the metadata and default collection files already exist within that directory, you have the option of appending to or overwriting the original files.
    

    • 

  • 

    -e Whether or not the RMIS connection to the OC4J is enabled (true or false). Default: false
    

    • 



You can also specify ONE of the following three parameters (-m, -d or -s) to retrieve a subset of MBeans available on the MBeanServer. By default, all MBeans on the MBeanServer are displayed for you to select from if none of these parameters are specified.


    

  • 

    -m MBean ObjectName of the required MBean that needs to be retrieved and examined. If this is an ObjectName pattern-matching multiple MBeans, you are shown a list of all MBeans that match the pattern, and you can select one at a time to work on.
    

    • 

  • 

    -d MBean domain of the required application whose MBeans need to be retrieved and examined. For example, you want to browse all MBeans for an application (myApp). MBeans for this application would be available in the JMX domain "myApp".
    

    • 

  • 

    -s MBean pattern-matching an existing set of MBeans from which the metrics are to be defined. The -s parameter allows bulk retrieval of JMX Attributes/Statistics from multiple MBeans of a similar type.
    

    If you specify the -s parameter, the resulting metrics created during this emjmxcli session appear as a table in the Enterprise Manager console with multiple rows — one row representing each MBean that matches the specified pattern, and with the MBean ObjectName as a key column. For example, if you specify -s 'oc4j:j2eeType=Servlet,*' the resulting metric will have multiple rows, one for each servlet that matches the ObjectName pattern. Besides the MBean ObjectName column, other columns would be the attributes or fields from the return object of the operation, selected during the emjmxcli session.
    

    • 








6.3.1.2 Generating the Files


To start the JMX command-line tool:


    

  1. 

    Go to the $AGENT_HOME/bin directory.
    

    2. 

  2. 

    Run the following command:
    

    emjmxcli <Oracle Home of the target 10.1.3 or greater OC4J> [OPTIONS]

    

    Once invoked, the command-line interface automatically prompts you for the requisite information, as shown in Example 6-6. If you need to abort a JMX command-line tool session, you can press Ctrl+C at any point to exit. Session information will not be saved.
    

    

    Example 6-5 Sample EMJMXCLI Invocation
    

    ./emjmxcli /scratch/shiphomes/oc4j/1013_SOA_M1/ -h localhost -p 12404 -m 'oc4j:J2EEApplication=orabpel,name=\"ServerBean\",*'

    

    3. 





Example 6-6 Sample EMJMXCLI Session


oracleHome=/ade/sparmesw_10202_ssm/oracle
targetHome=/scratch/shiphomes/oc4j/1013_SOA_M1/
The Port is 12404

Connecting to server: localhost:12404
Connecting as user: oc4jadmin
Enter the password:         

Obtained 1 MBeans matching pattern oc4j:J2EEApplication=orabpel,name="ServerBean",*. 

Enter the target type for this metric: [myJ2EEApp] myBPELApp



This is the target type for the new J2EE application as it should show up within Enterprise Manager.


Enter the target version: [1.0] 

Enter the target metadata file: [./metadata/myBPELApp.xml] 



This is the location of the metadata file that emjmxcli generates. You must have write permission on the directories where the target metadata and default collection files are to be created.


Enter the default collections file: [./default_collection/myBPELApp.xml] 
The file ./metadata/myBPELApp.xml already exists. 
Do you want to overwrite the existing file, append to it, or quit <o/a/q>? [a] a
Appending to existing file: ./metadata/myBPELApp.xml.
The available targets are: 
0: Identifies a deployed stateless session bean
        (oc4j:EJBModule="ejb_ob_engine",J2EEApplication=orabpel,J2EEServer=standalone,j2eeType=StatelessSessionBean,name="ServerBean")

Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 0



If multiple MBeans matched the -m <MBean pattern> specified when emjmxcli was invoked, all MBean ObjectNames matching the pattern are listed during this part of the command-line session, at which point you can select one among the list. You can choose another MBean from the above list after creating metrics for the first one without exiting this emjmxcli session.


If you want to append metrics from another MBean that does not match the above -m pattern, you must exit and start another emjmxcli session with the MBean ObjectName/Pattern of the latter MBean, and create metrics from this MBean which will be appended to the original target metadata and default collection files from the previous emjmxcli session. Using this method, you can append metrics created from multiple emjmxcli sessions to the same target metadata and default collection files, if necessary.


Following metric source types are available for selected target(s):
        0: JMX Attributes
        1: JMX Operations
        2: J2EE Statistics
Enter the index of your choice or press <Ctrl-C> to quit: 2

Statistics are: 
        0: CreateCount
        1: ejbCreate()ClientActive
        2: ejbCreate()ClientTime
        3: ejbRemove()ClientActive
        4: ejbRemove()ClientTime
        5: MethodReadyCount
        6: RemoveCount
        7: setSessionContext(javax.ejb.SessionContext)ClientActive
        8: setSessionContext(javax.ejb.SessionContext)ClientTime
Select one or more items as comma-separated indices: 0,6

JavaBean is : CreateCount
        0: count
        1: description
        2: lastSampleTime
        3: name
        4: startTime
        5: unit



This indicates that the Statistic call CreateCount is not a simple data type, but has a JavaBean pattern with the above listed properties, of which some may interest you.


Select one or more items as comma-separated indices: 0
JavaBean is : RemoveCount
        0: count
        1: description
        2: lastSampleTime
        3: name
        4: startTime
        5: unit
Select one or more items as comma-separated indices: 0
Number of possible columns in the resultant metric are 2.

Enter the name for this metric column at index=0 : [countOfCreateCount] createCount



You can specify any meaningful name here. If you do not specify a name, the JMX command-line tool generates a default name that may not be appropriate in all cases.


Is this column a KEY Column <y/n>? [n] 



In situations where multiple rows can be returned, as might be the case when the Attribute or return value of the Operation is TabularData, you need to specify one or more of your chosen metrics as "Key" columns.


Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [createCount] 
Enter the NLSID for column: [createCount] 
Enter the UNIT for column "createCount": [count] 
Do you want to create a threshold for this column <y/n>? [n] y
Creating threshold!!
Following operators are available for creating thresholds: 
 0: GT
 1: EQ
 2: LT
 3: LE
 4: GE
 5: CONTAINS
 6: NE
 7: MATCH



If you want to create a threshold on this column, you can specify an operator and then a value that would trigger a CRITICAL or WARNING alert.


Enter the index of your choice or press <Ctrl-C> to quit: 0
Enter the CRITICAL threshold: [NotDefined] 100
Enter the WARNING threshold: [NotDefined] 85
Enter the number of occurrences that trigger threshold: [6] 3



This is the number of consecutive occurrences of above CRITICAL or WARNING values that would trigger an alert.


Enter the message to be used when threshold is triggered: [createCount is %value%
and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold.] 
Enter NLSID for the message used when threshold is triggered: [createCount_cond] 
Enter the name for this metric column at index=1 : [countOfRemoveCount] removeCount
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [removeCount] 
Enter the NLSID for column: [removeCount] 
Enter the UNIT for column "removeCount": [count] 
Do you want to create a threshold for this column <y/n>? [n] 
Enter the name of this metric: ServerBeanStats
Enter the label for this metric: [ServerBeanStats] 

Do you want periodic collection for this metric <y/n>? [n] y



If the metric does not have to be collected periodically, as would be the case with real-time-only metrics, you can specify "no".


Enter the collection interval in seconds: 60
Periodic collection interval is: 60 seconds.

Do you want to create another metric <y/n>? [n] y
The available targets are: 
0: Identifies a deployed stateless session bean
        (oc4j:EJBModule="ejb_ob_engine",J2EEApplication=orabpel,J2EEServer=standalone,j2eeType=StatelessSessionBean,name="ServerBean")

Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 0



If multiple MBeans match the MBean pattern for the -m option (specified when emjmxcli was invoked) you can select a different MBean from the above list for the next iteration of this command-line session.


Following metric source types are available for selected target(s):
        0: JMX Attributes
        1: JMX Operations
        2: J2EE Statistics

Enter the index of your choice or press <Ctrl-C> to quit: 0

Attributes are:         0: activeInstances       Return Value: int
        1: activeInstancesHighWaterMark  Return Value: int
        2: eventProvider         Return Value: boolean
        3: maxInstances  Return Value: int
        4: minInstances  Return Value: int
        5: ObjectName    Return Value: javax.management.ObjectName
        6: stateManageable       Return Value: boolean
        7: statisticsProvider    Return Value: boolean
        8: stats         Return Value: javax.management.j2ee.statistics.Stats
        9: transactionTimeout    Return Value: int
Select one or more items as comma-separated indices: 0,3,4

Number of possible columns in the resultant metric are 3.
Enter the name for this metric column at index=0 : [activeInstances] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [activeInstances] 
Enter the NLSID for column: [activeInstances] 
Enter the UNIT for column "activeInstances": [millisec, kb etc.. ] Do you want to create a threshold for this column <y/n>? [n] 
Enter the name for this metric column at index=1 : [maxInstances] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [maxInstances] 
Enter the NLSID for column: [maxInstances] 
Enter the UNIT for column "maxInstances": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] 

Enter the name for this metric column at index=2 : [minInstances] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [minInstances] 
Enter the NLSID for column: [minInstances] 
Enter the UNIT for column "minInstances": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] 

Enter the name of this metric: ServerBeanCount
Enter the label for this metric: [ServerBeanCount] 

Do you want periodic collection for this metric <y/n>? [n] y
Enter the collection interval in seconds: 300
Periodic collection interval is: 300 seconds.

Do you want to create another metric <y/n>? [n] n
Written the metadata xml file: ./metadata/myBPELApp.xml.
Updated the default collection file for myBPELApp at location ./default_collection/myBPELApp.xml.
Exiting...




After the JMX command-line tool generates the target metadata and collection files, you can create the Management Plug-in archive. See Section 6.6, "Creating a Management Plug-in Archive". A sample of each generated file from the command-line tool session above is shown in Example 6–7 and Example 6–8.




Example 6-7 Generated Target Metadata File


<!DOCTYPE TargetMetadata SYSTEM "../dtds/TargetMetadata.dtd">
<TargetMetadata META_VER="1.0" TYPE="myBPELApp" CATEGORY
_PROPERTIES="VersionCategory">
   <Display>
      <Label NLSID="myBPELAppNLSID">myBPELApp</Label>
      <ShortName NLSID="myBPELAppShortName">myBPELApp</ShortName>
      <Description NLSID="myBPELAppDescription">myBPELApp</Description>
   </Display>

   <Metric NAME="ServerBeanStats" TYPE="TABLE">
      <Display>
         <Label NLSID="ServerBeanStats">ServerBeanStats</Label>
      </Display>
      <TableDescriptor>
         <ColumnDescriptor NAME="createCount" TYPE="NUMBER">
            <Display>
               <Label NLSID="createCount">createCount</Label>
               <Unit NLSID="count">count</Unit>
            </Display>
         </ColumnDescriptor>
         <ColumnDescriptor NAME="removeCount" TYPE="NUMBER">
            <Display>
               <Label NLSID="removeCount">removeCount</Label>
               <Unit NLSID="count">count</Unit>
            </Display>
         </ColumnDescriptor>
      </TableDescriptor>
      <QueryDescriptor FETCHLET_ID="OJMX">
         <Property NAME="machine" SCOPE="INSTANCE">HTTPMachine</Property>
         <Property NAME="OracleHome" SCOPE="INSTANCE">OracleHome</Property>
         <Property NAME="oc4jInstanceName" SCOPE="INSTANCE"  OPTIONAL="TRUE">OC4JInstanceName</Property>
         <Property NAME="jvmId" SCOPE="INSTANCE" OPTIONAL="TRUE">JVMId</Property>
         <Property NAME="mgmtWebSite" SCOPE="INSTANCE" OPTIONAL="TRUE">MgmtWebSite</Property>
         <Property NAME="authuser" SCOPE="INSTANCE" OPTIONAL="TRUE">authUser</Property>
         <Property NAME="authpwd" SCOPE="INSTANCE" OPTIONAL="TRUE">authPasswd</Property>
         <Property NAME="metric" SCOPE="GLOBAL">ServerBeanStats</Property>
         <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
         <Property NAME="name" SCOPE="GLOBAL">getStatistics</Property>
         <Property NAME="signature" SCOPE="GLOBAL">objectName,statNames,languageCode,countryCode</Property>
<Property NAME="returnType" SCOPE="GLOBAL">arrayOfComplexObjectBean</Property>
         <Property NAME="dontAddDefaultRowKey" SCOPE="GLOBAL">true</Property>
         <Property NAME="columnOrder" SCOPE="GLOBAL">/CreateCount/count,/RemoveCount/count</Property>
         <Property NAME="arguments" SCOPE="GLOBAL">
            <![CDATA[<arguments>
   <argument>
      <value>oc4j:EJBModule="ejb_ob_engine",J2EEApplication=orabpel,J2EEServer=standalone,j2eeType=StatelessSessionBean,name="ServerBean"</value>
   </argument>
   <argument>
      <value>CreateCount</value>
      <value>RemoveCount</value>
   </argument>
   <argument>
      <value>en</value>
   </argument>
   <argument>
      <value>US</value>
   </argument>
</arguments>]]>
         </Property>
      </QueryDescriptor>
   </Metric>

<Metric NAME="ServerBeanCount" TYPE="TABLE">
      <Display>
         <Label NLSID="ServerBeanCount">ServerBeanCount</Label>
      </Display>
      <TableDescriptor>
         <ColumnDescriptor NAME="activeInstances" TYPE="NUMBER">
            <Display>
               <Label NLSID="activeInstances">activeInstances</Label>
            </Display>
         </ColumnDescriptor>
         <ColumnDescriptor NAME="maxInstances" TYPE="NUMBER">
            <Display>
               <Label NLSID="maxInstances">maxInstances</Label>
            </Display>
         </ColumnDescriptor>
         <ColumnDescriptor NAME="minInstances" TYPE="NUMBER">
            <Display>
               <Label NLSID="minInstances">minInstances</Label>
            </Display>
         </ColumnDescriptor>
      </TableDescriptor>
      <QueryDescriptor FETCHLET_ID="OJMX">
         <Property NAME="machine" SCOPE="INSTANCE">HTTPMachine</Property>
         <Property NAME="OracleHome" SCOPE="INSTANCE">OracleHome</Property>
         <Property NAME="oc4jInstanceName" SCOPE="INSTANCE" OPTIONAL="TRUE">OC4JInstanceName</Property>
         <Property NAME="jvmId" SCOPE="INSTANCE" OPTIONAL="TRUE">JVMId</Property>
         <Property NAME="mgmtWebSite" SCOPE="INSTANCE" OPTIONAL="TRUE">MgmtWebSite</Property>
         <Property NAME="authuser" SCOPE="INSTANCE" OPTIONAL="TRUE">authUser</Property>
         <Property NAME="authpwd" SCOPE="INSTANCE" OPTIONAL="TRUE">authPasswd</Property>
         <Property NAME="metric" SCOPE="GLOBAL">ServerBeanCount</Property>
         <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
         <Property NAME="name" SCOPE="GLOBAL">getAttributes</Property>
         <Property NAME="signature" SCOPE="GLOBAL">objectName,attributeNames,languageCode,countryCode</Property>
         <Property NAME="returnType" SCOPE="GLOBAL">arrayOfComplexObjectBean</Property>
         <Property NAME="dontAddDefaultRowKey" SCOPE="GLOBAL">true</Property>
         <Property NAME="columnOrder" SCOPE="GLOBAL">/activeInstances,/maxInstances,/minInstances</Property>
<Property NAME="arguments" SCOPE="GLOBAL">
            <![CDATA[<arguments>
   <argument>      <value>oc4j:EJBModule="ejb_ob_engine",J2EEApplication=orabpel,J2EEServer=standalone,j2eeType=StatelessSessionBean,name="ServerBean"</value>
   </argument>
   <argument>
      <value>activeInstances</value>
      <value>maxInstances</value>
      <value>minInstances</value>
   </argument>
   <argument>
      <value>en</value>
   </argument>
   <argument>
      <value>US</value>
   </argument>
</arguments>]]>
         </Property>
      </QueryDescriptor>
   </Metric>

<Metric NAME="Response" TYPE="TABLE">
      <Display>
         <Label NLSID="Response">Response</Label>
      </Display>
      <TableDescriptor>
         <ColumnDescriptor NAME="Status" TYPE="NUMBER">
            <Display>
               <Label NLSID="Status">Status</Label>
            </Display>
         </ColumnDescriptor>
      </TableDescriptor>
      <QueryDescriptor FETCHLET_ID="OJMX">
         <Property NAME="machine" SCOPE="INSTANCE">HTTPMachine</Property>
         <Property NAME="OracleHome" SCOPE="INSTANCE">OracleHome</Property>
         <Property NAME="oc4jInstanceName" SCOPE="INSTANCE" OPTIONAL="TRUE">OC4JInstanceName</Property>
         <Property NAME="jvmId" SCOPE="INSTANCE" OPTIONAL="TRUE">JVMId</Property>
         <Property NAME="mgmtWebSite" SCOPE="INSTANCE" OPTIONAL="TRUE">MgmtWebSite</Property>
         <Property NAME="authuser" SCOPE="INSTANCE" OPTIONAL="TRUE">authUser</Property>
         <Property NAME="authpwd" SCOPE="INSTANCE" OPTIONAL="TRUE">authPasswd</Property>
         <Property NAME="metric" SCOPE="GLOBAL">Response</Property>
         <Property NAME="delimiter" SCOPE="GLOBAL">|</Property>
         <Property NAME="name" SCOPE="GLOBAL">getAttributes</Property>
         <Property NAME="signature" SCOPE="GLOBAL">objectName,attributeNames,languageCode,countryCode</Property>
         <Property NAME="returnType" SCOPE="GLOBAL">arrayOfComplexObjectBean</Property>
         <Property NAME="dontAddDefaultRowKey" SCOPE="GLOBAL">true</Property>
         <Property NAME="columnOrder" SCOPE="GLOBAL">/state</Property>
         <Property NAME="arguments" SCOPE="GLOBAL">
            <![CDATA[<arguments>
   <argument>
      <value>oc4j:J2EEServer=standalone,j2eeType=J2EEApplication,name=orabpel</value>
   </argument>
   <argument>
      <value>state</value>
   </argument>
   <argument>
      <value>en</value>
   </argument>
   <argument>
      <value>US</value>
   </argument>
</arguments>]]>
         </Property>
      </QueryDescriptor>
   </Metric>

   <InstanceProperties>
      <InstanceProperty NAME="HTTPMachine">
         <Display>
            <Label NLSID="dms_HTTPMachine_iprop">Machine name</Label>
         </Display>
      </InstanceProperty>
      <InstanceProperty NAME="OracleHome">
         <Display>
            <Label NLSID="dms_OracleHome_iprop">Oracle home path</Label>
         </Display>
      </InstanceProperty>
<InstanceProperty NAME="OC4JInstanceName" OPTIONAL="TRUE"><Display><Label NLSID="OC4JInstanceNameiprop">OC4JInstanceName</Label></Display>home</InstanceProperty>
      <InstanceProperty NAME="JVMId" OPTIONAL="TRUE"><Display><Label NLSID="JVMId_iprop">JVMId</Label></Display>1</InstanceProperty>
      <InstanceProperty NAME="MgmtWebSite" OPTIONAL="TRUE"><Display><Label NLSID="MgmtWebSite_iprop">MgmtWebSite</Label></Display>default-web-site</InstanceProperty>
      <InstanceProperty NAME="URI" OPTIONAL="TRUE"><Display><Label NLSID="URI">URI</Label></Display>/JMXSoapAdapter/JMXSoapAdapter</InstanceProperty>
      <InstanceProperty NAME="authUser" OPTIONAL="TRUE">
         <Display>
            <Label NLSID="dms_authUser_iprop">Username for Basic authorization</Label>
         </Display>
      </InstanceProperty>
      <InstanceProperty NAME="authPasswd" OPTIONAL="TRUE" CREDENTIAL="TRUE">
         <Display>
            <Label NLSID="dms_authPasswd_iprop">Password for Basic authorization</Label>
         </Display>
      </InstanceProperty>
      <InstanceProperty NAME="Version" OPTIONAL="TRUE"><Display><Label NLSID="oc4j_version_iprop">Version of myBPELApp</Label></Display>1.0</InstanceProperty>
   </InstanceProperties>
</TargetMetadata>






Example 6-8 Generated Metric Collection File


<!DOCTYPE TargetCollection SYSTEM "../dtds/TargetCollection.dtd">
<!-- This file is generated by Collector at 2006-04-28 12:11:55 -->

<TargetCollection TYPE="myBPELApp" INCLUDE_DEFAULT="TRUE">
        <CollectionItem NAME="ServerBeanStats" UPLOAD="YES">
                <Schedule>
                        <IntervalSchedule INTERVAL="60" TIME_UNIT="Sec"/>
                </Schedule>
                <MetricColl NAME="ServerBeanStats">
                        <Condition COLUMN_NAME="createCount" CRITICAL="100"           WARNING="85" OPERATOR="GT" OCCURRENCES="3" MESSAGE="createCount is %value% and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold." MESSAGE_NLSID="createCount_cond"/>
                </MetricColl>
        </CollectionItem>
        <CollectionItem NAME="ServerBeanCount" UPLOAD="YES">
                <Schedule>
                        <IntervalSchedule INTERVAL="300" TIME_UNIT="Sec"/>
                </Schedule>
                <MetricColl NAME="ServerBeanCount">
                </MetricColl>
        </CollectionItem>

        <CollectionItem NAME="Response" UPLOAD="YES">
                <Schedule>
                        <IntervalSchedule INTERVAL="30" TIME_UNIT="Sec"/>
                </Schedule>
                <MetricColl NAME="Response">
                        <Condition COLUMN_NAME="Status" CRITICAL="1" WARNING="NotDefined" OPERATOR="NE" OCCURRENCES="2" MESSAGE="Status is %value% and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold." MESSAGE_NLSID="Status_cond"/>
                </MetricColl>
        </CollectionItem>
</TargetCollection>











6.3.2 Displaying Target Status Information


For the status information of your targets to appear correctly within the Enterprise Manager console, you must define a metric, called Response, that has a column, named Status, with a critical threshold set. The status of target instances of this type appears in the console as "Up" (available) if the metric value is below the critical threshold. When the threshold is exceeded, the target status appears as "Down" in the console.


You can create the Response metric in another emjmxcli session (append the metric to the metadata and collection files created in an earlier session). Example 6–9 illustrates adding a Response metric to previously generated metadata and collection files from a new command-line session.




Example 6-9 Adding a Response Metric


./emjmxcli /scratch/shiphomes
//oc4j/1013_PRODUCTION/ -p 12403 -c welcome1 -m 'oc4j:j2eeType=J2EEApplication,n
ame=orabpel,*'

oracleHome=/ade/sparmesw_10202_ssm/oracle
targetHome=/scratch/shiphomes//oc4j/1013_PRODUCTION/
The Port is 12403

Connecting to server: localhost:12403
Connecting as user: oc4jadmin

Obtained 1 MBeans matching pattern oc4j:j2eeType=J2EEApplication,name=orabpel,*.

Enter the target type for this metric: [myJ2EEApp] myBPELApp

Enter the target version: [1.0]

Enter the target metadata file: [./metadata/myBPELApp.xml]

Enter the default collections file: [./default_collection/myBPELApp.xml]
The file ./metadata/myBPELApp.xml already exists.

Do you want to overwrite the existing file, append to it, or quit <o/a/q>? [a] a
Appending to existing file: ./metadata/myBPELApp.xml.
The available targets are:
0: Identifies a J2EE application EAR that has been deployed
        (oc4j:J2EEServer=standalone,j2eeType=J2EEApplication,name=orabpel)

Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 0
Following metric source types are available for selected target(s):
        0: JMX Attributes
        1: JMX Operations

Enter the index of your choice or press <Ctrl-C> to quit: 0

Attributes are:
        0: allAccessibleGroups   Return Value: java.util.Set
        1: allAccessibleUsers    Return Value: java.util.Set
        2: applicationRootDirectoryPath  Return Value: java.lang.String
        3: archivePath   Return Value: java.lang.String
        4: childApplicationNames         Return Value: [Ljava.lang.String;
        5: childApplications     Return Value: [Ljavax.management.ObjectName;
        6: dataSourcesDescriptor         Return Value: java.lang.String
        7: deploymentDescriptor  Return Value: java.lang.String
        8: ejbClassLoaderPath    Return Value: java.lang.String
        9: eventProvider         Return Value: boolean
        10: groups       Return Value: java.util.Set
        11: iiopStubs    Return Value: [B
        12: metricRulesDescriptor        Return Value: java.lang.String
        13: Modules      Return Value: [Ljavax.management.ObjectName;
        14: objectName   Return Value: java.lang.String
        15: ohsRouting   Return Value: boolean
        16: parentApplication    Return Value: javax.management.ObjectName
        17: parentApplicationName        Return Value: java.lang.String
        18: properties   Return Value: java.util.Properties
        19: proprietaryDeploymentDescriptor      Return Value: java.lang.String
        20: proxyInterfaceSQLObjects     Return Value: [Ljava.lang.String;
        21: routingId    Return Value: java.lang.String
        22: Server       Return Value: javax.management.ObjectName
        23: sharedLibraryImports   Return Value: [Loracle.oc4j.admin.management.shared.SharedLibraryImport;
        24: startTime    Return Value: long
        25: state        Return Value: int
        26: stateManageable      Return Value: boolean
        27: statisticsProvider   Return Value: boolean
        28: syntheticWebModules  Return Value: oracle.oc4j.admin.management.shared.WebModule
        29: users        Return Value: java.util.Set
        30: webSite      Return Value: java.lang.String
        31: webSiteBindings      Return Value: java.util.Map
Select one or more items as comma-separated indices: 25

Number of possible columns in the resultant metric are 1.

Enter the name for this metric column at index=0 : [state] Status
Is this column a KEY Column <y/n>? [n]
Is this column for SUMMARY_UI <y/n>? [n]
Enter the label for column: [Status]
Enter the NLSID for column: [Status]
Enter the UNIT for column "Status": [millisec, kb etc.. ]
Do you want to create a threshold for this column <y/n>? [n] y
Creating threshold!!
Following operators are available for creating thresholds:
 0: GT
 1: EQ
 2: LT
 3: LE
 4: GE
 5: CONTAINS
 6: NE
 7: MATCH
Enter the index of your choice or press <Ctrl-C> to quit: 6
Enter the CRITICAL threshold: [NotDefined] 1
Enter the WARNING threshold: [NotDefined]
Enter the number of occurrences that trigger threshold: [6] 2
Enter the message to be used when threshold is triggered: [Status is %value% and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold.]
Enter NLSID for the message used when threshold is triggered: [Status_cond]

Enter the name of this metric: Response
Enter the label for this metric: [Response]

Do you want periodic collection for this metric <y/n>? [n] y
Enter the collection interval in seconds: 30
Periodic collection interval is: 30 seconds.

Do you want to create another metric <y/n>? [n] n
Written the metadata xml file: ./metadata/myBPELApp.xml.
Updated the default collection file for myBPELApp at location ./default_collecti
on/myBPELApp.xml.
Exiting...

Please note that the Response metric collected in this emjmxcli session would be appended to the metadata and default_collection file created in an earlier session of the tool. (User can chose to overwrite the earlier file as well if they specific  the "o" option to the following prompt)

Do you want to overwrite the existing file, append to it, or quit <o/a/q>? [a] a











6.4 Monitoring a Standalone JMX-instrumented Java Application or Java Virtual Machine (JVM) Target




Note:

If your Java application is not JMX-instrumented, but you want to monitor the J2SE 5.0 JVM on which it is running, go directly to Section 6.9.3, "Configuring a Standalone Java Application or JVM Target" to create target instances of type JVM. This enables you to monitor these JVMs in Enterprise Manager Grid Control, preferably from an Enterprise Manager Agent installed on the same host as your JVM. The pre-requisites and known limitations discussed below still apply, however.


Enterprise Manager provides an out-of-box JVM target type. This enables you to add and configure metrics from standalone J2SE1.5 JVMs that are enabled for remote management in Enterprise Manager Grid Control version 10.2.0.3 or greater.


If your standalone Java application exposes data through JMX MBeans as for a J2EE application deployed on an Oracle Container for J2EE, you can use the JMX command-line tool to define such an application as an Enterprise Manager target type and generate a metadata and default collection file for this target type. You can monitor your standalone application targets from an Enterprise Manager Agent, preferably installed on the same host as your JVM. Multiple JVMs running on that host can be monitored by the same Enterprise Manager Agent.


You can collect metrics from user-defined MBeans on a standalone (J2SE1.5-based) JVM and place them into Enterprise Manager Grid Control using the JMX fetchlet. The fetchlet is designed for a standalone Sun J2SE1.5-based (or higher) JVM containing user-defined MBeans that use JMX OpenTypes as arguments and return values.


Prerequisites


    

  • 

    Java virtual machine J2SE 1.5 or higher instance running on a specific host. This JVM could be running a JMX-enabled application that exposes metrics via MBeans that need to be monitored as a target in Enterprise Manager Grid Control. If the application does not expose MBeans, the JVM itself could be monitored using the built-in JVM target type provided in Enterprise Manager Grid Control. See Section 6.9.3, "Configuring a Standalone Java Application or JVM Target" for more information.
    

    • 

  • 

    JMX agent enabled for local access. Set this system property when you start the JVM or Java application:
    

    com.sun.management.jmxremote
    

    • 

  • 

    Monitoring and management from remote systems enabled. Set this system property when you start the JVM:
    

    com.sun.management.jmxremot.port=portNum
    

    For additional information about enabling the JVM for remote management, see the following document:
    

    http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote
    

    • 

  • 

    Enterprise Manager Grid Control Management Agent version 10.2.0.3 or greater installed on that host.
    

    • 

  • 

    Enterprise Manager Grid Control Management Server (OMS) version 10.2.0.3 or greater with which the Management Agent communicates.
    

    • 



Known Limitations


    

  • 

    Currently, the emjmxcli tool only allows you to browse and monitor MBeans (platform and application-defined) that are available on the default platform MBeanserver on the target JVM instance. The tool does not support monitoring a custom MBeanServer on the target JVM instance. The emjmxcli tool primarily handles attributes as well as parameter and return values for operations that are OpenTypes, such as SimpleTypes, CompositeTypes, TabularTypes, and arrays of SimpleTypes.
    

    • 





6.4.1 Generating Metadata and Default Collection Files


As with Web Services and the J2EE application on OC4J, the command-line tool (emjmxcli) simplifies creating the requisite target definition files: metadata and the default collection file for a standalone JMX-instrumented Java application. The tool is an offline configuration utility that connects you to an MBeanServer on a J2SE1.5 or higher JVM and enables you to browse available MBeans. It can also append metrics to an existing set of files during a subsequent invocation of the tool.


During a command-line tool session, you select specific MBeans and then choose the desired attributes/statistical values or operations Enterprise Manager needs to retrieve or invoke periodically on these MBeans to collect these values. The tool helps define packaging for these collected values as one or more Enterprise Manager metrics (with columns), and also enables you to specify a metric collection interval.




6.4.1.1 JMX Command-line Tool Syntax


The JMX command-line tool syntax is as follows:


emjmxcli -t JVM
                [  -l <JMXServiceURL>
                   -h <hostname>
                   -p <port>
                   -u <username>
                   -c <credential/password>
                   -w <work directory>
                   -e <true/false>
                   [-m <MBeanName> | -d <jmx_domain> | -s <mBeanPattern>]
                ]



The emjmxcli command accepts the following options:


    

  • 

    -t JVM Indicates that the MBeanServer is on a standalone JVM
    

    • 

  • 

    -l JMXServiceURL of the target JVM
    

    • 

  • 

    -h Hostname of the JVM. Default: "localhost" if the -l option is not specified
    

    • 

  • 

    -p RMI/RMIS port of the JVM. Default: "23791" if the -l option is not specified. From the ORACLE_HOME/opmn/bin directory of your Application Server 10.1.3.0 or later instance, run opmnctl status -1 to determine the RMI port for the OC4J for which MBeans were deployed.
    

    • 

  • 

    -u Valid username for the JVM. Default: None
    

    • 

  • 

    -c Password for the above user. Default: None. The password is only used to retrieve data and is not stored anywhere.
    

    • 

  • 

    -w Work directory where the metadata and default collection files are created. Default: Current directory. When invoking the command-line tool, you must have write permission on this directory to create subdirectories and add files. If the metadata and default collection files already exist within that directory, you have the option of appending to or overwriting the original files.
    

    • 

  • 

    -e True for enabling the SSL connection to the JVM. Default: false
    

    • 



You can also specify ONE of the following three parameters (-m, -d or -s) to retrieve a subset of MBeans available on the MBeanServer. By default, all MBeans on the MBeanServer are displayed for you to select from if none of these parameters are specified.


    

  • 

    -m MBean ObjectName of the required MBean that needs to be retrieved and examined. If this is an ObjectName pattern-matching multiple MBeans, you are shown a list of all MBeans that match the pattern, and you can select one at a time to work on.
    

    • 

  • 

    -d MBean domain of the required application whose MBeans need to be retrieved and examined. For example, you want to browse all MBeans for an application (myApp). MBeans for this application would be available in the JMX domain "myApp".
    

    • 

  • 

    -s MBean pattern matching an set of similar MBeans from which the metrics are to be defined. The -s parameter allows bulk retrieval of JMX Attributes/Statistics from multiple MBeans of a similar type.
    

    If you specify the -s parameter, the resulting metrics created during this emjmxcli session appear as a table in the Enterprise Manager console with multiple rows — one row representing each MBean that matches the specified pattern, and with the MBean ObjectName as a key column. For example, if you specify -s 'oc4j:j2eeType=Servlet,*' the resulting metric will have multiple rows, one for each servlet that matches the ObjectName pattern. Besides the MBean ObjectName column, other columns would be the attributes or fields from the return object of the operation, selected during the emjmxcli session.
    

    • 








6.4.1.2 Generating the Files


The following steps explain how to prepare for and then use the JMX command-line tool to generate the files.


    

  1. 

    Bring up the standalone JVM instance with the MBeans. The following example shows an invocation of the JVM:
    

    JDK15/bin/java -Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=6789 
-Dcom.sun.management.jmxremote 
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false MyJMXEnabledApp $*

    

    The emjmxcli fetchlet connects to the port number above as a JSR-160 client.
    

    2. 

  2. 

    Go to the $ORACLE_HOME/bin directory of the 10.2.0.3 or higher version of the Enterprise Manager Agent.
    

    3. 

  3. 

    Set the environment variable as follows:
    

    setenv USER_JARS /myAppHome/<myJar1.jar>;/myAppHome/<myJar2.jar>

    

    This step is needed if custom classes are being returned in attributes and/or operations in any of the MBeans registered with the target MBeanServer. The Enterprise Manager Agent (fetchlet) can only effectively monitor attributes and/or operations that return JMX OpenTypes, but it could also handle Java Bean properties (through getters and setters) on any custom classes.
    

    

    Note:
    
If the application-defined MBeans are returning custom classes, you need to also set up the corresponding user jar file in the CLASSPATH of the Enterprise Manager Agent monitoring this application. To do this, manually insert the location of this jar into the $ORACLE_HOME/sysman/config/classpath.lst file on the Enterprise Manager Agent, then restart the Agent.
    

    4. 

  4. 

    Run the following command:
    

    ./emjmxcli –t JVM –h localhost –p 6789 u <user> -c <password>

    

    where:
    

      

    • 

      -t JVM indicates that the MBeanServer is running on a standard JVM
      

      • 

    • 

      -h Hostname where the JVM is running
      

      • 

    • 

      -p Port number that enables the JVM for JSR-160 remote access
      

      • 

    

    You can also specify an -l <JMXServiceURL> option instead of -h <host> and -p <port> options.
    

    You can invoke emjmxcli with a -w <work directory> option to create the metadata and default collection files in the specified work directory. If you do not specify -w when you start emjmxcli, it defaults to the current directory, which is the directory where you start emjmxcli.
    

    5. 



Once invoked, the command-line interface automatically prompts you for the requisite information, as shown in Example 6–10. For most of the prompts, you can just press enter to use defaults. If you need to abort a JMX command-line tool session, you can press Ctrl+C at any point to exit. Session information will not be saved.


When the session concludes after you exit, the result will be a myJ2EEApp.xml file (or whatever target type you specified) as metadata/myJ2EEApp.xml, and a default_collection/myJ2EEApp.xml file if you specified periodic collection.


Sample EMJMXCLI Invocations


The following sample enables you to browse all MBeans on a remote MBeanServer:


./emjmxcli –t JVM –p 6789 (the host defaults to “localhost”)



The following sample invokes the command-line interface and filters MBeans based on the MBeanPattern specified as the argument for the -m option:


./emjmxcli –t JVM –p 6789 –m “java.lang:*”





Example 6-10 Sample EMJMXCLI Session


oracleHome=/ade/sparmesw_emas_ml/oracle
userJars=
 
Connecting to server: localhost:6789
Connecting without authentication. For specifying username and password use
the 
-u and -c options.
 
Obtained 14 MBeans matching pattern java.lang:*. 
 
Enter the target type for this metric: [myJ2EEApp] myJavaApp
 
Enter the target version: [1.0] 
 
Enter the target metadata file: [./metadata/myJavaApp.xml] 
 
Enter the default collections file: [./default_collection/myJavaApp.xml] 
 
Enter a label for this target type: [myJavaApp] 
 
Enter a description for this target type: [myJavaApp] 
The available targets are: 
0: sun.management.CompilationImpl
        (java.lang:type=Compilation)1: sun.management.MemoryManagerImpl        (java.lang:name=CodeCacheManager,type=MemoryManager)2: sun.management.GarbageCollectorImpl        (java.lang:name=Copy,type=GarbageCollector)3: sun.management.MemoryPoolImpl        (java.lang:name=Eden Space,type=MemoryPool)4: sun.management.RuntimeImpl        (java.lang:type=Runtime)5: sun.management.ClassLoadingImpl        (java.lang:type=ClassLoading)6: sun.management.MemoryPoolImpl        (java.lang:name=Survivor Space,type=MemoryPool)7: sun.management.ThreadImpl        (java.lang:type=Threading)

8: sun.management.GarbageCollectorImpl        (java.lang:name=MarkSweepCompact,type=GarbageCollector)9: com.sun.management.UnixOperatingSystem        (java.lang:type=OperatingSystem)10: sun.management.MemoryImpl        (java.lang:type=Memory)11: sun.management.MemoryPoolImpl        (java.lang:name=Code Cache,type=MemoryPool)12: sun.management.MemoryPoolImpl        (java.lang:name=Tenured Gen,type=MemoryPool)13: sun.management.MemoryPoolImpl        (java.lang:name=Perm Gen,type=MemoryPool)Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 4Following metric source types are available for selected target(s):        0: JMX AttributesEnter the index of your choice or press <Ctrl-C> to quit: 0Attributes are:         0: BootClassPath         Return Value: java.lang.String        1: BootClassPathSupported        Return Value: boolean        2: ClassPath     Return Value: java.lang.String        3: InputArguments        Return Value: [Ljava.lang.String;        4: LibraryPath   Return Value: java.lang.String        5: ManagementSpecVersion         Return Value: java.lang.String        6: Name  Return Value: java.lang.String        7: SpecName      Return Value: java.lang.String        8: SpecVendor    Return Value: java.lang.String        9: SpecVersion   Return Value: java.lang.String        10: StartTime    Return Value: long        11: SystemProperties     Return Value:javax.management.openmbean.TabularData        12: Uptime       Return Value: long        13: VmName       Return Value: java.lang.String        14: VmVendor     Return Value: java.lang.String        15: VmVersion    Return Value: java.lang.StringSelect one or more items as comma-separated indices: 6,7,8

Number of possible columns in the resultant metric are 3.Enter the name for this metric column at index=0 : [Name] Is this column a KEY Column <y/n>? [n] yIs this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [Name] Enter the NLSID for column: [Name] Enter the UNIT for column "Name": [millisec, kb etc.. ] Enter the name for this metric column at index=1 : [SpecName] Is this column a KEY Column <y/n>? [n] Is this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [SpecName] Enter the NLSID for column: [SpecName] Enter the UNIT for column "SpecName": [millisec, kb etc.. ] Do you want to create a threshold for this column <y/n>? [n] Enter the name for this metric column at index=2 : [SpecVendor] Is this column a KEY Column <y/n>? [n] Is this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [SpecVendor] Enter the NLSID for column: [SpecVendor] Enter the UNIT for column "SpecVendor": [millisec, kb etc.. ] Do you want to create a threshold for this column <y/n>? [n]

Enter the name of this metric: RuntimeMetricEnter the label for this metric: [RuntimeMetric] Do you want periodic collection for this metric <y/n>? [n] yEnter the collection interval in seconds: 300Periodic collection interval is: 300 seconds.Do you want to create another metric <y/n>? [n] Written the metadata xml file: ./metadata/myJavaApp.xml.Creating new file: ./default_collection/myJavaApp.xml.Updated the default collection file for myJavaApp at location./default_collection/myJavaApp.xml.Exiting...










6.4.2 Using the Metadata and Default Collection Files


Look at the <currentDir>/metadata and currentDir/default_collection directories to see the myTarget.xml files (for the target type you specified earlier).


You can use these files as follows:


    

  • 

    Convert the files to a Management Plug-in Archive (MPA) and push them from OMS to the Agent and target instances created from OMS. See Section 6.6, "Creating a Management Plug-in Archive" and Section 6.9.3, "Configuring a Standalone Java Application or JVM Target".
    

    • 

  • 

    Edit the files, extract the metric definitions and QueryDescriptors, move them to other metadata and default collection files, and post-process them by creating ExecutionDescriptors as needed.
    

    • 



If you want the status information of your targets to appear correctly in the Enterprise Manager console, you need to define a Response metric. See Section 6.3.2, "Displaying Target Status Information" for more information.










6.5 Monitoring JMX Applications Deployed on Oracle Weblogic Application Servers


The JMX fetchlet, supplied with 11.1 Management Agents, enables you to monitor key metrics in your JMX-instrumented applications deployed on Oracle WebLogic Application Server 9.x or above.Monitoring JMX-instrumented applications with Enterprise Manager entails defining a new target type that Enterprise Manager can monitor via Management Plug-ins. As with the Web Services wsperfcli command-line tool (and as was possible for Oracle Application Servers (OC4J), Enterprise Manager provides an emjmxcli command-line tool to automate the generation of the target metadata and collection files for custom JMX instrumented applications on Weblogic servers.


Prerequisites


    

  • 

    Oracle WebLogic Server 9.x instance running on a specific host with a JMX-enabled application deployed on it that needs to be monitored as a target in Enterprise Manager Grid Control.
    

    • 

  • 

    Enterprise Manager Grid Control Management Agent version 11.1 or greater installed (preferably) on that host.
    

    • 

  • 

    Enterprise Manager Grid Control Management Server (OMS) version 10.2.0.4 or greater with which the Management Agent communicates.
    

    • 

  • 

    The emjmxcli tool primarily handles attributes and parameter and return values for operations that are OpenTypes. Examples: SimpleTypes, CompositeTypes, TabularTypes, and arrays of SimpleTypes.
    

    • 





6.5.1 Creating Metadata and Default Collection Files using emjmxcli


As with Web Services, the JMX command-line tool (emjmxcli) simplifies creating the requisite target definition files: metadata and the default collection file. The tool is an offline configuration utility that connects you to an MBeanServer and enables you to browse available MBeans. It can also append metrics to an existing file during a subsequent invocation of the tool.During a command-line tool session, you select specific MBeans and then choose the desired JMX attributes/statistical values the Enterprise Manager needs to retrieve or JMX operations that need to be invoked periodically on these MBeans to collect these values. The tool helps define packaging for these collected values as one or more Enterprise Manager metrics (with columns), and also enables you to specify a metric collection interval and thresholds for the columns.




6.5.1.1 JMX Command-line Tool Syntax


The JMX command-line tool syntax is as follows for a JMX-enabled target on an Oracle Weblogic Application Server:


emjmxcli -t WebLogic [help|options]
  where options are:           [  -l <JMX ServiceURL>              
              -u <username>
              -c <credential/password>
              -w <work directory>              
              [-m <MBeanName> | -d <jmx_domain> | -s mBeanPattern>]
                ]



The emjmxcli command accepts the following options:


    

  • 

    l - JMXServiceURL to the Weblogic managed server hosting the custom MBeans in the form
    

    service:jmx:t3://<host:t3port>/jndi/weblogic.management.mbeanservers.runtime

    • 

  • 

    u - Valid username for the Weblogic domain. Default: "weblogic"
    

    • 

  • 

    c - Password associated with the user specified by the -u option. Default: None. If you do not specify a password, you are prompted for the password.
    

    • 

  • 

    w - Directory where the metadata and default collection files created by the JMX command-line tool are placed. Default: Current directory.
    

    When invoking the command-line tool, you must have write permission on this directory to create subdirectories and add files. If the metadata and default collection files already exist within that directory, you have the option of appending to or overwriting the original files.
    

    • 



You can also specify ONE of the following three parameters (-m, -d or -s) to retrieve a subset of MBeans available on the MBeanServer. By default, all MBeans on the MBeanServer are displayed for you to select from if none of these parameters are specified.


    

  • 

    m - MBean ObjectName of the required MBean that needs to be retrieved and examined. If this is an ObjectName pattern-matching multiple MBeans, you are shown a list of all MBeans that match the pattern, and you can select one at a time to work on.
    

    • 

  • 

    d - MBean domain of the required application whose MBeans need to be retrieved and examined. For example, you want to browse all MBeans for an application (myApp). MBeans for this application would be available in the JMX domain "myApp".
    

    • 

  • 

    s - MBean pattern-matching an existing set of MBeans from which the metrics are to be defined. The -s parameter allows retrieval of JMX Attributes/Statistics from multiple MBeans of a similar type into one Metric.
    

    If you specify the -s parameter, the resulting metrics created during this emjmxcli session appear as a table in the Enterprise Manager console with multiple rows - one row representing each MBean that matches the specified pattern (with the MBean ObjectName as a key column if no other key columns are defined). For example, if you specify -s 'com.bea:Type=ServletRuntime,*' the resulting metric will have multiple rows, one for each servlet that matches the ObjectName pattern. Besides the MBean ObjectName key column, other columns would be the attributes or fields from the return object of the operation, selected during the emjmxcli session.
    

    • 








6.5.1.2 Generating the Files


To start the JMX command-line tool:


    

  1. 

    Go to the $AGENT_HOME/bin directory.
    

    2. 

  2. 

    Run the following command:
    

    emjmxcli -t WebLogic [OPTIONS]
    

    3. 



Once invoked, the command-line interface automatically prompts you for the requisite information, as shown in the following example. If you need to abort a JMX command-line tool session, you can press Ctrl+C at any point to exit. Session information will not be saved.


The following example illustrates a sample emjmxcli session:




Example 6-11 emjmxcli Session


ade:[ sparmesw_egcli ] [sparmesw@stacc20 bin]$ ./emjmxcli -t WebLogic -l "service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime" -u weblogic -c welcome1 -s "*:type=soainfra_bpel_requests,*"



NOTE 1: The -s option above will result in a metric with as many rows as the number of MBeans which match the ObjectName pattern specified, every time the metric is collected by the emagent. If you need to always collect from a specfic Mbean then use the -m <ObjectName> option instead of the -s <Mbean pattern> used in above example.


NOTE 2: If you need to use t3s to connect to the weblogic server then the following env variable needs to be set before invoking the emjmxcli


setenv USER_JAVA_PROPS=-Dweblogic.security.TrustKeyStore=CustomTrust
 -Dweblogic.security.CustomTrustKeyStoreFileName=$ORACLE_HOME/sysman/config/montrust/AgentTrust.jks
 -Dweblogic.security.SSL.enforceConstraints=off
 -Dweblogic.security.SSL.ignoreHostnameVerification=true
 -Djavax.net.ssl.trustStore=$ORACLE_HOME/sysman/config/montrust/AgentTrust.jks  (or set USER_JAVA_PROP= … equivalent on win32)
setenv USER_JARS  <; separated list of jars needed in classpath if custom authentication modules are involved in SSL connection>



A semi-colon is used as a delimiter for the list of jar files.


Example: setenv USER_JARS "jar1;jar2;jar3"


In some cases, if MBeans return custom weblogic objects in their MBeanInfo, the weblogic.jar may need to be set to the above env variable before invoking the emjmxcli.


Example: setenv USER_JARS $BEA_HOME/server/lib/weblogic.jar


oracleHome=/ade/sparmesw_egcli/oracle/work/middleware/oms
userJars=
Connecting to server:
 service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime
Connecting as user: weblogic
Obtained 3 MBeans matching pattern *:type=soainfra_bpel_requests,*. 

Enter the target type for this metric: [myJ2EEApp] myCustomWLApp
Enter the target version: [1.0] 
Enter the target metadata file: [./metadata/myCustomWLApp.xml] 
Enter the default collections file: [./default_collection/myCustomWLApp.xml] 
Enter a label for this target type: [myCustomWLApp] 
Enter a description for this target type: [myCustomWLApp] 
The available targets are: 
0: DMS metric mbean
        (oracle.dms:name=/soainfra/engines/bpel/requests/engine,type=soainfra_bpel_requests)
1: DMS metric mbean
        (oracle.dms:name=/soainfra/engines/bpel/requests/system,type=soainfra_bpel_requests)
2: DMS metric mbean
        (oracle.dms:name=/soainfra/engines/bpel/requests/invoke,type=soainfra_bpel_requests)
Following metric source types are available for selected target(s):
        0: JMX Attributes
Enter the index of your choice or press <Ctrl-C> to quit: 0
Attributes are: 
        0: active_count  Return Value: java.lang.Integer
        1: active_maxValue       Return Value: java.lang.Integer
        2: active_minValue       Return Value: java.lang.Integer
        3: active_value  Return Value: java.lang.Integer
        4: Name  Return Value: java.lang.String
        5: Parent        Return Value: java.lang.String
        6: scheduled_count       Return Value: java.lang.Integer
        7: scheduled_maxValue    Return Value: java.lang.Integer
        8: scheduled_minValue    Return Value: java.lang.Integer
        9: scheduled_value       Return Value: java.lang.Integer
        10: threadCount_count    Return Value: java.lang.Integer
        11: threadCount_maxValue         Return Value: java.lang.Integer
        12: threadCount_minValue         Return Value: java.lang.Integer
        13: threadCount_value    Return Value: java.lang.Integer

Select one or more items as comma separated indices: 4,0,1,2
Number of possible columns in the resultant metric are 4.

Enter the name for this metric column at index=0 : [Name] 
Is this column a KEY Column <y/n>? [n] y



Specifying "y" signifies that the value of this column is unique in case multiple rows are returned.


Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [Name] 
Enter the NLSID for column: [Name] 
Enter the UNIT for column "Name": [millisec, kb etc.. ] 

Enter the name for this metric column at index=1 : [active_count] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [active_count] 
Enter the NLSID for column: [active_count] 
Enter the UNIT for column "active_count": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] y
Creating threshold!!
Following operators are available for creating thresholds: 
 0: GT
 1: EQ
 2: LT
 3: LE
 4: GE
 5: CONTAINS
 6: NE
 7: MATCH

Enter the index of your choice or press <Ctrl-C> to quit: 0
Enter the CRITICAL threshold: [NotDefined] 50
Enter the WARNING threshold: [NotDefined] 45
Enter the number of occurrences that trigger threshold: [6] 3
Enter the message to be used when threshold is triggered: [active_count is %value% and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold.] 
Enter NLSID for the message used when threshold is triggered: [active_count_cond] Enter the name for this metric column at index=2 : [active_maxValue] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [active_maxValue] 
Enter the NLSID for column: [active_maxValue] 
Enter the UNIT for column "active_maxValue": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] 

Enter the name for this metric column at index=3 : [active_minValue] 
Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [active_minValue] 
Enter the NLSID for column: [active_minValue] 
Enter the UNIT for column "active_minValue": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] 

Enter the name of this metric: bpel_requests
Enter the label for this metric: [bpel_requests] 

Do you want periodic collection for this metric <y/n>? [n] y
Enter the collection interval in seconds: 300
Periodic collection interval is: 300 seconds.

Do you want to create another metric <y/n>? [n]  
Written the metadata xml file: ./metadata/myCustomWLApp.xml.
Creating new file: ./default_collection/myCustomWLApp.xml.
Updated the default collection file for myCustomWLApp at location ./default_collection/myCustomWLApp.xml.
Exiting...






Example 6-12 Sample emjmxcli Invocation (using -m and defining multiple metrics from multiple Mbeans in one emjmxcli session


$ ./emjmxcli -t WebLogic -l "service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime" -u weblogic -c welcome1 -m "com.bea:ApplicationRuntime=soa-infra,WebAppComponentRuntime=soa_server1_/b2b,*"

oracleHome=/ade/sparmesw_egcli/oracle/work/middleware/oms
userJars=
Connecting to server: service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime
Connecting as user: weblogic
Obtained 8 MBeans matching pattern com.bea:ApplicationRuntime=soa-infra,WebAppComponentRuntime=soa_server1_/b2b,*. 

Enter the target type for this metric: [myJ2EEApp] myCustomWLApp

Enter the target version: [1.0] 

Enter the target metadata file: [./metadata/myCustomWLApp.xml] 

Enter the default collections file: [./default_collection/myCustomWLApp.xml] 
The file ./metadata/myCustomWLApp.xml already exists. 

Do you want to overwrite the existing file, append to it, or quit <o/a/q>? [a] 



Note: Because the file already exists, it will be appended.


Appending to existing file: ./metadata/myCustomWLApp.xml.The available targets are: 0: (com.bea:ApplicationRuntime=soa-infra,Name=JspServlet,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)1: (com.bea:ApplicationRuntime=soa-infra,Name=transportServlet,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)2: (com.bea:ApplicationRuntime=soa-infra,Name=transportServletV,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)3: (com.bea:ApplicationRuntime=soa-infra,Name=b2b_starter_wls,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)4: (com.bea:ApplicationRuntime=soa-infra,Name=soa_server1_soa_server1_/b2b,ServerRuntime=soa_server1,Type=PageFlowsRuntime,WebAppComponentRuntime=soa_server1_/b2b)5 (com.bea:ApplicationRuntime=soa-infra,Name=WebServiceServlet,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)6: (com.bea:ApplicationRuntime=soa-infra,Name=RedirectUIServlet,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)7: (com.bea:ApplicationRuntime=soa-infra,Name=FileServlet,ServerRuntime=soa_server1,Type=ServletRuntime,WebAppComponentRuntime=soa_server1_/b2b)Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 4Following metric source types are available for selected target(s):        0: JMX Attributes        1: JMX OperationsEnter the index of your choice or press <Ctrl-C> to quit: 0Attributes are:         0: AppName       Return Value: java.lang.String        1: ContextPath   Return Value: java.lang.String        2: HttpServerName        Return Value: java.lang.String        3: Name  Return Value: java.lang.String        4: PageFlows     Return Value: [Ljavax.management.ObjectName;        5: Parent        Return Value: javax.management.ObjectName        6: ServerName    Return Value: java.lang.String        7: Type  Return Value: java.lang.StringSelect one or more items as comma separated indices: 3,0,1Number of possible columns in the resultant metric are 3.Enter the name for this metric column at index=0 : [Name] Is this column a KEY Column <y/n>? [n] yIs this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [Name] Enter the NLSID for column: [Name] Enter the UNIT for column "Name": [millisec, kb etc.. ] Enter the name for this metric column at index=1 : [AppName] Is this column a KEY Column <y/n>? [n] Is this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [AppName] Enter the NLSID for column: [AppName] Enter the UNIT for column "AppName": [millisec, kb etc.. ] Do you want to create a threshold for this column <y/n>? [n] Enter the name for this metric column at index=2 : [ContextPath] Is this column a KEY Column <y/n>? [n] Is this column for SUMMARY_UI <y/n>? [n] Enter the label for column: [ContextPath] Enter the NLSID for column: [ContextPath] Enter the UNIT for column "ContextPath": [millisec, kb etc.. ] Do you want to create a threshold for this column <y/n>? [n] Enter the name of this metric: PageFlowsRuntimeEnter the label for this metric: [PageFlowsRuntime] Do you want periodic collection for this metric <y/n>? [n] yEnter the collection interval in seconds: 3600Periodic collection interval is: 3600 seconds.Do you want to create another metric <y/n>? [n] y    



This indicates more metrics need to be created in this emjmxcli session. This process will repeat until you answer "n" to the question.


Do you want to create another metric <y/n>? [n] Written the metadata xml file: ./metadata/myCustomWLApp.xml.Updated the default collection file for myCustomWLApp at location ./default_collection/myCustomWLApp.xml.Exiting...



After the JMX command-line tool generates the target metadata and collection files, you can create the Management Plug-in archive.










6.5.1.3 Displaying Target Status Information


For the status information of your targets to appear correctly within the Enterprise Manager console, you must define a metric, called Response, that has a column, named Status, with a critical threshold set. The status of target instances of this type appears in the console as "Up" (available) if the metric value is below the critical threshold. When the threshold is exceeded, the target status appears as "Down" in the console.You can create the Response metric in another emjmxcli session (append the metric to the metadata and collection files created in an earlier session).




Example 6-13 Adding a Response Metric


setenv USER_JARS $T_WORK/middleware/wlserver_10.3/server/lib/weblogic.jar



This is required as some MBeans return Weblogic-specific classes which the JMX client (emjmxcli) needs in its classpath.


$ ./emjmxcli -t WebLogic -l "service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime" -u weblogic -c welcome1 -m com.bea:Type=ApplicationRuntime,Name=soa-infra,*"



For J2EE applications deployed on Weblogic it may be appropriate to make the ActiveVersionState JMX attribute of the ApplicationRuntime Mbean corresponding to the application deployment as the Status column. However, any other attribute of any other relevant Mbean to the application could also be used.


oracleHome=/ade/sparmesw_egcli/oracle/work/middleware/oms
userJars=
Connecting to server: service:jmx:t3://stbct14:22048/jndi/weblogic.management.mbeanservers.runtime
Connecting as user: weblogic
Obtained 1 MBeans matching pattern
 com.bea:Type=ApplicationRuntime,Name=soa-infra,*. 
Enter the target type for this metric: [myJ2EEApp] myCustomWLApp
Enter the target version: [1.0] 
Enter the target metadata file: [./metadata/myCustomWLApp.xml] 
Enter the default collections file: [./default_collection/myCustomWLApp.xml] 
The file ./metadata/myCustomWLApp.xml already exists. 

Do you want to overwrite the existing file, append to it, or quit <o/a/q>? [a] 
Appending to existing file: ./metadata/myCustomWLApp.xml.
The available targets are: 
0: (com.bea:Name=soa-infra,ServerRuntime=soa_server1,Type=ApplicationRuntime)
Enter the index of target/MBean you wish to monitor or press <Ctrl-C> to quit: 0
Following metric source types are available for selected target(s):
        0: JMX Attributes
        1: JMX Operations
Enter the index of your choice or press <Ctrl-C> to quit: 0
Attributes are: 
        0: ActiveVersionState    Return Value: java.lang.Integer
        1: ApplicationName       Return Value: java.lang.String
        2: ApplicationVersion    Return Value: java.lang.String
        3: ClassRedefinitionRuntime      Return Value: javax.management.ObjectName        4: ComponentRuntimes     Return Value: [Ljavax.management.ObjectName;
        5: EAR   Return Value: java.lang.Boolean
        6: HealthState   Return Value: weblogic.health.HealthState
        7: KodoPersistenceUnitRuntimes   Return Value: [Ljavax.management.ObjectName;        8: LibraryRuntimes       Return Value: [Ljavax.management.ObjectName;
        9: MaxThreadsConstraintRuntimes  Return Value: [Ljavax.management.ObjectName;
        10: MinThreadsConstraintRuntimes         Return Value: [Ljavax.management.ObjectName;
        11: Name         Return Value: java.lang.String
        12: OptionalPackageRuntimes      Return Value: [Ljavax.management.ObjectName;
        13: Parent       Return Value: javax.management.ObjectName
        14: QueryCacheRuntimes   Return Value: [Ljavax.management.ObjectName;
        15: RequestClassRuntimes         Return Value: [Ljavax.management.ObjectName;
        16: Type         Return Value: java.lang.String
        17: WorkManagerRuntimes  Return Value: [Ljavax.management.ObjectName;
        18: WseeRuntimes         Return Value: [Ljavax.management.ObjectName;

Select one or more items as comma separated indices: 0

Number of possible columns in the resultant metric are 1.

Enter the name for this metric column at index=0 : [ActiveVersionState] Status



Note: The column name must be "Status".


Is this column a KEY Column <y/n>? [n] 
Is this column for SUMMARY_UI <y/n>? [n] 
Enter the label for column: [Status] 
Enter the NLSID for column: [Status] 
Enter the UNIT for column "Status": [millisec, kb etc.. ] 
Do you want to create a threshold for this column <y/n>? [n] y
Creating threshold!!
Following operators are available for creating thresholds: 
 0: GT
 1: EQ
 2: LT
 3: LE
 4: GE
 5: CONTAINS
 6: NE
 7: MATCH

Enter the index of your choice or press <Ctrl-C> to quit: 6
Enter the CRITICAL threshold: [NotDefined] 2




Status of target is marked down if a CRITICAL THRESHOLD is triggered on the Status column of the Response Metric. In this case if value != ACTIVATED (ie: != 2)


Enter the WARNING threshold: [NotDefined] 
Enter the number of occurrences that trigger threshold: [6] 1
Enter the message to be used when threshold is triggered: [Status is %value% and has crossed warning (%warning_threshold%) or critical (%critical_threshold%) threshold.] 
Enter NLSID for the message used when threshold is triggered: [Status_cond] 

Enter the name of this metric: Response



Note: The metric name must be "Response".


Enter the label for this metric: [Response] 

Do you want periodic collection for this metric <y/n>? [n] y
Enter the collection interval in seconds: 30
Periodic collection interval is: 30 seconds.

Do you want to create another metric <y/n>? [n] 
Written the metadata xml file: ./metadata/myCustomWLApp.xml.
Updated the default collection file for myCustomWLApp at location ./default_collection/myCustomWLApp.xml.
Exiting...










6.5.2 Using the Metadata and Default Collection Files


Look at the <currentDir>/metadata and currentDir/default_collection directories to see the myTarget.xml files (for the target type you specified earlier).


You can use these files as follows:



If you want the status information of your targets to appear correctly in the Enterprise Manager console, you need to define a Response metric. See Section 6.5.1.3, "Displaying Target Status Information" for more information.










6.6 Creating a Management Plug-in Archive




Note:

The Management Plug-in creation process applies to the Web Service, JMX-instrumented, and standalone JVM target types. Section 6.4 through Section 6.8 use Web Services as an illustrative example.


Using the Enterprise Manager Command-Line Interface (EM CLI), you create a Management Plug-in Archive, as shown in the following example.


>./emcli add_mp_to_mpa -mpa=TargetWithWSMgmtInterface.jar -mp_version="1.0" -ttd="{META_FILE} -dc="${DC_FILE}"



META_FILE and DC_FILE represent the target metadata and default collection files that the Web Services Command-Line tool generates. For more information about the EM CLI, see Oracle Enterprise Manager Command Line Interface Guide.


After archive jar file is created, you can upload the archive to Enterprise Manager and import the Management Plug-in. For more information about Management Plug-in Archives, see Chapter 2, "Developing a Management Plug-in".








6.7 Importing a Management Plug-in


The next step is to import the Management Plug-in from the archive file. You perform this operation from the Enterprise Manager console.


    

  1. 

    From the Enterprise Manager console, click Setup.
    

    2. 

  2. 

    Click Management Plug-ins from the left navigation bar.
    

    3. 

  3. 

    Click Import.
    

    4. 

  4. 

    From the Import page, specify the Management Plug-in Archive file and click List Archive. All Management Plug-ins contained within the archive are displayed.
    

    5. 

  5. 

    Select the Web service Management Plug-in from the list and click OK. Enterprise Manager returns you to the Management Plug-ins page with your Web service-specific plug-in added to the list.
    

    6. 





Figure 6-1 Importing the TargetWithWSMgmtInterface Management Plug-in

Description of Figure 6-1 follows

Description of "Figure 6-1 Importing the TargetWithWSMgmtInterface Management Plug-in"










6.8 Deploying a Management Plug-in to the Management Agent


After the Management Plug-in has been imported into Enterprise Manager, you can deploy the plug-in to any number of Management Agents. Deploying the Management Plug-in to an Agent allows that Agent to monitor targets exposing a Web Service management interface.


    

  1. 

    From the Management Plug-in main page, click the Deploy icon for the Management Plug-in you want to deploy. The Deploy Management Plug-in: Select Targets page appears, as shown in the following figure.
    

    

    Figure 6-2 Deploying the Management Plug-in to Management Agents
    
Description of Figure 6-2 follows
    
Description of "Figure 6-2 Deploying the Management Plug-in to Management Agents"
    

    

    2. 

  2. 

    Click Add Agents. The Search and Select: Agents page appears.
    

    3. 

  3. 

    Choose the desired Management Agent. Use the appropriate search parameters to find the desired Agent.
    

    4. 

  4. 

    Click Select. Enterprise Manager returns you to the Deploy Management Plug-in: Select Targets page. The selected Agent(s) appears in the deployment list.
    

    If deployment issues are detected for one or more the selected Agents, the Deployment Verification page appears. Only Agents for which an issue is detected appear in the table on this page. See online help for more information.
    

    5. 

  5. 

    Click Next to go to the Review page. The Management Plug-in name and version are shown. This page contains important information pertaining to the deployment process. Ensure that you understand the information before proceeding.
    

    6. 

  6. 

    Click Finish.
    

    7. 









6.9 Adding a Target Instance


Now that the Management Plug-in has been deployed to the appropriate Agent(s), you are ready to begin monitoring target types defined by your Management Plug-in. Because of the different target type properties, separate procedures for adding all target types are covered.




6.9.1 Adding a Web Services Target Instance


Now that the Management Plug-in has been deployed to the appropriate Agent(s), you can begin monitoring targets that expose a Web Service management interface, as defined by your Management Plug-in.


    

  1. 

    From the Monitored Targets section of the Management Agent home page, choose the desired target type from the Add drop-down menu and click Go. The Add target page appears.
    

    Note that Username/Password for basic authorization are the login credentials used to access the Web Service.
    

    2. 

  2. 

    Enter the requisite target properties and click OK, as shown in Figure 6-3. The newly added target appears in the Agent's Monitored Targets list.
    

    3. 





Figure 6-3 Adding a Target Instance

Description of Figure 6-3 follows

Description of "Figure 6-3 Adding a Target Instance"









6.9.2 Adding a JMX-instrumented J2EE Target Instance


If you deployed a Management Plug-in that defines a JMX-instrumented target type, you can begin configuring your JMX-enabled J2EE application targets so that metrics for these targets can be collected in Enterprise Manager Grid Control.


    

  1. 

    From the Monitored Targets section of the Management Agent home page, choose the desired target type from the Add drop-down menu and click Go. The Add target page appears.
    

    

    Figure 6-4 Selecting a JMX Target Type
    
Description of Figure 6-4 follows
    
Description of "Figure 6-4 Selecting a JMX Target Type"
    

    

    2. 

  2. 

    Enter the requisite target properties, as shown in Figure 6-5, then click OK. The newly added target appears in the Agent's Monitored Targets list.
    

    

    Figure 6-5 Specifying JMX Target Properties
    
Description of Figure 6-5 follows
    
Description of "Figure 6-5 Specifying JMX Target Properties"
    

    


    Table 6–1 provides definitions for the instance properties.
    

    

    Table 6-1 JMX Target Properties
    

    


    
Property
Definition

    
    


    


    Name
    
    		


    Unique name for this target instance.
    
    		

    

    


    MachineName
    
    		


    Hostname/IpAddress of the machine running the 10.1.3 version or higher of the Oracle Application Server.
    
    		

    

    


    Oracle Home Path
    
    		


    Absolute path to the Oracle_Home of the application server.
    
    		

    

    


    OC4JinstanceName
    
    		


    Instance name of the OC4J to which this JMX-enabled j2ee application is deployed. Default is the "home" instance.
    
    		

    

    


    JVMId
    
    		


    If this OC4J instance is running multiple JVMs, the index (starts with 1) of the JVM where this metric needs to be collected from (if there are multiple JVMs, a target instance may be added for each JVM instance).
    

    Note: You can create a "Group" from all these target instances running on multiple JVMs and see rolled-up values across all the JVMs, dashboards, and other targets where aggregate monitoring is advantageous.
    
    		

    

    


    MgmtWebSite
    
    		


    The http website on which the JMXSoapAdapter is deployed. This is default-web-site by default.
    
    		

    

    


    URI
    
    		


    WebService end-point for the JMXSoapAdapter (by default this is /JMXSoapAdapter/JMXSoapAdapter).
    
    		

    

    


    User Name for Basic Authorization
    
    		


    oc4jadmin user name.
    
    		

    

    


    Password for Basic Authorization
    
    		


    Password for the above user.
    
    		

    

    


    Version of TargetType
    
    		


    Default to the value from the metadata file created with emjmxcli.
    
    		

    
    

    

    

    3. 









6.9.3 Configuring a Standalone Java Application or JVM Target


If you deployed a Management Plug-in that defines your standalone Java application or you want to use the built-in JVM target type, you can begin configuring your JVM or JMX-enabled Java application targets so that metrics for these targets can be collected in Enterprise Manager Grid Control.


    

  1. 

    On the system running the JVM, install an Enterprise Manager Grid Control Agent for version 10.2.0.3 or greater. Although recommended, this is not absolutely necessary for JVM and standalone Java application targets.
    

    2. 

  2. 

    From the Enterprise Manager console, navigate to the home page of the Enterprise Manager Agent.
    

    3. 

  3. 

    In the Monitored Targets section, select the JVM target (or your standalone Java application target type for which you deployed the MPA earlier) from the drop-down list as shown in Figure 6–6.
    

    

    Figure 6-6 Selecting the JVM Target
    
Description of Figure 6-6 follows
    
Description of "Figure 6-6 Selecting the JVM Target"
    

    

    4. 

  4. 

    Enter the instance properties for this JVM or Java application instance that the Enterprise Manager Agent needs to monitor, as shown in Figure 6–7, then click OK.
    

    

    Figure 6-7 Specifying JVM Instance Properties
    
Description of Figure 6-7 follows
    
Description of "Figure 6-7 Specifying JVM Instance Properties"
    

    


    Table 6–2 provides definitions for the instance properties.
    

    

    Table 6-2 JVM Instance Properties
    

    


    
Property
Definition

    
    


    


    Name
    
    		


    Target name for this JVM instance.
    
    		

    

    


    MachineName
    
    		


    Host name where this JVM is running.
    
    		

    

    


    Admin Port Number
    
    		


    Port number a JSR-160 client can use (such as jconsole when using the “remote” option) to connect to the JVM. (This is the port specified for the –Dcom.sun.management.jmxremote.port property when the JVM is started up to enable remote management.)
    
    		

    

    


    User Name
    
    		


    Required if JVM started with: Dcom.sun.management.jmxremote.authenticate=truewith a password and access file.
    
    		

    

    


    JVM Admin User Password
    
    		


    See User Name above.
    
    		

    

    


    Communication Protocol
    
    		


    Establishes a connection to the MBeanServer on the target JVM. This corresponds to the properties of the JMX ServiceURL needed to establish the JMX connection to the target MBeanServer. The default of rmi should be retained.
    
    		

    

    


    Service Name
    
    		


    Establishes a connection to the MBeanServer on the target JVM. This corresponds to the properties of the JMX ServiceURL needed to establish the JMX connection to the target MBeanServer. The default of jmxrmi should be kept.
    
    		

    

    


    SSL Trust Store
    
    		


    Location of the SSL Trust Store, which is needed if the target JVM has SSL enabled with -Dcom.sun.management.jmxremote.ssl=true on its startup.
    
    		

    

    


    SSL Trust Store Password
    
    		


    Password needed to access the SSL Trust Store path.
    
    		

    

    


    Custom Lookup Provider Class
    
    		


    Full package name of a user-implemented Java lookup class that can be integrated into the Enterprise Manager client and be used to perform a custom lookup of the MBeanServer through LDAP or other lookup protocols. For information about providing a custom lookup service, see Section 6.9.4.
    
    		

    
    

    

    

    5. 

  5. 

    Navigate to the All Metrics page of the added JVM (Java application) target to see the metrics collected from the JVM (Java application) to Enterprise Manager Grid Control, as shown in Figure 6–8. These metrics are exposed by the platform MBeans, which is available on JDK1.5 or above, or from application-defined MBeans for your Java application.
    

    

    Figure 6-8 Metrics Collected from the JVM
    
Description of Figure 6-8 follows
    
Description of "Figure 6-8 Metrics Collected from the JVM"
    

    


    Figure 6–9 shows details (columns) for these metrics.
    

    

    Figure 6-9 Details of Collected Metrics
    
Description of Figure 6-9 follows
    
Description of "Figure 6-9 Details of Collected Metrics"
    

    

    6. 








6.9.4 Using a Custom Look-up Service to Obtain MBean Server Details


In some situations, you may not be able to statically provide the host:port information of an MBeanServer/JVM when you configure a JVM or Java application target in Enterprise Manager. Instead, you could use the machine name and port properties of the target instance as information for a look-up service, and apply your implementation of a custom look-up class to return the appropriate MBeanServer properties to the EM JMX fetchlet, which would then proceed to collect the metric.


The look-up service can override the value of any configuration parameter for a particular target instance. For example, assume you specify port=8000 (lookup service's port number) and a custom look-up provider class as com.mycompany.lookup when adding the JVM/Java application target in the targets.xml file in Enterprise Manager Grid Control. The resolveProperties method of your custom lookup class (com.mycompany.lookup) is called with all the properties defined when your target was added in Enterprise Manager Grid Control (that is, with the value of port as 8000:petstore). Your code can now parse the incoming port property and connect to port 8000 to look up petstore and decide that the MBeanServer of interest is on port 9000, and can thereby return port=9000 (actual port needed to connect to the MBeanServer). The Enterprise Manager Agent JMX fetchlet will now use port 9000 as the port number for the JMX connection.




6.9.4.1 Writing the Java Class


You can use the look-up service by writing a Java class that implements the following interface:


oracle.sysman.emd.fetchlets.JMX.generic.JMXLookUp


This interface contains one method:


public Properties resolveProperties(Properties p)


This method should connect to the look-up service and return the values for configuration parameters the fetchlet requires as a java.util.Properties object with each parameter name and its corresponding value as a key-value pair. The input to this method is also a java.util.Properties object with the properties MachineName, Port, Username, and Password passed on by default to the resolveProperties method of the custom look-up implementation object.







6.9.4.2 Passing Additional Information


If you need to pass additional information to the look-up service, you could, for example, append the information in one of the above properties (MachineName, Port, Username, and Password) and custom-process these in their look-up implementation class. However, when the method in the look-up class returns the Properties object, the method needs to replace the above properties with the corresponding properties of the target MBean Server it looked up.


For example, If you need to look up an MBeanServer “petstore1” on a look-up service on host myHost1, you could define the MachineName as myHost1:petstore1 and handle the custom processing of the MachineName property in your custom processing code. The look-up code would have to pass the correct value of 'myHost1' as the value of MachineName in the Properties object that the resolveProperties function returns.


Alternatively, you could manually create additional properties in the QueryDescriptor of each metric definition in the target metadata file. By specifying look-up properties by means of a special property called lookupProperties, you can provide a comma-separated list of additional properties to be passed to the look-up class. These additional properties can either be instance properties for the new target type (SCOPE=INSTANCE) or static values (SCOPE=GLOBAL).


Example 6–14 shows a portion of a QueryDescriptor with additional static look-up properties (Property NAME="lookupProperties").




Example 6-14 QueryDescriptor Example for Manually Creating Additional Properties


  <QueryDescriptor FETCHLET_ID="JMX">
         <Property NAME="MachineName" SCOPE="INSTANCE">MachineName</Property>
         <Property NAME="Port" SCOPE="INSTANCE">Port</Property>
         <Property NAME="UserName" SCOPE="INSTANCE" OPTIONAL="TRUE">UserName</Property>
         <Property NAME="password" SCOPE="INSTANCE" OPTIONAL="TRUE">password</Property>
         <Property NAME="protocol" SCOPE="INSTANCE" OPTIONAL="TRUE">protocol</Property>
         <Property NAME="service" SCOPE="INSTANCE" OPTIONAL="TRUE">service</Property>
         <Property NAME="SSLTrustStore" SCOPE="INSTANCE" OPTIONAL="TRUE">SSLTrustStore</Property>
         <Property NAME="SSLTrustStorePassword" SCOPE="INSTANCE" OPTIONAL="TRUE">SSLTrustStorePassword</Property>
         <Property NAME="lookupClass" SCOPE="INSTANCE" OPTIONAL="TRUE">com.mycompany.JMXLookup</Property>
         <Property NAME="lookupP1" SCOPE="GLOBAL" OPTIONAL="TRUE">false</Property>
         <Property NAME="lookupP2" SCOPE="GLOBAL" OPTIONAL="TRUE">myMBeanServerName</Property>
<Property NAME="lookupProperties" SCOPE="INSTANCE" OPTIONAL="TRUE">lookupP1, lookupP2</Property>
         <Property NAME="nestedView" SCOPE="GLOBAL" OPTIONAL="TRUE">false</Property>
         <Property NAME="metric" SCOPE="GLOBAL">java.lang:type=Runtime</Property>
         <Property NAME="identityCol" SCOPE="GLOBAL" OPTIONAL="TRUE">none</Property>
         <Property NAME="columnOrder" SCOPE="GLOBAL">VmName;VmVendor;VmVersion;Uptime</Property>
      </QueryDescriptor>




This example indicates that two additional properties, lookupP1 and lookupP2, are passed to the look-up class com.mycompany.JMXLookup as input to the method resolveProperties. The function resolveProperties can perform its look-up processing, but needs to return appropriate values for the properties MachineName, Port, Service, and Protocol. This enables the JMX fetchlet to establish the JSR-160 (remote) JMX connection to the MBeanServer.


Example 6–15 performs the look-up and gets values for the configuration parameters:




Example 6-15 Look-up Class Code Example





public class MylookupImplementationClass implements JMXLookUp{
        public java.util.Properties resolveProperties(java.util.Properties input){
                /*  your custom code here that does the lookup and gets values for the configuration parameters. The return Properties object should have the keys corresponding to the configuration parameters shown in Table 6–3. If any of the keys are missing in the return object, it defaults to whatever is available in the metadata file */
        }
}



Table 6–3 shows the properties the fetchlet uses in making the JMX connection that the lookup implementation class could override (by returning these properties in the Properties object returned in the resolveProperties call in the example above). These refer to properties overridden by the Lookup class.




Table 6-3 Properties the Fetchlet Uses






Property
Default
Description








MachineName




localhost




MBean server host machine name.








Port




8888




Port on which the MBean server is listening for connections.








Username




null




User name if required for a connection.








Password




null




Password if required for a connection.








Protocol




rmi




Protocol used for the connection.








Service




jmxrmi




Service used for the connection.








SSLTrustStore




null




Path to the SSLTrustStore.








SSLTrustStorePassword




null




Password needed to access the SSLTrustStore path.















6.9.4.3 Compiling the Look-up Class


To compile the JMXLookUp implementation class, put $ORACLE_HOME/lib/emagentRT.jar in the classpath when compiling your lookup class. The JMXLookUp implementation class/jar must eventually be available in the Enterprise Manager Agent's classpath so that it can be used at run time.


To achieve this, do the following after you build the custom look-up class:


    

  1. 

    Put the custom look-up class in a jar file.
    

    2. 

  2. 

    Put the location of this jar file in emagent/sysman/config/classpath.list or /emagent/sysman/config/emd.properties under the CLASSPATH section.
    

    3. 

  3. 

    Restart the Enterprise Manager Agent.
    

    4. 











6.9.5 Adding a Target Instance for a custom J2EE application on Weblogic


You have a custom J2EE application on WebLogic from which you need to collect custom metrics into EMGC that are exposed via JMX Mbeans. Once you have defined and deployed a Management Plug-in that defines your custom target type, you can begin configuring your JMX-enabled J2EE application target instances on the various agents where you deployed the Management Plug-ins to. This is so that metrics for these target instances can be collected in Enterprise Manager Grid Control.


    

  1. 

    From the Monitored Targets section of the Management Agent home page where you want to create this target instance (preferably the Agent running on the weblogic server machine where this application instance is deployed), choose your desired target type (created above via the emjmxcli) from the Add drop-down menu and click Go. The Add target page appears.
    

    

    Figure 6-10 Selecting a JMX Target Type
    
Selecting JMX target type
    
selecting a jmx target type part 2
    

    2. 

  2. 

    Enter the requisite target properties, as shown in Figure 6-11, then click OK. The newly added target appears in the Agent's Monitored Targets list.
    

    

    Figure 6-11 Specifying Target Properties
    
graphic shows specifying target properties.
    


    The following table provides definitions for instance properties.
    

    

    Table 6-4 Target Properties
    

    


    
Property
Definition

    
    


    


    Name
    
    		


    Unique name for this target instance.
    
    		

    

    


    MachineName
    
    		


    Hostname/IP Address of the machine running the 9.x version or higher of the Oracle WebLogic Application Server.
    
    		

    

    


    Username
    
    		


    User Name used to establish the JMX connection to the WebLogic server. This could be either an administrator or monitor user.
    
    		

    

    


    JVM Admin User Password
    
    		


    Password for above user.
    
    		

    

    


    Communication Protocol
    
    		


    t3 (default) or t3s.
    
    		

    

    


    Service Name
    
    		


    weblogic.management.mbeanservers.runtime (or other MbeanServer where the application registers its Mbeans).
    
    		

    

    


    Metric Source
    
    		


    WebLogic
    
    		

    
    

    

    

    3. 











6.10 Viewing Monitored Metrics


With a target instance added to the Agent for monitoring, you can now view metrics defined for your target type.


    

  1. 

    From the Agent home page, click on the target instance you added in the previous step in the Monitored Targets list. Enterprise Manager takes you to that target's home page.
    

    2. 

  2. 

    In the Related Links section, click All Metrics. The All Metrics page appears for the monitored target. An expandable tree list for each metric enables you to drill down to view specific metric parameters, as shown in Figure 6-12.
    

    3. 





Figure 6-12 Viewing Metrics

Description of Figure 6-12 follows

Description of "Figure 6-12 Viewing Metrics"