Working with Log Sinks and Debug Logs

This topic describes the procedures for common scenarios involving log sinks and debug logs for the .
gateway93
This topic describes the procedures for common scenarios involving log sinks and debug logs for the
Layer7 API Gateway
.
Log sinks are not suitable for the Container Gateway. Layer7 recommends using other third-party tools for managing, storing, and aggregating logs. See the latest reference architecture for more information.
Contents:
2
IMPORTANT:
Avoid creating too many log sinks, as this affects Gateway performance. CA Technologies recommends no more than three log sinks for best performance. Any detailed filtering should be handled by external systems.
Creating and Using a Custom Log sink
To create a log sink for all messages from a custom logger:
  1. Run the Manage Log/Audit Sinks task and create a new log sink.
  2. Complete the properties for the log sink:
    • In the
      Base Settings
      tab, define at least one filter:
      Filter Type:
      Category
      Filter Details:
      Select
      Gateway Log
    • Define another filter:
      Filter Type:
      Package
      Filter Details:
      Enter the name of your custom logger:
      com.l7tech.log.custom.<customLoggerName>
      Make note of the
      <customLoggerName>
      string.
  3. Configure an Add Audit Detail Assertion for your custom logger.
    1. Set the
      Category
      to
      Log
      . This directs the log messages to the log system.
    2. Select the
      Custom logger name
      check box.
    3. Enter your
      <customLoggerName>
      string in the field following
      com.l7tech.log.custom
      .
    4. Select an appropriate
      Level
      for the logging.
During policy execution, audit details are sent to the log sink for the specified custom logger.
Creating Log Sink for Service(s)
To create a log sink for all messages from a service:
During policy execution, only messages related to the selected services are sent to the log sink.
Debugging a Client IP
To create a log sink for all messages from a client IP:
  1. Use the Manage Log/Audit Sinks task to create a new log sink that filters by a specific client IP address.
  2. In the Log Sink Properties, set the severity threshold to FINE.
  3. Set the severity level for the appropriate package to FINE in the
    log.levels
    cluster property for the appropriate loggers—for example, "<packageName>.level=FINE". For assistance with package names, contact Support.
During policy execution, only messages related to the specified client IP address are sent to the log sink.
Debugging SSL/TLS
To enable SSL/TLS debugging:
  1. Set the
    io.debugSsl
    cluster property to "true" to enable SSL/TLS debugging globally.
  2. Perform one of the following:
    • Gateway version 10.0 CR2 or earlier - Set the
      log.stdoutLevel
      cluster property to FINE and append the line STDOUT.level=FINE  to the
      log.levels
      cluster property.
    • Gateway version 10.0 CR3 or newer - Set the
      log.stderrLevel
      cluster property to FINE and append the line STDERR.level=FINE to the
      log.levels
      cluster property.
To create a log sink file configured for SSL/TLS debugging:
  1. Run the Manage Log/Audit Sinks task and create a new log sink.
  2. Use the following properties:
    • Name:
      ssl
    • Description:
      SSL debug logs
    • Severity Threshold:
      FINE
    • Filters:
      • Filter Type =
        Category
        , Filter Details =
        Gateway Log
      • Enter one of the additional filter settings:
        • Gateway version 10.0 CR2 or earler - Filter Type =
          Package
          , Filter Details =
          STDOUT
        • Gateway verion 10.0 CR3 or newer - Filter Type =
          Package
          , Filter Details =
          STDERR
  3. Select the
    Enabled
    option and click
    OK
    to save the log sink file.
  4. Configure the JVM from the Gateway privileged shell:
    1. Locate the system.properties file at
      /opt/SecureSpan/Gateway/node/default/etc/conf/system.properties
    2. Append
      javax.net.debug=<options>
      to the system.properties file.
    3. Set javax.net.debug=<options> according to the options specified in Java 8 Secure Socket Extension (JSSE) Reference Guide > Debugging Utilities.
      Example values for the option include
      javax.net.debug=all
      OR
      javax.net.debug=ssl:handshake:verbose
      Do NOT use the option
      help.
      It may cause some providers to terminate the JVM.
  5. Save the changes to the system.properties file.
  6. Restart the Gateway:
    # service ssg restart
  7. Verify SSL debug logging is enabled by consuming a service using an HTTPS Listen Port.
During policy execution, the SSL/TLS output related to the consumption is sent only to the configured log sink. (This assumes that no other log sinks are currently configured to allow "FINE" messages.)
If debug trace logging has been enabled for HTTP(S), be aware that this can log passwords, including passwords used to log in to the Policy Manager. Use this capability with caution. For assistance on enabling debug trace logging in HTTP(S), contact Support.