Controlling Activity Logging with Hooks

coreActivity provides hooks for choosing what to track and for integrating with the logging lifecycle. This guide groups the hooks by purpose. For the event and log concepts used here, see Components and Events and How Activity Logging Works.

Before you begin

These examples are PHP code for a custom plugin or a must-use plugin. Register callbacks early, before coreActivity initializes the relevant component or fires the action. A must-use plugin is one way to make early registration predictable.

Test on a staging site and use your own site-specific identifiers. An enabled event and an active logging switch are still required for normal logging.

Filters receive a value and must return the value that subsequent callbacks and coreActivity should use. Actions notify callbacks that a particular point has been reached; returning a value from an action does not change the event. WordPress passes only the number of arguments specified in the last argument to add_filter() or add_action().

Exclude a group of objects

When the same rule should apply to a whole group, use a component’s exclusion filter. The coreactivity_post_do_not_log_post_types filter receives post-type names excluded by the Posts component. Add to the supplied array so that you retain the plugin’s existing exclusions and changes made by other callbacks:

add_filter( 'coreactivity_post_do_not_log_post_types', function ( $post_types ) {
    // Replace this example with a post type registered on your site.
    $post_types[] = 'my_temporary_item';

    return array_unique( $post_types );
} );

This affects the Posts component; it should not be assumed to exclude every event involving the same content in other components. To exclude taxonomies from term activity, use coreactivity_term_do_not_log_taxonomies. To choose which user metadata keys the Users component monitors, use coreactivity_user_meta_fields_to_monitor. For choices available in the interface, see Events and Activity Settings.

Decide whether to skip one event

Use coreactivity_skip_log for a decision based on the event and its supplied data. It runs after the main logging switch is checked but before coreActivity fills in default request fields or checks for duplicates. Only a return value of true skips the event.

The following example skips successful login entries for one example service account. Replace the ID and use this only if that omission matches your audit requirements:

add_filter( 'coreactivity_skip_log', function ( $skip, $event_id, $event, $data, $meta ) {
    if ( $skip === true ) {
        return true;
    }

    return $event
        && $event->component === 'coreactivity/user'
        && $event->event === 'login'
        && (int) ( $data['user_id'] ?? 0 ) === 123;
}, 10, 5 );

The example preserves an earlier callback’s decision to skip. At this point $data and $meta are the values supplied by the event; fields such as the request context may not yet have been added. Suppressing an event means it will not be available in logs or notifications, so use narrow conditions.

For a persistent event-wide change rather than a per-entry decision, use the Events panel or coreactivity_change_event_status(). That function accepts a component code, event code, and either active or inactive; it returns false for an invalid status or an event it cannot find.

Respond after an entry is recorded

coreactivity_event_logged fires after a successful write and passes the new log ID, the prepared main data, metadata, and event object. The following callback delegates only successful login entries to a separate site integration:

add_action( 'coreactivity_event_logged', function ( $log_id, $data, $meta, $event ) {
    if ( $event->component === 'coreactivity/user' && $event->event === 'login' ) {
        do_action( 'my_site_coreactivity_login_recorded', $log_id, $data['user_id'] ?? 0 );
    }
}, 10, 4 );

The my_site_coreactivity_login_recorded action is an example integration point in your own code; it does nothing until you attach a callback to it. Keep callbacks fast, handle any data carefully, and avoid creating an unbounded loop by causing another event that triggers the same callback.

For a single event, the dynamic logged-event action combines the component and event codes. For example, the Users component’s login event uses coreactivity_event_logged_coreactivity/user_login. It receives the same four arguments. The slash and hyphen characters in component and event codes are part of the hook name.

coreactivity_event_log_failed runs if the database log write fails; it receives the data, metadata, and event object, with no log ID. It does not report entries skipped by a filter, duplicate detection, or the main logging switch.

Other related lifecycle actions

The component registration, event registration, and tracking-ready actions receive the activity manager during plugin preparation. They are useful when building an integration that registers components or events; inspect the relevant registration methods and reference posts for the plugin version you support.

For changes to WordPress metadata, coreActivity also emits added, updated, and deleted hook families. Replace the scope placeholder with post, comment, term, or user. These metadata actions report the underlying change; they are not confirmation that a corresponding coreActivity log entry was stored.

Continue with Customizing Log Displays and Notifications for hooks that operate after data has been collected.