The following sections describe the fetchlets supplied with Enterprise Manager:

21.2OS Command Fetchlets

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)

21.2.1OS Fetchlet

The OS fetchlet executes a given OS command and returns the command's output in a single cell table.

Input Parameters

Table 21-1 OS Fetchlet Input Parameters

Parameter

Type

Description

Use

command

string

Operating system command to be executed.

Required

ENVname

string

OSFetchlet parameters starting with "ENV" appear in the execution environment for the command as name environment variables

Zero or more

errStartsWith

String

When defined, this property allows you to define a custom prefix for error messages. If this property is not defined, the OSFetchlet defaults to "em_error=" as the message prefix.

Optional

script

string

Specifies the script to be executed if command property only provides an interpreter. For example, command might consist of "perl." script is then used to specify the particular perl script to be run.

Although scripts can be specified directly from the command parameter, using the script parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

args

string

A property that is taken as one or more arguments to the command and script properties.

Although args can be specified directly from the command parameter, using the args parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

separateErrorStream

boolean

If an error occurs while executing a command, this property instructs the fetchlet whether to return both the stdout and stderr to the user as an error message. When set to TRUE, only stderr output is sent to the user as an error message when there is a command error. When set to FALSE (default value), both the stdout and the stderr are sent to the user as an error message upon command failure.

Optional. (TRUE/FALSE)

em_metric_timeout

integer

Metric timeout period (in seconds). After the timeout period has finished, the Management Agent returns a timeout exception and terminates any child processes that may have been created. The Management Agent doesnot terminate any of the grandchild processes.

The raw output of the OS command is returned. Any standard error output is appended to the standard output.

Error Handling

Any problems encountered launching the command (For example, the command program no longer exists) results in an oracle.sysman.emSDK.emd.fetchlet.MetricSourceException wrapping a java.io.IOException. If the command exits with a non-zero exit value, the fetchlet throws an oracle.sysman.emSDK.emd.fetchlet.MetricSourceException wrapping an oracle.sysmand.emd.fetchlets.CommandFailedException.

Notes

Commands are not executed as if they are being run in a shell. This means that common shell symbols do not work, including piping, output redirection, and backgrounding.

Commands cannot read from standard input.

The fetchlet blocks and waits for the command to finish.

21.2.2OSLines Fetchlet (split into lines)

The OS Lines fetchlet executes a given OS command and tokenizes the OS command's output. The output is tokenized by lines. The fetchlet returns the tokens in a single column table. The nth row in the table represents the nth line in the output of the OS command.

To get the raw, untokenized output of an OS command, use the OS fetchlet. To get the output of an OS command tokenized by lines and each line tokenized by a given delimiter, see the OS Line Token fetchlet.

Input Parameters

Table 21-2 OSLines Fetchlet Input Parameters

Parameter

Type

Description

Use

command

string

Operating system command to be executed.

Required

startsWith

string

Only lines starting with this string are included in the result.

Optional; default = "" (all lines are included)

ENVname

string

Parameters starting with "ENV" appear in the execution environment for the command as name environment variables

Zero or more of these

errStartsWith

string

When defined, this property allows you to define a custom prefix for error messages. If this property is not defined, the OSFetchlet defaults to "em_error=" as the message prefix.

Optional

script

string

Specifies the script to be executed if command property only provides an interpreter. For example, command might consist of "perl." script is then used to specify the particular perl script to be run.

Although scripts can be specified directly from the command parameter, using the script parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

args

string

A property that is taken as one or more arguments to the command and script properties.

Although args can be specified directly from the command parameter, using the args parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

separateErrorStream

boolean

If an error occurs while executing a command, this property instructs the fetchlet to whether to return both the stdout and stderr to the user as an error message. When set to TRUE, only stderr output is sent to the user as an error message when there is a command error. When set to FALSE (default value), both the stdout and the stderr are sent to the user as an error message upon command failure.

Optional. (TRUE/FALSE)

em_metric_timeout

integer

Metric timeout period (in seconds). After the timeout period has finished, the Management Agent returns a timeout exception and terminates any child processes that may have been created. The Management Agent DOES NOT kill any of the grandchild processes.

Note that without content, "\n" results in a blank line inserted between Line 2 and Line 4.

Notes:

Commands are not executed as if they are being run in a shell. This means that common shell symbols do not work, including piping, output redirection, and backgrounding.

Commands cannot read from standard input.

The fetchlet blocks and waits for the command to finish.

The standard output of the command is captured and the standard error is captured and appended to the standard output.

Lines are tokenized using "\n".

21.2.3OSLineToken Fetchlet (tokenized lines)

The OS Line Token fetchlet executes a given OS command and tokenizes the output of the OS command. The output is tokenized first by lines, and then each line is tokenized by a given delimiter set. The fetchlet returns the tokens in a table. The nth row in the table represents the nth line in the output of the OS command. The nth column in the table represents the nth token in a line as determined by the given delimiter set.

Parameters starting with "ENV" appear in the execution environment for the command as name environment variables

Zero or more of these

errStartsWith

String

When defined, this property allows you to define a custom prefix for error messages. If this property is not defined, the OSFetchlet defaults to "em_error=" as the message prefix.

Optional

script

String

Specifies the script to be executed if command property only provides an interpreter. For example, command might consist of "perl." The script is then used to specify the particular perl script to be run.

