5 Management Using Web Services

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

Note:

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

HTTP://www.w3.org

Using Enterprise Manager's Management Plug-in mechanism, you can add a new target type that exposes a WSDL management interface and monitor new target instances of this type using SOAP messages. Once a target instance of this type (one that exposes a Web Service management interface) has been added to the Enterprise Manager framework, Enterprise Manager functionality, such as notifications, jobs, and reporting is automatically extended to it.

This chapter covers the following:

Monitoring Using Web Services in Enterprise Manager
Generating Target Metadata and Collection Files
Creating a Management Plug-in Archive
Importing the Management Plug-in
Deploying the Management Plug-in to the Management Agent
Adding a Target Instance
Viewing Monitored Metrics

Monitoring Using Web Services in Enterprise Manager

Using Enterprise Manager to monitor targets that expose a Web Services management interface entails defining a new target type via Management Plug-ins.

Note:

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

Setting up Enterprise Manager to monitor a target via its Web Service management interface involves the following steps:

Generate the target metadata and default collection files to be added to the Management Plug-in.
Create a Management Plug-in Archive containing the Management Plug-in(s) defining a Web services target type. An archive may contain more than one Management Plug-in.
Import the Management Plug-in into Enterprise Manager.
Deploy the Management Plug-in to the appropriate Management Agent(s).

Generating Target Metadata and Collection Files

The first step is to create the requisite target definition files for your Web Service: Target metadata and default collection. At the very least, these two files are required to create a Management Plug-in. You generate the target metadata and default collection file using Web Services command line tool.

Web Services Command Line Tool

The command line tool simplifies creating new Management Plug-ins by generating the requisite target metadata and collection files, both of which are required to collect metrics from resources that support the WSDL interface. Information retrieval is achieved via the SOAP fetchlet that is integrated with the Management Agent.

This tool parses a specified WSDL file for all the operations and allows you to pick one or more operations to be invoked. If there are multiple port types specified in the WSDL file, the tool will prompt you to select one of them. Operations are listed along with their parameters. An operation in a Web Service can be one of four types:

One Way
Request Response
Solicit Response
Notification

Of the aforementionedtypes, Request Response is the most interesting one for the purpose of this tool. The selected operation could have primitive or complex parameters and results. The result of Web Service invocation will be 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 columnOrder property in the metadata below). This can be useful for complex return types out of 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

Security

The tool does not make any invocation of the Web Service and only generates metadata required by Enterprise Manager for target monitoring purposes. Users running this tool are only expected to have read permission on the WSDL file or URL and permission to save generated files to the appropriate directory.

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 Web Service
-useSSL Use SSL to communicate with 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.

Usage

The following example shows a sample WSDL file passed to the command line tool to generate the target metadata and collection files.

Example 5-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>

The following sample Web Services command line tool session uses the WSDL file shown in Example 5-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 will first prompt you to select a port type.

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 pick 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 5-2.

Example 5-2 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 5-3 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>

Creating a Management Plug-in Archive

Using the Enterprise Manager Command Line Interface (EM CLI), you create a Management Plug-in Archive, as shown in the following example. META_FILE and DC_FILE represent the target metadata and default collection files generated by the Web Services Command Line tool.

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

For more information about the EM CLI, see Oracle Enterprise Manager Command Line Interface.

Once the archive jar file is created, you are ready to 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".

Importing the Management Plug-in

The next step is to import the Management Plug-in from the archive file. This operation is performed from the Enterprise Manager console.

From the Enterprise Manager console, click Setup.
Click Management Plug-ins from the left navigation bar.
Click Import.
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.
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.

Figure 5-1 Importing the TargetWithWSMgmtInterface Management Plug-in

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

Deploying the Management Plug-in to the Management Agent

Once the Management Plug-in has been imported into Enterprise Manager, you are now ready to 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.

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

Figure 5-2 Deploying the Management Plug-in to Management Agents

Description of "Figure 5-2 Deploying the Management Plug-in to Management Agents"
Click Add Agents. The Search and Select: Agents page appears.
Choose the desired Management Agent. Use the appropriate search parameters to find the desired Agent.
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 is displayed. Only Agents for which an issue is detected appear in the table on this page. See online help for more information.
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.
Click Finish.

Adding a Target Instance

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

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.
Enter the requisite target properties and click OK (shown in Figure 5-3). The newly added target appears in the Agent's Monitored Targets list.

Figure 5-3 Adding a Target Instance

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

Viewing Monitored Metrics

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

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.
In the Related Links section, click All Metrics. The All Metrics page appears for the monitored target. An expandable tree list for each metric allows you to drill down to view specific metric parameters, as show in Figure 5-4.

Figure 5-4 Viewing Metrics

Description of "Figure 5-4 Viewing Metrics"