Log Sink Properties

When you create or view details about a log sink on the , the Log Sink Properties appear. Information about the sink is organized across these tabs:
gateway91
When you create or view details about a log sink on the
API Gateway
, the Log Sink Properties appear. Information about the sink is organized across these tabs:
  • Basic Settings
  • File Settings
  • Syslog Settings
To access log sink properties:
  1. 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.
  2. Configure each tab in the dialog as necessary.
  3. Click [
    OK
    ] when done.
Contents:
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 you are creating a new log sink, enter a name for the log sink here. If you are 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 are stored in a file that is defined in the [
    File Settings
    ] tab.
  • Syslog
    : The logged messages are 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 is 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 Gateway Logging Levels and Thresholds.
Filters
Configure the filters for the log sink to control which messages are sent to the sink. By combining several filters, you can indicate with precision which events are logged.
  • To define a new filter, click [
    Add
    ] and then complete the filter details. See "conf" below this table for details on each of the different filter types.
  • To delete a filter from the list, select it and then click [
    Remove
    ].
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 Gateway log information to be output by the log sink.
  • Audits
    : This is information gathered from the Gateway auditing subsystem. For more information, see About Message Auditing.
  • Gateway Log
    : This is information that is gathered from the Gateway logging subsystem.
  • Traffic Log
    : This is information for each request/response that is processed by the Gateway.  
Create at least one Category filter 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 one or more folders to be output by the log sink. All items within that folder (including any subfolders) are included in the related log sink. The effect is the same 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) are not 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 Organize Services and Policies into Folders.
Package
Enter the name of the package to be output by the log sink. CA Support can 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.
Service
Select the services to be output by the log sink. Only log messages that are associated with that service are included in the log sink.
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.
User
  1. Search for the users to be output by the log sink. For information about using the search interface, see Search Identity Providers.
  2. In the Search Results box, select the users to include.
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 hourly. The rotation occurs at the top of each hour.
  • Daily
    : Select this to rotate the log file daily. 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" has 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 Gateway uses an "ordered sticky with failover" strategy, beginning with the first host, then moving to subsequent hosts upon failure. If the 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 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. Selecting this option may result in access being denied.
  • 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.