Oracle9iAS Portal Developer Kit (PDK)
An Overview of Event Logging

Introduction

Oracle9iAS Portal can log events that occur during transactions with its objects.  These logs are stored in the database and are available through standard SQL calls and reporting tools. 

You can choose the events you would like to log and organize them categorically based on user-defined domains and sub-domains.  While viewing the logged events, you can view information about the event, the time the event started and stopped, the host/IP address of the remote user, the type of browser being used, and the language used when the event occurred.

Event logging services are available through the wwlog_api & wwlog_api_admin packages.

Key Features

Event logging services in the Oracle9iAS Portal framework provider the user with the following key features.

Log Events

Event logs are useful to users who want to track specific usage of their portal.  To track such information, you need to create a log event.  For log events you need to define its name space.  That name space consists of:

• Name :  Event Name
• Domain :  Area of the product where the event occurred.
• Sub-domain :  Sub-system that generated the event.

The default domains include the Portal (WWC), Application (WWV) and Content Areas (WWS).  Each domain is further classified into sub-domains which define the object types.  The Portal domain includes Portlet, Page, Document object types; the Application domain includes Form, Menu, Report, Chart etc.; and the Content Area domain includes Folder, Item, Category, Perspective etc.  Events themselves could be of the types Add, Delete, Customize, Hide, Copy, Execute, Export etc.  If you need to define a different type of event that does not fall within these domains and sub-domains classification, define your own domain and sub-domains for your events.

Log Usage

The logs can be used to track information in two different ways:

• Interval logging :  Calculate the elapsed time for the action performed.  (e.g. Time taken to render a portlet.)
• Event logging :  Log the occurrence of a single-step event you care about. (e.g. Whenever user customizes a portlet.)

Log Switching

Oracle9iAS Portal allows the user to set a Log Switch interval that defines how long you want to maintain your existing log records.  The log information stored in the database uses two different tables for its purpose.  The log records will be purged based on the value entered for the 'Log Switch Interval' in the Global Settings portlet.  When the log interval (stored in days) has been reached, the logging switches between the two logging tables in the database (let's call them A and B).  Logs first go into A.  When the log interval is reached the first time, the logs are now put into B.  When the log interval is reached again, the logs switch again. A is emptied in preparation to store new log records.  So if you set your log interval to 14 (the default setting), the logs will switch every 14 days, thus preserving for you, at any point of time, records dated between 14 and 28 days old.

How to use Event Logging

The general model for working with event logging can be described as follows:

1. Add the event object, with an appropriate domain and sub-domain combination, using the wwlog_api_admin.add_log_event method.  This ensures that the LOVs and other UI components invoked when the user is monitoring the events, would show this new event in their lists.
2. Register the log event record by using the wwlog_api_admin.add_log_registry method.  The Log Registry record represents the events you want to log in the future and provides a means to filter the events that need to be logged.
3. Use the start_log and stop_log methods to mark the events you want to log in your code.  Alternatively for entering single-step event log information, just call the log method to mark that event.

Tips for using Event Logging

Event logging can be leveraged for your own purposes in different ways.  However to maximize your returns on using logs, keep in mind the following:

Event logging usage hints

• Log only what you really care about to improve performance. You don't want to flood the system with log messages that you don't care about. If events are logged in MODE_SHOW then multiple instances of these portlets will mean additional hits to the database.

• Choose your domain, sub-domain and log events carefully. While using the log APIs, do not use the Portal domains like WWC, WWV or WWS for your log messages. Organize your domains and sub-domains hierarchically ensuring that these are unique across portlets. If other portlets happen to use the same domains or sub-domains, you would see those log messages interspersed with your own.

• Create log events that will show up in the pop-up LOVs while monitoring the logs. You can simply create log registry records that filter the events that would be actually logged, by either specifying particular events or using the generic filters with "%" wild cards. Apart from creating log registry records, it is recommended that you create log events for the events you want to monitor, so that the LOVs in the UI show these records for additional functions like monitoring etc.

• Provide required privileges to users or user groups who need to monitor the logs. Any logs created by a user can be viewed by that user, the Portal Administrator, and any user with the Edit level privilege on the ANY_LOGS object type. 

For further details regarding implementation, refer to Implementing Event Logging.