Although scripts can be specified directly from the command parameter, using the script parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

args

String

A property that is taken as one or more arguments to the command and script properties.

Although args can be specified directly from the command parameter, using the args parameter adds to stylistic clarity and readability when defining a target type metadata file.

Optional

separateErrorStream

Boolean

If an error occurs while executing a command, this property instructs the fetchlet to whether to return both the stdout and stderr to the user as an error message. When set to TRUE, only stderr output is sent to the user as an error message when there is a command error. When set to FALSE (default value), both the stdout and the stderr are sent to the user as an error message upon command failure.

Optional. (TRUE/FALSE)

em_metric_timeout

Integer

Metric timeout period (in seconds). After the timeout period has finished, the Management Agent returns a timeout exception and terminates any child processes that may have been created. The Management Agent DOES NOT kill any of the grandchild processes.

Any problem launching the command (unable to find the command program) results in an oracle.sysman.emSDK.emd.fetchlet.MetricSourceException wrapping a java.io.IOException.

If the command exits with a non-zero exit value, the fetchlet throws a oracle.sysman.emSDK.emd.fetchlet.MetricSourceException wrapping a oracle.sysmand.emd.fetchlets.CommandFailedException.

Notes

Commands are not executed as if they are being run in a shell. This means that common shell symbols do not work, including piping, output redirection, and backgrounding.

The fetchlet promptly closes the input stream to the running command.

The fetchlet blocks and waits for the command to finish.

Lines are tokenized using "\n".

The delimiter can be a single character or a set of characters. For example, it can be "|+_", if the line should be broken up by pipes, pluses, and underscores. If two or more delimiters are together in the output text, such as "||" or "+|+", then it is as if there are empty string tokens between them. These empty strings get columns in the result table. It is not considered that there are empty strings preceding a delimiter that starts a line or following a delimiter that ends a line.

In order to express non-printable characters in the delimiter set (such as tabs) in XML, use "&#xHH;" where H is the hexadecimal identifier for the character.

21.2.4 Invoke an OS Fetchlet as a Specific User for Metric Collection

Depending on requirements, your plug-in may need to utilize the OS fetchlet to invoke a pre-existing script on the Management Agent monitoring a target to collect data for a specific metric as a specific user; that is, as a user other than the default "oracle" user.

Enterprise Manager supports the use of Privilege Delegation Providers (sudo and powerbroker) to invoke metric collections as a specific user. Enabling PDP for a plug-in requires credential setup on both the plug-in and on hosts where the target(s) being monitored are deployed.

In your plug-in, you must set the credential reference in the metric definition in the target metadata file. In the example, example Credentialref line has "your_cred". This value refers to monitoring credential set name.

On the Management Agent monitoring the target, a referenced credential type must be created that points to host:HostCreds, and allow the monitoring credential set be of the new type that you add. See "Sudo and PowerBroker Support" in the Enterprise Manager Cloud Control Administrator's Guide for details on privilege delegation setup using Enterprise Manager Cloud Control.

The credential data will be persisted to the target metadata file (target.xml) for the Management Agent monitoring the target.

The below example defines the referenced credential type MyHostCreds in target.xml, which is of the credential type host:HostCreds.

21.3SQL Fetchlet

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

Input Parameters

Table 21-4 SQL Fetchlet Input Parameters

Parameter

Type

Description

Use

Connection Information

MachineName

String

Database host

Required

Port

Integer

Database port

Required

SID

String

Database SID

Required unless ServiceName is specified

ServiceName

String

Database ServiceName

Required unless SID is specified

OracleHome

String

Database's Oracle Home (used in conjunction with OidRepSchemaName).

Required when OidRepSchemaName is used.

Credential Information

UserName

String

user name

Required

password

String

user password

Optional; default is ""

Role

String

Role used when connecting to the database (e.g., SYSDBA)

Optional; allowed choices are SYSDBA, SYSOPER, and NORMAL (default)

General

STATEMENT

String

SQL statement or PL/SQL block

Required unless FILENAME is specified.

FILENAME

String

Full path of the file containing the SQL statement or PL/SQL block

Required unless STATEMENT is specified.

NUMROWS

Integer

Maximum number of rows to output.

Required

Bind Parameters

SQLINPARAM<position>

String

Value of input parameter at position <position>

Zero or more, one for each input parameter.

SQLOUTPARAMPOS

Integer

Position of output parameter, if it exists

There can be exactly one output parameter, if it exists.

SQLOUTPARAMTYPE

String

Type of the output parameter, if it exists.

There can be exactly one output parameter type, if it exists.

transpose

TRUE/FALSE

If TRUE, the result is transposed: rows to columns and columns to rows.

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.

Note:

When using a SQLOUTPARAMTYPE of type 'ARRAY', you must identify the array as follows:

If you create the array type specified in the SQLOUTPARAMTYPE from SQL*Plus or any utility without using double quotation marks to surround the array name, then you must specify the array name using all upper-case letters in the target metadata file for this property. The reason for this because the RDBMS automatically changes the array name to all upper-case.

If you create the array type specified in the SQLOUTPARAMTYPE from SQL*Plus or any utility using double-quotation marks to surround the array name, then the RDBMS retains the case specified. For this reason, users must specify the array name using the same case used in the target metadata file.

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:

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:

