10-5 Audit Logging Guide
10-5 Audit Logging Guide
Version 10.5
October 2019
This document applies to webMethods Product Suite Version 10.5 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 2005-2019 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or
its affiliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
hp://softwareag.com/licenses.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices, license terms, additional rights or
restrictions, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party Products". For certain specific third-party
license restrictions, please refer to section E of the Legal Notices available under "License Terms and Conditions for Use of Software AG
Products / Copyright and Trademark Notices of Software AG Products". These documents are part of the product documentation, located
at hp://softwareag.com/licenses and/or in the root installation directory of the licensed product(s).
Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with
Software AG.
Table of Contents
This guide explains how to configure webMethods Integration Server error, session,
service, security, document, and guaranteed delivery audit logging, and how to
view logged data. In addition, the guide briefly describes business process, task, and
integration process audit logging, and points to the webMethods documentation that
provides more detailed information for those types of logging.
Document Conventions
Convention Description
Italic Identifies:
Variables for which you must supply values specific to your own
situation or environment.
New terms the first time they occur in the text.
References to other documentation sources.
Monospace Identifies:
font
Text you must type in.
Messages displayed by the system.
Program code.
{} Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.
Convention Description
... Indicates that you can type multiple options of the same type.
Type only the information. Do not type the ellipsis (...).
Software AG TECHcommunity
You can find documentation and other technical information on the Software AG
TECHcommunity website at “hp://techcommunity.softwareag.com”. You can:
Access product documentation, if you have TECHcommunity credentials. If you do
not, you will need to register and specify "Documentation" as an area of interest.
Access articles, code samples, demos, and tutorials.
Use the online discussion forums, moderated by Software AG professionals, to
ask questions, discuss best practices, and learn how other customers are using
Software AG technology.
Link to external websites that discuss open standards and web technology.
Data Protection
Software AG products provide functionality with respect to processing of personal data
according to the EU General Data Protection Regulation (GDPR). Where applicable,
appropriate steps are documented in the respective administration documentation.
Overview
Audit logging for webMethods products provides important data you need to monitor
webMethods system activity and correct problems. Integration Server maintains most
of the audit logging data in the webMethods product suite. This chapter describes audit
logging maintained by Integration Server.
Note: You can only log request and response payloads if you are writing API
Gateway transaction events to an external RDBMS.
For information about identifying the audit log as the destination and enforcing policies
with API Gateway, see webMethods API Gateway User's Guide.
If Integration Server has tried repeatedly to publish or deliver a document for a trigger
from its outbound store and failed, Integration Server logs the document to the external
RDBMS as a retries exceeded document.
For complete information, see the Working with webMethods Messaging Triggers
section in the Publish-Subscribe Developer’s Guide.
basis. If you enable customized logging, you set up the customized logging for specific
services in Designer. For each service, you can choose the following:
When to log based on how the service is called. For example, you might choose to
log only when the service is called by a client request or trigger, as opposed to by
other services.
On what status to log. For example, you might choose to log only when the service
fails.
Whether to store the service’s input pipeline and, if so, when. For example, you
might choose to log the input pipeline only when an error occurs. Storing the input
pipeline allows you to resubmit the service later if necessary.
Note: Whether you enable or disable service logging in Integration Server and
Designer, if error logging is enabled, Integration Server always writes error
log entries when service errors occur. The data includes stack trace data about
the errors.
You can augment service logging data using Integration Server built-in services. The
built-in services do the following:
Enable services to post user-defined progress messages to the Integration Server
server log or the IS Core Audit Log. For example, you might have a service post
messages to indicate that certain pieces of code ran successfully, or to record run-
time values for variables so you can see how the values changed as the service ran.
Enable services to write the pipeline to the Integration Server server log.
Task Engines log audit data for tasks and send the data to Integration Server. The
Task Engine is a feature installed on every My webMethods Server that runs tasks.
For detailed information on the Task Engine and instructions on seing up task
logging, see webMethods Task Engine User’s Guide.
Users perform the actions listed above from the task list in My webMethods. For
instructions on performing actions on tasks, see webMethods Task Engine User’s Guide.
For tasks that are called from business processes, you can write business process log
entries. Tasks called from business processes are run as business process steps, so
you can log the same data for a task that you can log for any other business step (see
“ Business Process Audit Logging”, above). Process Engines log all business process
entries.
Globalization
If a webMethods product is equipped with webMethods language packs and some of
those language packs correspond to the language used by the operating environment
in which the product is running, the product writes its log entries in the language used
by the operating system. If the product is equipped with no language packs or with
language packs that do not correspond to the language used by the operating system, the
product writes its log entries in U.S. English.
Suppose your operating environment uses Japanese as its language. You have installed
language packs including the Japanese Language Packs on Integration Server, so
Integration Server stores its own log entries in Japanese. You have not installed the
Japanese Language packs on Trading Networks, so Integration Server stores Trading
Networks log entries in U.S. English.
Note: Even if no language packs are installed on the webMethods product and
the product is using U.S. English, Integration Server might store log entries
from external sources, such as database drivers or adapter resources, in the
language used by the operating environment in which the product is running.
Note: If your Integration Server license does not include security auditing,
guaranteed delivery, or API Gateway, those loggers are unavailable.
Value Description
Brief The logger writes start and failure or start and success log entries for
every service every time the service is called, either directly (top-level) or
by another service (nested).
Verbose Same as Brief, except that the logger also writes the input pipeline in all
cases.
The brief and verbose values are globally applied to services; if you choose one of
those values, you cannot override it in Designer for individual services. Software AG
Note: The messaging audit logger always writes to a file and cannot be configured
to write to a database.
In the Maximum Retries field, specify the maximum times the logger should retry writing
the entry to the destination if the first aempt fails because of a transient error. A
transient error is an error that arises from a temporary condition that might be resolved
or corrected quickly, such as the unavailability of a resource due to network issues or
failure to connect to a database.
Also set the Wait Between Retries field.
Note: If the logger is logging data asynchronously (see below) and the logging
queue has many audit records in it, the elapsed time between logging
aempts may be longer than the value in the Wait Between Retries field.
Note: The Maximum Retries field and the Wait Between Retries field do not apply to
the messaging audit logger because the messaging audit logger cannot be
configured to write to a database.
load. In contrast, synchronous mode might be slower for a logger writing to a file under
load.
When the logger tries to log in synchronous mode, one of the following occurs:
The logger writes the entry to the destination.
The logger cannot write the entry to the destination because of an error.
When the logger tries to write an entry in asynchronous mode, one of the following
occurs:
The logger writes the entry to the destination.
The logger cannot write the entry to the destination because of an error.
Note: The Service logger cannot write the input pipeline to this file, and the
API Gateway logger cannot write request and response payloads to the
FailedAudit_yyyymmdd_hhmmss .log file.
Note: The messaging audit logger uses the internal, light-weight queue as the audit
logging queue. The messaging logger cannot be configured to use a queue on
Universal Messaging as the audit logging queue.
Note: When the Universal Messaging connection alias is configured to share the
client prefix, multiple Integration Servers in a stateful or stateless cluster can
use the alias to use the same Universal Messaging queue as the logging queue.
Additionally, this logging queue can be shared across a Universal Messaging
realm. That is, loggers on multiple Integration Servers can write log entries
to and read log entries from one Universal Messaging queue shared across a
Universal Messaging realm.
pending entries during lulls. Make sure the Integration Server host machine has enough
disk space or memory to accommodate the largest possible size of the queue as specified
in this field, as well as the requirements of other applications the Integration Server
is hosting. The queue’s insertion of logged data into a database is constrained by the
database’s availability and connections limit.
If the queue reaches its maximum, the logger writes the log entries to a file called
FailedAudit_yyyymmdd_hhmmss .log in the Integration Server_directory\instances
\instance_name \logs directory. You can scan the file to find events that were not logged.
Note: The Service logger cannot write the input pipeline to this file, and the API
Gateway logger cannot write request and response payloads to this file.
If a logger uses a JDBC functional alias for which fail-fast mode is configured, the
queue for the loggers must be large enough to hold all the audit logging records it may
receive while the audit logging database is unavailable. For more information about
fail-fast mode for audit logging, see “Queue Size Considerations for Fail-Fast Mode” on
page 38.
Note: If you want multiple Integration Servers to use the same Universal Messaging
queue as the logging queue across a Universal Messaging realm, the Universal
Messaging connection alias used for logging must have the Client Prefix Is
Shared check box selected. This ensures that Universal Messaging includes
the client prefix in the namespace portion of the Universal Messaging queue
name. Each of the Integration Servers in the cluster must use the same
Universal Messaging connection alias.
Integration Server creates a session pool for each Universal Messaging connection
alias that is used by a logger. The session pool contains the Universal Messaging
sessions used by the logger to write an entry to the Universal Messaging queue. For
example, if the error logger uses aliasOne and the service and session loggers use
aliasTwo, Integration Server creates a session pool for aliasOne that is used only by the
error logger, and a session pool for aliasTwo that is shared by the service and session
loggers. You specify the minimum and maximum size of the session pools used to
contain Universal Messaging sessions on the wa.server.audit.um.sessionPool.min and
Note: The Connection Alias field does not apply to the messaging audit logger
because the messaging audit logger cannot be configured to use a Universal
Messaging queue as the audit logging queue.
Note: The Number of Readers field does not apply to the messaging audit logger
because the messaging audit logger cannot be configured to use a Universal
Messaging queue as the audit logging queue. The messaging audit logger
always uses the internal queue as the audit logging queue.
Queue Fail-Fast Mode for Loggers that Use Universal Messaging Queues
Integration Server provides a queue fail-fast mode for loggers that use Universal
Messaging queues. In queue fail-fast mode, loggers writes all entries to their internal
queues rather than to their Universal Messaging queues. Loggers configured as readers
pause their reader threads.
Integration Server enters queue fail-fast mode when Integration Server cannot
connect to the Universal Messaging server at startup, or when the connection to
the Universal Messaging server is lost after Integration Server has started running.
Integration Server tries to reconnect to the Universal Messaging server. For a connection
failure at startup, Integration Server tries to reconnect at the interval specified on
wa.server.audit.um.sessionPool.retryInterval server configuration parameter. For
instructions on seing the parameter, see webMethods Integration Server Administrator’s
Guide.
After the connection is established or re-established, Integration Server exits fail-fast
mode and the loggers resume logging. Reader loggers drain their internal queue by
writing entries from the queues to the destination.
Note: Writing security events during startup makes the startup sequence
significantly slower.
In the Generate Auditing Data on area, choose when Integration Server should log security
events as described in the following table.
Value Description
In the Security Areas to Audit area, select the areas for which to log security-related events.
Note: The logging level for the messaging audit logger can be different than the
logging level for the 0168 Messaging (Enhanced Logging) server log facility
for the server log.
Note: You can only log input pipelines if you are writing service data to an
external RDBMS.
Note: If any of the selected fields you log from the service signature require
a greater length than the default of 512 characters, you can modify the
length of the STRINGVALUE column in the WMSERVICECUSTOMFLDS
table to accommodate a larger value. Keep the following points in mind
when increasing the column length:
If the data wrien to the STRINGVALUE column contains multibyte
characters, data can be truncated in the middle of a character. To avoid
this, Integration Server truncates the last character boundary before the
maximum length of the field, which could result in the data contained
in the column being slightly smaller than the maximum value set in
the audit logging database. To ensure that characters are not truncated,
use the wa.server.audit.dbEncoding server configuration parameter
to specify the character set used by the audit logging database. For
more information about wa.server.audit.dbEncoding, see webMethods
Integration Server Administrator’s Guide.
Integration Server checks the database for column width by
obtaining the metadata and examining the CHAR_OCTET_LENGTH
field of the column. If the database vendor does not supply a
CHAR_OCTET_LENGTH value for the column, Integration Server
uses the default length of 512 characters for the STRINGVALUE
column.
You must restart Integration Server for the new length to take effect.
Whether to associate a custom value with an auditing context. The custom value can
be used to search for service audit records in the Integration Server.
To improve service logging performance, do the following:
Set up customized logging for top-level services only. Avoid logging nested services.
Log on service failure or log on service failure or success. Only choose to log on
service failure or success and start when you need the greatest possible quality of
service.
Logging the pipeline can negatively affect performance, especially if the pipeline
contains large objects, because Integration Server has to make a copy of the pipeline
every time the service is invoked. Store the input pipeline only for top-level services,
and only when absolutely necessary (for example, on failure only). Remove all
unnecessary data from the pipeline to minimize the volume of data to store.
The audit log entries that the Process Engine can write for business process steps
that run services convey the same information as the audit log entries you can write
for services. In addition, the Process Engine can store the input pipeline for services
that are run by process steps. To improve logging performance, avoid logging the
same information twice by coordinating audit logging for services that are invoked
by process steps.
Note: When coordinating logging, keep in mind that when a service is run by a
process step, it is actually called by a wrapper service, making it a nested
service rather than a top-level service.
Input Parameters
id String Optional. The custom value for the current auditing context. Specify
a value that you want to associate with the auditing context.
Output Parameters
None.
The pub.prt.log:logActivityMessages service is stored in the WmPRT package. Its input and
output parameters are described below.
Input Parameters
Message Description
Type
Output Parameters
None.
the developer. In a production environment, you might direct these messages to the
Integration Server administrator.
5. By default, Integration Server uses character set UTF-8 for the messages. If you want
to use a different character set, identify the character set in the Default Email Charset
field.
6. Click Save Changes.
7. By default, Integration Server connects to port 25 on the specified SMTP server. Also
by default, when sending a message, Integration Server provides its own address
(the From Address) as Integration-Server@localhost , where localhost is the Integration
Server host machine. If you want to change either of these properties, follow these
steps:
a. In Integration Server Administrator, go to the Settings > Extended page.
Integration Server Administrator displays a list of Integration Server
configuration properties you can change using this method.
b. Click Edit Extended Settings. In the Extended Settings box, set the properties as
follows:
If this parameter is set to true (basic exception logging), the stack trace is often
truncated and the cause of the exception becomes more difficult to trace. For this reason,
Software AG recommends that you do not set this parameter to true unless you are
executing services that catch exceptions and do not re-issue them.
For more information about this parameter, see webMethods Integration Server
Administrator’s Guide.
Note: If this property is not set, Integration Server uses the time zone of the
hosting Integration Server.
For more information about these parameters, see webMethods Integration Server
Administrator’s Guide.
Note: Integration Server always rotates the audit log for a logger when
the current audit log reaches the maximum size as set by the
wa.server.audit.logRotateSize parameter. Integration Server also rotates
the audit log for a logger after server start up and daily, after midnight.
Integration Server rotates the audit logs after the logger writes data to the
log. Some audit loggers write data to the log immediately after startup or
midnight. Other audit loggers, such as the error logger, do not necessarily
write audit log data at start up or at midnight. Instead, Integration Server
rotates the log when the logger writes data to the log file.
When you subscribe to an audit error event, you can supply a filter to limit the events
that your event handler receives. The filter applies to the concatenated values of the
destination and errorCode fields. The following table shows how you can use filters to
limit the events that your event handler will receive:
This filter Limits the events that the event handler receives to
*YourSearchTerm Events that contain YourSearchTerm at the end of the audit error
event value.
You subscribe to audit error events using pub.event:addSubscriber and then define the
specifications for the audit error event handlers with the pub.event:auditError service. For
more information about these services, see webMethods Integration Server Built-In Services
Reference .
You can indicate whether event handlers for audit error events are invoked
synchronously or asynchronously by using the wa.server.event.audit.async server
configuration parameter. For more information, see webMethods Integration Server
Administrator’s Guide.
transient error. By causing requests that will not succeed to fail quickly, Integration
Server eliminates the time a request spends making retry aempts.
When fail-fast mode is enabled and the JDBC pool alias used by the JDBC functional
alias cannot establish a connection to the database, the JDBC functional alias enters fail-
fast mode. In fail-fast mode:
All aempts by an Integration Server component that uses the JDBC functional alias
to get a database connection will return immediately with a SQLException.
The JDBC function monitors database connectivity. When database connectivity
is restored, the JDBC functional alias exits fail-fast mode. Integration Server
components that use the JDBC functional alias to obtain a database connection will
obtain a connection when one is requested.
Fail-fast mode can improve performance when used with synchronous audit logging.
When a synchronous logger encounters a transient error while aempting to write to the
audit logging database, the ISCoreAudit function, which is used by the logger, aempts
to reconnect and write to the database after waiting the amount of time specified in the
Wait Between Retries field for the logger. The ISCoreAudit function continues to retry
connecting and writing to the database until it succeeds or the makes the maximum
number of retries specified for the logger, which is specified in the Maximum Retries field.
Additionally, if the transient error occurs because the database is unavailable, each
aempt to connect to the database will pause while the logger waits for the connection
aempt to fail. All of the waiting contributes to synchronous audit logging becoming
very slow when the audit logging database is unavailable.
However, if the ISCoreAudit function has fail-fast enabled, the first time that audit
logging fails because the database is unavailable, the affected loggers stop trying to
write to the database. Any loggers that use the functional alias to request a database
connection return with an exception immediately when the logger makes a request
for a database connection. The logger does not make any aempts to retry. After
connectivity is restored, the ISCoreAudit functional alias exits fail-fast mode The affected
loggers resume normal operation. As a result of using fail-fast mode, client threads that
generate audit records do not experience the pauses associated with database connection
timeouts.
Note: For the initial audit log entry that cannot be wrien to the database because of
a transient error that prevents a connection to the database, Integration Server
retries writing the entry according to the Maximum Retries and Wait Between
Retries properties configured for the logger. If connectivity to the database is
not restored before Integration Server exhausts the retries, Integration Server
writes the audit log entry to the FailedAudit log. That is, Integration Server
writes the audit log entry that triggers fail-fast mode for the logger to the
FailedAudit log if Integration Server makes the maximum number of retry
aempts before connectivity to the database is restored.
Where N is the number of seconds for connections to timeout and M is the number of
seconds for queries or updates to timeout, respectively.
For example:
jdbc:wm:dbProvider://your-db-host:1521;ServiceName=your-db-svc;LoginTimeout=5;QueryTimeout=3
These properties are set in the Database URL field of the Settings > JDBC Pools > Connection
Aliases page.
Note: Software AG recommends that you create a separate JDBC Pool Alias for use
by the ISCoreAudit JDBC Functional Alias. This way, the LoginTimeout and
QueryTimeout seings will affect audit logging only.
Overview
The following table lists the type of Audit log data that you can view using Integration
Server Administrator, Monitor, or both.
Documents No Yes
Messaging Yes No
Security Yes No
Sessions Yes No
Tasks* No No
API Gateway No No
transaction**
* For information on viewing logged data for tasks, see webMethods Task Engine
User’s Guide.
** To view logged data for API Gateway transactions, you must open the log
file manually or look up the data in the AGW_EVENT_TXN table. For more
information, see “View the API Gateway Transaction Logs” on page 48.
Monitor links related logged data in its display; for example, for a business process or
business process step, you can see all relevant service, error, and user-defined message
entries. You can also perform a variety of actions from Monitor; for example, if you
logged input pipelines for services, you can edit the pipelines and resubmit the services,
and you can archive or delete audit log data. For complete information, see webMethods
Monitor User’s Guide.
Integration Server Administrator does not link related data for you. You must look
through the individual logs for related data yourself. This chapter explains how to view
audit logs in Integration Server Administrator and change various aspects of the log
displays.
Column Description
Time Stamp Date and time the entry was wrien to the log.
Service Stack Parent services for the service in which the error occurred.
Stack Trace Trace that shows the call sequence leading to the error. To
expand the display of stack trace data, select the Expand Stack
Trace Data check box in the Log display controls area and click
Refresh.
Root Context Context information Monitor uses to connect related entries from
different logs.
Parent Context
Column Description
Current Context
Note: For more information about interpreting the error log and using the log to
help debug services, see webMethods Integration Server Administrator’s Guide.
Column Details
Time Stamp Date and time the entry was wrien to the log.
Error Message If the transaction failed, message that describes the error that
occurred.
Root Context Context information Monitor uses to connect related entries from
different logs.
Parent Context
Current Context
Integration Server writes guaranteed delivery log entries to two logs, one for inbound
transactions and one for outbound transactions. By default, Integration Server
Administrator displays the most recent entries in the inbound guaranteed delivery
transactions log. You can switch to the log entries in the outbound transactions log by
clicking View Guaranteed Delivery Outbound Log.
Column Description
Time Stamp Date and time the entry was wrien to the log.
Column Description
Column Description
Note: You can search the messaging log for all log entries for a particular UUID. On
the Logs > Messaging page, enter the UUID for which you want to search in the
UUID field. Then, click Refresh.
Column Description
Time Stamp Date and time the entry was wrien to the log.
Client Id Network IP address for the client from which the security
event was performed.
Column Description
Security Event Category for the security event that occurred (authentication,
Type authorization, certificates, configuration, and so on).
Column Description
Time Stamp Date and time the entry was wrien to the log.
User Id Integration Server user name of the client that called the service
that generated the log entry.
Server Id Integration Server on which the service that generated the log
entry ran. This is necessary information when Integration Servers
are clustered and writing to a shared RDBMS. The ID can be
DNSname:port or IPaddress:port .
Resubmittable Whether you can resubmit the service from Monitor. You can
resubmit a service if it is a top-level (as opposed to nested)
service and the service’s input pipeline was logged.
Error Message If the service failed, message that describes the error that
occurred.
Root Context Context information Monitor uses to connect related entries from
different logs.
Parent Context
Current Context
For information about viewing service log entries in Monitor, see webMethods Monitor
User’s Guide.
Column Description
Time Stamp Date and time the entry was wrien to the log.
User Id Integration Server user name under which the client connected
for the session.
Client Id IP address of the machine from which the client request was
submied. The word “system” appears for session requests from
Integration Server for operations such as running a scheduled
service or refreshing the display.
RPCs Number of services the client has called so far during the session.
The log file (the flat file). You can open the log file using a text editor. The log
file is located in the Integration Server_directory\instances\instance_name \logs
\APIGateway directory.
The audit table. You can open the audit table using your RDBMS editor. The table
name is AGW_EVENT_TXN. For more information, see the documentation for your
RDBMS editor.
The following table describes the columns in the API Gateway transaction log.
API Name API_NAME Name of the API that generated the log
entry.
API Version API_VERSION Version of the API that generated the log
entry.
Service Name SERVICE_NAME Name of the API that generated the log
entry.
will also affect the Integration Server server log, described in webMethods
Integration Server Administrator’s Guide.
Also by default, the time stamps in the log entries default to local time and display
the time zone. You can change this to the Coordinated Universal Time (UTC) that is
recorded for the entries in the IS Core Audit Log database component.
For more information on server configuration parameters mentioned in the above table,
see webMethods Integration Server Administrator’s Guide
Note: If Integration Server is storing logged data in an external RDBMS, most log
pages offer From: and To: fields that let you choose the entries to display using
a date range. However, using date ranges can slow system performance.