Enterprise Manager data retrieval is handled through predefined "fetchlets." A fetchlet is a parametrized data access mechanism that takes arguments (for example, a script, a SQL statement, a target instance's properties) as input and returns formatted data. Each fetchlet handles a specific type of data access. The fetchlets supplied with Enterprise Manager provide data retrieval capability for the most common data access methods, such as SQL, SNMP (Simple Network Management Protocol), HTTP, and DMS (Dynamic Monitoring Service). To handle more complex data access requirements, Enterprise Manager also provides an OS command fetchlet that allows developers to implement custom metric collection methods.

The following sections describe the fetchlets supplied with Enterprise Manager:

The operating system (OS) command fetchlets allow you to obtain metric data by executing OS commands (either individually or from scripts) that return a standard out (stdout) data stream.

Three OS command fetchlets are available:

• OS Fetchlet (raw)

• OSLines Fetchlet (split into lines)

• OSLineToken Fetchlet (tokenized lines)

The SQL fetchlet executes a given SQL statement on a given database as a given user and returns the table result.

Input Parameters

Notes

The SQL statement or PL/SQL block can be specified either through the STATEMENT property, or via a file whose name is provided through the FILENAME property.

The SQL fetchlet supports input parameters. Input and output parameters are indicated in the SQL/PLSQL text in the usual way, by using ":<number>". Input parameters can be used to bind values to both SQL queries and PL/SQL blocks.

Input parameter values are specified as properties of the form SQLINPARAM<position>. There can be any number of input parameters. The input parameters need to be scalar: input parameters of type ARRAY and STRUCT are not supported.

The SQL fetchlet supports the execution of anonymous PL/SQL blocks (which may call other functions or procedures) to retrieve data. When executing a block of PL/SQL, data is returned to the fetchlet by means of an OUT parameter. There can be exactly one out parameter. It must be of type SQL_CURSOR (a PL/SQL REF CURSOR), or it must be a named type that represents an array of objects. In the latter case, each field of the object represents one column of the table; and each object instance in the array represents one complete row in the table. The OUT parameter position and type are specified by means of the properties SQLOUTPARAMPOS and SQLOUTPARAMTYPE. If an OUT parameter is specified, then the fetchlet assumes it is executing PL/SQL and treats the STATEMENT property as an anonymous PL/SQL block.

If no OUT parameter is specified, the fetchlet assumes that it is executing a SQL query.

Note that all input parameters to the SQL fetchlet are strings. This means that all other datatypes will have to be converted to strings. This is straightforward for datatypes such as numbers, but not, for example, dates and timestamps. You can pass an absolute date or timestamp by passing a character representation of the value (using a DateFormat class). There is no way currently to pass in a date function, such as SYSDATE or SYSDATE+1. In such case, you could embed the date argument directly in the SQL, for example:

begin func1(:1, :2, SYSDATE); end;

The other caveat is passing null arguments to a procedure. Consider the following SQL:

STATEMENT=begin func1(:1,:2); end;
SQLINPARAM1=null
SQLOUTPARAMPOS=2
SQLOUTPARAMTYPE=fooret

Assume that the first argument is intended to be a varchar2. By parameterizing it and passing 'null' as the first argument, what we are really doing is passing the *string* 'null' to the argument, and not a null value. If you intend to pass a null value, do the following:

STATEMENT=begin func1(null, :1); end;
SQLOUTPARAMPOS=1
SQLOUTPARAMTYPE=fooret

Examples

The following properties execute a query (get all users) with no parameters:

Example 1: Query With No Parameters

MachineName=skini-pc 
Port=1521 
SID=o817 
UserName=scott 
password=tiger 
STATEMENT=select * from all_users; 
NUMROWS=30 

The following properties execute a query (get the first few objects of a specified type owned by a specified user) with input parameters:

Example 2: Query With Input Parameters

MachineName=skini-pc 
Port=1521 
SID=o817 
UserName=scott 
password=tiger 
STATEMENT=select * from all_objects where owner=:1 and object_type=:2 and rownum<:3tt>
NUMROWS=30 
SQLINPARAM1=SYSTEM 
SQLINPARAM2=INDEX 
SQLINPARAM3=10 

The following example executes a PL/SQL procedure that returns a cursor and has input parameters:

Example 3: PL/SQL Procedure With Input Parameters

achineName=skini-pc
Port=1521
SID=o817
UserName=scott
password=tiger
STATEMENT=begin :1 := skini_junk.func1(:2); end;
NUMROWS=30
SQLINPARAM2=SYSTEM
SQLOUTPARAMPOS=1
SQLOUTPARAMTYPE=sql_cursor

The following example specifies a PL/SQL procedure that returns an array of strings:

Example 4: PL/SQL Procedure Returning an Array of Strings

MachineName=skini-pc
Port=1521
SID=o817
UserName=scott
password=tiger
STATEMENT=begin skini_junk.newproc(:1,:2); end;
NUMROWS=30
SQLINPARAM1=SYSTEM
SQLOUTPARAMPOS=2
SQLOUTPARAMTYPE=my_string_array

The following example specifies a PL/SQL package that returns an array of structures:

Example 5: PL/SQL Package Returning an Array of Structures

MachineName=skini-pc
Port=1521
SID=o817
UserName=scott
password=tiger
STATEMENT=begin :1 := skini_junk.func2(:2,:3,:4,:5,:6); end;
NUMROWS=30
SQLINPARAM2=somename
SQLINPARAM3=someplace
SQLINPARAM4=someanimal
SQLINPARAM5=something
SQLINPARAM6=22
SQLOUTPARAMPOS=1
SQLOUTPARAMTYPE=my_struct_array

The following example provides the PL/SQL used in the previous examples for reference.

Example 6: PL/SQL Used in Examples

create or replace type my_type as Object (
    name varchar2(128),
    place varchar2(128),
    animal integer,
    thing number,
    thing2 number);
/
create or replace type my_struct_array as table of my_type;
/

create or replace type my_string_array as table of varchar2(3000);
/

create or replace type my_int_array as table of integer;
/

create or replace package skini_junk as

type Jcr is ref cursor;

function func1(username in varchar2) return Jcr;
function func2(name varchar2, place varchar2, animal integer,
             thing number, thing2 number) return my_struct_array;
procedure newproc(name varchar2, outArray OUT my_string_array);
procedure newproc2(numrows in varchar2, outArray OUT my_int_array);

end skini_junk;
/


create or replace package body skini_junk as

function func1(username in varchar2) return Jcr is
cr Jcr;
begin
    open cr for select object_name, object_type, status from all_objects where
         owner=upper(username);

     return cr;
end;

function func2(name varchar2, place varchar2, animal integer,
             thing number, thing2 number) return my_struct_array IS
ret my_struct_array := my_struct_array();

begin
    ret.extend(50);

    for i in 1..50 loop
        ret(i) := my_type(name || i,
                          place || i,
                          animal+i,
                          thing+i,
                          thing2+i);
    end loop;
    return ret;
end;

procedure newproc(name varchar2, outArray OUT my_string_array) IS
begin
    outArray := my_string_array();
    outArray.extend(100);

    for i in 1..100 loop
        outArray(i) := name || i;
    end loop;
end;

procedure newproc2(numrows in varchar2, outArray OUT my_int_array) IS
begin
    outArray := my_int_array();
    outArray.extend(numrows);
    for i in 1..numrows loop
        outArray(i) := i;
    end loop;
end;

end skini_junk;
/

An object identifier (OID) corresponds to either a MIB variable instance or a MIB variable with multiple instances. Given a list of OIDs, the SNMP fetchlet polls an SNMP agent on a given host for corresponding instances.

Input Parameters

Error Handling

MissingParameterException is thrown if either host name or OIDS is not given. FetchletException is thrown if TABLE is not equal to either TRUE or FALSE, an I/O error occurs while sending or receiving SNMP messages to or from the agent, or the agent responds with an SNMP error.

Notes

The table returned by the fetchlet contains a column for every OID in OIDS. If input OIDs correspond to single variable instances, the table will have just one row with those instances. On the other hand, if the OIDs correspond to variables with multiple instances, each column in the table will contain instances for its OID and each row will correspond to a different subidentifier. (A subidentifier is an OID extension that uniquely identifies a particular variable instance for some MIB variable.) OIDS must contain either all OIDs with subidentifiers or all OIDs without the subidentifiers.

For example, to request the variable instances for the three OIDs: sysDescr, sysUpTime, and sysName, OIDS would have to be "1.3.6.1.2.1.2.1.1.1.0 1.3.6.1.2.1.2.1.1.3.0 1.3.6.1.2.1.2.1.1.5.0". In this case, all OIDs contain the instance subidentifier, ".0". The return table appears as follows (the actual values may be different):

Figure 20-4 SNMP Fetchlet

Description of "Figure 20-4 SNMP Fetchlet"

Alternatively, assume that some MIB contains the following 3 columns and 4 instances:

Figure 20-5 SNMP Fetchlet: Columns 3 and 4 Content

Description of "Figure 20-5 SNMP Fetchlet: Columns 3 and 4 Content"

To construct a table with 3 columns corresponding to ifDescr, ifInOctets, and ifOutOctets, OIDS would be defined as follows

"1.3.6.1.2.1.2.1.2.2.1.2 1.3.6.1.2.1.2.1.2.2.1.10 1.3.6.1.2.1.2.1.2.2.1.16"

The fetchlet returns the following:

Figure 20-6 SNMP Fetchlet:ifDescr, ifInOctets, and ifOutOctets OIDS

Description of "Figure 20-6 SNMP Fetchlet:ifDescr, ifInOctets, and ifOutOctets OIDS"

The rows correspond to subidentifiers 1,2,3,4 respectively.

Any OID in OIDS can be appended with another placement OID. The variable instances for the placement OID do not appear in the returned table. Instead, they determine the place for the variable instances of the original OID within a column. In particular, for every variable instance I with subidentifier S in the set of instances for the original OID, (a) there must exist a variable instance X with subidentifier S in the set of instances corresponding to the placement OID, and (b) X is used as the subidentifier for the instance I.

For example, consider a MIB containing the following 3 columns, each with 4 variable instances:

Figure 20-7 SNMP Fetchlet: MIB Content with 4 Variable Instances

Description of "Figure 20-7 SNMP Fetchlet: MIB Content with 4 Variable Instances"

To construct a table containing ifDescr and ipAdEntNetMask, OID of ipAdEntIfIndex would have to be used as the placement OID to "align" the columns. Thus, the OIDS input to the fetchlet would be "1.3.6.1.2.1.2.1.2.2.1.2 1.3.6.1.2.1.2.1.4.20.1.3*1.3.6.1.2.1.2.1.4.20.1.2". The fetchlet output will be as follows:

Figure 20-8 SNMP Fetchlet: Table Containing ifDescr and ipAdEntNetMask

Description of "Figure 20-8 SNMP Fetchlet: Table Containing ifDescr and ipAdEntNetMask"

If OIDS were "1.3.6.1.2.1.2.1.2.2.1.2 1.3.6.1.2.1.2.1.4.20.1.3" for the previous example, the output would be as follows:

Figure 20-9 SNMP Fetchlet: Alternate OID

Description of "Figure 20-9 SNMP Fetchlet: Alternate OID"

The HTTP data fetchlets obtain the contents of a URL and returns the contents of the URL as data. Three fetchlets are available:

• URL Fetchlet

• URL Lines

• URL Lines Token

The URL XML fetchlet obtains the XML content of a given URL, and extracts information based on a given pattern. A pattern is a list of "chunks" of XML to match against. The return table is a table with a column for each grabber (*) in the pattern in order and a row each time the pattern chunk matches in the XML content.

Input Parameters

Example

Take the following URL:

http://localhost/urlxmltestfile.xml

It has the following content:

<?xml version="1.0"?>
<testfile>
    <test>Simple text</test>
    <test><level>A little more complex</level></test>
    <test></test>
    <notatest></notatest>
    <test>Yet more complexity<level>Even a little more complex</level>Will it ever stop?</test>
    <test1>must match<level>extract me!</level></test1>
    <test1>must match here<level>extract me, too!</level></test1>
</testfile>

Running the URL XML fetchlet with the given URL and the pattern:

<testfile><test>*<level>*</level></test></testfile>

returns the following table:

Figure 20-13 URL XML Fetchlet Output

Description of "Figure 20-13 URL XML Fetchlet Output"

Error Handling

MissingParameterException if URL or pattern parameters are missing.

A FetchletException is generated if:

• The URL is malformed.

• An I/O error occurs in retrieving the content of the URL.

• The URL contents or pattern contains invalid XML.

Notes

Setting the proxy host and/or port changes these settings for the java.net package for the whole Java environment and is not thread-safe if the proxy settings are changing.

The URL Timing fetchlet gets the contents of a given URL, timing not only the base page source but any frames or images in the page as well.

Input Parameters

Metric Columns and Output Modes

The format of information and specific metric information returned are controlled by the "output_format" and "metrics" input parameters. Table 20-11 lists the format categories and the metrics (columns) returned by each. For a description of available metric columns, see Table 20-12

Metric Columns

Table 20-12 shows the metric columns returned by the URLTIMING fetchlet.

Example

Take the following URL:

url0=http://www.example.com/ 

With the input parameter output_format=summary, the fetchlet returns the following table (minus the headers on the columns):

Figure 20-14 Summary Output Format

Description of "Figure 20-14 Summary Output Format"

With output_format = summary and metrics = total_response_time, status, status_description the fetchlet returns the following table (minus the headers on the columns):

Figure 20-15 Summary Output Format with Specified Metric Columns

Description of "Figure 20-15 Summary Output Format with Specified Metric Columns"

With output_format = summary and metrics = total_response_time, status, status_description the fetchlet returns the following table (minus the headers on the columns) and the server is giving error:

Figure 20-16 Summary Output Format with Specified Metric Columns and Internal Server Error

Description of "Figure 20-16 Summary Output Format with Specified Metric Columns and Internal Server Error"

Take the following URL:

url0=http://www.example.com/
url1=http://nedc.us.example.com/

With the output_format=summary, the fetchlet returns the following table (minus the headers on the columns). Here the numbers are time taken for fetching both the urls.

Figure 20-17 Summary Output Format for Two URLs

Description of "Figure 20-17 Summary Output Format for Two URLs"

With the output_format=detailed, the fetchlet returns the following table (minus the headers on the columns):

Figure 20-18 Detailed Output for Two URLs

Description of "Figure 20-18 Detailed Output for Two URLs"

With the output_format=repeat_column, the fetchlet returns the following table (minus the headers on the columns):

Figure 20-19 Repeat Column Output Format

Description of "Figure 20-19 Repeat Column Output Format"

Error Handling

Metric error if the URL parameter is missing, malformed, or if the metric cannot be computed.

Notes

The time required to perform a retry will be added on to the total time of the page. For example, if two retries are performed and then a success occurs, the total page time will be the time of the page that succeeded plus the time it took for the two retries to fail.

Proposed usage:

• For basic monitoring:

  Use url0=<URL to be monitored> , output_mode=summary and specify metrics=status, computed_response_time, status_description

• For getting all columns:

  Use url0=<url to be monitored> , output_mode=summary

The Dynamic Monitoring Service (DMS) fetchlet contacts an Application Server (AS) and then collects the metrics instrumented by the DMS.

The DMS allows application and system developers to measure and export customized, component-specific performance metrics. The Oracle Management Agent allows software components to import runtime performance data into Oracle Enterprise Manager.

The DMS fetchlet is an Oracle Management Agent plug-in module that allows the Management Agent to import the performance data that is exported by the DMS. Using the DMS fetchlet, any component that is instrumented using DMS API calls may share its performance data with Enterprise Manager.

Call-level interfaces such as JDBC permit external access to SQL database manipulation and update commands. The Java Database Connectivity (JDBC) fetchlet allows you to execute common JDBC commands and obtain their response time for any type of database.

Input Parameters

jdbc:oracle:thin:@hostname:port

jdbc:mysql://hostname:port

Example: Properties Passed to JDBC Fetchlet

The following example provides the properties passed to the JDBC fetchlet when invoked.

<QueryDescriptor FETCHLET_ID="JDBC">
<Property NAME="TxnName" SCOPE="GLOBAL">TxnName</Property>
<Property NAME="BeaconName" SCOPE="GLOBAL">BeaconName</Property>
<Property NAME="connstring" SCOPE="INSTANCE">connString</Property>
<Property NAME="username" SCOPE="INSTANCE">username</Property>
<Property NAME="password" SCOPE="INSTANCE">password</Property>
<Property NAME="statement" SCOPE="GLOBAL">select * from user_tables</Property>
<Property NAME="classstring" SCOPE="GLOBAL">oracle.jdbc.none</Property>
<Property NAME="role" SCOPE="GLOBAL" OPTIONAL="TRUE">DBA</Property>
<Property NAME="useconnpool" SCOPE="GLOBAL" OPTIONAL="TRUE">FALSE</Property>
<Property NAME="GetTimingData" SCOPE="GLOBAL">TRUE</Property>
</QueryDescriptor> 

The WBEM fetchlet accesses a CIMOM and retrieves requested information using the specified CIM class. The CIM class is mapped to a Management Repository table metric. The name of the CIM class is the name of the table metric that is returned, and the properties defined for the CIM class are used to name the table columns for the metric. The properties of interest must be specified during metric definition.

The fetchlet returns the instances that have been instantiated for the CIM class as rows of the Management Repository table metric.

Input Parameters

Error Handling

The following types of errors have been identified for the WBEM fetchlet.

MissingParameterException occurs when:

• No CIM Class parameters match.

Fetchlet exception occurs when:

• The class name is not found in the CIMOM namespace.

• The namespace is not found.

• The connection to the CIMOM does not have valid credentials.

• The connection to the CIMOM failed because the CIMOM was not running.

• The CIM class property does not exist

• An unsupported operation was specified

• No properties were specified.

Notes

Ports: Some CIMOM client interfaces expose the port that the CIMOM is listening on while some clients do not. To cover both cases, the port is exposed as an optional input parameter that defaults to port 5988. This is the default Pegasus CIMOM listener port. The Java API that is provided through Sun's Wbem Services does not expose the CIMOM port.

Protocols: Most CIMOMs support either an RMI or HTTP protocol for communicating with the CIMOM. The testing that has been done shows that the HTTP protocol is not as stable, and in some cases, not fully implemented in the CIMOM. Because of this, the protocol currently defaults to RMI. The actual parameters for the WBEM Services CIMOM for the protocol are: CIMClient.CIM_RMI or CIMClient.CIM_XML.

Fetchlet Operations: The WBEM APIs are very flexible at allowing clients to traverse the class hierarchies that are defined and their associations. At this point in time, the options on accessing CIM data from an EMD are restricted to counting, getting the properties of classes, and CIMOM status. These are the more important operations that need to be performed for monitoring. As additional requirements come in, we can add new operations to support them if necessary. For the prototype, only the count operation has been implemented.

Authentication: Most CIMOMs provide APIs to support authentication through a user identity mechanism. The majority of the CIMOMs have not implemented the API, so this capability is really a no-op. In any case, we've supplied the capability in the fetchlet so that as CIMOM implementations catch up with the standard, we'll have the necessary support in place.

Examples

The Wbem fetchlet supports three basic operations. At this point, the fetchlet only handles one operation at a time, so you cannot mix count, status, and value operations within a single fetchlet call. Example 1 shows how to write the metadata for a COUNT operation:

Example 1: COUNT Operation Metadata

<Metric NAME="Load" TYPE="TABLE">
    <Display>
       <Label NLSID="wbem_cimom_load">Load</Label>
     </Display>
     <TableDescriptor>
       <ColumnDescriptor NAME="Active Clients" TYPE="NUMBER" IS_KEY="FALSE">
           <Display>
             <Label NLSID="wbem_cimom_active_clients">Active CIMOM Clients</Label>
           </Display>
         </ColumnDescriptor>
     </TableDescriptor>  
    <QueryDescriptor FETCHLET_ID="Wbem">
       <Property NAME="username" SCOPE="GLOBAL">guest</Property>
       <Property NAME="password" SCOPE="GLOBAL">guest</Property>
       <Property NAME="CIMClassname" SCOPE="GLOBAL">EX_SFLProvider</Property>
       <Property NAME="operation" SCOPE="GLOBAL">COUNT</Property> 
    </QueryDescriptor>
  </Metric>

The FETCHLET_ID is identified as Wbem. Property names are passed to the fetchlet for the required parameters user name, password, and CIMClassname. The operation is identified as COUNT.

The following example shows how to implement a Response Status metric to determine whether the CIMOM is running or not. It returns a value of 1 if the connection to the CIMOM is successful, otherwise 0.

Example 2: Response Status Metric

  <Metric NAME="Response" TYPE="TABLE">
     <Display>
       <Label NLSID="wbem_cimon_response">Response</Label>
     </Display>
     <TableDescriptor>
       <ColumnDescriptor NAME="Status" TYPE="NUMBER" IS_KEY="FALSE">
           <Display>
             <Label NLSID="wbem_cimom_response_status">Status</Label>
           </Display>
         </ColumnDescriptor> 
    </TableDescriptor> 
    <QueryDescriptor FETCHLET_ID="Wbem">
       <Property NAME="username" SCOPE="GLOBAL">guest</Property>
       <Property NAME="password" SCOPE="GLOBAL">guest</Property>
       <Property NAME="operation" SCOPE="GLOBAL">STATUS</Property>
     </QueryDescriptor>
   </Metric>

The default operation is the VALUES operation. It is used to fetch the values of a class that is defined in the CIMOM.

In the final example, the EX_Teacher class is accessed and fetches the name column. Name is the key of the class and of the new metric being defined, so the IS_KEY property is set to true. The CIM class properties will be mapped to the Enterprise Manager columns in the order that they are specified in the properties property. In this case, there is only 1 property - Name.

Example 3: Single Property Fetched for a Class

<Metric NAME="EX_Teacher" TYPE="TABLE">
     <Display>
       <Label NLSID="wbem_EX_Teacher">EX_Teacher Class</Label>
     </Display>
     <TableDescriptor>
       <ColumnDescriptor NAME="Name" TYPE="STRING" IS_KEY="TRUE">
           <Display>
             <Label NLSID="wbem_ex_teacher_name">Name</Label>
           </Display>
         </ColumnDescriptor>
     </TableDescriptor>
     <QueryDescriptor FETCHLET_ID="Wbem">
       <Property NAME="username" SCOPE="GLOBAL">guest</Property>
       <Property NAME="password" SCOPE="GLOBAL">guest</Property>
       <Property NAME="CIMClassname" SCOPE="GLOBAL">EX_Teacher</Property>
       <Property NAME="properties" SCOPE="GLOBAL">Name</Property>
     </QueryDescriptor>
   </Metric>

If multiple properties are fetched for a class, semi-colons should separate them. The properties should be provided in the order that the column descriptors are specified for the metric table definition.

Example 4: Multiple Properties Fetched for a Class

<Metric NAME="EX_SFLProvider" TYPE="TABLE">
     <Display>
       <Label NLSID="wbem_EX_SFLProvider">EX_SFLProvider Class</Label>
     </Display>
     <TableDescriptor>
       <ColumnDescriptor NAME="Name" TYPE="STRING" IS_KEY="TRUE">
           <Display>
             <Label NLSID="wbem_ex_sfl_name">Name</Label>
           </Display>
         </ColumnDescriptor>
       <ColumnDescriptor NAME="Win" TYPE="NUMBER" IS_KEY="FALSE">
           <Display>
             <Label NLSID="wbem_ex_sfl_win">Win</Label>
           </Display>
         </ColumnDescriptor>
       <ColumnDescriptor NAME="Lost" TYPE="NUMBER" IS_KEY="FALSE">
           <Display>
             <Label NLSID="wbem_ex_sfl_lost">Lost</Label>
           </Display>
         </ColumnDescriptor>
     </TableDescriptor>
     <QueryDescriptor FETCHLET_ID="Wbem">
       <Property NAME="username" SCOPE="GLOBAL">guest</Property>
       <Property NAME="password" SCOPE="GLOBAL">guest</Property>
       <Property NAME="CIMClassname" SCOPE="GLOBAL">EX_SFLProvider</Property>
       <Property NAME="properties" SCOPE="GLOBAL">Name;Win;Lost</Property>
     </QueryDescriptor>
   </Metric>

The JMX fetchlet retrieves Java Management Extensions (JMX) attributes (or invokes a JMX operation) from an MBean and returns the result as a (table) metric. If the ObjectName specified is an ObjectName pattern, then multiple rows are returned. Each row corresponds to an MBean matching the specified ObjectName pattern.

Input Parameters

Notes:

In target metadata files generated by the Web Services Command-Line tool, the <QueryDescriptor> element specifies the properties that will be passed to the Web Services fetchlet when being invoked.

Input Parameters

Table 20-18 lists the supported properties:

Examples

Example 1 provides an example of a metric definition for Remote Procedure Call (RPC) or encoded Web services and Example 2 provides an example of a metric definition for doc or literal Web services.

Example 1: Metric Definition for RPC or Encoded Web Service

 <Metric NAME="getVacantRooms" TYPE="TABLE">
   <Display>
     <Label NLSID="NLSID_GET_VACANT_ROOMS">getVacantRooms</Label>
   </Display>

   <TableDescriptor>
     <ColumnDescriptor IS_KEY="TRUE" NAME="roomID" TYPE="STRING">
       <Display>
         <Label NLSID="COL_ROOM_ID">roomID</Label>
       </Display>
     </ColumnDescriptor>
     <ColumnDescriptor IS_KEY="FALSE" NAME="floor" TYPE="STRING">
       <Display>
         <Label NLSID="COL_FLOOR">floor</Label>
       </Display>
     </ColumnDescriptor>
     <ColumnDescriptor IS_KEY="FALSE" NAME="number" TYPE="STRING">
       <Display>
         <Label NLSID="COL_NUMBER">number</Label>
       </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="rate" TYPE="STRING">
        <Display>
          <Label NLSID="COL_RATE">rate</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="roomType" TYPE="STRING">
        <Display>
          <Label NLSID="COL_ROOM_TYPE">roomType</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="smoking" TYPE="STRING">
        <Display>
          <Label NLSID="COL_SMOKING">smoking</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="available" TYPE="STRING">
        <Display>
          <Label NLSID="COL_AVAILABLE">available</Label>
        </Display>
      </ColumnDescriptor>
    </TableDescriptor>
    <QueryDescriptor FETCHLET_ID="OWSM_WSF">
     <Property NAME="SecurityPolicy" SCOPE="INSTANCE">NONE</Property>
      <Property NAME="WsdlURL" SCOPE="INSTANCE">wsdlURL</Property>
      <Property NAME="ServiceEndpoint" SCOPE="INSTANCE">serviceURL</Property>
      <Property NAME="ServiceName" SCOPE="GLOBAL">ns0:SimpleHotelServiceRE</Property>
      <Property NAME="PortName" SCOPE="GLOBAL">ns0:HotelService</Property>
      <Property NAME="OperationName" SCOPE="GLOBAL">getVacantRooms</Property>
      <Property NAME="MessageType" SCOPE="GLOBAL">SOAP</Property>
      <Property NAME="SOAPBindingStyle" SCOPE="GLOBAL">RPC</Property>
      <Property NAME="SOAPBindingUse" SCOPE="GLOBAL">ENCODED</Property>
      <Property NAME="ParameterStyle" SCOPE="GLOBAL">BARE</Property>
      <Property NAME="SOAPVersion" SCOPE="GLOBAL">SOAP_1_1</Property>
      <Property NAME="Namespace" SCOPE="GLOBAL"><![CDATA[[ns1="http://hotel.apps.muws/"][ns0="http://hotel.apps.muws/rpc/"]]]></Property>
      <Property NAME="RowType" SCOPE="GLOBAL">//ns1:getVacantRoomsResponse/return/item/@roomID,//ns1:getVacantRoomsResponse/return/item/floor,
      //ns1:getVacantRoomsResponse/return/item/number,//ns1:getVacantRoomsResponse/return/item/rate,//ns1:getVacantRoomsResponse/return/item/roomType,
      //ns1:getVacantRoomsResponse/return/item/smoking,//ns1:getVacantRoomsResponse/return/item/available</Property>
      <Property NAME="ColType" SCOPE="GLOBAL">roomID:STRING,floor:STRING,number:STRING,rate:STRING,roomType:STRING,smoking:STRING,available:STRING</Property>
      <Property NAME="Payload" SCOPE="GLOBAL"><![CDATA[<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns="http://hotel.apps.muws/"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
            <soap:Body soap:encodingStyle="">
              <ns:getVacantRooms/>
            </soap:Body>
          </soap:Envelope>]]></Property>
    </QueryDescriptor>
  </Metric>

Example 2: Metric Definition for Doc or Literal Web Service

    <Metric NAME="square" TYPE="TABLE">
      <Display>
        <Label NLSID="NLSID_SQUARE">square</Label>
      </Display>
      <TableDescriptor>
        <ColumnDescriptor IS_KEY="FALSE" NAME="arg0" TYPE="STRING">
          <Display>
            <Label NLSID="COL_ARG0">arg0</Label>
          </Display>
        </ColumnDescriptor>
      </TableDescriptor>
      <QueryDescriptor FETCHLET_ID="OWSM_WSF">
        <Property NAME="SecurityPolicy" SCOPE="INSTANCE">NONE</Property>
        <Property NAME="ServiceEndpoint" SCOPE="INSTANCE">serviceURL</Property>
        <Property NAME="ServiceName" SCOPE="GLOBAL">ns0:CalculatorService</Property>
        <Property NAME="PortName" SCOPE="GLOBAL">ns0:CalculatorPort</Property>
        <Property NAME="OperationName" SCOPE="GLOBAL">square</Property>
        <Property NAME="MessageType" SCOPE="GLOBAL">SOAP</Property>
        <Property NAME="SOAPBindingStyle" SCOPE="GLOBAL">DOCUMENT</Property>
        <Property NAME="SOAPBindingUse" SCOPE="GLOBAL">LITERAL</Property>
        <Property NAME="ParameterStyle" SCOPE="GLOBAL">WRAPPED</Property>
        <Property NAME="SOAPVersion" SCOPE="GLOBAL">SOAP_1_1</Property>
        <Property NAME="Namespace" SCOPE="GLOBAL"><![CDATA[[ns0="http://tests.jaxws.oracle.com/"]
[ns1="http://www.oracle.com/jaxws/tests"]]]></Property>
        <Property NAME="RowType" SCOPE="GLOBAL">//ns1:squareResponse/arg0</Property>
        <Property NAME="ColType" SCOPE="GLOBAL">arg0:STRING</Property>
        <Property NAME="Payload" SCOPE="GLOBAL"><![CDATA[<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
              <soap:Body xmlns:ns1="http://www.oracle.com/jaxws/tests">
                <ns1:square>
                  <arg0>%square.arg00001%</arg0>
                </ns1:square>
              </soap:Body>
            </soap:Envelope>]]></Property>
      </QueryDescriptor>
    </Metric>

In target metadata files generated by the wsmancli Command-Line Tool, the <QueryDescriptor> element specifies the properties that will be passed to the WSManagement fetchlet when being invoked.

Input Parameters

Table 20-19 provides a complete list of the supported properties:

Example: Metric definition for using the WS-Management Fetchlet

The following example provides an example of a metric definition using the WS-Management fetchlet.

  <Metric NAME="trafficLight" TYPE="TABLE">
    <Display>
      <Label NLSID="NLSID_TRAFFIC_LIGHT">trafficLight</Label>
    </Display>
    <TableDescriptor>
      <ColumnDescriptor IS_KEY="YES" NAME="name" TYPE="STRING">
        <Display>
          <Label NLSID="COL_NAME">name</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="color" TYPE="STRING">
        <Display>
          <Label NLSID="COL_COLOR">color</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="x" TYPE="STRING">
        <Display>
          <Label NLSID="COL_X">x</Label>
        </Display>
      </ColumnDescriptor>
      <ColumnDescriptor IS_KEY="FALSE" NAME="y" TYPE="STRING">
        <Display>
          <Label NLSID="COL_Y">y</Label>
        </Display>
      </ColumnDescriptor>
    </TableDescriptor>
    <QueryDescriptor FETCHLET_ID="WSManagementFetchlet">
      <Property NAME="SecurityPolicy" SCOPE="INSTANCE">NONE</Property>
      <Property NAME="ResourceURL" SCOPE="INSTANCE">resourceURL</Property>
      <Property NAME="To" SCOPE="INSTANCE">To address</Property>
      <Property NAME="OptionSet" SCOPE="INSTANCE">optionSet</Property>
      <Property NAME="Locale" SCOPE="INSTANCE">locale</Property>
      <Property NAME="MaxEnvelopeSize" SCOPE="INSTANCE">maxEnvelopeSize</Property>
      <Property NAME="OperationTimeout" SCOPE="INSTANCE">operationTimeout</Property>
      <Property NAME="Namespace" SCOPE="GLOBAL"> <![CDATA[[ns1="http://schemas.wiseman.dev.java.net/traffic/1/light.xsd"]
            [ns0="http://www.w3.org/2001/XMLSchema"]
            [wsa="http://www.w3.org/2005/08/addressing"]
            [env="http://www.w3.org/2003/05/soap-envelope"]]]></Property>
      <Property NAME="RowType" SCOPE="GLOBAL">//ns1:trafficlight/ns1:name,//ns1:trafficlight/ns1:color,//ns1:
      <Property NAME="ColType" SCOPE="GLOBAL">name:STRING,color:STRING,x:STRING,y:STRING</Property>
      <Property NAME="ReplyTo" SCOPE="GLOBAL">http://www.w3.org/2005/08/addressing/role/anonymous</Property>
      <Property NAME="Action" SCOPE="GLOBAL">http://schemas.xmlsoap.org/ws/2004/09/transfer/Get</Property>
      <Property NAME="TransferOperation" SCOPE="GLOBAL">GET</Property>
      <Property NAME="SelectorSet" SCOPE="GLOBAL">[name,Light1]</Property>
    </QueryDescriptor>
  </Metric>

The REST fetchlet provides target monitoring for RESTful web resources. Based on input properties, this fetchlet can construct a request to communicate with the managed targets using HTTP standards. It can retrieve relevant data from the response to build and return monitoring metrics.

This release supports the following RESTful web services only:

• HTTP methods

  • GET: Define a reading access of the source without any side-effects. The resource is never changed through a GET request.

  • POST: Update an existing resource or create a new resource.

  • HEAD: vCheck if a given path is serviceable.

• Media type of request or response representations

  • application/xml (both request and response)

  • application/json (both request and response)

  • text/xml (response only)

  • application/x-www-form-urlencoded (request only)

• Authentication scheme

  Supports BASIC authentication.