Oracle Enterprise Manager Oracle Trace Developer's Guide
Release 1.4.0
A53697_01

Library

Product

Contents

Index

2
Oracle Trace Architecture

The primary goal of the Oracle Trace architecture is to collect event-driven data with minimum overhead. This chapter describes:

Oracle Trace Concepts

The following terms are the building blocks of Oracle Trace concepts:

product definition
event
item
event set
collection
process

The following sections describe these terms.

Product Definition

A product definition is a set of events and their associated data items. A product definition describes the information that Oracle Trace can collect from a software product. Defining the proper set of information to collect is the most important part of using Oracle Trace in your product.

To create a product definition, run the Oracle Trace Manager application in Administrative mode. This enables the Create Product menu option. When you have completed the product definition, the Oracle Trace Manager writes the product definition to the product definition file, which has a file extension of .fdf for historical reasons. See Chapter 5, Creating Product Definitions, for more information on creating product definitions.

Event

An event is the occurrence of some significant activity within a product. You define events in the product definition and then instrument your product with Oracle Trace API calls to collect information about those events.

There are two types of events:

point events

Represent an instantaneous occurrence of an event. An example of a point event is an error condition.

duration events

Have a beginning and an end. An example of a duration event is a database transaction.

Duration events allow you to track their time span and the resources consumed between the beginning and the end of the duration event. For example, you can have several file I/Os and an error condition during a database transaction.

Item

Items are specific pieces of information about an event. When you create a product definition, you associate items with events. Oracle Trace groups items into the following categories:

Product-specific items

Data items specific to the product. You define these items in the product definition. The product supplies values for these items by passing a parameter on the Oracle Trace API calls. See "Recording Events" for more information.

Resource items

Operating-system performance data related to CPU, I/O, and memory usage, predefined by Oracle Trace. Oracle Trace supplies values for these items. See Chapter 4, Advanced Topics, for more information.

Cross-product items

Application context information, predefined by Oracle Trace. You supply values for these items using special Oracle Trace API calls. See Chapter 4, Advanced Topics, for more information.

Oracle Trace automatically collects a timestamp and process ID for each event, so you do not need to define items for this information.

Event Set

When you create a product definition, you can also define subsets of the definition called event sets. An event set is a logical subgroup of events that can encapsulate a particular tracing category. Each event set is written to its own product definition file (.fdf). See Chapter 4, Advanced Topics, for more information about event sets.

Collection

A collection encompasses the description of data to gather, the activity of gathering data, and the resulting set of data. The steps for a collection are:

Define a collection by listing a product definition file (.fdf) for each software product you are interested in.
Run the collection and gather data from those products you listed. The collection creates two output files:

collection definition file (.cdf)

Includes the collection definition and a list of participating processes.

data collection file (.dat)

Includes the event records generated by the participating processes.

You can have multiple collections running at the same time on the same system. Oracle Trace maintains a list of collections for each system.

Process

Oracle Trace is interested in processes that are running products instrumented with Oracle Trace API calls. These processes can contribute data to collections, but they generate data only when a collection is running. Oracle Trace maintains a list for each system of processes that can participate in collections.

Oracle Trace Runtime Behavior

When you start a collection, Oracle Trace and the participating processes work in concert to gather the desired data. This work consists of the following stages:

initialization
starting a collection
collecting data
ending a collection
formatting collected data

Figure 2-1 shows the behavior.

Figure 2-1 Oracle Trace Behavior

Initialization

The first Oracle Trace routine called by an instrumented product is epc_init. When the process runs the product, epc_init records that the process is available to participate in collections for that product. If a process invokes more than one product, each epc_init call makes the process available for the collections involving the corresponding product.

The epc_init routine also provides an array of event flags, one flag per event in the product definition and one extra flag reserved to Oracle Trace. The event flags indicate that a collection has started or stopped, as well as which events should be collected. The product should make the API call to log an event only if the corresponding event flag for the event is set.

Once epc_init prepares the process to participate in collections, it checks to see if any collections for this product are currently running. If so, it sets the event flags array and the process begins collecting data.

Starting a Collection

Oracle Trace creates the collection definition file and appends the product definition file(s) to the collection definition file. This provides a stable definition of the events and items. At this time, Oracle Trace determines the settings for the event flags for each product. If you have passed in an event set, instead of a full product definition, only the subset of events in the event set will be collected.

Finally, Oracle Trace scans the list of available processes, locates the ones that should participate in the collection, and sets their event flags. Oracle Trace uses the first element of the event flags array as an internal communication mechanism. Once notified, each process writes a record in the collection definition file to register its participation in the collection.

Collecting Data

The product should first check the corresponding event flag before logging an event. If you try to log an event that is not being collected, the Oracle Trace API returns an error.