21.4SNMP Fetchlet

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

Table 21-5 SNMP Fetchlet Input Parameters

Parameter

Type

Description

Use

hostname

String

Host name of the SNMP agent

Required. Default is "localhost"

Examples:

"bigip.host.example.com"

"148.87.10.5"

PORT

String

Port of the SNMP agent

Optional. Default is "161"

COMMUNITY

String

SNMP community string

Optional. Default is "public"

TIMEOUT

String

SNMP timeout.

Optional. Default is five seconds

OIDS

String

A list of substrings separated by delimiters. Each substring starts with an OID (in numerical dot notation), and can be optionally ended with *PlacementOID. (See notes for details.)

Required.

Examples:

"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"

"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"

"1.3.6.1.2.1.2.2.1.3 1.3.6.1.2.1.2.2.1.5

1.3.6.1.2.1.4.20.1.1*1.3.6.1.2.1.4.20.1.2

1.3.6.1.2.1.4.20.1.3*1.3.6.1.2.1.4.20.1.2"

DELIM

String

A delimiter to separate individual substrings in OIDS.

Optional; default is whitespace characters, (dot), *(star) and 0-9 (digits) cannot be used as delimiters

TABLE

String

Each OID in OIDS corresponds to a variable with multiple instances if this parameter is "TRUE" and to a single variable instance if it is "FALSE".

Optional; default is "FALSE"

PINGMODE

Boolean

Used for defining PINGMODE Response metric

If set to TRUE, then a successful GetResponse generates a single-row, single-column table with the value "1" in its cell. A timeout generates a single-row, single-column table with the value "0".

This is useful for defining a Response metric for an SNMP-based target.

Optional. Default is "FALSE"

IGNORE_TIMEOUT_ERR_BOOLEAN

Boolean

Specifies whether to generate an error when a non-PINGMODE invocation times out while waiting for a response.

If set to TRUE, then a non-PINGMODE invocation that times out while waiting for a response should not generate a metric collection error. This is reasonable behavior for targets that define a PINGMODE Response metric. If that Response metric is going to generate an availability severity when the SNMP agent stops responding, then there is no need to generate metric errors on any non-Response metrics that happen to run before the Response metric can identify the problem.

Optional. Default is "TRUE"

MAX_NUM_ROWS_FETCH

Integer

The maximum number of rows to be returned by a TABLE invocation.

The configuration property "SnmpTableMaxNumRowsFetch" can override the default value.

Optional. Default is 1000

CONTEXT_NAME

String

Along with CONTEXT_ENGINE_ID, these two properties specify a set of SNMPv3 credentials, which replace the community string used by SNMPv1 and SNMPv2c.

Note: If these two properties are specified, then the COMMUNITY and the VERSION parameters are ignored, and the sent request is an SNMPv3 request.

Optional. No default value

CONTEXT_ENGINE_ID

String

For information about this parameter, see the CONTEXT_NAME description.

Optional. No default value

VERSION

String

Specifies the SNMP version.

If the following occurs, then VERSION is set to "v2c", indicating an SNMPv2c request:

disallowV1Requests is set to TRUE or hasV2Types is set to TRUE

and

CONTEXT_NAME and CONTEXT_ENGINE_ID are not specified

If these previous conditions do not apply, then VERSION is set to "v1" indicating an SNMPv1 request.

Optional. Default is "v1"

disallowV1Requests

Boolean

This parameter enables the user to specify that the Management Agent should use SNMPv2c only when sending any request to a particular target

Optional. Default is "FALSE"

hasV2Types

Boolean

This parameter is a global-scoped property for an SNMP QueryDescriptor that includes OIDs for MIB variables whose types are 64-bit integer values. These are not representable in SNMPv1. Even if other requests for the same target instance are sent using SNMPv1, the target-type owner knows that this request must be SNMPv2c.

Optional. Default is "FALSE"

USE_GET_NEXT_ONLY

Boolean

If an SNMP QueryDescriptor is SNMPv2c, according to the conditions described in the VERSION description, and if TABLE is TRUE, then the multiple rows that the SNMP fetchlet returns will be fetched using the SNMPv2c GetBulk request, and not the GetNext request used in SNMPv1.

If USE_GET_NEXT_ONLY is set to TRUE, then the SNMP fetchlet returns will be fetched using GetNext requests.

Optional. Default is "FALSE

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):

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:

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:

MissingParameterException if URL parameter is missing.
FetchletException if the URL is malformed or an I/O error occurs in retrieving the content of the URL.

21.5.2URL Lines Fetchlet (split into lines)

The URL fetchlet gets the contents of a given URL and tokenizes the contents of the URL. The output is tokenized by lines. The fetchlet returns the tokens in a single column table. The nth row in the table represents the nth line of the URL contents.

Note:

To get the raw, untokenized contents of a URL, see the URL fetchlet. To get the contents of a URL tokenized by lines and each line tokenized by a given delimiter, see the URL Line Token fetchlet.

FetchletException if the URL is malformed or an I/O error occurs in retrieving the content of the URL.

Notes

Lines are tokenized using "\n".

21.5.3URL Line Token Fetchlet (tokenized lines)

