Flight Logs

Key Features

• Capture Gravity Forms log messages through the gform_pre_log_message hook
• Store logs in a custom database table instead of relying only on flat log files
• Generate a unique Request ID for each PHP request
• Correlate related requests with Trace IDs across form submissions and async processing
• Enrich log entries with structured context such as request details, timing, and memory usage
• Parse log messages to extract source, form ID, entry ID, and feed ID when possible
• Browse logs in a dedicated admin UI under Forms → Logs
• View individual request details and multi-request trace timelines
• Filter requests by log level, plugin, search term, date, stashed status, and shared status
• Stash important logs to protect them from automated cleanup
• Create public share links for traces or requests
• Configure expiring share links or never-expiring links
• Export request or trace logs as Markdown
• Add a Flight Logs meta box to Gravity Forms entry detail pages
• Automatically clean up old non-stashed logs based on retention settings
• Enforce a maximum record cap for stored logs
• Delete all non-stashed logs from plugin settings

Requirements

• WordPress 5.9+
• PHP 7.4+
• Gravity Forms 2.9.26+
• Gravity Forms logging enabled for at least one plugin

Optional Requirements

• WP-Cron enabled for automatic retention cleanup and share expiration cleanup
• Gravity Forms async or feed processing features if you want multi-request trace correlation
• Public sharing enabled in plugin settings if you want shareable trace or request URLs

Installation

1. Upload the plugin to your /wp-content/plugins/ directory, or install it using your preferred deployment workflow.
2. Activate the plugin from the WordPress Plugins screen.
3. Ensure the Gravity Forms Logging Add-On is installed and active.
4. Enable logging for at least one plugin so Gravity Forms emits log events.
5. The plugin will create its custom tables automatically during installation or upgrade.

Using the Plugin

The plugin works by listening for Gravity Forms log events and storing them as structured records.

1. Activate Gravity Forms Flight Logs.
2. Make sure Gravity Forms logging is enabled.
3. Perform actions that generate Gravity Forms logs, such as form submissions or feed processing.
4. Go to Forms → Logs to view captured requests and traces.
5. Use filters, trace views, stash actions, share links, and Markdown exports as needed.

Global Plugin Settings

The plugin settings page is located at Forms → Settings → Flight Logs.

Available settings include:

• Minimum Log Level — only capture logs at or above the selected severity
• Retention Period — how long to retain non-stashed logs
• Maximum Records — safety cap for total stored log records
• Enable Public Share Links — allow creation of unauthenticated read-only log URLs
• Share Link Duration — controls how long public links remain valid

How It Works

Flight Logs intercepts Gravity Forms log messages via the gform_pre_log_message action.

For each message, the plugin:

• checks the configured minimum log level
• parses the message for structured metadata
• generates or resolves a Request ID
• resolves a Trace ID when available
• enriches the entry with request context
• stores the structured record in the custom log table

This allows logs to be viewed as grouped requests or as end-to-end traces spanning multiple requests.

Key Concepts

Request ID

A Request ID is generated for each PHP request. All log entries generated during that request share the same Request ID, making it easier to inspect one page load, AJAX request, cron task, or processing cycle.

Trace ID

A Trace ID correlates related activity across multiple requests. For example, a form submission may trigger later async processing, and those requests can all be tied together through the same trace.

Stashing

Stashing marks log entries as protected so they are excluded from automated retention cleanup. This is useful for preserving important debugging data.

Share Links

Share links create public read-only URLs for a trace or request. Sharing is disabled by default and must be explicitly enabled in settings.

Admin UI

Access the log viewer at Forms → Logs.

The interface provides:

• List View — paginated and filterable request list
• Request Detail View — full log detail for a single request
• Trace Timeline View — grouped multi-request trace view
• Status Filters — All, Stashed, and Shared
• Search and Filtering — by level, plugin, message text, and date range

Entry Integration

The plugin adds a Flight Logs meta box to the Gravity Forms entry detail page.

This meta box can:

• display the trace ID associated with the entry
• link directly to the submission trace in the log viewer
• indicate when trace logs have already expired or been deleted

