CA API Gateway 9.1

9.4 9.1

Log Sink Properties

When creating or viewing details about a log sink, the Log Sink Properties appear. Information about the sink is organized across these tabs:
gateway83
When creating or viewing details about a log sink, the Log Sink Properties appear. Information about the sink is organized across these tabs:
  • Basic Settings
  • File Settings
  • Syslog Settings
For more information, see Manage Log/Audit Sinks.
To access the properties for a log sink:
  1. Run the Manage Log Sinks/Audit Sinks task.
  2. Select a log sink and then click [
    Properties
    ]. You can also click [
    Create
    ] to enter the properties for a new log sink. The Log Sink Properties appear.
  3. Configure each tab in the dialog as necessary. See below for a complete description of each tab.
  4. Click [
    OK
    ] when done.
Configuring the [Base Settings] tab
The [
Base Settings
] tab defines properties common to both File and Syslog sinks. Complete this tab as follows:
Field
Description
Name
If creating a new log sink, enter a name for the log sink here. If editing a log sink, the existing name is displayed here and cannot be changed.
The log sink name is restricted to ASCII letters and numbers, underscores, and hyphens. Non-English single byte and multi-byte characters are not supported.  
Enabled
Select this check box to enable the log sink.
Clear this check box to disable the log sink.
Description
Optionally enter or modify the description of the log sink.
Type
Choose the type of log sink from the drop-down list:
  • File
    : The logged messages will be stored in a file, defined in the [
    File Settings
    ] tab.
  • Syslog
    : The logged messages will be forwarded to a central repository, as defined in the [
    Syslog Settings
    ] tab.
Severity Threshold
Choose the severity threshold for information to be recorded by this sink. Only information at this level or higher will be processed. Choose All to include events from every severity threshold.
To learn more about how the severity threshold in log sinks work, see "Understanding Logging Thresholds" in the
CA API Gateway Administrators Manual
.
Filters
Configure the filters for the log sink to control which messages are output to the sink. By combining several filters, you can indicate with precision which events will be logged.
  • To define a new filter, click [
    Add
    ] and then complete the filter details. See Configure Log Sink Filters below for details on each of the different filter types.
  • To delete a filter from the list, select it and then click [
    Remove
    ].
You may remove multiples filters at once by holding down the [
Ctrl
] key to select the filters.
If an item in the filter list has been deleted or is inaccessible (that is, the user does not have permission to access the entity), "Not Found/Inaccessible" will be shown next to the entity name; for example:
Folder=Not Found/Inaccessible '-2:12345678'
where "-2" is an internal code for the entity type and "12345678" is an internal identifier for the entity.  
Security Zone
Optionally choose a security zone. To remove this entity from a security zone (security role permitting), choose "No security zone".
For more information about security zones, see Understanding Security Zones.
This control is hidden if either: (a) no security zones have been defined, or (b) you do not have Read access to any security zone (regardless of whether you have Read access to entities inside the zones).
Configuring Log Sink Filters
You can configure the following filter types for a log sink:
Filter Type
Description
Category
Select the category(ies) of
API Gateway
 log information to be output by the log sink.
Hold down the [
Ctrl
] key to select more than one category.
  • Audits
    : This is information gathered from the
    API Gateway
     auditing subsystem. For more information, see Message Auditing.
  • Gateway Log
    : This is information gathered from the
    API Gateway
     logging subsystem.
  • Traffic Log
    : This is information for each request/response that is processed by the
    API Gateway
    .  
At least one Category filter must be created in order for the log sink to work correctly.
Client IP
Enter the IP address of the client to be output by the log sink.
Folder
Select the folder(s) to be output by the log sink. All items within that folder (including any subfolders) will be included in the related log sink (as if you had manually selected all the services and policies).
Any logging events that are not generated in relation to an item (service or policy) within the selected folder(s) will not be included in the related log sink.
Selecting the root folder will include log events from all your services and policy fragments, including the contents of all subfolders. For more information, see Organizing Services and Policies into Folders.
Package
Enter the name of the package to be output by the log sink. CA Support will typically provide you with specific package names.
The package can be the name entered in the Add Audit Detail assertion.
Policy
Select the policies to be output by the log sink.
At least one policy (fragment, global, or internal) must exist before this filter can be used. For more information, see Working with Service Policies.
Service
Select the services to be output by the log sink. Only log messages associated with that service will be included in the log sink.
For more information, see Services and Policies.
Transport
  1. From the drop-down list, choose which transport Type should be output to the log sink: Email Listener, JMS Connection (Inbound only), or Listen Port. The items that have been defined for the type are listed.
  2. In the Name box, select the items to include.
    Hold down the [
    Ctrl
    ] key to select more than one item.
User
  1. Search for the users to be output by the log sink. For information on using the search interface, see Searching Identity Providers.
  2. In the Search Results box, select the users to include.
    Hold down the [
    Ctrl
    ] key to select more than one user.