The URL fetchlet gets the contents of a given URL and tokenizes the contents of the URL. The output is tokenized first by lines, and then each line is tokenized by a given delimiter set. The fetchlet returns the tokens in a table. The nth row in the table represents the nth line of the URL content. The nth column in the table represents the nth token in a line as determined by the given delimiter set.

To get the raw, untokenized contents of a URL, see the URL fetchlet.

Table 21-8 URL Line Token Fetchlet Input Parameters

Name

Description

Use

url

URL to retrieve the contents of

required

delimiter

set of characters that act as delimiters to tokenize the lines

optional; default = "" (just breaks output into lines)

proxyHost

proxy host through which to make the URL connection.

optional

proxyPort

proxy port through which to make the URL connection.

optional

startsWith

only lines starting with this string are included in the result

optional; default = "" (all lines are included)

Example

Take the following URL:

http://localhost/nhcities.txt

It has the following contents:

Line 1: Nashua, Keene,

Line 2: Concord

Line 3: , Conway, Manchester, Milford, Brookline,

Line 4:

Line 5: Hollis, Meredith

Now run the URL fetchlet with the given URL and a single character "," for the delimiter.

FetchletException if the URL is malformed or an I/O error occurs in retrieving the content of the URL.

Notes

Lines are tokenized using "\n".

The delimiter can be a single character or a set of characters. For example, it can be "|+_", if the line should be broken up by pipes, pluses, and underscores. If two or more delimiters are together in the output text, such as "||" or "+|+", then it is as if there are empty string tokens between them. These empty strings get columns in the result table. It is NOT considered that there are empty strings preceding a delimiter that starts a line or following a delimiter that ends a line.

In order to express non-printable characters in the delimiter set (such as tabs) in XML, use "&#xHH;" where H is the hexadecimal identifier for the character.

21.6URLXML Fetchlet

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

Table 21-9 URLXML Fetchlet Input Parameters

Name

Description

Use

url

URL to retrieve the contents of

Required.

pattern

The pattern used to extract information from XML; this is a list of XML chunks that that is compared against the XML content of the URL. Each chunk contains one or more "grabbers" (*) in the text portion of the elements that define what should the flattened into text and extracted.

Required.

proxyHost

The proxy host through which to make the URL connection.

Optional.

proxyPort

The proxy port through which to make the URL connection.

Optional.

ignoreDtd

If set to TRUE, specifies that the DTD file referenced by the content XML should be ignored. This is useful in cases where the DTD file cannot be accessed.

Optional.

generateKey

If set to true, a unique key will be generated for each row. The key will occupy the first column of the result, and will be numeric.

Optional.

throwConnException

If set to TRUE, a java.net.ConnectException will be thrown. Otherwise, it will be caught and an empty result set will be returned. Setting this property to FALSE provides behavior which is consistent with the DMSFetchlet.

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.

21.7URL Timing Fetchlet

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

Table 21-10 URL Timing Fetchlet Input Parameters

Parameter

Description

Use

url#

URL(s) to download. "url0" is required but any number of URLs can be specified beyond url0 that following the convention: url0, url1, url2, url3.

Required.

proxy_host

Proxy host used to make a URL connection.

Optional. Specifies the proxy to be used for accessing URLs. If the proxy_host_override value is provided, then that value will be used instead.

proxy_port

Port used by the proxy host used make the URL connection.

Optional.

dont_proxy_for

Domains for which the proxy will not be used.

Optional. For example, .us.example.com, .uk.example.com

use_proxy

When used in conjunction with the proxy override input parameters, use_proxy specifies a proxy to be used in lieu of the original proxy. When set to false without the proxy override parameters set, no proxy is used.

Optional. Parameter can be set to true or false.

proxy_host_override

Alternate proxy host used to make the URL connection.

Optional. Overrides proxy_host.

proxy_port_override

Alternate proxy port used to make the URL connection.

Optional. Overrides proxy_port.

dont_proxy_override

Do not use the proxy for domains.

Optional. Parameter can be set to true or false.

internet_cert_loc

Path pointing to the location of a certificate to be used to access a secure (HTTPS) URL.

Optional.

auth_realm

Realm for the Basic Authentication log on. If the realm is not specified for the authentication, authentication does not occur and the download of the page fails with a 401 response code.

Optional.

auth_user

User name for Basic Authentication.

Optional.

auth_password

Password for Basic Authentication.

Optional.

retries

Number of times to retry the url if it initially fails.

Optional. Default = 1

connection_timeout

Wait time (in milliseconds) allowed to establish a connection to a server. This time also includes time required for name resolution.

Optional. Default= 60000 milliseconds (1 minute)

read_timeout

Idle time in the read waiting for the server to respond. For example, if no data is received from the server during the specified timeout period, the operation is considered failure.

Optional. Default = 12000 milliseconds (2 minutes)

timeout

Number of milliseconds after which the page download is considered a failure. This will detect if the site is functional but is extremely slow.

Optional. Default = 300000 ms (5 minutes)

status_comparator

When collating the rows to make a single row, the status_comparator parameter will indicate whether all URLs should have been a success (and) or any URLs should have been a success (or).

Optional. Default = and

cache

Indicates whether to use a cache when accessing an URL. Set the parameter to "n" to specify that no cache be used.

Optional. Default = yNote: The scope of the cache is per request. There is no persistent cache across multiple get metric requests.

