Log your own events

Developers can add their own events to the Pastmark log with one function. The events show in the log like normal Pastmark events.

The function #

pastmark_log_event( $event_type, $action, $args );

Parameter	Required	What it is
$event_type	Yes	The group of the event, for example my_plugin_sync.
$action	Yes	The action, for example completed.
$args	No	An array with more data. See below.

The function returns the new event ID. It returns false if the event type or action is empty, if the site’s exclusions block the event, or if saving fails.

The $args array #

Key	What it is
message	The text shown in the log.
object_type	The type of the item, for example sync_job.
object_id	The ID of the item.
severity	info, warning, error, critical or debug. The default is info.
context	An array with any extra data.
before_data	The value before the change.
after_data	The value after the change.
integration	The source label. The default is custom.
user_id	The user who did it. The default is the current user.

Example #

add_action( 'my_plugin_sync_done', function ( $count ) {
    if ( function_exists( 'pastmark_log_event' ) ) {
        pastmark_log_event( 'my_plugin_sync', 'completed', array(
            'message'  => sprintf( 'Synced %d records from Acme CRM.', $count ),
            'severity' => 'info',
            'context'  => array( 'records' => $count ),
        ) );
    }
} );

Good to know #

• Call the function on init or later. Pastmark adds it on the plugins_loaded hook, so it does not exist before that.
• Always check function_exists( 'pastmark_log_event' ). Then your code keeps working when Pastmark is not active.
• Your events follow the site’s exclusions, for example excluded users and IP addresses.
• Your events are always recorded. They do not have an on/off switch in User Activity → Events.
• Pastmark hides passwords, tokens and keys in context, before_data and after_data. It does not change your message, so do not put secrets in the message.

REST API #

You can also add an event with a POST request to /wp-json/pastmark/v1/logs. The user must be able to manage options (an administrator).