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.
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.
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|
|See Monitor > Enable/Disable debug in the Command Line Management Console reference||
|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, 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.
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.
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.
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.
- Allows admins to download log information for an Access Gateway cluster.
See Download logs for details of downloading logs.
- Rotates logs daily.
- Stores the log files for a month and deletes old log files to save disk space.
- Can be configured, by Okta Support, to support other log rotation and archival schedules.