Required. summary : gives a default set of metrics in a single row for all urlsdetailed: gives a default set of metrics for each url.repeat_column : gives a single row of metric with timing for each of the url.

Optional. Allows you to specify of what needs to be returned from the fetchlet and in which order.Example: status, status_description, total_response_time

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 21-11 lists the format categories and the metrics (columns) returned by each. For a description of available metric columns, see Table 21-12, "URLTIMING Fetchlet: Metric Columns"

Table 21-11 URLTIMING Fetchlet: Output Formats

Output Format

Description

Metric Columns

summary

Returns a default set of metrics in a single row for all URLs

If the metrics input parameter is specified, then only the columns specified will be returned.

If the metrics input parameter is specified, then those columns will be returned for each URL followed by overall status and status_description. (Note the output will always be single row).

total_response_time repeated for each URL followed by overall status and status_description.

Metric Columns

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

Table 21-12 URLTIMING Fetchlet: Metric Columns

Column Name

Description

status

The overall status of all URLs. By default AND is used to compute overall status but this can be changed using the status_comparator input parameter.

connect_time

The time to connect to the server and send the request.

first_byte_time

Time taken between sending the request and reading the first byte from the response.

total_response_time

Time taken for fetching ALL urls and associated content (gif, css, javascript, and so on).

max_response_time

Also referred as Slowest page time. This the time taken by the slowest URL.

avg_response_time

Average response time for URL. Computed as total response time / number of pages (urls).

rate

Kilo Bytes per second. This is computed by total bytes received / total time taken to receive them.

html_time

Total time taken to download the html part of all pages. This time excludes time to fetch images and other contents. (Includes time to fetch frame html).

content_time

Time taken to download the page content (gif, javascripts, css, and so on).

redirect_time

Total time taken for all redirects occurring while fetching the set of urls specified.

redirect_count

Number of redirects.

total_bytes

Total number of bytes.

html_bytes

Total number of HTML bytes. (Includes bytes for frame html).

content_bytes

Total number of content bytes.

status_description

This is present only when the status is down. Corresponds to HTTP Status description.

request_count

Number of request made. (Includes all html as well as content requests).

broken_count

Number errors while fetching images or other content elements.

broken_details

List of images or other content elements that could not be fetched. This has format of url[broken list], url[broken list...

computed_response_time

This time approximates the time it would have taken for a client (like browser) to fetch all the pages in the transaction. This number is computed as if the contents of every page (gifs, css, and so on) were fetched using multiple threads.

avg_connect_time

Total connect_time / total number of connections made.

avg_first_byte_time

Total First Byte Time / Number of requests made (either to fetch HTML or content).

dns_time

Time to resolve host name (not implemented, always returns zero).

url

Returns the url, can only be used in 'detailed' output_format.

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):

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

21.8Dynamic Monitoring Service (DMS) Fetchlet

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

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 Cloud Control.

21.8.1 Advantages to Using DMS for Oracle Management Agent Integration

With DMS, a component can insulate itself from the operational details of the Management Agent. A component would not need to deploy (or maintain) its own fetchlet or deploy (or maintain) a Tcl script or shell script to plug into one of the existing fetchlets. A component would not need to devise its own new way of measuring or exporting performance metrics. Performance metrics can be measured and reported in a consistent way across components. The DMS fetchlet contacts the remote DMS runtime directly with no need for forking shell scripts or Tcl scripts. Most importantly, DMS automatically produces the long, complicated metadata document for you and thereby saves many hours of tedious and error-prone hand editing.

Input Parameters

Table 21-13 DMS Fetchlet Input Parameters

Name

Type

Description

Use

oraclehome

String

Top directory under which the monitored IAS instance is installed. It is used only for monitoring local IAS processes. For monitoring remote IAS processes, users should give it an empty value and specify property "opmnremoteport" and/or "machine" instead.

Required.

Example:

"/private/oracle/ias"

version

String

AS Version number of the target. It is used to distinguish the version of monitored AS instance.

Optional

Example:

"9.0.4"

opmnport

Integer

Oracle Process Monitoring and Notification (OPMN) port. It is used primarily for monitoring remote AS processes. It should be specified together with property "machine". If it is present and valid , property "oraclehome" and "httpport" are ignored.

Optional

Example:

"6200"

httpport

Integer

HTTP port is used primarily for monitoring stand-alone processes. It should be specified together with property "machine". It will be ignored, if property "opmnport" is present. If it is present and valid, property "oraclehome" is ignored.

Optional

Example:

"7777"

machine

String

Host name where the Internet Application Server (AS) instance runs. It should be specified together with property "opmnport". If it is not present, the local host is assumed.

Optional

Example:

"my-sun.us.example.com"

metric

String

Name of the table-type metric.

Required

Example:

"Servlets"

columnOrder

String

A list of metric column names separated by ";". The column names must be specified in same order as they appear in the target type metadata file.

Do not include "name", "host", "process" and "fullname" columns.

Required

Example:

"processTimes;totalRequest;requestRate"

usecache

String

Whether to cache this metric. The legal values are "true", "false" and "refreshall" with "true" being the default. The "refreshall" value tells the DMS to delete its cache data and retrieve the most recent data from all targets.

Optional.

Example: "false"

Setting "usecache" to "false" will bypass DMS caching

