| Oracle® Application Server Advanced Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28975-02 |
|
|
View PDF |
| Oracle® Application Server Advanced Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28975-02 |
|
|
View PDF |
This chapter describes the auditing and tracing (logging) functionality available for Oracle Application Server Web Services. Auditing enables you to keep a complete, persistent record of request, response, and fault SOAP messages. It records the entire message. Tracing enables you to extract and persistently store discrete portions of request, response, and fault SOAP messages.
Auditing enables you to keep a complete, persistent record of SOAP requests, responses, and faults. During development it is often very convenient to be able to inspect the contents of SOAP requests and responses to diagnose problems.In a production environment, specific SOAP messages can be stored to support non-repudiation efforts. For example, an on-line retailer could record all received purchase order requests.
Auditing also enables you to design a strategy that records and analyzes security-related events. A history of audit records can produce an audit trail enabling the reconstruction and examination of a sequence of events. The audit trail can be used to detect attacks, confirm compliance with policy, deter abuse, and so on.
Auditing is initiated and performed by the server. It cannot be initiated or performed by the client. Adding auditing to your Web service does not require changes or extensions to the WSDL.
If you enable auditing, there will probably be a measurable impact upon the performance of the system. You should use it only during development and debugging, or when there is a clear need to persist the entire contents of a message during production. Auditing for non-repudiation is a good example. In this case, it is likely that you will have to audit only a small set of Web service operations, so the performance impact should be acceptable.
The size of the logged messages will effect how large the performance impact will be. Larger message will take more time and system resources to store.
Auditing can be applied at runtime to messages flowing into the platform (request messages), flowing out of the platform (response messages), and generated fault messages. The runtime stores these messages in the following persistent log file:
ORACLE_HOME\j2ee\OC4J_Instance_Name\log\group_name_n\wsmgmt\auditing\log.xml
This is a rolling file: after it reaches a certain size, it is renamed log-[number].xml and a new log.xml file is started. Over time, older versions of the file may be deleted. Application Server Control can read this file.
The location of the log file is determined by the configuration file ORACLE_HOME\j2ee\OC4J_instance_name\config\j2ee-logging.xml.
See Also:
"Controlling the Output of Web Services Loggers" for more information on how diagnostic logging for auditing and logging is configured in OracleAS Web Services.
"Configuring OC4J Logging" in the Oracle Containers for J2EE Configuration and Administration Guide provides more information on the j2ee-logging.xml file.
The following sections describe how the runtime processes these messages.
Example 6-1 illustrates a sample logged SOAP message. The original SOAP message appears in the <MSG_TEXT> element and is highlighted in bold in this example.
Example 6-1 Sample SOAP Message in the Audit Log
<MESSAGE>
<HEADER>
<TSTZ_ORIGINATING>2006-05-17T17:05:23.421-04:00</TSTZ_ORIGINATING>
<COMPONENT_ID>webservices</COMPONENT_ID>
<MSG_TYPE TYPE="NOTIFICATION"></MSG_TYPE>
<MSG_LEVEL>1</MSG_LEVEL>
<HOST_ID>bjones-lap</HOST_ID>
<HOST_NWADDR>138.2.8.215</HOST_NWADDR>
<MODULE_ID>management.auditing</MODULE_ID>
<THREAD_ID>73</THREAD_ID>
<USER_ID>SYSTEM</USER_ID>
<SUPPL_ATTRS>
<ATTR NAME="J2EE_MODULE.name">owsm-test-service-web</ATTR>
<ATTR NAME="J2EE_APP.name">owsm-test-service</ATTR>
<ATTR NAME="WEBSERVICE_PORT.name">OwsmTestPort</ATTR>
<ATTR NAME="WEBSERVICE.name">OwsmTestService</ATTR>
</SUPPL_ATTRS>
</HEADER>
<CORRELATION_DATA>
<EXEC_CONTEXT_ID>
<UNIQUE_ID>138.2.8.215:27595:1147899923421:429</UNIQUE_ID><SEQ>0</SEQ>
</EXEC_CONTEXT_ID>
</CORRELATION_DATA>
<PAYLOAD>
<MSG_TEXT><soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://oracle.com/owsm-test/wsdl"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Body soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns:hello>
<name xsi:type="xsd:string">Oracle Customer</name>
</ns:hello>
</soap:Body>
</soap:Envelope></MSG_TEXT>
</PAYLOAD>
</MESSAGE>
When an inbound SOAP message is received, the runtime determines, based on the configuration, whether auditing is enabled for the port. The configuration also indicates whether request messages are to be audited. If auditing is enabled for both the port and operation, then the entire message is written to the audit log.
When the Web service implementation creates outbound response SOAP messages, the management features are applied in reverse order. If auditing is enabled for the port and the configuration also indicates that response messages are to be audited, then the entire message is written to the audit log.
The configuration information for auditing is located in the server-side Web services proprietary deployment descriptor oracle-webservices.xml. The contents of this file can be modified during packaging or deployment. At runtime, changes must be made using either Application Server Control or by editing the management configuration file:
ORACLE_HOME\j2ee\OC4J_Instance_Name\config\wsmgmt.xml file.
Auditing can be performed only at the operation level; you cannot configure auditing at the global or port-level.
See Also:
Configuring Auditing for a Web Service in the Application Server Control on-line help for more information about the log.xml file.
An auditing configuration can be defined for each operation in a Web service port. The <auditing> element and its three attributes, request, response, and fault, define the auditing configuration. Each attribute can have a true or false value to indicate whether Web service management will store these messages. The following is a sample auditing configuration.
<auditing request="true" response="false" fault="false"/>
Example 6-2 illustrates the <auditing> element, highlighted in bold, as it appears in the oracle-webservices.xml deployment descriptor. Note that even though you cannot specify auditing for a port, a <runtime enabled="auditing"> element is still required at the port level. The schema for this file is:
http://xmlns.oracle.com/oracleas/schema/oracle-webservices-10_0.xsd
Example 6-2 Operation-Level Auditing Element in the Server-Side Configuration File
... <port-component name="String"> ... <runtime enabled="auditing"> ... </runtime> <operations> <operation name "..." > <runtime> ... <auditing request="true" response="true" fault="false"/> </runtime> </operation> </operations> </port-component> ...
Table 6-1 describes the attributes of the auditing element.
Table 6-1 Elements to Enable Message Auditing
| Element Name | Description |
|---|---|
|
<auditing> |
Has attributes
|
The configuration information for auditing is located in the J2EE client-side Web services proprietary deployment descriptor. Depending on the client application, this can be either orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml. The contents of this file can be modified during packaging or deployment.
Auditing can be performed only at the operation level. Hence, there is no global or port-level configuration.
Similar to the server-side, a client-side auditing configuration can be defined for each operation in a Web service port. The <auditing> element and its three attributes, request, response, and fault, define the auditing configuration. Each attribute can have a true or false value to indicate whether Web service management will store these messages. Table 6-1 provides a description of the <auditing> element and its attributes. The following is a sample auditing configuration.
<auditing request="true" response="false" fault="false"/>
The auditing configuration appears within the <operation> clause of the <service-ref-mapping> element. Each operation can have its own auditing configuration. Example 6-3 illustrates the skeleton of an orion-web.xml Oracle proprietary client-side deployment descriptor that indicates the position of the auditing configuration in the hierarchy. The auditing configuration is highlighted in bold. Note that the configuration occurs within the <port-info> element. The schema for this file is:
http://xmlns.oracle.com/oracleas/schema/orion-web-10_0.xsd
Example 6-3 Sample Client-Side orion-web.xml with an Auditing Configuration
<orion-web-app ...>
<service-ref-mapping name="service/MyTestServiceRef">
<port-info>
...
<runtime>
...
<security/>
<reliability/>
...
</runtime>
<operations>
...
<operation name="echo">
<runtime enabled = "security,reliability,auditing">
...
<security/>
<reliability/>
<auditing request="true" response="true" fault="false"/>
...
</runtime>
</operation>
...
</operations>
</port-info>
</service-ref-mapping>
</orion-web-app>
OracleAS Web Services includes basic SOAP message tracing (logging). This functionality lets you extract and persistently store discrete portions of request, response, and fault SOAP messages.
There are many situations where you might want to persistently capture information from SOAP messages. For example many large organizations deploying internal Web services may want to track which groups within the organization are using the service. Tracing could enable this by extracting and collecting group information from messages.
Note:
Tracing is not available, nor can it be configured for Web service clients.Tracing is likely to have a minor impact upon the performance of the system. Since only simple types can be extracted from messages, this impact should be limited. If the tracing mechanism is asked to extract large amounts of information from individual messages (for example, large text blocks) a proportional performance impact may occur.
Tracing can be applied at runtime to messages flowing into the platform (request messages), flowing out of the platform (response messages), and generated fault messages. Tracing information is stored in the following persistent log file:
ORACLE_HOME\j2ee\OC4J_Instance_Name\log\group_name_n\wsmgmt\logging\log.xml
This is a rolling file: after it reaches a certain size, it is renamed log-[number].xml and a new log.xml file is started.
The location of the log file is determined by the configuration file ORACLE_HOME\j2ee\OC4J_instance_name\config\j2ee-logging.xml.
See Also:
"Controlling the Output of Web Services Loggers" for more information on how diagnostic logging for auditing and logging is configured in OracleAS Web Services.
"Configuring OC4J Logging" in the Oracle Containers for J2EE Configuration and Administration Guide provides more information on the j2ee-logging.xml file.
The following sections describe how the runtime processes these messages.
Example 6-4 provides a sample of a log record derived from an inbound SOAP request message.
Example 6-4 Sample Log File Entry
<MESSAGE>
<HEADER>
<TSTZ_ORIGINATING>2006-05-17T17:05:23.421-04:00</TSTZ_ORIGINATING>
<COMPONENT_ID>webservices</COMPONENT_ID>
<MSG_TYPE TYPE="NOTIFICATION"></MSG_TYPE>
<MSG_LEVEL>1</MSG_LEVEL>
<HOST_ID>bjones-lap</HOST_ID>
<HOST_NWADDR>138.2.8.215</HOST_NWADDR>
<MODULE_ID>management.logging</MODULE_ID>
<THREAD_ID>73</THREAD_ID>
<USER_ID>SYSTEM</USER_ID>
<SUPPL_ATTRS>
<ATTR NAME="J2EE_MODULE.name">owsm-test-service-web</ATTR>
<ATTR NAME="J2EE_APP.name">owsm-test-service</ATTR>
<ATTR NAME="WEBSERVICE_PORT.name">OwsmTestPort</ATTR>
<ATTR NAME="WEBSERVICE.name">OwsmTestService</ATTR>
</SUPPL_ATTRS>
</HEADER>
<CORRELATION_DATA>
<EXEC_CONTEXT_ID>
<UNIQUE_ID>138.2.8.215:27595:1147899923421:429</UNIQUE_ID><SEQ>0</SEQ>
</EXEC_CONTEXT_ID>
</CORRELATION_DATA>
<PAYLOAD>
<MSG_TEXT>name='Oracle Customer'</MSG_TEXT>
</PAYLOAD>
</MESSAGE>
When an inbound SOAP message is received, the runtime determines, based on the configuration, whether tracing is enabled for the port. The tracing mechanism then determines, based again on the configuration, what information, if any, is to be extracted from the message for the operation. This information is then stored.
When the Web service implementation creates outbound response SOAP messages, the management features are applied reverse order. If tracing is enabled for the port and the configuration also indicates that information from response messages should be logged, then the information is extracted and stored.
The configuration elements for tracing are defined in the oracle-webservices-logging-10_0.xsd schema. This file can be found in the oc4j-schemas.jar file.
OC4J_HOME\j2ee\home\lib\oc4j-schemas.jar
The tracing configuration for the server-side is stored in the oracle-webservices.xml proprietary deployment descriptor. The contents of this file can be modified during packaging or deployment. At runtime, changes must be made either by using Application Server Control or by editing the management configuration file:
ORACLE_HOME\j2ee\OC4J_Instance_Name\config\wsmgmt.xml file.
Tracing must be configured at the port and operation levels. There is no global-level configuration.
If tracing features are employed, they must be configured at both the port and the operation level. The port-level configuration contains information that is referenced by the operation level. Unlike security, operation-level configuration does not override port-level configuration.
Example 6-5 displays the port-level tracing elements as they appear in the server-side Web services proprietary deployment descriptor, oracle-webservices.xml. These elements are used to create a set of namespace prefix and URI pairs that are referenced by the operation level configuration. The schema for this file is:
Example 6-5 Port-Level Tracing Elements in the Server-Side Configuration File
... <port-component name="..."> ... <runtime enabled="logging"> <logging> <namespaces> <namespace prefix='env' uri='http://schemas.xmlsoap.org/soap/envelope/'/> <namespace prefix='ns0' uri='http://oracle.com/test/wsdl'/> </namespaces> </logging> ... </runtime> </port-component> ...
Table 6-2 describes the port-level namespace elements that must be set for tracing information to be reported. The namespace prefix-URI pairs are used for processing xpath expressions.
Example 6-6 illustrates the operation-level tracing elements as they appear in the server-side Web services proprietary deployment descriptor, oracle-webservices.xml. At the operation level, you can enable or disable tracing for request, response, and fault messages.
Example 6-6 Operation-Level Tracing Elements in the Server-Side Configuration File
...
<port-component name="String">
...
<operations>
<operation name="...">
<runtime>
...
<logging>
<request enabled='true'>
<attributes>
<attribute name='input'
...
xpath='/env:Envelope/env:Body/ns0:echo/String_1/text()'/>
</attributes>
</request>
<response enabled='true'>
<attributes>
<attribute name='output'
xpath='/env:Envelope/env:Body/ns0:echoResponse/result/text()'/>
</attributes>
</response>
<fault enabled='true'>
<attributes>
<attribute name='output'
xpath='/env:Envelope/env:Body/ns0:echoResponse/result/text()'/>
</attributes>
</fault>
</logging>
</runtime>
</operation>
</operations>
</port-component>
...
Table 6-3 describes the message tracing elements: request, response, and fault. Setting an element to true enables tracing for that message type. If tracing is enabled, you can specify one or more attributes you want to log for each message type. These attributes are indicated by its name and xpath.
If tracing for a message type is enabled, but no attributes are configured, then no tracing will occur. Similarly, if the xpath query returns no results, then no tracing will occur.
Table 6-3 Elements to Enable Message Tracing
| Element Name | Description |
|---|---|
|
<fault> |
If |
|
<request> |
If |
|
<response> |
If |
This section provides an overview of the parts of the Web service auditing and tracing configuration that can be set by the Oracle JDeveloper and Application Server Control tools. For detailed information of the individual auditing and tracing options that can be controlled by these tools, see the on-line help for Application Server Control and Oracle JDeveloper.
How to Use WebServicesAssembler to Add an Auditing and Tracing Configuration
How Application Server Control Supports Auditing and Tracing
This section describes how to use WebServicesAssembler commands to add an auditing and tracing configuration to a Web service. A configuration can be added in a top down or bottom up Web service assembly. Auditing can also be assembled into a J2EE Web service client (tracing is not available on the client). In each case, the configuration is specified in an XML file and passed to the WebServicesAssembler command with the ddFileName argument.
Steps to Assemble Auditing and Tracing into a Web Service Bottom Up
Steps to Assemble Auditing and Tracing into a Web Service Top Down
Steps to Assemble Auditing into a J2SE Web Service Client Proxy
The following general steps describe how to assemble an auditing and tracing configuration into a Web service bottom up.
Create the XML file that provides settings for the auditing and tracing features you want to enable. There are two different ways in which you can do this.
Manually write the XML file that contains the auditing and tracing settings. Example 6-8 illustrates a sample XML file that contains these settings. Save the file.
Run the WebServicesAssembler tool with the appropriate *Assemble command for your Web service. One of the files it creates will be an oracle-webservices.xml file that contains a skeleton of the ports and operations. For example, you could run the Ant task in Example 6-7 without the ddFileName argument to obtain this file. Edit the oracle-webservices.xml file to enter the appropriate settings for the auditing and tracing features. Save the file under a different name.
"Server-Side Auditing Configuration Elements" and "Server-Side Tracing Configuration Elements" provide descriptions of the port-level and operation-level auditing and tracing features that are available on the server.
Use the appropriate *Assemble command to assemble the Web service. Use the ddFileName argument to pass the file with the auditing and tracing configuration you created in Step 1 to the WebServicesAssembler tool.
See "Web Service Assembly Commands" in the Oracle Application Server Web Services Developer's Guide for descriptions of the *Assemble commands.
See "ddFileName" in the "Deployment Descriptor Arguments" section of the Oracle Application Server Web Services Developer's Guide for more information about the ddFileName command.
Example 6-7 illustrates an assemble Ant task that uses the ddFileName argument to add the auditing and tracing configuration in wsmBankServiceConfig.xml to the Web service.
Example 6-7 Passing an Auditing and Tracing Configuration in a Bottom Up Web Service Assembly
<oracle:assemble appName="bank"
targetNamespace="http://www.oracle.com/bank"
typeNamespace="http://www.oracle.com/bank"
serviceName="Banking"
interfaceName="oracle.ws.server.bank.Bank"
className="oracle.ws.server.bank.BankImpl"
input="./build/classes/service"
output="build"
ear="build/bank.ear"
style="rpc"
use="encoded"
ddFileName="wsmBankServiceConfig.xml"
>
</oracle:assemble>
Example 6-8 illustrates the contents of the wsmBankServiceConfig.xml for a server-side auditing and tracing configuration. While both auditing and tracing are enabled at the port level, only a tracing configuration is provided. At the operations level, an auditing configuration is provided for the withdraw operation and a tracing configuration is provided for the deposit operation. Note that the contents of the file are enclosed in the <oracle-webservices> element.
Example 6-8 Sample Server-Side Auditing and Tracing Configuration
<?xml version='1.0' encoding='UTF-8'?>
<oracle-webservices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
oracle-webservices-10_0.xsd">
<webservice-description name="Bank">
<port-component name="HttpSoap11">
<runtime enabled="auditing, logging">
<auditing/>
<logging>
<namespaces>
<namespace prefix="target_ns" uri="http://oracle.com/bank/wsdl"/>
<namespace prefix="soap" uri="http://schemas.xmlsoap.org/soap/envelope/"/>
</namespaces>
</logging>
</runtime>
<operations>
<operation name="withdraw">
<runtime>
<auditing request="true" response="true" fault="false"/>
</runtime>
</operation>
<operation name="deposit">
<runtime>
<logging>
<request enabled="true">
<attributes>
<attribute name="request_string"
xpath="/soap:Envelope/soap:Body/target_ns:deposit/String_1/text()"/>
</attributes>
</request>
<response enabled="true">
<attributes>
<attribute name="response_result"
xpath="/soap:Envelope/soap:Body/target_ns:depositResponse/result/text()"/>
</attributes>
</response>
</logging>
</runtime>
</operation>
</operations>
</port-component>
</webservice-description>
</oracle-webservices>
The following general steps describe how to assemble an auditing and tracing configuration into a Web service top down.
Create the XML file that provides settings for the auditing and tracing features that you want to enable. There are two different ways in which you can do this.
Manually write the XML file that contains the auditing and tracing settings. Example 6-8 illustrates an XML file that contains sample auditing and tracing settings.
Run the WebServicesAssembler tool with the topDownAssemble command. One of the files it creates is an oracle-webservices.xml file that contains a skeleton of the ports and operations. For example, you could run the Ant task in Example 6-9 without the ddFileName argument to obtain this file. Edit oracle-webservices.xml file to enter the appropriate settings for the auditing and tracing features. Save the file under a different name.
"Server-Side Auditing Configuration Elements" and "Server-Side Tracing Configuration Elements" describe the port-level and operation-level auditing and tracing features that are available on the server.
Use the topDownAssemble command to assemble the Web service. Use the ddFileName argument to pass the file with the auditing and tracing configuration you created in Step 1 to the WebServicesAssembler tool.
See "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide for more information on the topDownAssemble command.
See "ddFileName" in the "Deployment Descriptor Arguments" section of the Oracle Application Server Web Services Developer's Guide for more information on this argument.
Example 6-9 illustrates a topDownAssemble Ant task that uses the ddFileName argument to add the auditing and tracing configuration in wsmLoggingServiceConfig.xml to the Web service.
Example 6-9 Passing an Auditing and Tracing Configuration in a Top Down Web Service Assembly
<oracle:topDownAssemble
wsdl="BankService.wsdl"
input="build/classes/service"
output="build"
className="oracle.ws.server.bank.BankImpl"
ear="dist/bank.ear"
packageName="oracle.ws.server.bank"
ddFileName="BankServiceWsmConfig.xml"/>
The following general steps describe how to assemble an auditing configuration into a J2SE Web service client proxy. Tracing is not available for a Web service client.
Provide settings for the auditing features that you want to enable in an XML file.
See "How to Configure Auditing in a J2EE Client" for a description of the operation-level auditing features that can be set for the client.
Use the genProxy command to assemble the Web service proxy. Pass the auditing configuration to the command with the ddFileName argument.
This will generate an XML file. For the genProxy command illustrated in Example 6-10, the file oracle\generated\runtime\BankPortBinding_Stub.xml will be generated into the test\src directory.
See "How to Pass Management Information to a J2SE Client" for more detailed information on adding a management configuration to a J2SE client.
Example 6-10 illustrates a genProxy Ant task that uses the ddFileName argument to add the auditing configuration in wsmClientDD.xml to the Web service.
Example 6-10 Passing an Auditing Configuration in a Web Service Client Assembly
<oracle:genProxy
wsdl="http://localhost:8888/bankdemo/bank?WSDL"
output="test/src"
packageName="oracle.generated"
ddFileName="wsmClientDD.xml"/>
</oracle:genProxy>
Example 6-11 illustrates the contents of the wsmClientDD.xml for a client-side auditing configuration. The auditing configuration is highlighted in bold. Note that the contents of the file are enclosed in the <port-info> tag.
J2EE Web service clients can be configured to perform auditing. Tracing is not available for Web service clients. The following general steps describe how you can add an auditing configuration to a J2EE Web service client. In addition to generating the client code, you must also edit both the standard and the Oracle proprietary Web service deployment descriptor.
Generate the J2EE client code by providing the WSDL and the service endpoint interface as input to the genInterface command.
"How to Assemble a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides more detailed information on using WebServicesAssembler to assemble J2EE client code.
Edit the deployment descriptor for the J2EE component (either web.xml, ejb-jar.xml, or application-client.xml) to add the code to the <service-ref> element that will allow the component to access the Web service endpoint. For examples of how auditing and other Web service management information can be added to a standard J2EE Web service client deployment descriptor, see the following examples.
Example 3-5, "web.xml—Static Configuration for a Servlet or JSP Web Service Client"
Example 3-7, "ejb-jar.xml—Static Configuration for an EJB Web Service Client"
See "Adding J2EE Web Service Client Information to Deployment Descriptors" in the Oracle Application Server Web Services Developer's Guide for information on the <service-ref> element and its contents.
Edit the Oracle proprietary deployment descriptor for the J2EE component (either orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml) to add OC4J platform-specific information and the auditing configuration to the <service-ref-mapping> element.
For examples of how auditing and other Web service management information can be added to a J2EE Web service client, see the following examples.
See "Adding OC4J-Specific Platform Information" in the Oracle Application Server Web Services Developer's Guide for information on the <service-ref-mapping> element and its contents.
Example 6-12 illustrates a sample orion-web.xml file that has been edited to contain an auditing configuration. The configuration appears within the <service-ref-mapping> element, which is used to provide platform-specific information.
Example 6-12 orion-web.xml File Edited to Contain an Auditing Configuration
<?xml version="1.0"?>
<orion-web-app
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/orion-web-10_0.xsd">
<service-ref-mapping name="service/BankTeller">
<port-info>
<wsdl-port namespaceURI="http://oracle.com/bank" localpart="BankPort"/>
<service-endpoint-interface>oracle.ws.client.bank.BankService</service-endpoint-interface>
<runtime enabled="auditing"/>
<operations>
<operation name="deposit">
<runtime>
<auditing request="true" response="true" fault="false"/>
</runtime>
</operation>
</operations>
</port-info>
</service-ref-mapping>
</orion-web-app>
Application Server Control lets you enable and configure different auditing options at deployment and at runtime. Application Server Control lets you perform the following tasks.
Modify at deployment time which Web service operations and messages to audit.
Control at runtime which Web service operations and messages to audit.
Browse the messages contained in the audit logs for services and J2EE clients.
Similarly, you can enable and configure different tracing options at deployment and at runtime. Application Server Control lets you perform the following tasks.
Modify at deployment time the type of information to extract and log.
Control at runtime the type of information to extract and log.
Browse the messages contained within the logs.
Wizards in Oracle JDeveloper let you configure auditing and tracing (which is called "logging" in JDeveloper) for a Web service in a deployment module. The auditing and logging configuration is stored in the Oracle proprietary deployment descriptor, oracle-webservices.xml.
When Oracle JDeveloper performs the final packaging of a Web service module, it includes the deployment descriptor in the location required by the Web services runtime. When Oracle JDeveloper is used as the deployment tool for deploying Web services, you have the option to override any auditing and logging configuration that was set during packaging.
The auditing and logging configuration created by Oracle JDeveloper can also be overridden after deployment by Application Server Control.
See Also:
Oracle JDeveloper on-line help for more information on enabling logging and auditing.
Edit Auditing Configuration Page and Edit Tracing Configuration Page in the Application Server Control on-line help for more information on overriding auditing and tracing features after deployment.
The Oracle Diagnostic Logging (ODL) framework provides diagnostic logging for Web services auditing and logging. In the ODL framework, log files are formatted as XML documents, enabling logs to be parsed and reused by other Oracle Application Server components such as Application Server Control.
The various components of OC4J use Java loggers that direct log messages of a pre-determined severity to the OC4J log file.
ORACLE_HOME\j2ee\OC4JInstanceName\log\instanceName_groupName_n\oc4j\log.xml
The OC4J log file is generated in XML format using the Oracle Diagnostic Logging framework. It can be viewed and configured through the Logger Configuration page of the Application Server Control Console.
The j2ee-logging.xml file, also known as the "oracle logger", provides the configuration for diagnostic log handlers. This file is described in the following sections.
See Also:
"Using Oracle Diagnostic Logging (ODL)" in the Oracle Containers for J2EE Configuration and Administration Guide provides more information on the features of ODL and the contents of the j2ee-logging.xml file.
The j2ee-logging.xml file, also known as the "oracle logger", provides the configuration for diagnostic log handlers. The file contains two sections. The log handler section is where you can define the output properties of a particular logger. The logger section links a particular logger with its handler.
A log handler specifies the output properties of a particular logger. In the j2ee-logging.xml file, the <log_handler> element defines the handler. Attributes, such as the maximum log file size and its character encoding, are specified by <property> sub-elements. You can also direct the output to a file other than the OC4J log file.
Table 6-4 describes the properties that can be configured for log handlers.
Table 6-4 Properties for Log Handlers
| Property Name | Description |
|---|---|
|
encoding |
Specifies the character encoding for the log file. Default is UTF-8. |
|
maxFileSize |
Sets the maximum size, in bytes, that any log file in the directory will be allowed to grow to. Default is 104857600 bytes. |
|
maxLogSize |
Sets the maximum size, in bytes, for the log file directory. Default is 104857600 bytes. |
|
path |
Specifies the directory in which the handler will generate the log files. For example, the default location for the diagnostic log file for auditing is:
The default location for the diagnostic log file for tracing is:
If you do not provide a value for this property, then messages will be sent to the default log file:
|
|
supplementalAttributes |
These values help the Application Server Control log viewer find the log records for a particular Web service. These values are determined at deployment time. Default is:
|
Example 6-13 illustrates the log handler configuration for auditing and tracing in the j2ee-logging.xml file. The names of the handlers for auditing and logging are oracle-webservices-management-auditing-handler and oracle-webservices-management-logging-handler, respectively.
Example 6-13 Configuration for Auditing and Tracing Log Handlers
...
<logging_configuration>
<log_handlers>
...
<!-- The log handler for the oracle.webservices.management.auditing logger. -->
<log_handler name='oracle-webservices-management-auditing-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='%ORACLE_HOME%/j2ee/%OPMN_PROC_TYPE%/log/%OPMN_PROC_TYPE%_%OPMN_PROC_SET%_%OPMN_PROC_INDEX%/wsmgmt/auditing'/>
<property name='maxFileSize' value='104857600'/>
<property name='maxLogSize' value='104857600'/>
<property name='encoding' value='UTF-8'/>
<property name='supplementalAttributes' value='J2EE_APP.name,J2EE_MODULE.name,WEBSERVICE.name,WEBSERVICE_PORT.name'/>
</log_handler>
<!-- The log handler for the oracle.webservices.management.logging logger. -->
<log_handler name='oracle-webservices-management-logging-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='%ORACLE_HOME%/j2ee/%OPMN_PROC_TYPE%/log/%OPMN_PROC_TYPE%_%OPMN_PROC_SET%_%OPMN_PROC_INDEX%/wsmgmt/logging'/>
<property name='maxFileSize' value='104857600'/>
<property name='maxLogSize' value='104857600'/>
<property name='encoding' value='UTF-8'/>
<property name='supplementalAttributes' value='J2EE_APP.name,J2EE_MODULE.name,WEBSERVICE.name,WEBSERVICE_PORT.name'/>
</log_handler>
...
Note:
In the current release, if you want to make any changes to thej2ee-logging.xml file, you must edit it by hand. Restart OC4J after making any changes to the file.See Also:
"Configuring OC4J Logging" in the Oracle Containers for J2EE Configuration and Administration Guide provides more information on the contents of the j2ee-logging.xml file.
As described in "Understanding Diagnostic Loggers", OC4J provides a number of Java loggers. In the <loggers> section of the j2ee-logging.xml file, separate <logger> elements define each individual component logger. In addition to linking the specified logger to its output properties in the log handler section, the <logger> element provides attributes that define the Java logging level, whether the logger can inherit the logging level of its parent logger, and the name of the log handler that it is associated with.
The level attribute specifies the Java log level for the logger. By default, the ODL message type and log level is set to NOTIFICATION:1, which maps to the Java log level INFO.
The Web services diagnostic log levels set in the j2ee-logging.xml file can be viewed and configured in the Logger Configuration page of Application Server Control. You can use Application Server Control to change the value of the log level, but these changes are not persistent; they are kept only for the duration of the JVM process.
Note:
You can make changes to the <log-handler> section of the j2ee-logging.xml file, but changing the <loggers> section is not recommended.
The "per Web service port" logging level that can be set through Application Server Control cannot currently be specified through the j2ee-logging.xml file.
See Also:
"Configuring OC4J Logging" in the Oracle Containers for J2EE Configuration and Administration Guide provides more information on the Java and ODL logging levels that can be defined in the j2ee-logging.xml file.
Example 6-14 illustrates the <loggers> section of the j2ee-logging.xml file for auditing and tracing. The name of the auditing logger is oracle.webservices.management.auditing; the name of the tracing logger is oracle.webservices.management.logging. Their level attributes are set to their default value, NOTIFICATION:1, which maps to the Java Info log level. The useParentHandlers attribute is set to false, to prevent the auditing and tracing loggers from inheriting the level set for its parent, root, logger.
Example 6-14 Log Level Configuration for Auditing and Tracing
...
<loggers>
...
<logger name='oracle.webservices.management.auditing' level='NOTIFICATION:1' useParentHandlers='false'>
<handler name='oracle-webservices-management-auditing-handler'/>
</logger>
...
<logger name='oracle.webservices.management.logging' level='NOTIFICATION:1' useParentHandlers='false'>
<handler name='oracle-webservices-management-logging-handler'/>
</logger>
...
</loggers>
...
You can use the Diagnostic Logger Configuration page in the Application Server Control to change the log level for a Web service. However, it does not let you change the level for individual loggers and any changes you make are not persistent.
If you want to change the default configuration for a logger, such as the log level or the target file where it will store messages, you can add a configuration for it to the j2ee-logging.xml file.
To add a configuration, you must identify the logger in the <loggers> section of the file and define a handler for it in the <log_handlers> section.
See Also:
"Log Handlers" and "Loggers" for more information on the <log_handlers> and <loggers> sections of the j2ee-logging.xml file.
Example 6-15 provides a sample configuration for the Web services security logger oracle.webservices.management.security. The configuration specifies that the log messages will be stored in the ORACLE_HOME\j2ee\OC4J_Instance_Name\log\group_name_n\wsmgmt\security\log.xml file instead of the OC4J log file.
Example 6-15 Sample Configuration for a Web Services Security Logger
...
<log_handlers>
...
<!-- The log handler for the oracle.webservices.management.security logger. -->
<log_handler name='oracle-webservices-management-security-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='path' value='%ORACLE_HOME%/j2ee/%OPMN_PROC_TYPE%/log/%OPMN_PROC_TYPE%_%OPMN_PROC_SET%_%OPMN_PROC_INDEX%/wsmgmt/security'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
<property name='encoding' value='UTF-8'/>
<property name='supplementalAttributes' value='J2EE_APP.name,J2EE_MODULE.name,WEBSERVICE.name,WEBSERVICE_PORT.name'/>
</log_handler>
</log_handlers>
...
<loggers>
...
<logger name='oracle.webservices.management.security' level='NOTIFICATION:1' useParentHandlers='false'>
<handler name='oracle-webservices-management-security-handler'/>
</logger>
...
</loggers>
...
Application Server Control enables you to set diagnostic logging levels for each Web service port. To set the logging level, click the Diagnostic Logger Configuration link on the Application Server Control Web Service Administration page. Follow that link to set a logging level for the Web service port.
The level that you set through Application Server Control will override the level of the individual oracle.webservice.* loggers if and only if a "finer" level is set.
For example:
if the oracle.webservice.security logger is set to INFO and the "per port" level is set to FINE, then all diagnostic messages for the logger oracle.webservice.security that are SEVERE-FINE will be logged for that port.
if the "per port" level is set to WARNING and the webservice.oracle.security logger is set to INFO, then all diagnostic messages for the logger oracle.webservice.security for the port at level SEVERE-WARNING will be logged and all oracle.webservice.security diagnostic messages of level SEVERE-INFO will be logged regardless of port.
See Also:
"Controlling the Output of Web Services Loggers" for more information on how diagnostic logging for auditing and logging is configured in OracleAS Web Services.
Configuring Auditing for a Web Service and Configuring Tracing for a Web Service in the Application Server Control on-line help.
Configuring the Diagnostics Logger for a Web Service and Logging Levers Used by OC4J Loggers in the Application Server Control on-line help.
For more information on:
the contents of the oracle-webservices.xml deployment descriptor which contains the Web services management configuration, see "Packaging and Deploying Web Services", in the Oracle Application Server Web Services Developer's Guide.
adding Web service management information, including security, to a Web service, see Chapter 3, "Managing Web Services".
adding security information to a Web service, see Chapter 4, "Ensuring Web Services Security" and the Oracle Application Server Web Services Security Guide.
adding reliability information to a Web service, see Chapter 5, "Ensuring Web Service Reliability".
the contents of the wsmgmt.xml file which contains the security configuration, see Appendix A, "Understanding the Web Services Management Schema".
assembling a Web service top down, see "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide.
using Java classes to assemble a Web service, see "Assembling a Web Service with Java Classes" in the Oracle Application Server Web Services Developer's Guide.
using EJBs to assemble a Web service, see "Assembling a Web Service with EJBs" in the Oracle Application Server Web Services Developer's Guide.
using JMS topics and destinations to assemble a Web service, see "Assembling Web Services with JMS Destinations" in the Oracle Application Server Web Services Developer's Guide.
using database resources, such as PL/SQL packages, SQL queries, DML statements, Oracle Streams AQ, or server-side Java classes, to assemble a Web service, see "Assembling Database Web Services" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2EE Web Service client, see "Assembling a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2SE Web service client, see "Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
using WebServicesAssembler commands to assemble Web service artifacts, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
the contents of the oracle-webservices.xml deployment descriptor which contains the Web services management configuration, see "Packaging and Deploying Web Services" in the Oracle Application Server Web Services Developer's Guide.
