Release 1.4.0
A53697_01
 Library |
 Product |
 Contents |
 Index |
| Oracle
Enterprise Manager Oracle Trace Developer's Guide Release 1.4.0 A53697_01 |
|
Once you have decided that you want to instrument your product, that is, embed Oracle Trace API calls in your product, follow the steps outlined here and described in the following sections:
The most important step in using Oracle Trace in your products is designing the data you want to retrieve from your application. You want to make sure the information is useful.
Consider why you are using Oracle Trace. What do you want to know about your application? If you want to examine performance, you will need certain information. If you want to know how many people use a particular function, you will need a different set of data.
What operations are significant? You will want to define events to represent these operations. For example, the way a database processes a SQL statement has a major impact on performance, so the Oracle Server product definition includes parse, execute, and fetch events.
For system applications, events tend to be the services those applications provide. If you have a message queueing application, placing a message on a queue would be a significant operation. For business applications, events tend to be business transactions. For the Oracle Trace ATM demo application, different types of banking transactions, such as deposit and withdrawal, are events.
For each event, consider what you need to know to determine or interpret its behavior. This includes not only performance characteristics, but also identifying characteristics. These become the data items for each event.
Oracle Trace automatically associates a timestamp, process ID, and collection ID with every event. In addition, Oracle Trace provides some predefined data items. See Chapter 4, Advanced Topics, for descriptions of these data items.
You might have several reasons to collect data from your application. Database administrators will want one set of data; capacity planners another. As you create events and items, consider how different people will use the information. If different groups want different information about the same event -- for example, one group wants to debug while another wants to examine performance -- list the items they need. If the lists have little overlap, you should probably create separate events for each group.
Once you have defined events and items, you need to examine your data model for usability. In particular, pay attention to identifying specific events and connecting them to related events. Suppose you have an event that represents a user session. Within a session, several other events take place. If you want to be able to examine all the events for a particular session, you will need to record information about the session in each subordinate event. If you have a data item that uniquely identifies a session, you can include this data item in other events. Using the session ID as a connection, you can then locate all the events generated within a session. In the formatted database you will be able to perform joins across event tables to make meaningful queries.
To create the product definition file (.fdf), use the Oracle Trace Manager application in the Oracle Trace Manager Performance Pack. See Chapter 5, Creating Product Definitions, for information on using the Oracle Trace Manager.
When you have finished creating the product definition file, make sure you document its contents. Users need to know what information is being collected so they can make use of it. For each item, provide a description and data type. For each event, provide a description, associated items, and relationship to other events.
Once you have defined the items and events, you can add the Oracle Trace API calls to your application to collect the data. For historical reasons, all Oracle Trace routines have the prefix epc, which stands for Event Performance Collector.
A number of parameters appear in almost every Oracle Trace call:
The version of the Oracle Trace API being used. Because parameters might change between versions, this lets Oracle Trace support multiple versions of the API.
The unique identifier for the vendor or application developer, based on the company's Internet address. See Chapter 5, Creating Product Definitions, for an explanation of how to derive the vendor id.
The product number, assigned by the developer.
The product version, assigned by the developer.
The combination of vendor, product, and version should uniquely identify a product definition. The product definition file stores values for each parameter. The values you pass must exactly match what is stored in the product definition file, or the call will return an error.
Most of the examples in this section are from the ATM demo application that ships with Oracle Trace. Several parameters are used for more advanced features or to support the Oracle Server. They are not described in this section. See Chapter 7, "Oracle Trace Routines", for a complete description of Oracle Trace calls and their parameters.
The first Oracle Trace call in an application must be epc_init, which initializes structures and indicates that the process is available to supply data:
epc_init(api_version, vendor, product, version, registration_id, NULL,
&eventflags, max_event, EPC_K_ALLOC, 0, 0, NULL, NULL, epcfctx_ptr);
The optional registration ID is a way to associate a string value with this particular process. For Oracle8 databases, the Oracle SID is passed in the registration_id parameter. Oracle Trace can restrict participation in collections based on this registration ID.
Oracle Trace uses an array of flags to indicate whether each event is being collected. A collection might request a subset of events, called an event set. In that case, you want to make calls only for the events being collected. The eventflags array is a 0-based array of size max_event + 1. Flags 1 through max_event are each allocated to an event.
The application can check the array element at runtime to determine if an event should be logged. Checking the individual array elements avoids unnecessary calls to the Oracle Trace product when the event is not currently specified by an active collection.
Oracle Trace uses eventflags[0] internally to notify the process of state changes. The EPC_K_ALLOC parameter indicates that Oracle Trace should allocate space for the event flags in its own shared memory region and return the address in the eventflags parameter.
The epc_init routine does not cause the collection of data. It indicates that the process could participate in a collection if one were scheduled. No event data can be collected from an application until epc_init has been called. Therefore, you should always call epc_init at the beginning of your application.
To record an event, you need to make a call to the appropriate Oracle Trace routine. Point and duration events use slightly different API calls.
Before making the API call, check the event's flag in the event flag array. If you try to log an event that is not being collected, the call returns an error. If the event has any product-specific items, you need to construct an event record to pass values for those items. The order of items in the event record must match the order of items in the event definition as specified in the product definition file.
| Note:
The following examples are in C. |
For a point event, call epc_event:
if (eventflags[OVERDRAFT]) {
memcpy(orecord, &txn_amt, orecord_size);
status = epc_event(api_version, vendor, product, OVERDRAFT, 0,
orecord, orecord_size, 0, 0, 0, epcfctx_ptr);
}
OVERDRAFT is a constant, the event number of the overdraft event. This is a programming convention that makes it easier to see which event is being collected.
For duration events, the calls are epc_start_event and epc_end_event:
if (eventflags[DEPOSIT]) {
memset(record, 0, record_size);
status = epc_start_event(api_version, vendor, product, DEPOSIT,
&handle, 0, record, record_size, 0, 0, 0, epcfctx_ptr);
}
.
.
.
if (eventflags[DEPOSIT]) {
memcpy(record, &txn_amt, record_size);
status = epc_end_event(api_version, vendor, product, DEPOSIT,
&handle, 0, record, record_size, 0, 0, 0, epcfctx_ptr);
}
Duration events have an extra parameter, the event handle, which Oracle Trace uses to match the start and end of the event. You must pass the same value to epc_end_event that you received from the epc_start_event call. Event handles let you nest duration events; the outer event would have one variable for its event handle and the inner event would have a different variable.
To improve performance, the event routines write data to a buffer rather than to the data collection file. Oracle Trace flushes the buffer automatically when it becomes full, when the collection ends, or when the process terminates. To force a flush of the collection buffers, you can call the epc_flush routine:
status = epc_flush(api_version);
This call flushes data to all collections active for the process.
Oracle Trace provides several ways to start and stop collections, including the otrccol command-line interface and the Oracle Trace Manager application. You can also let your application start and stop collections.
To start a collection, call epc_collect:
status = epc_collect(api_version, vendor, product, version, 0,
collection_name, fdf_file, 0, 0, epcfctx_ptr);
Oracle Trace uses the collection name to generate filenames for the collection definition (.cdf) and data collection (.dat) files. The.fdf file contains the product definition to use for this collection. If you call epc_collect, you can collect data from only one product per collection. However, you can have multiple collections for each product.
The collection scheduled by epc_collect is not recorded in the collect.dat file. Therefore, it is not visible to anyone except the application that scheduled it and can be controlled only by the application.
To stop the collection, call epc_cancel:
status = epc_cancel(api_version, vendor, product, version,
collection_name, 0, epcfctx_ptr);
You can call epc_collect any time after you call epc_init. Consider what scenarios would lead you to start a collection from the application. Also consider what methods you have available to influence your application's behavior. For example, Oracle Server and SQL*Net both use a flag in their INIT.ORA file to turn on a collection. If your application has a menu interface, you might consider adding a menu item that would start a collection. This could be particularly useful for capturing debug information if users report a problem.
Before compiling your application, make sure it contains the following include statement:
#include "$ORACLE_HOME/otrace/public/epc.h" (for UNIX systems) #include "$ORACLE_HOME\otracexx\include\epc.h" (for Windows NT systems)
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, libcore3, and libnlsrt13. These libraries are located in the $ORACLE_HOME/lib directory.
A collection definition includes a list of products and a start time. When you create a collection, you need to pay attention to the volume of data generated, or you could run out of disk space. The volume of data depends on the product definitions, the number of events you collect, and the number of processes contributing data.
You should experiment by scheduling collections for only a few minutes to see how quickly data accumulates. Once you know what kind of volume to expect, you can plan what kind of collections to schedule and how often to run them.
You can also limit the size of the collection definition file through the epc_collect routine, the Oracle Trace command-line interface, and the Oracle Trace Manager.
The data collection (.dat) file is in a binary format, so you need to process the data before you can use it. Oracle Trace lets you load the data into an Oracle database. You can format the data from several collections into the same schema or into different schemas. If you have a long-running collection, you can format the data periodically while the collection is still active. Oracle Trace marks how much of the file has been formatted, to avoid duplication of data in the database.
Determine the schema you will use for the data and verify that you have sufficient space. If you add the number of bytes in the .cdf file to the number of bytes in the .dat file and double the result to allow for overhead, you will have a rough estimate of the space needed.
If you have not formatted data into this schema before, you will need to create the Oracle Trace formatter tables. (See Appendix D, "Oracle Trace Format Database", for descriptions of these tables.) Execute the vobsh command. See the Oracle Enterprise Manager Configuration Guide for more information.
When the formatting operation is complete, you will have one table for each event collected. Oracle Trace generates table names from the information in the product definition:
V_<vendor>_F_<product number>_E_<event number>_<version>
If you have any periods in the version string, they will be converted to underscores in the table name.
You should provide a script that defines synonyms for the tables generated for your product. This will make it easier to locate and use event data.
For point events, the names of the columns in the table are simply the names of the data items associated with that event. For duration events, you have one column for each data item associated with the start event and one column for each data item associated with the end event. The column names have _START and _END appended to the data item name.
The naming convention is also used for the timestamp information that Oracle Trace collects automatically. Because the calculation of time differs from platform to platform, the timestamp is broken into two columns. The TIMESTAMP column is an Oracle date field, accurate to the second. The TIMESTAMP_NANO field contains fractions of seconds. The granularity of TIMESTAMP_NANO depends on the hardware platform. The MS_GRANULARITY column of the EPC_COLLECTION table stores the granularity used for each collection.
All event records include a collection ID and process ID. This allows the use of the same event tables by multiple collections; you can still isolate the records from a specific collection.
Once you format the data, you can use any tool that accesses Oracle databases to analyze the information you have collected. Regardless of the tool, you need to consider what you want to do with the data. What kind of summaries will help you understand application performance? When will it be useful to examine detailed data for each event? You should provide scripts to execute some of the more common queries.
If you have more than a few hundred records in a table, you should define indexes to improve query performance. If you have documented the relationships between your events, you can identify the columns you use to access data most frequently; these are excellent candidates for indexes.
|
 Copyright © 1997 Oracle Corporation. All Rights Reserved. |
|