proxyHost

String

Proxy host through which to make the HTTP connection

Optional

Example:

"proxy.us.example.com"

proxyPort

Integer

Proxy port through which to make the HTTP connection

Optional

Example:

"80"

dontProxyFor

String

Domains for which the proxy will not be used.

Optional

Example:

".us.example.com" or "18.219.0"

useDefaultProxy

String

When used in conjunction with the proxy override parameters, this variable specifies a proxy other than the original one. When set to false without the proxy override parameters set, no proxy at all is used.

Optional

Example:

"true" or "false"

proxyHostOverride

String

proxy host through which to make the HTTP connection

Optional

Example:

"www-proxy.us.example.com"

proxyPortOverride

Integer

proxy port through which to make the HTTP connection

Optional

Example:

"80"

authrealm

String

Realm for the Basic Authentication logon. If the realm is not specified for the authentication, authentication does not occur and the download of the page fails with a 401 response code.

Optional

Example:

"Please input your flex account login:"

authuser

String

Username for Basic Authentication

Optional

"superuser"

authpwd

String

Password for Basic Authentication

Optional

Example:

"welcome"

Error Handling

The DMS fetchlet throws MissingParameterException if any of the properties "oraclehome", "metric", "columnOrder", "opmnport", or "httpport" is missing. It throws FetchletException if any of the ports given is not valid.

Notes

The first four columns of the metric table returned are always column "name", "fullname", "host" and "process". Therefore, do not include them in columnOrder string. Property "machine" should be specified together with either properties "opmnport" or "httpport". In this case, the property "oraclehome" is ignored.

21.8.2DMS Fetchlet/Oracle Management Agent Integration Instructions

DMS has been used in several components (such as Apache, JServ, OSE, and Portal) to provide a consistent performance monitoring infrastructure for Oracle 9i Application Server. The Sensors are easy to use and save most of the work related to performance measurement because they hide most of the details related to timing, counting, and categorization. Finally, DMS hides many Management Agent details from component developers and much of the Management Agent integration effort.

To enable DMS metrics for Enterprise Manager Cloud Control, you must follow two additional rules:

Rule 1: All Nouns exported to the Management Agent must have types
Noun types can be set either by specifying the "type" parameter in the Noun.create() methods or by using the Noun.setType(String) method. The idea is that every Noun type will be converted automatically to a Management Repository table. Every Noun of a given type will become a row in the type's corresponding Management Repository table. The metrics contained by a Noun become columns in the Management Repository table metric. Any Noun without a type will not be exported to Management Agent.

Rule 2: All Nouns of a given type must contain a consistent set of Sensor names Because the metrics contained by a Noun become columns in a management repository table, you must make sure that all Nouns of a given type contain the same Sensors. This ensures that each row of the corresponding Management Repository table has the same set of columns. DMS does not check this constraint for you.

For example, the following Java snippet shows how to create typed Nouns that contain a consistent set of Sensors. DMS will automatically convert these into a Management Repository table named "MyType":

For this example, the "MyType" table will contain three rows and four columns. Besides the columns corresponding to the two Sensors, there will be a "name" column and a "path" column that will contain the DMS path name including the process name and "/myExample/myCom...".

If these Nouns/Sensors are created in several servlet engines within the AS site, then the AggreSpy will find each of the servlet engines and will aggregate all of the Nouns/Sensors into a single MyType table.

Step 4: Generate your Target Metadata Document

You can generate the Target Metadata Document using your browser. Point your browser to your AS site that you want to monitor using the following URL:

You should use the actual host, port and servlet path of your AS installation in the above URL. The servlet path usually defaults to "servlet". The XML document you get is the Target Metadata Document for your AS site. The first comment of the XML document explains where you can obtain the Target Metadata Document and instructions telling you what needs to be done to this document.

Step 5: Install the Target Metadata Document

Follow the steps described in the first comment of the XML document. Save the XML document to a file called "oracle_dms.xml" under the "metadata" directory of your Enterprise Manager installation (OMS_ORACLE_HOME/sysman/admin/metadata/). If you want to monitor a subset of the metrics or merge the metrics with the ones in the existing "oracle_dms.xml" file, you should save this new definition to a separate file called target_name.xml. You will also need to change the Target Type entry in the generated metadata document.

Next, you should add the target instance information of your AS site to your "targets.xml" file residing under the top directory of your Enterprise Manager installation. You can find a block of XML tags in the comment you read. They look like:

Copy this block and paste it to the targets.xml file between <targets> and </targets> tags.

Finally, to add the new target metadata file and target instance information from the targets.xml file to Enterprise Manager Cloud Control, you must run the following command:

>$ORACLE_HOME/bin/emctl reload

Step 6: View Your Metrics

You are ready to view your metrics using Enterprise Manager's Metric Browser. First, make sure that AS and your component are still running. Next, restart the Oracle Management Agent. Finally, point your browser to your Management Agent installation using the following URL:

http://YOUR_AGENT_HOST:YOUR_AGENT_PORT/emd/browser/main

The Management Agent port information can be found in the $AGENT_HOME/sysman/config/emd.properties file at the EMD_URL line.

