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.

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.