mod_logging

Logs messages to the database and adds log views to the admin.

Logging messages to the database

To persist a log message in the database, enable mod_logging in your Zotonic site. Then, in your code, send the #zlog{} notification:

-include_lib("zotonic_core/include/zotonic.hrl").

some_function() ->
    %% do some things

    z_notifier:notify(
        #zlog{
            user_id = z_acl:user(Context),
            props=#log_email{
                severity = ?LOG_LEVEL_ERROR,
                message_nr = MsgId,
                mailer_status = bounce,
                mailer_host = z_convert:ip_to_list(Peer),
                envelop_to = BounceEmail,
                envelop_from = "<>",
                to_id = z_acl:user(Context),
                props = []
        }},
        Context
    );

E-mail log

The e-mail log is a separate view, which lists which email messages have been sent to which recipients. Any mail that gets sent gets logged here.

This module stores selected log events in the site database and provides admin views and APIs to inspect those logs, including e-mail delivery log entries.

Accepted Events

This module handles the following notifier callbacks:

• observe_acl_is_allowed: Allow access to log resources only for users with the required log-view permissions.

• observe_admin_menu: Add log viewers and log configuration entries to the admin menu.

• observe_search_query: Provide module-specific search query handlers with ACL-aware filtering.

• observe_tick_1h: Delete expired log records during hourly maintenance.

• observe_tick_1m: Cleanup UI log de-duplication hashes and check the database pool health.

• observe_tick_1s: Fetch UI log messages from the circular buffer.

Content-Security-Policy Log

The mod_logging module observes incoming Content-Security-Policy violation reports sent by browsers to the controller_csp_report controller, and logs them in the database with de-duplication based on the report content. Recent CSP violation reports can be viewed in the admin interface.

The most recent CSP violation reports are kept in memory and can be retrieved via the csp_reports/1 API function, which is used by the admin interface to display recent CSP violations without needing to query the database.

Only the most recent 100 unique CSP violation reports are kept in memory to prevent unbounded growth in memory usage. When the limit is exceeded, the oldest report is dropped. For each unique CSP violation, the number of occurrences and the most recent occurrence timestamp are tracked, along with the original policy, the document URL, and the source file and line number of the violation when available.

UI Log

Browser-side UI errors can be posted to this module and are stored in the log_ui table for later inspection in the admin.

To keep a sudden flood of client-side errors from overloading the site, incoming UI events are first written to an in-memory ringbuffer with a fixed size. This means the logging path stays bounded during overload: when the buffer fills up, older buffered messages are overwritten instead of allowing unbounded growth in work or memory usage.

To reduce noise, near-simultaneous duplicate UI errors are also dropped for a short period. The duplicate detection key is based on the error type, message, file, and line, specifically so that the same site problem reported by many different users is coalesced into a single logged event even when user ids, user agents, or other request-specific values differ.

See also

For regular application logging, use Logger instead.