You should use the actual host and port of your Management Agent installation in the above URL. You will find your AS site listed as the target "DMS_YOUR-AS-HOST_YOUR-AS-PORT". If you click the link, you will see a list of metric IDs. You can browse your metrics by clicking on the respective metric IDs.

21.9JDBC Fetchlet

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

Table 21-14 JDBC Fetchlet Input Parameters

Name

Description

Use

Transaction Name

(Standard)

Required.

Beacon Name

(Standard)

Required.

Connect String

Connection string provided by the user. The Connect String must comply with the URL format specified by the vendor of the database to which the user is trying to connect.

Examples:

Format required by Oracle:

jdbc:oracle:thin:@hostname:port

Format required by MySQL:

jdbc:mysql://hostname:port

Required.

Class Name String

The driver class name to be used for connections.

Example:

oracle.jdbc.driver.OracleDriver

You have two options for configuring the Agent to use the .jar file containing the driver:

Place the .jar file in $JAVA_HOME/jre/lib/ext. CLASSPATH does not need to be modified.

Place the .jar file anywhere and update CLASSPATH in emd.properties file with the path to jar. Bounce Agent. This should be scripted and be transparent to user.

Required.

Username

User name to be used when connecting to the database.

Required.

Password

Password to be used when connecting to the database.

Required.

Role

User Role

Required.

Statement

SQL statement to be executed. Use of PL/SQL is possible by using prepareCall() API.

Required.

Table 21-15 Metric Columns Collected

Column

Description

Status

Status of the test. Status is 'down' if there is a SQLException generated by the fetchlet.

Total Time

Time required for the fetchlet to execute the test.

Connect Time

Time required for DriverManager.getConnection() to complete.

Prepare Time

Time required for conn.prepareStatement() to complete.

Execute Time

Time required for stmt.executeQuery() to complete.

Fetch Time

Time required for while(rs.next()) { rs.getRow() } to complete.

Close Time

Time required for closing resultset, statement, connection to complete.

Number of rows

Number of rows fetched.

Total time per row

Fetch time per row

Example

Example 21-10 provides the properties passed to the JDBC fetchlet when invoked.

21.10WBEM Fetchlet

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

Table 21-16 WBEM Fetchlet Input Parameters

Name

Type

Description

Use

hostname

String

Host name of the CIMOM

Optional; default is "localhost"

port

Integer

Port for the CIMOM

Optional; default is 5988

namespace

String

CIM Namespace

Optional; default is "root/cimv2"

username

String

User name to use for CIMOM authorization on the host where the CIMOM is running

Required

password

String

Password to use for CIMOM authorization on the host where the CIMOM is running

Required

CIMclassname

String

Name of the CIM class whose instances will be returned

Required for all operations except STATUS. STATUS operations just check whether the CIMOM is running, so a class name is not needed.

operation

String

Operation to be performed. Supported operations include COUNT, which returns a count of the number of instances in the class, VALUES, which returns the values of the specified properties for each instance of the class, or STATUS, which provides status information about the CIMOM.

Optional, default is VALUES

properties

String

The property names from the CIM class definition that we are interested in collecting.

Required for VALUES operation. If the operation is VALUES, we can have 1 to N of these, separated by a semicolon. If the operation is VALUES, and no properties are provided, an error is returned. Properties are handed to the EMD in the order that they are specified.

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 21-11 shows how to write the metadata for a COUNT operation:

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.

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.

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.

21.11JMX Fetchlet

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

Table 21-17 JMX Fetchlet Major Input Parameters

Name

Type

Description

Use

MachineName

String

MBean server host name

Optional

Port

Port on which the MBean server is listening for new connections

Optional

UserName

String

User name for JMX connections, if required

Required

password

String

Password for JMX connections, if required

Required

protocol

String

Protocol used for the connection

Optional

service

String

Service used for connection

Optional

serviceURL

String

serviceURL used for JMX connection. This is instead of the previous MachineName, Port, protocol, and service properties.

Note: For middleware targets, the serviceURL can be obtained from either the farm or managedServer association depending on whether metric needs to be collected from AdminServer or the managed server.

Required (unless MachineName and Port are specified)

Metric

String

Mbean object name (or if MetricService=true, the DMS table name)

Required

columnOrder

String

Semi colon separated list of JMX attributes for the previous MBean corresponding to the column definitions in the TableDescriptor of the metric.

Required

operation

String

Name of the JMX operation to be invoked.In this case, the columnOrder represents the values from the return object to be populated in the Metric. (Oracle recommends using jmxcli to generate this).

Optional

arguments

String

The XML representing the arguments for the JMX operation. Oracle recommends using jmxcli to generate this.

Optional

MetricService

Boolean

MetricService=true implies that the metric is retrieved by the Oracle-specific DMS Metric Service. In this case the previous columnOrder property is a list of column names and the &rsquor;metric' property indicates the actual DMS table name.

Optional

identityCol

String

The Mbean object name key (or a semi-colon separated list of keys) that will be extracted from the Mbean ObjectName and surfaced as key columns in the resultant metric.If the value &rsquor;canonical' is specified, an additional key metric column with the complete Mbean object name is returned by the fetchlet.This property makes sense only if the previous metric property is an ObjectName pattern that matches more than one Mbean on the server.

Optional

autoRowID

String