To improve collection performance, Oracle Trace buffers event data. The event records are flushed to disk when the buffer is full.

Ending a Collection

When a collection ends, Oracle Trace updates the list of collections on the system. Oracle Trace then uses the event flags array to notify participating processes that the collection has stopped. If a process is participating in any other collections, Oracle Trace resets the event flags appropriately for the remaining collections.

Formatting Collected Data

The Oracle Trace API does not include a call for formatting data. You can use the command-line interface, the Oracle Trace Manager, or the Oracle Trace formatter utility to format data to an Oracle database.

The formatter first reads the collection definition file to get information about the collection. This information is then stored in the following formatter database tables:

epc_collection

Describes the collection.

epc_process

Lists the processes that participated in the collection.

epc_facility

Lists the products that contributed event data (previous versions of Oracle Trace used the word 'facility' for 'product').

epc_event

Lists events collected for products.

epc_item

Lists items collected for products.

epc_event_item

Indicates which items are associated with which events.

epc_facility_registration

Lists any registration IDs associated with processes in the collection.

See Appendix D, Oracle Trace Format Database, for complete descriptions of these tables.

Using information in the epc_event, epc_item, and epc_event_item tables, the formatter generates a table definition for each event. If the table already exists from a previous formatting operation, it is not created again; the formatter simply uses the existing table.

Finally, the formatter reads the data collection file for event records, storing event data in the corresponding database table.

Using the Oracle Trace Command-Line Interface

You can use the Oracle Trace command-line interface (CLI) to manage collections. The CLI is invoked by the otrccol command for the following functions:

otrccol start <job_id> <input_parameter_file>
otrccol stop <job_id> <input_parameter_file>
otrccol format <input_parameter_file>
otrccol dcf <coll_name> <cdf_file>
otrccol dfd <coll_name> <username> <password > <service>

The job_id can be any numeric value and must be unique. The input parameter file contains specific parameter values required for each function. The coll_name (collection name) and cdf_file (collection definition file) are initially defined in the start function input parameter file.

Note:

For Oracle Server 7.3 and earlier, the CLI collects event data for all server sessions attached to the database at collection start time. Sessions that attach after the collection is started are excluded from the collection.

Starting a Collection

The otrccol start command invokes a collection based upon parameter values contained in the input parameter file. For example:

otrccol  start  1234  my_start_input_file

where my_start_input_file contains the following input parameters:

col_name= my_collection

dat_file= <usually same as collection name>.dat

cdf_file= <usually same as collection name>.cdf

fdf_file= <event set>.fdf

regid= <flag> <vendor> <cfnum> <cfval> <fac#> <regid_str>

The server event sets that can be used as values for the fdf_file include oracle (all event set), oracled (default event set), and oraclee (Oracle Expert event set). See the Oracle Enterprise Manager Oracle Trace User's Guide for more information on the server event sets.

The values that must be used for the regid input parameter are:

flag
vendor ID (vendor)
cross-product number (cfnum)
cross-product value (cfval)
product number (fac#)
regid_str, type the service name (for Oracle Server release 7.3.3) or the SID (for Oracle Server release 8.0 and higher) for the database.

An example of collecting information from the server would be:

regid= 1 192216243 0 0 5 mydb.world

Stopping a Collection

The otrccol stop command halts a running collection, as follows:

otrccol stop 1234 my_stop_input_file

where my_stop_input_file contains the collection name and cdf_file name, or the same file as was used to start the collection.

Formatting Collection Files

The otrccol format command formats the binary collection file to tables in the Oracle database. An example of the format command is as follows:

        otrccol format my_format_input_file

where my_format_input_file contains the following input parameters:

username= <database username>

password= <database password>

service= <database service name>

cdf_file= <usually same as collection name>.cdf

full_format= <0/1>

A full_format value of 1 produces a full format. A value of 0 produces a partial format. See the Oracle Enterprise Manager Oracle Trace User's Guide for information on formatting part or all of an Oracle Trace collection, and other important information on creating the Oracle Trace formatting tables prior to issuing the format command.

Deleting Collection Files

Use the otrccol dcf command to delete collection files (collection definition file and data collection file) for a specific collection. For example:

otrccol dcf <coll_name> <cdf_file>

where the input parameters are:

coll_name= <collection name>cdf_file= <collection definition file>

Deleting Formatted Data

Use the otrccol dfd command to delete formatted data from the Oracle Trace formatter tables for a specific collection. An example of this command is as follows:

        otrccol dfd <coll_name> <username> <password> <service> [col_id]

where the input parameters are:

coll_name= <collection name>

username= <database username>

password= <database password>

service= <database service name>

col_id= <optional collection identifier of the formatted data>

Note:

You can have more than one collection identifier for a collection name. If you do not specify col_id, all the formatted data for that collection is deleted.