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

Library Product Contents Index

4
Advanced Topics

This chapter describes more complex Oracle Trace concepts. These include:

• in-depth information about items
• resource items
• cross-product items
• registration IDs
• event sets
• multi-thread support

More About Items

For every event in a product, you can collect specific pieces of information called items. The following sections describe resource items and cross-product items.

Resource Items

Oracle Trace predefines a set of data items called resource utilization items or resource items. These items are for operating system data -- CPU utilization, I/O, and memory resources. Oracle Trace provides values for these items automatically, so they are transparent to the application. If you want to collect resource items for an event, you must explicitly associate the items with the event when you create the product definition. Table 4-1 describes these items.

Table 4-1 Standard Resource Utilization Items

Cross-Product Items

Oracle Trace also provides a set of 14 items called cross-product items. These items can be used to relate events across applications. One application can set the value of a cross-product item to indicate the current execution context and then make a call to another application. The cross-product items can be passed across to the second application and the values logged with its events. This lets you correlate events in one application that were performed on behalf of another.

For example, the ATM demo application sets the first cross-product item to indicate the business transaction being executed, such as a deposit or withdrawal. It then uses SQL statements to manipulate data. These statements are executed by the Oracle Server. Any Oracle Server events that occur on behalf of the ATM transaction have the same value for the first cross-product item. This lets you analyze the Oracle Server information according to the business transaction that generated it.

How Cross-Product Items Work

Oracle Trace allocates an array of 14 cross-product items in process local memory. If two instrumented applications run in the same process context -- like the ATM demo and the client portion of SQL*Net -- then they both have access to that memory. They automatically have the same values for the cross-product items.

If the instrumented applications run in different processes -- like the ATM demo and Oracle Server -- then the cross-product items must be communicated to the remote process. For Oracle Server, SQL*Net sends a special data packet containing cross-product item values. Other applications might require a special call to transfer cross-product item values or pass them as additional parameters on their usual processing calls.

Table 4-2 lists the cross-product items available. (Previous versions of Oracle Trace used 'facility' instead of 'product,' which is why these items are named CROSS-FAC-N.) Some of the cross-product items are reserved by Oracle to be associated with certain products.

Table 4-2 Cross-Product Items

Using Cross-Product Items to Correlate Events

Values for cross-product items are not passed to event calls in event records. Instead, Oracle Trace provides API calls to set and retrieve their values. To set a specific item, call epc_cf_value:

status = epc_cf_value(api_version, 1, DEPOSIT, NULL, NULL);

This example sets the value of the first cross-product item to the value of the constant DEPOSIT, which is the event number of the ATM deposit event. The fourth parameter is an optional context parameter; see "Multi-Thread Support" for more information on context parameters. The last parameter lets you receive the address of the item. This lets you set the item value by referencing the address directly rather than calling epc_cf_value again.

Cross-product values are always numeric. If you want to provide a text translation of the values, you can associate a registration ID with the cross-product value. See "Registration IDs" for more information.

Passing Cross-Product Items to Remote Processes

If you need to communicate cross-product items to another application running in a separate process, you can use API calls, which manipulate the entire array of items. The client-side application retrieves the values of all items with the epc_get_cf_items call:

status = epc_get_cf_items(api_version, item_array, NULL, NULL);

The client then passes these values to the server-side application, which sets the values on its side with the epc_set_cf_items call:

status = epc_set_cf_items(api_version, item_array, NULL);

Registration IDs

Registration IDs are text strings. You can associate a registration ID with a process or with the value of a cross-product item to provide a meaningful comment or description. This makes it easier for users to identify processes or transactions that they are interested in. For Oracle8 database collections, Oracle Trace allows restriction of collected data by registration ID (Oracle SID) through the command-line interface.

Oracle Trace provides two ways to assign a registration ID to a process:

• pass the registration ID as a parameter on the epc_init call
• call epc_add_reg_id without supplying a cross-product item

A process can have multiple registration IDs.

If you use cross-product items, you might find it useful to provide a text translation of the cross-product item value. For example, in the ATM demo application, cross-product item 1 is set to the value 2 for a deposit transaction. (The deposit event has an event number of 2.) The application associates the string "Deposit" with cross-product item 1 for the duration of the deposit transaction. The last parameter (the 1 after regid) states that the current value of cross-product 1 is related to the regid.

strcpy(regid, "Deposit"); 

status = epc_cf_value(api_version, 1, DEPOSIT, NULL, NULL); 

status = epc_add_reg_id(api_version, vendor, product, version,

                        regid, 1); 

.

.

.

<deposit transaction>

.

.

. 

status = epc_remove_reg_id(api_version, vendor, product, version,

                           regid, 1);

See "Using the Oracle Trace Command-Line Interface" for information on restricting data collection using registration IDs.

Event Sets

When you create a product definition, you have the option of defining subsets of events called event sets. Event sets let you tailor collections for specific functions. For example, you might have an event set for performance tuning and another event set for capacity planning. Each event set is written to a separate product definition (.fdf) file. You can collect a particular set of data by specifying the appropriate .fdf file when you start a collection.

Oracle Trace automatically creates the ALL event set which, as the name suggests, includes every event in the product definition. All other event sets must be subsets of the ALL class.

When you define an event set, you choose which events to collect. You also choose which data items to collect, with limitations. You can include or omit any of the event's resource and cross-product items. However, the product-specific items for an event are treated as an indivisible unit; you can have all or none associated with an event in an event set. Parsing the structure of the event record each time you recorded an event would add significant overhead and could affect the performance of the application.

For example, a throughput event set may only be interested in a count of actual events but not any other event data. You could construct an event set with the desired events and no items at all. This reduces the file size and overhead for throughput counts but still gives you the elapsed time information.

Multi-Thread Support

Applications that implement their own threading packages can use Oracle Trace to gather information about each thread of execution. For each thread context switch, the application calls an Oracle Trace API routine. At this point, Oracle Trace takes a snapshot of resource utilization. For each event collected, the application passes a thread context variable. The resources used by these events are calculated on a per-thread basis, rather than a per-process basis. At the conclusion of the thread execution, the application makes another Oracle Trace API call, which deletes the thread context.

The typical implementation of multi-threading has each thread allocate a local thread context block, to carry information pertaining to that thread. The application has an additional field in this thread context block for the Oracle Trace thread context variable:

struct {

.

.

.

int32 trace_thread_ctx;
.

.

.

} thread_context_block;

The first time a thread executes, call epc_context with trace_thread_ctx set to 0:

status = epc_context(api_version, &current.trace_thread_ctx);

Oracle Trace supplies a thread context; you can then pass this context on event routines:

status = epc_event(api_version, vendor, product, event_id,

                   current.trace_thread_ctx, &event_rec,

                   rec_size, 0, NULL, NULL, epcfctx_ptr);

When you switch to a new thread, call epc_context to establish a new thread context in Oracle Trace. When you switch to the first thread again, you call epc_context with the existing value, assigned by the first epc_context call. This tells Oracle Trace you have resumed execution.

At the end of thread execution, call epc_delete_context:

status = epc_delete_context(api_version, &current.trace_thread_ctx);

This removes all the per-thread context information. Oracle Trace zeroes out the thread context parameter. If you later pass that parameter on an epc_context call, Oracle Trace will assume you are starting a new thread.

Prev Next

Copyright © 1997 Oracle Corporation. All Rights Reserved.

Library Product Contents Index