Prefix for an automatically generated key column. The suffix is sequential numbers starting at 1.For example, autoRowID set to ROW_ generates a key column at position 0 with values ROW_1, ROW_2, and so on up to the number of rows returned.This is usually the case if none of the other columns (JMX attributes selected) are unique and multiple rows are returned as a result of multiple mbeans matches and mbean pattern.

Optional

useCache

Boolean

Applicable only when MetricService=true and indicates if metric service cache needs to be used

Optional

ServerNames

String

Applicable only when MetricService=true and is a semicolon list of server names from which the DMS metrics need to be retrieved. This is relevant only when collecting these metrics from the AdminServer (that is, serviceURL points to AdminServer through farm association), which has metrics from all managed servers

Optional

valueWhenNoMBean

Number

Typically used for response metrics and has the value that the fetchlet returns as a single row and column when no mbeans are found that match the given mbean pattern (in the previous metric property).

Optional

valueWhenDown

Number

Typically used for response metrics. This has the value that the fetchlet returns as a single row and column when the connection to the server fails due to a connection exception (indicating that the server is down).

Optional

admlMap

String

Applicable only when MetricService=true and is an XML snippet that indicates what adml parameters need to be passed for this adml table.(Oracle recommends using jmxcli to generate this).

Optional

Notes:

The JMX fetchlet is used to retrieve primarily JMX attributes from Mbeans on a target MbeanServer. It can also retrieve attributes from multiple MBeans of the same kind in the form of a table (with multiple rows where each row represents a matching MBean).

For example, if an MBean ObjectName pattern specifies servlets, (that is, *:Type=ServletRuntime,* in the metric property), and the columnOrder specifies A1;A2;A3, then the resultant metric will have one row for each servlet.

If the metric data must be obtained using a JMX operation (this is not typical for collecting metrics), then the QueryDescriptor property operation must specify the JMX operation name and the arguments are an XML representation of the parameters to be passed into the JMX operation.

For example, the following QueryDescriptor indicates the invocation of a JMX operation called "getNumUserSessions" with a single string argument with a value="total".

A QueryDescriptor for the JMX fetchlet contains JMX connection information. This is usually in the form of a serviceURL. If the serviceURL property is not available in the QueryDescriptor, then the combination of MachineName, Port, protocol, and service properties must be present in the QueryDescriptor to provide connection information to the JMX fetchlet.

21.12Web Services Fetchlet

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.

A valid CredentialSet of a Store Credential Type defined in the <CredentialInfo>

Must be defined as a monitoring credential.

SSLTrustStoreCredential

SSL truststore credentialset name

Optional

A valid CredentialSet of a StoreCredential Type defined in the <CredentialInfo>

Must be defined as a monitoring credential.

UserCredential

User token credentialset name

Optional

A valid CredentialSet of a AliasCredential or CSFKeyCrdential Type defined in the <CredentialInfo>

Must be defined as a monitoring credential.

ValueWhenDown

Default response when target is down

Required (only for response metric). Not required for regular metric. For Response metric, when a target is down, this value (if specified) will be returned.

A target is considered as down when the Fetchlet catches a ConnectionException.

Examples

Example 21-16 provides an example of a metric definition for Remote Procedure Call (RPC) or encoded Web services and Example 21-17 provides an example of a metric definition for doc or literal Web services.

21.14REST Fetchlet

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.

21.14.1 Response Processing

The fetchlet relies on response data to construct monitoring metrics. Because the response media type can be application/xml, application/json, or text/xml, different mechanisms are adapted to process the response. Table 21-20 describes the different mechanisms for each response media type.

In Enterprise Manager Cloud Control Release 2 (12.1.0.3), a new fetchlet property, ”SSLTrustServerCert”, has been added. If set to ”TRUE”, the fetchlet will use the non-validating mode for the server certificate, and there is no need to provide or specify the SSL trust store.

Example 21-23

<Property NAME="SSLTrustServerCert" SCOPE="GLOBAL">TRUE</Property>

21.14.3 Using REST CLI to Generate Metadata

REST CLI is a client command line tool for generating target metadata and default collection files to enable the Management Agent to monitor RESTful web resources through invoking the REST fetchlet.

Use the following emctl command to invoke REST CLI:

emctl restcli

Table 21-22 provides a list of the command-line arguments that you can use with the emctl restcli command.

Table 21-22 Command-line Arguments Supported by REST CLI

Argument

Description

Example

metadata

Generate target metadata

-metadata

wadl

WADL location

-wadl=http://......

-wadl=file:///.....

wsdl

WSDL location

-wsdl=http://......

-wsdl=file:///.....

username

User name to log in to the host

-username=admin

proxyhost

Host name of the proxy server

-proxyhost=proxy.example.com

proxyport

Port number of the proxy server

-proxyport=80

To use REST CLI:

Run the REST CLI command with the Web Application Description Language (WADL) location. For example:

If the WADL location is access protected, then enter a user name and password.

Example 21-24 provides an example of a user running the REST CLI tool.

REST CLI prompts you to enter the target type and location where the output directory will contain the generated target and collection metadata files.

REST CLI lists out all the available resources paths for monitoring. You must select a resource path and one of its methods to define monitoring metric for that resource.

REST CLI also prompts you to define the collection schedule.

When all the information is gathered from the user, the tool generates the target and default collection metadata files under the specified output directory similar to the metadata provided in Example 21-25.