Log Capture Behavior

The plugin captures log messages only when Gravity Forms logging is active.

During capture, it can store:

• plugin slug
• log level
• cleaned log message
• parsed source method or class
• request ID
• trace ID
• elapsed request time
• structured context payload

Message Parsing

The plugin includes heuristic parsing for common Gravity Forms log formats.

It can attempt to extract:

• source class or method
• form ID
• entry ID
• feed ID

Because parsing relies on regex patterns and message conventions, non-standard third-party log formats may not always be parsed correctly.

What Gets Stored

Each stored log entry may include:

• timestamp
• request ID
• trace ID
• plugin slug
• log level
• message text
• context JSON
• parsed source
• elapsed milliseconds
• stashed status

Database

The plugin creates two custom tables:

• {prefix}_gf_flight_log — stores log entries
• {prefix}_gf_flight_log_shares — stores public share links

The log table supports indexing for request ID, trace ID, plugin and level, timestamp, and stashed state.

The shares table stores:

• token
• type (request or trace)
• target ID
• created timestamp
• expiration timestamp

Share Links

If public sharing is enabled, admins can generate a public URL for either a request or a trace.

Share link behavior includes:

• unique token generation
• optional expiration
• support for request and trace views
• lazy expiration checks
• scheduled cleanup of expired links
• automatic stashing of shared logs

Exporting Logs

The plugin supports exporting request or trace data as Markdown.

Exports can be triggered from:

• admin AJAX download actions
• public share pages when download is requested

Export filenames use a format similar to:

• flight-log-request-xxxxxxxx.md
• flight-log-trace-xxxxxxxx.md

Retention and Cleanup

The plugin automatically removes old non-stashed logs based on configured retention settings.

Cleanup behavior includes:

• deleting records older than the retention threshold
• enforcing a maximum record count
• preserving stashed entries
• cleaning expired share links during scheduled cleanup

This cleanup is intended to run through WP-Cron on a daily schedule.

Delete Logs

The settings page includes a Danger Zone section.

From there, authorized users can:

• see the current total record count
• delete all non-stashed log entries
• preserve stashed entries during deletion

Capabilities and Permissions

The plugin defines custom capabilities for access:

• gravityforms_flightlogs
• gravityforms_flightlogs_uninstall

These capabilities are used for settings access and protected actions such as stashing, sharing, revoking shares, and downloading logs.

Public Share Page Behavior

When a valid share token is present in the URL, the plugin can render a public read-only trace or request page without requiring WordPress authentication. However, please bear in mind that log files can sometimes capture and expose sensitive information.

If sharing is disabled, the token is invalid, or the link has expired, the public view is not shown.

Uninstallation

When the plugin is deleted through WordPress:

1. The custom log table is dropped.
2. The custom shares table is dropped.
3. Plugin settings and version options are removed.
4. The cleanup cron event is unscheduled.

Development

PHP Tooling

The repository includes Composer scripts for:

• phpcs
• phpcbf
• phpstan
• phpunit
• install-tests
• semgrep

Build and Packaging

The repository also includes npm scripts for:

• release
• package
• publish

Notes and Limitations

• This is a Gravity Labs Add-On and is marked experimental
• It is not covered by standard Gravity Forms support
• Message parsing is heuristic and depends on current log message conventions
• Log capture depends on Gravity Forms logging being enabled
• Public share links may expose raw diagnostic data and should be used carefully
• Automatic cleanup depends on WP-Cron running correctly
• Trace correlation is strongest when entries or lifecycle hooks provide enough information to resolve trace IDs

Troubleshooting

If logs are not appearing as expected:

• Confirm Gravity Forms is installed and active
• Confirm logging is enabled under Forms → Settings → Logging
• Confirm the plugin’s minimum log level is not filtering out expected messages
• Generate a new form submission or other Gravity Forms activity to create log events
• Check that the custom log tables were created successfully
• Confirm WP-Cron is working if retention cleanup or share expiration cleanup is expected
• If trace links are missing on entries, confirm logging was active during submission
• If public shares are not working, confirm sharing is enabled in plugin settings

License

GPL-2.0+