Configuring the [File Settings] tab
The following configuration options are available for logs of type "File": 
Tab
Description
Maximum File Size
Enter the maximum size per log file, in KB. Once the maximum is reached, the system rotates to the next log file. The minimum file size is 1KB, while the maximum is 1GB (1048576KB).  The default is 1024.
Log Files to Keep
Enter the number of log files to keep, from 1 to 100. The default is 2.
(1) The combined maximum file for all logs is 5GB. (Maximum File Size x Log Files to Keep). (2) If you keep only one log file, it will be purged when its maximum size is reached.
Format
Choose the format to write log messages:
  • Raw
    : Contains only the logged message; this is most suitable for traffic logging. Example of a Raw message:
Boot process complete.
  • Standard
    : The default format, recommended for general use. Example of a Standard message:
Dec 5, 2007 3:49:27 PM 10 com.l7tech.server.BootProcess
INFO: Boot process complete.
  • Verbose
    :  A verbose format, useful for debugging but not recommended for production environments due to potential performance impact. Example of a Verbose message:
Dec 5, 2007 3:49:27 PM 10 com.l7tech.server.BootProcess start
INFO: Boot process complete
Roll logs based on time period
Select this check box to roll the log files based on time interval. The file size settings are disabled when this is selected.
Clear this check box to roll the log files based on file size.
Rolling Interval
When rolling logs are based on time interval, choose the frequency from the drop-down list.
  • Hourly
    : Select this to rotate the log file on an hourly basis. The rotation occurs at the top of each hour.
  • Daily
    : Select this to rotate the log file on a daily basis. The rotation occurs at midnight.
The date format for each type of rotation is as follows:
  • Daily
    : yyyy-MM-dd
  • Hourly
    : yyyy-MM-dd-HH
For example, a sink named "TEST" will have a file named "TEST.2012-10-23.log" for a daily rotation.
Time-based rotation may create very large log files, especially if the sink is configured to log a large amount of information. It is best to keep the amount of data being logged to a minimum.
Configuring the [Syslog Settings] tab
The following configuration options are available for logs of type "Syslog": 
Tab
Description
Protocol
Select the protocol to use: TCP (plain), UDP, or SSL. The default is TCP.
Host
Define the hosts to receive the log file. You can enter multiple hosts to support Syslog failover. The
API Gateway
 uses a "ordered sticky with failover" strategy, beginning with the first host, then moving to subsequent hosts upon failure. If the
API Gateway
 is restarted, the first host on the list is used.
  • To add a host, click [
    Add
    ] and then enter the hostname or IP address for the Syslog server, followed by the port number: <host>:<port>.
  • To remove a host from the list, select it and then click [
    Remove
    ].
  • To modify host details, select it and then click [
    Edit
    ].
To reposition the host in the list, select it and then click either [
Move Up
] or [
Move Down
].
Facility
Enter the facility number to log as, from 0 to 23. The default is 1. For assistance on the facility number, contact your Syslog administrator.
Format
Choose the format to write log messages:
  • Raw
    : Contains only the logged message; this is most suitable for traffic logging. Examples of Raw messages:
Sep 14 10:44:05 localhost SSG[101]: Authenticated on Internal Identity Provider
Sep 14 10:44:05 localhost SSG[101]: User 'admin' logged in from IP '127.0.0.1'.
  • Standard
    : The default format, recommended for general use. Example of a Standard message:
Sep 14 10:44:56 localhost SSG[117]: INFO com.l7tech.server.admin.AdminSessionManager: Authenticated on Internal Identity Provider
Sep 14 10:44:56 localhost SSG[117]: INFO com.l7tech.server.admin.AdminLoginImpl: User 'admin' logged in from IP '127.0.0.1'.
  • Verbose
    :  A verbose format, useful for debugging but not recommended for production environments due to potential performance impact. Example of a Verbose message:
Sep 14 10:45:56 localhost SSG[129]: [SyslogLogSink] INFO com.l7tech.server.admin.AdminSessionManager authenticate: Authenticated on Internal Identity Provider
Sep 14 10:45:56 localhost SSG[129]: [SyslogLogSink] INFO com.l7tech.server.admin.AdminLoginImpl login: User 'admin' logged in from IP '127.0.0.1'.
Log Hostname
Select this check box to include the
API Gateway
 hostname in the logged information. This setting is turned on by default, but you may need to clear the check box to avoid duplication with certain Syslog servers.
Character Set
Select the character set to log in from the drop-down list: UTF-8, LATIN-1, ASCII. The default is UTF-8.
Timezone
Select the time zone for logging. The default is to use the existing system settings.
SSL Settings
This section is available only if the selected Protocol is "SSL".
  • Use Client Authentication
    : When connecting using SSL, select this check box to present a certificate to the server during the SSL handshake, if one is requested. Clear this check box to never present a certificate, even if one is requested. Note that access may be denied in this case.
  • Keystore
    : From the drop-down list, select the keystore from which to retrieve the certificate. Used only if client certificates are used.
Send a Test Message
Click this button to send a test message to the Syslog sink. Use this to verify the settings.

Content feedback and comments