Configure API Gateway logging and events

Overview

You can use the Logs and Events view in the API Gateway Manager web console to view and search the API Gateway log and event files. The Logs view enables you to configure and manage following API Gateway logging options:

Domain Audit: Displays management changes at the API Gateway domain level (for example, updates to API Gateway configuration, topology, login, or deployment). The domain audit log is configured by default.
Trace Log: Records detailed diagnostic and debugging information on API Gateway instance execution (for example, services starting or stopping, and messages sent through the API Gateway). The trace log is configured by default. You should submit trace log files when raising issues with Oracle Support.
Transaction Log: Records the message transaction log entries generated by each API Gateway filter as the message passes through the filter (for example, success, failure, or abort). You can configure different log output destinations.
Access Log: Provides a summary of the HTTP request and response messages in Apache HTTP Server format. You can configure the access log per path.

This topic explains how to view and configure the domain audit log, transaction log and events, and access log. For details on configuring the trace log, see Configure API Gateway tracing.

Configure audit logs per domain

View in API Gateway Manager
View the domain audit log file
Customize domain audit log output

The domain audit log captures management changes in the API Gateway domain that are written by the Admin Node Manager and by API Gateway instances. This includes details such as API Gateway configuration changes, logins, deployments, user, or topology changes. For example, user Joe deployed a new configuration, admin user created a new group, or user Jane has read deployment data. The domain audit log is enabled by default. However, you can configure filtering options such as the number of events displayed, time interval, and event type.

For example, the displayed event types include the following:

Configuration
Service
Application
Topology
User store
Key Property Store (KPS)

View in API Gateway Manager

To view domain audit log events in the API Gateway Manager web console, perform the following steps:

In the API Gateway Manager, select Logs > Domain Audit.
Configure the number of events displayed in the Max results per server field on the left. Defaults to 1000.
Configure the Time Interval for events. Defaults to 1 day.
Click the Filter button to add more viewing options (Event Type or Groups and Servers).
Click Apply when finished.

View the domain audit log file

Alternatively, you can view contents of the domain audit log file. For example, the following shows the file for the Admin Node Manager:

<install-dir>/apigateway/logs/audit.log

For example:

{"timestamp":1397724538713,"message":"User 'admin' connected with 3 defined user roles",
   "eventId":107,"metadata":{"userID":"admin"}}
{"timestamp":1397724539638,"message":"Deployment data read by user 'admin'","eventId":1037,
   "metadata":{}}
{"timestamp":1397726232992,"message":"Performing domain audit lookup for service 
   'Node Manager on cayote.acme.com' over a 24h interval","eventId":9,"metadata":
   {"userID":"admin","serviceID":"nodemanager-1"}}
{"timestamp":1397726235233,"message":"Performing domain audit lookup for service 
   'Node Manager on cayote.acme.com' over a 24h interval","eventId":9,"metadata":
   {"userID":"admin","serviceID":"nodemanager-1"}}

The default maximum size for the audit log file is 1 MB. A new file is created when the server instance restarts. The maximum of files stored in the logs directory is 50. When this maximum number of log files is reached, the files roll over, and the oldest files are deleted.

Customize domain audit log output

Domain audit rule syntax

You can also customize and filter the contents of the output in the logs/audit.log file. For example, for security purposes, you can redact sensitive information, such as specific query parameters that contain customer details, passwords, or credit card information. Alternatively, you can prevent the file from becoming flooded with specific messages, such as GET API calls for metrics.

You can use the following file to customize the output of the domain audit log file:

<install-dir>/apigateway/conf/apiaudit.xml

This file enables you to specify rules to filter out sensitive details or noisy API calls. The default file contains some predefined rules (for example, filtering out metrics). You can use this file to specify whether an entry is made to the domain audit log file, and to specify the contents of the text in the output message.

For example, the following entry specifies an outputMessage for all GET messages on the ops/setserviceconfig path:

<apiauditrule>
   <method>GET</method>
   <path>^ops/getserviceconfig$</path>
   <pathMatch>MATCHES</pathMatch>
     <queryArgs>*</queryArgs> 
     <outputMessage>Update configuration for service '${serviceName}': 
        ${queryArgs}</outputMessage>
</apiauditrule>

The following example specifies no outputMessage for GET messages on the api/monitoring/metrics path:

<apiauditrule>
   <method>GET</method>
   <path>api/monitoring/metrics</path>
   <pathMatch>BEGINS_WITH</pathMatch> 
