About Access Gateway logging


Access Gateway logs a variety of events which can be forwarded to a logging server or downloaded on demand. As an inline proxy, Access Gateway can generate a large volume of log events which provides important visibility into web traffic. However the number of persisted log events consumes disk resources, presenting a trade off between available information and disk resources.

Many Access Gateway components, including application and system level components, can specify at what level log events are emitted. Specifying which log events are emitted is separate from how log events are filtered. To specify what log events are emitted Access Gateway provides application level and system level configuration.

Topics:

Configuring log events

The Access Gateway Management console can be used to specify the level of log event emitted by system components. System components include the NGINX engine, Kerberos, the Access Gateway UI, the management console, underlying shell scripts and similar components.

The logging interaction diagram details the interaction of system components, applications and log verbosity filtering.

Access Gateway system components and application emit log events. System components are controlled by the Monitor > Enable/Disable debug in the Command Line Management Console reference. Application debug settings control whether application emit log events in either debug or info mode and log verbosity acts as a event filter, reducing the number of events stored to disk.

 

Important Note

Access Gateway component level logging new install vs upgrade behavior:

When being upgraded Access Gateway migrates current system setting values. For component logging, as described below, the default prior to 2020.12.3 is Debug. New installs default to Info.

 

Component Where to change Defaults

System components:

  • SimleSAMLphp
  • Kerberos
  • Access Gateway UI service
  • Access Gateway Management console service
  • Other system components
  • Underlying shell scripts
See Monitor > Enable/Disable debug in the Command Line Management Console reference
  • SimpleSAMLphp(Notice)
  • Kerberos(Info)
  • Events(Error)
  • Access Gateway UI* (Info)
  • Access Gateway Management console(Info)
  • Shell scripts(Info)
Applications The Access Gateway Admin UI console can be used to enable debug for a given application. See the Configure section in Troubleshoot applications for more information. Info
Note

*Note, the Access Gateway Admin UI console service emits log events based on the Access Gateway Management console Enable/disable setting, but is not filtered by log verbosity.

 

Log verbosity

Access Gateway log events are stored locally as well as forwarded to logging servers such as graylog, splunk and others. Log verbosity is a filter for specifying the level of granularity of events stored on disk and can have a considerable impact on disk resource consumption. Log granularity is a sliding scale with Debug representing the most granular and Fatal the least. For example, when set to Fatal only fatal log events are persisted to disk. When set to Error, both fatal and error events are persisted with lower level settings including all higher level events. With Debug all events are stored. Debug has the largest impact on disk use, and Fatal the least.

Important Note

The log verbosity setting dictates what granularity of logs are actually stored on disk. If the logs are not stored on disk, then they will not be present in the logs admins download using Log Download. Likewise, Okta Support won't be able to retrieve them.
Only those messages persisted to disk can be downloaded from Access Gateway. If a higher log level is specified, events below that level are discarded (filtered out). For example if Warn was selected, then any message below Warn( such as Info and Debug) would be discarded.
Note: Log verbosity does NOT impact log forwarding. If a log forwarder is specified all emitted events are forwarded regardless of log verbosity setting.

See Manage log verbosity to specify log verbosity.

Log verbosity and application level debug

Individual applications can be set to debug. Setting an application to debug ignores the system level log verbosity, specifying a level of Debug, but only for log events specific to the application. When an application is set to debug all application specific debug log events are persisted to disk and downloadable, regardless of log verbosity setting.
Be aware: setting an application to debug allows overrides the system debug level verbosity for that particular application and can rapidly consume disk resources.
Be sure to disable debug mode after troubleshooting applications. Leaving debug mode enabled, which ignores Log Verbosity, can quickly fill disk if traffic is high.

Be sure to turn off the Debug mode for an application as soon as you are done troubleshooting the issue. Leaving Debug mode on ignores the Log Verbosity setting and can fill the disk quickly if traffic is high.


See Troubleshoot applications for more information on enabling and disabling application debug mode as well a general application debugging techniques.

Log forwarding

Example common logging architecture showing Access Gateway and a Logging Input Hander.
Note

Note that in high availability clusters, log forwarder definitions are added to the main admin node and propagated to all worker nodes. Worker nodes then send log events directly to the syslog server.

In general log forwarding allows Access Gateway to relay or export logs to external sys log handlers, such as Graylog.

See Configure log forwarders for details of configuring log forwarders.

Log downloading

Example common logging architecture showing Access Gateway and a Logging Input Hander.
  • Allows admins to download log information for an Access Gateway cluster.

See Download logs for details of downloading logs.

Log rotation and archival

Access Gateway:

  1. Rotates logs daily.
  2. Stores the log files for a month and deletes old log files to save disk space.
  3. Can be configured, by Okta Support, to support other log rotation and archival schedules.