Logging
Access Gateway logs various events that you can forward to a log server or download on demand. As an inline proxy, Access Gateway can generate a large volume of log events that provide important visibility into web traffic. Each persisted log event consumes storage, so the available information depends on the amount of storage allocated.
Many Access Gateway components emit log events. Access Gateway provides application-level and system-level configuration options that enable you to specify which log events to emit. You can set the log verbosity level to filter logs.
The Access Gateway maximum size for log files is 20 gigabytes.
Configure log events
Access Gateway system components and application emit log events. You can choose whether to enable or disable debugging for a component from the Monitor menu of the Command Line Management Console reference.
You can specify the level of log events emitted by system components in the Access Gateway Management console. These components include the Access Gateway UI, management console, NGINX engine, Kerberos, underlying shell scripts, and similar components.
You can configure application debug settings to emit events in debug or info mode. Log verbosity acts as an event filter, which reduces the number of events stored to disk. The default component logging level for new Access Gateway installations is Info. Debug is the default component logging level for Access Gateway2020.12.3 and earlier. During an upgrade, Access Gateway migrates current system values to the new version.
The following diagram details the interaction of system components, applications, and log filtering:
Info is the default logging level for applications. You can use the Access Gateway Admin UI console to enable debug for applications. See Troubleshoot applications.
The following table lists the default logging level for components in Access Gateway. You can set these levels from Monitor > Enable/Disable debug in the Command Line Management Console reference.
|
Component |
Default logging level |
|---|---|
| SimpleSAMLphp | Notice |
| Kerberos | Info |
| Access Gateway UI service‡ | Info |
| Access Gateway Management console service | Info |
| Underlying shell scripts | Info |
‡ The Access Gateway Admin UI console service emits log events based on the Access Gateway Management console debug setting, but isn't filtered by log verbosity.
Log verbosity
Log verbosity lets you specify what level of granularity of events to store, which determines disk resource consumption. Log granularity is a sliding scale, where Debug represents the most granular and Fatal the least.
If you set log verbosity to Fatal, only fatal log events are saved. If you set log verbosity to Error, both fatal and error events are persisted with lower level settings, including all higher level events. Set log verbosity to Debug to store all events. The Debug setting has the greatest impact on storage usage, while Fatal has the least.
The log verbosity setting determines the granularity of logs stored on disk. If logs aren't stored on disk, then admins can't download them and Okta Support can't retrieve them.
When a log level is specified, events below that level are discarded. For example, if the log level is set to Warn, then messages with a lower level, such as Info and Debug, are discarded.
Log verbosity doesn't 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 can be downloaded, regardless of log verbosity setting.
Setting an application to debug overrides the system debug level verbosity for that application. Disable debug mode after troubleshooting the application. Leaving it enabled can rapidly consume storage space if there's a large amount of traffic.
See Troubleshoot applications for more information on enabling and disabling application debug mode.
Forward logs
In high availability clusters, when you add a log forwarder definition to the main admin node, the definition propagates to all worker nodes. Worker nodes then send log events directly to the syslog server.
Log forwarding allows Access Gateway to relay or export logs to external syslog handlers. See Configure log forwarders.
Available since Access Gateway version 2020.04.4
Download logs
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:
- Rotates logs daily.
- Stores log files for a month. Deletes older log files to save disk space.
- Can support other log rotation and archiving schedules. Contact Okta Support to have your configuration updated.