Setting an Oracle event:The structure of the trace syntax

PURPOSE
-------

The purpose of this article is to explain briefly the structure of the syntax to
event-based trace generation.

Setting an event: The structure of the trace syntax
---------------------------------------------------

@ A comprehensive/full overview of the event syntax can be found in:
@ Note:9331.1 - Full Event Syntax (from ksdp.c)
@ Note:45217.1 - Summary Event Syntax for WWCS

0. "Setting an Event" - Abstract definition:
============================================

   "Setting an event" means to tell oracle to generate information in form of a
   so called trace file in the context of the event.

1. Event Classes to be traced:
==============================

   There are 4 Classes of traceable events:

   Class 1 "Dump something": Traces are generated upon so called unconditioned,
                             immediate, events. This is the case when oracle data has
			     to be dumped like, e.g., the headers of all redolog files
			     or the contents of the controlfile. These events can not
			     be set in the init<SID>.ora.

   Class 2 "Trap on Error" : Setting this class of (error-) events cause oracle to
                             generate a so called errorstack everytime the event happens.

   Class 3 "Change execution path" : Setting such an event will cause oracle to
                             change the execution path for some specific code segment.
			     For example, setting event "10269" prevents SMON from doing
			     free space coalescing.

   Class 4 "Trace something": Events from this class are set to obtain traces that are
                             used for, e.g., sql tuning. A common event is "10046" which
			     will cause oracle to trace  the sql access path on each
			     sql-statement.

II. Event based trace generation syntax - Overview and examples:
================================================================

   1. Session:         alter session set events '10181 trace name context forever, level 1000';
   2. init<sid>.ora:   event="10181 trace name context forever, level 1000";

   -------------------------------------------------------------------------------------------
  | TRACE      |                        TRACE SYNTAX                                          |
  | CLASS      |                                                                              |
  |-------------------------------------------------------------------------------------------|
  |            | <event name> |                     <action>                                  |
  |-------------------------------------------------------------------------------------------|
  |            |              | <action key word> | "name" | <trace name> | <trace qualifier> |
   -------------------------------------------------------------------------------------------|
  |            |              |                   |        |              |                   |
  |            |  immediate   |   trace           | "name" | blockdump    |    level 67110390 |
  |            |  immediate   |   trace           | "name" | redohdr      |    level 10       |
  |            |  immediate   |   trace           | "name" | file_hdrs    |    level 10       |
  | "Dump      |  immediate   |   trace           | "name" | controlf     |    level 10       |
  | Something" |  immediate   |   trace           | "name" | systemstate  |    level 10       |
  |            |              |                   |        |              |                   |
  |-------------------------------------------------------------------------------------------
  |            |              |                   |        |              |                   |
  |            |        942   |   trace           | "name" | errorstack   |    forever        |
  |            |        942   |   trace           | "name" | errorstack   |    off            |
  | "Trap      |         60   |   trace           | "name" | errorstack   |    level 1        |
  | on         |       6501   |   trace           | "name" | processstate |    level 10       |
  | Error"     |       4030   |   trace           | "name" | heapdump     |    level 2        |
  |            |              |                   |        |              |                   |
  |-------------------------------------------------------------------------------------------
  |            |              |                   |        |              |                   |
  | "Change    |      10269   |   trace           | "name" | context      | forever, level 10 |
  | Execution  |              |                   |        |              |                   |
  | path"      |              |                   |        |              |                   |
  |            |              |                   |        |              |                   |
  |-------------------------------------------------------------------------------------------
  |            |              |                   |        |              |                   |
  |            |      10046   |   trace           | "name" | context      | forever, level 12 |
  | "Trace     |      10046   |   trace           | "name" | context      | off               |
  | something" |              |                   |        |              |                   |
  |            |              |                   |        |              |                   |
   -------------------------------------------------------------------------------------------

III: Trace syntax: Annotations
===============================

   0. There are tools like oradebug that allow for setting an event in another
      session; this is useful, e.g., for tracing the export utility.
      @Setting Events from Oracle Tools <Note:45219.1">
      @For a list of common ACTIONS see <Event:List>
      @For COMMON numeric events see    <event:Numeric>
   1. The general syntax of setting an event is:  <event name>  <action>
      <action> consists of three parts:           <action key word> <trace name> <trace qualifier>
      @<action key word> can be either "trace", "crash", or "debug".
      @ See <Note:9331.1">
      <event name> is either "immediate", by this indicating an unconditioned event
      or an event name given as a symbolic number from the system event name table.
      An unconditioned event (keyword "immediate") cannot be set in the parameter file.
      <trace qualifier> "forever" means: Activate a trace whenever this event occurs.
      <trace name> "context" is a special trace name and pertains only to events set up
      to either trace a diagnostic event or to change the behaviour of the oracle
      code execution path. It cannot be used in conjunction with errorstack- ("errorstack")
      or dump-generating ("immediate") events.
   2. There are exactly 2 types of events, session-events and process-events.
      Process-events are initialized in the parameter file, session-events
      are initialized with the "alter session..." or "alter system ..."command.
      When checking for posted events, the oracle server first checks for session events
      then for process-events.

RELATED DOCUMENTS
-----------------
@     Event Syntax for most common forms of event setting <Note:45217.1>
@     The FULL Event syntax <Note:9331.1>
@     Setting Events from Oracle Tools <Note:45219.1>
@     List of common ACTIONS <Event:List>
@     COMMON numeric events <Event:Numeric>