Oracle Enterprise Manager Oracle Trace User's Guide

Library

Product

Contents

Index

Instrumentation Guidelines

Know Why You Are Instrumenting
Know How Oracle Trace Interacts with an Application
Required Oracle Trace Routines
Decide What You Want to Know About Each Event
Compiling Your Instrumented Application
Create a Definition File for Your Product
Performance Impact of Instrumentation
Instrumenting a Multi-Threaded Application

This chapter provides general guidelines for instrumenting your application with Oracle Trace routines. The following topics are covered:

establishing your reasons for instrumenting
how Oracle Trace interacts with an application
required Oracle Trace routines
deciding what you want to know about each event in your application
compiling an instrumented application
creating a product definition
the impact on your application's performance when you add calls to Oracle Trace routines
instrumenting a multi-threaded application

For a complete description of Oracle Trace routines, refer to Chapter 8, Oracle Trace Routines. Refer to Appendix D, Sample Instrumented Application, for an example of an instrumented application.

Know Why You Are Instrumenting

When you instrument your application, you must clearly understand your purpose and goals for using Oracle Trace. You must be sure of what you want to know about your application as it runs. This means knowing your application well and taking a close look at how it works before you instrument. For example:

If you want to know how long it takes to perform business functions x, y, and z, you must first identify when and where in your application they start and end.
If you want to know how long database requests take and what portion of the application is actually spent in the database system, you must first identify the origin of the requests.
If you want to know why response time is poor, you must know which routines prompt for and display data to the user.

If you do not carefully analyze the type of information you need about your application, your instrumentation may not yield the most useful data to you.

Usually when an application is instrumented, the focus is on business-level and functional-level events. An example of a business-level event is individual transactions such as making, changing, canceling, and confirming reservations in an airline reservations application. An example of a functional-level event is a routine that reads and writes information to and from a disk.

Once you decide exactly what you want to know about your application as it runs, you can instrument it by adding calls to Oracle Trace routines that log the events and items you want to collect.

For a complete description of Oracle Trace routines, refer to Chapter 8, Oracle Trace Routines.

Know How Oracle Trace Interacts with an Application

To instrument effectively, you should understand how Oracle Trace will ultimately interact with the instrumented application. To better and more fully understand this, you need to know the definitions for a few terms as they pertain to Oracle Trace.

An application that contains calls to Oracle Trace routines is called a product.

A product definition file (.fdf) is a description of all the events and items that can be collected for a product. Items are more detailed pieces of information about an event. There can be many items for each event. For example, if the event is a Transaction, there could be items for the number of physical_reads or consistent_gets associated with the transaction.

Subsets of events and items for a product can be grouped into event sets. Event sets are important because they allow collections to be limited to only the information needed. Also, the use of event sets can reduce the performance impact of data collection on an application because time and resources are not spent collecting unnecessary data.

Oracle Trace allows data collection to be turned on and off dynamically, collecting data for only the events and items specified in the event set. This allows the instrumenter to place a wide range of event points in the application, enabling data collection to solve a variety of tuning and debugging needs.

Events are grouped into event sets because of their significance to certain functions or certain levels of analysis. For example, you might have an event set of data for performance purposes and another event set for debugging purposes.

The default event set is ALLCLASS, which contains all the events and items available for collection. You can create as many other event sets as you need, of any size. An event set can be as small as to contain only one event.

Every product for which you want to collect data must have a product definition file. This is because when Oracle Trace interacts with a product and collects data for it, Oracle Trace requires the name of the product definition file. Oracle Trace uses the file to determine which events and items to collect data from during a collection. You cannot collect data for a product that does not have an associated product definition file.

For more information about creating product definitions, refer to Chapter 7, Creating Product Definitions.

Required Oracle Trace Routines

Every product must contain a call to the epc_init routine to register with Oracle Trace. The call must precede any other calls to Oracle Trace and should be done early in the application's execution. No event data can be collected from a product until the epc_init routine has been called.

There are two types of events: duration events and point events. Duration events have logical start and end points. A transaction is a typical duration event. Point events occur instantaneously. The epc_event routine is for point events. For example, if you have an error, you could call the epc_event routine to record an error event.

At the starting point of each duration event, as determined by your analysis of the application, place a call to the epc_start_event routine. At the end of the event, place a matching call to the epc_end_event routine. For example, if your application produces its own forms and you want to track response time per user, call the epc_start_event routine, passing the form name as part of the event record, at the point where the user requests information from the application. At the point where the application returns to display the information, make the matching call to the epc_end_event routine.

Decide What You Want to Know About Each Event

For every event in a product, you can collect specific pieces of information called items. You need to decide which items you want to collect for each event. An item belongs to one of the following three categories:

standard resource utilization¯a set of items that Oracle Trace collects by default, but which you can choose not to collect. Table 5-1 describes these items.
cross-product¯a set of items used to relate events among instrumented products. Cross-product items are useful to identify resource usage in multi-tiered applications. Table 6-1 describes the cross-product items.
product-specific¯a set of items that you define specifically for your application.

Note:

For every event, Oracle Trace always collects elapsed time information, the process identification number (PID), and the product that logged the event. This is because Oracle Trace stamps each data record with the current date and time, the PID, the product number, and the event identifier.

Table 5-1: Standard Resource Utilization Items
Item Name	Item ID	Description	Datatype	Usage
UCPU	129	Amount of CPU time in user mode	4-byte integer	Counter
SCPU	130	Amount of CPU time in system mode	4-byte integer	Counter
INPUT_IO	131	Number of times file system performed input	4-byte integer	Counter
OUTPUT_IO	132	Number of times file system performed output	4-byte integer	Counter
PAGEFAULTS	133	Number of hard and soft page faults	4-byte integer	Counter
PAGEFAULT_IO	134	Number of hard page faults	4-byte integer	Counter
MAXRS_SIZE	135	Maximum resident set size used	4-byte integer	Counter

Compiling Your Instrumented Application

Before compiling your application, make sure it contains the following include statement:

#include "$ORACLE_HOME/otrace/public/epc.h"

Your instrumented application should be compiled using the appropriate commands for your operating system's C compiler. Also, the application must be linked against the following libraries: libepc, libepcpt, libcore3, and libnlsrt13. These libraries are located in the ORACLE_HOME directory.

Create a Definition File for Your Product

Before you can collect data for your product, you must create a product definition file. This file defines all the events, items, and event sets for a product. Oracle Trace uses the product definition to match collected data with the appropriate event, so it is important that the product definition file be complete and accurate.

For more information about creating product definitions, refer to Chapter 7, Creating Product Definitions.

Performance Impact of Instrumentation

To minimize the impact of data collection on an application's performance, Oracle Trace buffers data before writing it to disk. Oracle Trace writes the contents of these buffers out to a data file under the following circumstances:

The buffer becomes full.
The application performs a normal exit.
The application terminates abnormally, for example, when producing a bugcheck.
The collection is stopped using the Collection=>Stop option in the Oracle Trace main window.
The end of the collection is reached.
A call is made to the epc_flush routine.

Warning:

If the UNIX command, kill -9, is used to stop a process, data in the collection buffer is lost.

Instrumenting a Multi-Threaded Application

A multi-threaded application is instrumented in the same way as a single-threaded application. However, Oracle Trace provides two routines for collecting resource utilization and cross-product items on a per-thread basis. These routines are epc_context and epc_delete_context.

For a complete description of Oracle Trace routines, refer to Chapter 8, Oracle Trace Routines.

Prev Next

Library

Product

Contents

Index

Instrumentation Guidelines

Note:

Table 5-1: Standard Resource Utilization Items

Warning: