Administration Guide
|
 |
 |
|
 |
 |
This chapter describes the auditing framework, performance profiling, and logging capabilities provided with the AquaLogic Data Services Platform (DSP). It contains the following sections:
For information on data service monitoring, see Monitoring Applications.
The auditing framework system is used to collect auxiliary runtime data using a normal XQuery operation in a DSP application. This information may be used for security auditing, performance profiling and other purposes.
The data structure comprises a sequence of audit records containing an unordered collection of audit properties. Each audit record contains properties of a specific type, usually identified using a hierarchal name. Each audit record corresponds to an operation performed by DSP. For example, access to a relational data source may generate a record of "evaluation/wrappers/relational" type that includes the following audit properties: sql, datasource, returnedRows, evaluationTime, parameters, message, and exception.
Any individual property may be configured to be collected. Each property has an individual intrinsic severity level that can be used to configure an overall threshold of what properties to collect. In certain cases, like when an exception occurs, some properties may be added to the record even if they are not configured to be collected. Typically, this information would be identifiers for a failed data source or update operation.
On the other hand, a property configured for collection need not necessarily be collected. This might be attributed to any one of the following reasons:
Elements of the data structure collected can be individually configured to be:
Note: Auditing occurs whenever the engine is invoked and the Auditing option is enabled. Timestamps and other collected data enable you to match auditing information with particular query operations.
Use the DSP Console to configure application audits such as setting the global audit severity level and overriding audit settings for particular properties of interest.
The Auditing Tab (Figure 9-1) opens a page where you can select properties to be included in the DSP XQuery engine analysis, update, deployment, and re-configuration event audits. Auditing can be enabled or disabled for individual aspects of a query such as parameters or exceptions. There are also some global auditing options that inherently apply to every aspect of the auditing process.
Note: By default, the audit report generation utility is turned off. Before you begin generating reports for the first time, you need to specify the audit settings described in the subsequent sections. With auditing enabled, performance may be affected, depending on the audit levels and the number of properties being audited.
Table 9-1 describes available global auditing options. Click the respective check box in the DSP Console to select and implement the desired audit options.
|
Determines whether the auditing is activated or not. Note: When auditing is enabled, performance can be affected to a degree, depending on the audit level and the number of items being tracked. |
|
|
Determines whether the auditing is activated or not, during a query evaluation. |
|
|
Determines whether the auditing is activated or not during administrative operations such as application deployment and configuration changes. |
|
|
Determines whether auditing is activated or not during update operations. |
|
|
Determines the level of information to be captured by the auditing process. See Auditing Severity Levels section for more information. |
|
|
Determines whether the events are processed synchronously or asynchronously. |
|
|
Determines whether the auditing information is to be included in the application server log file. Note: If you enable this option (logging), ensure that the Log Level value in the General tab is set to either Info or Debug. Any other value will result in the log file not accepting any information. |
This section helps you determine which properties you want to audit and to what level. You can propagate generic audit settings through the Configure all Properties row, details of which are listed in Table 9-2. Or, you can set the audit settings at the individual properties level, details of which are shown in Table 9-1.
|
Click this checkbox to ensure the property-specific audit information is returned to the client API. |
|
|
This drop-down list has three options, which are generic to all the properties. The options are At Default Level, Always, and Never. By selecting At Default Level, levels of all the individual properties will be set to pre-determined default levels. See Table 9-1 for more information on each level. |
Note: After you set and apply individual auditing property settings, any changes you make on the individual properties will override the initial settings for that property only.
Table 9-1 lists the audit levels that you can set on each individual property. All levels listed in the table are not applicable to all the properties. Typically, each property has only three levels to choose from.
All the individual properties are categorized into four overall types (Admin, Common, Query and Update), depending on the corresponding operation that generates the audit data.
The audit information in this section pertains to the information exchanged while performing administration tasks such as configuration and application deployment. Only changes to the application made in the DSP Console are collected during audit.
The audit information in this section pertains to the generic transaction related information. It includes generic information on the event, such as: event type, application name, user id, user access rights, date, and time.
The audit information in this section pertains to all the information collected during query evaluation. The information includes the query itself, its result, the execution time, and details on the data source queried.
Note: When using the streaming APIs, or when using the RequestConfig.OUTPUT_FILENAME feature, the results of the query are not audited since they are presumed to be very large. This means the AuditEvent dispatched to the audit provider, as well as the DataServiceAudit returned to the client, will not contain a value for the audit property Query/Service/results.
|
Records the external parameters or variables passed to the query. |
|
|
Boolean value where |
|
|
Indicates the time remaining, in seconds, before the query cache is refreshed. |
|
|
Indicates whether the data was obtained from the query cache or not. |
|
|
Note: Queryplan audit properties are not collected when a function is executed from Test View in Workshop. This is because the function cache is not utilized for functions executed in Test View. |
|
|
Indicates whether the query plan cache has been located or not. |
|
|
Indicates whether the query plan cache has been inserted or not. |
|
|
In the event of a failover, this records the exception that caused it. |
|
|
Records the function name which can be either
|
|
|
Records the source column of the function call. For example: |
|
|
Records the time-out that was exceeded, if applicable. For example: |
|
|
Note: Function audit properties are collected only when the individual functions of a data service are selected for auditing. See Auditing Functions for more information. |
|
|
Records the parameters passed through the audited function. For example: |
|
|
Records the result after executing the audited function. For example: |
|
|
Records the query compilation time, in milliseconds. For example: |
|
|
Records the query evaluation time, in milliseconds. For example: |
|
|
Records the parameters passed through the query, for example: |
|
|
Records the complete text of the executed query on the data service, for example:
|
|
|
Records an exception, if any, when a function invoked belongs to a data service created over a File data source. For example:
|
|
|
Records the time taken to query, in milliseconds. For example: |
|
|
Records an exception, if any, when a function invoked belongs to a data service created over a Java class. For example:
|
|
|
Records the name of the service. It is always recorded if an exception property was added. For example:
|
|
|
Records the external parameters passed to the service. For example: |
|
|
Records the time taken to execute the query, in milliseconds. For example: |
|
|
Records an exception, if any, when a function invoked belongs to a data service created over a stored procedure. For example:
|
|
|
Records the procedure identifier. It is always recorded if an exception property was added. For example: |
|
|
Records the external parameters passed to the data service method. For example: |
|
|
Records the number of rows returned after execution of the procedure, for example: |
|
|
Records the time taken to execute the procedure, in milliseconds. For example: |
|
|
Records the relational database query exception, if any. For example:
|
|
|
Records the external parameters passed through to the data service method, for example: |
|
|
Records the number of rows returned from the relational database, for example: |
|
|
Records the database source name. It is always recorded if an exception property was added. For example: |
|
|
Records the SQL statement used for the query, for example:
|
|
|
Records the time spent executing the query, in milliseconds. For example: |
|
|
Records an exception, if any, when a function invoked belongs to a data service created over a web service. For example:
|
|
|
Records the data service method that is executed. For example: |
|
|
Records the parameters passed through to the data service method. For example:
|
|
|
Records the result returned after the query is executed. For example:
|
|
|
Records the time spent executing the query, in milliseconds. For example: |
|
By default, auditing for all directly invoked functions can be enabled through the /query/service record in the application Audit tab. However, to limit auditing to specific functions, set all properties of the /query/service record to NEVER and then enable audit for individual functions by selecting the Enable Audit check box as shown below.
If auditing for a function is enabled, all external calls to this function are audited. If the Enable Audit of Indirect Calls check box is selected, all calls originating from other data services are also audited.
Note: Enabling audit of indirect calls may disable query optimization for that function, and decrease performance.
The audit information in this section pertains to all the information related to performing an update function. It includes information on the time taken to update the source, when it was started, the unique transaction id and so on.
|
Every audit property is set to one of the following audit levels: |
|
|
Determines if a particular property may be returned to the client application. |
|
Severity levels are similar to those provided with WebLogic Server security. For WebLogic Server details, see "Message Severity" section in:
http://download.oracle.com/docs/cd/E13222_01/wls/docs81/ConsoleHelp/logging.html#1037756
You can record the audit information collected in the following ways.
Values of the audit properties are represented as Java objects of types: String, Integer, java.util.Date, Boolean, or String [].
Each audit event is sent to the WebLogic Server Security Framework as an instance of the weblogic.security.spi.AuditEvent interface, where:
Depending on the configuration, each event can be sent to the WebLogic Server audit API asynchronously and buffered by the DSP application.
The weblogic.security.spi.AuditEvent interface is implemented in the ld.server.audit.DSPAuditEvent interface, which collects all the information in the form of a list, where each entry is an instance of com.bea.dsp.DSPAuditEvent.
DSPAuditEvent adds the following interface:
com.bea.ld.DSPAuditRecord has the following API:
|
Returns the type of record, for example common/time/duration. |
|
|
Returns all properties in the record. Maps from String identifier to Object value. |
A sample security services audit provider is included that demonstrates use of this API.
You can use the com.bea.ld.DataServiceAudit client side instance as part of the com.bea.dsp.RequestConfig class, to collect the audit information from the client API. This class collects the audit information and returns it when the operation is successful. If the operation fails for any reason, the com.bea.ld.QueryException class can be used to collect the information as part of the exception thrown.
Note: When using Streaming APIs, auditing will not be complete until the returned XMLInputStream has its close( ) method called. This means that the AuditEvent will not be dispatched to the audit provider by the server, and the RequestConfig.getDataServiceAudit() method will return null, until close( ) is called.
Following are the four steps, with code examples, that need to be performed in order to retrieve audit information.
You need to initialize the RequestConfig class as shown in the code example below:
RequestConfig requestCfg = new RequestConfig();
requestCfg.enableFeature(RequestConfig.RETURN_DATA_SERVICE_AUDIT);
requestCfg.enableFeature(RequestConfig.RETURN_AUDIT_PROPERTIES);
requestCfg.setStringArrayAttribute(RequestConfig.RETURN_AUDIT_PROPERTIES, new String[]
{"query/service/dataservice"});
You need to pass the RequestConfig object to the invoked operation. The code example below uses getCustomer as the invoked operation.
CUSTOMERDocument [] custDocRoot1 = (CUSTOMERDocument [])custDS.invoke("getCustomer", params, requestCfg);
You need to filter the data and ensure there is no unsecured access to it. Only those audit properties that are configured in the Data Services Platform Console to be allowed to return to the client, will be returned to the client application.
You need to retrieve the data service audit from the RequestConfig object, as shown in the code example below:
DataServiceAudit query = requestCfg.retrieveDataServiceAudit();
RequestConfig.RETURN_AUDIT_PROPERTIES is an array of string identifiers for audit properties. If you set this request attribute those specified properties will be collected for this particular evaluation even if they are not configured to be collected through the administration console. They will be returned only if it is allowed. If the RETURN_DATA_SERVICE_AUDIT request attribute is not enabled, only those properties will be returned.
RequestConfig.RETURN_DATA_SERVICE_AUDIT configures all collected audit information (that is allowed to be returned to the client application) to be returned.
Performance profiling allows you to store select audit information in a relational database. Relational databases supported by the DSP audit provider are: Oracle, DB2, PointBase, Sybase, and MS SQL.
Information about audit events are stored as records in a table. A table can be used to record audit events for DSP applications running on a server, or for applications running on shared servers in a cluster.
You can deploy the DSP audit provider for performance profiling using the WebLogic Administration Console and configure it using the DSPProfiler MBean. Configuration parameters you need to set at the time of deployment are described in Table 9-9.
This section lists the steps needed to create a performance profiler.
common/time/timestamp query/service/function query/performance/evaltime common/application/user common/application/name common/application/server A DSP audit provider sample file profiler.zip, is available in the DSP root installation directory. The zip file contains the following files:
README.txt lists steps to use the sample audit provider). dsp_profile.sql files - Contains table definitions. build.xml - Defines build configurations. DSPProfilerMBean.xml - MBean definition file for the DSP profiling auditor. DSPProfilerImpl.java - Sample java code that implements the weblogic.security.spi.AuditProvider and weblogic.security.spi.AuditChannel interfaces.
Server log files contain information about the time spent to compile and execute a query. The log is in the following location:
<BeaHome>\user_projects\domains\<domainName>\<serverName>\<server>.log
For more information about WebLogic Server logs, see "Viewing the WebLogic Server Logs" at:
http://download.oracle.com/docs/cd/E13222_01/wls/docs81/logging/viewing.html
You can configure the log levels, by application, using the General application configuration page. For more information, see General Application Settings. The log levels include:
Debug logging occurs by default for any server in development mode. Client applications can contribute to the server log through the WebLogic Logger facility. For more information, see "Using WebLogic Logging Services at:
http://download.oracle.com/docs/cd/E13222_01/wls/docs81/logging/use_log.html
Query strings are echoed in the server log as a debug-level log message when the log level is set to Information in the DSP Administration Console and the WebLogic Administration Console is set to log debug messages to stdout.
You can use the WebLogic Server Administration Console to monitor the health and performance of the domain in which WebLogic is deployed, including resources such as servers, JDBC connection pools, JCA, HTTP, the JTA subsystem, JNDI, and Enterprise Java Beans (EJB).
The domain log is located in the following directory:
<BeaHome>\user_projects\domains\<domainName>\<domainName>.log
For more information, see Monitoring a WebLogic Server Domain in Configuring and Managing WebLogic Server.
You can use performance monitoring tools, such as the OptimizeIt and JProbe profilers, to identify Data Services Platform application "hot spots" that result in either high CPU utilization or high contention for shared resources.
For more information, see Tuning WebLogic Server Applications. For a complete list of performance monitoring resources, see Related Reading in WebLogic Server Performance and Tuning.
|
|
|