The retrieveObjectData command retrieves profile and measurement data for one or more objects. You can use this command's output file in the following ways:

  • Input to a reporting tool.

Business Transaction Management provides Oracle BI Publisher templates that you can use with the command's output file to produce formatted reports. See Chapter 8, "Creating Reports," for more information on using these templates.

  • Input to the setBaseLines command.

In this case, you set performance baseline values for a set of objects by using the output file of retrieveObjectData as an input file to setBaselines. Setting baselines enables you to then create a baseline SLA policy. (Do not set the retrieveObjectData command's attribute if you are using the output file to set baselines.)

Command syntax

btmcli retrieveObjectdata -t type1 [[type2] ...] [-query filterQuery]
           [-attributeNames attrName1 [attrName2] ... instrName1 [instrName2] ...]
           [-segments segment1 [segment2] ...] 
           [-inTheLast inTheLast] | [-startTime startTime] [-endTime endTime]
           [-intervalSize intervalSize] 
           [-format XML|CSV|SQL] 
           [-o outputFile] 
           [-metadata drop|create|none] [-tableName tableName] 
           -s sphereUrl -l username:password

You can use the listInstruments command to get the information about attributes, segments, and instruments that you must pass as arguments to the retrieveObjectData command. If you specify a list of attributes and a list of segments, the command parser applies each segment to any instrument in the attribute list that has that segment.

If no time values are specified, the last hour's data is retrieved in a single segment.

Name Long Name Description
-t -type Specifies the object tree whose data is to be retrieved.

At a minimum a root object type must be given that determines (along with the query) which objects will be retrieved.

In addition to this, you can specify any number of 'child' types. These trees mirror those found in the custom data explorer. An example type tree is 'service endpoint operation' or 'observer probe endpoint'.

-query -filterQuery Limits the objects to be retrieved to the set defined by the query filter.

The query must apply to the root object type of the tree. Only those objects that match the given query will be returned in the result set, along with the associated objects in the sub-tree.

Use the Filter tool to construct AQL queries, and then copy and paste these into the command line.

-- -attributeNames Use this argument to specify which attribute and instrument values to retrieve for each object, for example:

-attributeNames friendlyName averageResponseTime

In this example, friendlyName is an attribute and averageResponseTime is an instrument. You can specify multiple attribute names (separated by spaces) followed by multiple instrument names (separated by spaces).

Attribute names can refer to any attribute that is available in the column chooser. Attributes can be qualified by an object type followed by two colons ('::'), for example:


If you specify a qualified attribute name, attribute values are retrieved for only the specified object type (in the example, that would be the friendly names of only endpoints). If you specify an unqualified attribute name, attribute values are retrieved for all object types listed in the type argument that have that attribute (for example, endpoints, services, and operations). See Attribute Names, for a complete list of commonly used attribute names and object types.

For a complete list of instrument names, run the listInstruments command.

-segments -- Specifies the segments to use when retrieving the data for any specified measurement attributes (instruments). This provides a breakdown of the data for each specific value of the named segment that was recorded during the specified time-frame.
-inTheLast -- Specifies a time range extending from the current time back into the past by the indicated amount.

The value is given as a number followed by a unit (s, S = seconds; m, M = minutes; h, H = hours; d, D = days) e.g. "1H" for "1 Hour".

-startTime -- Specifies the start of a time range over which to produce values for any specified measurement attributes (instruments). If 'endTime' is not specified, the range ends at the current time.

The current default date format is used, e.g. "2010-08-03 15:00:00".

-endTime -- Specifies the end of a time range over which to get values for any specified measurement attributes (instruments).

The current default date format is used, e.g. "2010-08-03 18:00:00".

-- -intervalSize Indicates the size of the intervals into which the specified time range is to be divided.

The interval size is given as a number followed by a unit (s, S = seconds; m, M = minutes; h, H = hours; d, D = days) e.g. "1H" for "1 Hour". The interval size must be less than or equal to the length of the specified time range.

If this optional argument is not specified the entire time range will be used and only a single interval is returned.

Note: Do not set this attribute if you are using the output file as input to the setBaselines command. The setBaselines command cannot accept more than one value per instrument type per object. Omitting this attribute ensures that only one value per instrument type per object is output.

-format -- Specifies the format of the output file. Legal values are XML, CSV, and SQL. XML is the default format.
-o -outputFile Name of the output file.
-metadata -- Specifies whether SQL metadata commands are created.

Valid values are "drop" to drop and create the table, and "create" to only create the table.

-tablename -- Specifies the SQL table name used for SQL output; if no name is specified then a name is generated.
-s -sphereUrl The URL of the sphere. For example, http://hostname:port/btmcentral/sphere/

This flag is not required if you have set the AP_SPHERE_URL environment variable for your sphere.

-l -userLogin The username and password associated with the sphere, in the format: username:password. This set of credentials must belong to a user in the btmadmin role.

See Security Options in Accessing CLI Commands for information on furnishing login credentials.

You can encrypt passwords using the encryptPassword command.

Example 1: Retrieving data for containers.

btmcli retrieveObjectData
         -t container
         -s http://myHost:7003/btmcentral/sphere/
         -l my_sphere_username:my_sphere_password
         - my_containers_output.xml

Example 2: Retrieving the average response time for each service for purposes of reporting (note that -intervalSize is specified).

btmcli retrieveObjectData
         -t service
         -s http://my_host:7003/btmcentral/sphere/
          -l my_sphere_username:my_sphere_password
          -attributeNames firendlyName averageResponseTime
          -inTheLast 24h
          -intervalSize 1h
          -format xml
          -o my_avg_response_time_output_for_reporting.xml

Example 3: Retrieving the average response time for each service, endpoint, and operation for purposes of setting baselines (note that -intervalSize is not specified).

btmcli retrieveObjectdata
          -t service endpoint operation
          -s http://my_host:7003/btmcentral/sphere/
          -l my_sphere_username:my_sphere_password
          -attributeNames friendlyName averageResponseTime
          -inTheLast 24h
          -o my_avg_response_time_output_for_baselines.xml