</apiauditrule>

Domain audit rule syntax

The rules in the apiaudit.xml file analyze the traffic passing through the API Gateway router service, and control the entries in the domain audit log. These rules are checked in the order specified in the file. The method, path and pathMatch elements determine whether a rule is triggered. If a rule is triggered, all subsequent rules are ignored. You should specify all rules in order of priority (for example, most sensitive or noisy first).

The domain audit rule elements are described as follows:

Element	Description
`method`	Required comma-separated list of HTTP methods (`GET`, `PUT`, and so on). Use the `*` wildcard to specify all methods.
`path`	Required regular expression that specifies a URL path (for example, `^api/domainaudit/search$`). Use the `*` wildcard to specify all paths.
`pathMatch`	Required path matching statement (one of the following: `MATCHES`, `BEGINS_WITH`, `ENDS_WITH`, `CONTAINS`, `DOES_NOT_CONTAIN`, `IS`, `IS_NOT`, `DOES_NOT_MATCH`).
`queryArgs`	Option to specify query string arguments output in the log. To redact certain arguments, you must explicitly list only the arguments you wish to show in a comma-separated list. Leaving this blank or omitting the element specifies that no query arguments are displayed. The * wildcard specifies that all query arguments are available for printing.
`outputMessage`	Option to specify the message output printed in the log. Leaving this blank or omitting the element means that no entry is made in the domain audit log for this rule.

For more details and example rules, see the contents of the conf/apiaudit.xml file.

Configure transaction logs per API Gateway

The API Gateway provides detailed transaction logging for specific message filters (for example, the request, the time of the request, where the request was routed to, and the response returned to the client). You can configure transaction logging to a number of different locations:

Text file
XML file
Database
Local syslog
Remote syslog
System console

Transaction logging is not configured by default. To configure where transaction logging information is sent, perform the following steps:

In the Policy Studio tree, select the Server Settings > Logging > Transaction Log.
Specify the required settings on the appropriate tab (for example, Text File, Database, or XML File).
When finished, click Apply Changes at the bottom right.
Click the Deploy button in the toolbar to deploy your settings to the API Gateway.

For details on configuring all the available options, see the topic on Transaction Log settings.

Configure transaction logs per filter

You can also configure the transaction log level and log message for a specific filter as follows:

In the Policy Studio tree, click any policy to display it in the canvas on the right (for example, QuickStart > Virtualized Services > REST > GetProducts.
Double-click a filter on the canvas to edit (for example, Connect to Heroes REST Service).
Click Next to display the Transaction Log Level and Message screen.
Select Override Logging Level for this filter.
Select the log levels required for troubleshooting (for example, Fatal and Failure).
Enter any non-default log messages if required.
Click Finish.
Click the Deploy button in the toolbar to deploy your settings to the API Gateway.

For more details on transaction logging for specific message filters, see the API Gateway User Guide.

Configure access logs per path

The access log provides summary of the HTTP request and response messages that are written to an access log file in the format used by Apache HTTP Server. For example, this includes details such as the remote hostname, user login name, and authenticated user name.

Access logging is not configured by default. To configure the access log output, perform the following steps:

In the Policy Studio tree, select the Server Settings > Logging > Access Log.
Specify the required settings (for example, remote hostname, user login name, and authenticated user name).
When finished, click Apply Changes at the bottom right.
Click the Deploy button in the toolbar to deploy your settings to the API Gateway.

For details on configuring all the available options, see Access Log settings.

Manage API Gateway events

The Events view in API Gateway Manager enables you to view and search the contents of the following API Gateway events:

Transaction: When transaction logging is configured per filter, this displays an in-memory list of transaction log events. A transaction log destination does not need to be enabled for the in-memory list of events to be updated. For more details, see the section called “Configure transaction logs per filter”
Alerts: When Alert filters are configured in your policies, this displays an in-memory list of alert events. An alert destination does not need to be enabled for in-memory list of events to be updated.
SLA Alerts: When SLA Alert filters are configured in your policies, this displays an in-memory list of Service Level Agreement (SLA) alert events. An alert destination does not need to be enabled for in-memory list of events to be updated.

For details on how to configure Alert filters and SLA Alert filters in your policies, see the API Gateway User Guide.

Oracle® Fusion MiddlewarePart 5. Troubleshoot your API Gateway installation