Skip to content

Latest commit

 

History

History
168 lines (131 loc) · 6.68 KB

README.md

File metadata and controls

168 lines (131 loc) · 6.68 KB

Craft Activity Log

activity_logs

This plugin provides a detailed activity log for incoming web requests.

Requirements

This plugin requires Craft CMS 4.x or later.

Installation

  1. Include the package:
composer require matfish/craft-activity-log
  1. Install the plugin:
php craft plugin/install activity-logs

Usage

Once the plugin is installed Craft will start recording all requests, excluding Control Panel AJAX requests (except for Login request). Data points include:

  • URL
  • Action (if it is an action request)
  • User
  • Site
  • Query
  • Payload
  • IP
  • User agent
  • Method (GET,POST,PUT or DELETE)
  • Is CP (Control Panel) Request?
  • Is AJAX request?
  • Response Code
  • Execution Time
  • Timestamp (Created at)

The user can control which request types to record under the Settings page.

Screenshot 2023-07-05 122540

Advanced Request Filtering

For a more fine-grained control, on top of request type settings, you can use the requestFilter setting:

  1. In your project create a config/activity-logs.php file
  2. Define a requestFilter callback that returns a boolean. E.g:
<?php
return [
 'requestFilter' => function () {
        if ($this->isAjax) {
            return $this->isActionRequest && count($this->actionSegments) === 2 && $this->actionSegments[1] === 'save-draft';
        }

        return true;
    }
]

The $this object in this context will be an instance of the request class (craft\web\Request). Only requests satisfying the condition (returning true) will be recorded.

View Filtering

While reqestsFilter allows you to control which requests are being recorded to the database, at times, you may wish to filter some recorded requests from the viewable audit trail for specific users, either due to permissions or in order to reduce the cognitive load of parsing unnecessary data. This can be accomplished using the viewFilters setting, following the same structure as the example below:

'viewFilters'=> [
        [
            'users'=>['admin'], // Username(s) of relevant users
            'filters'=>[ // Filters to be applied for said users:
                'isCp'=>true, // Only Control Panel requests
                'isAction'=>true, // Only Action requests 
                'isAjax'=>false, // Only page Requests
                'siteId'=>1, // or (e.g) [1,2] for multiple sites
                'actions'=>[ // Only display those actions 
                    ['user-settings','save-group'] // full action array, can be found under `actionSegments` in `activitylog` table
                ]
            ]
        ]

Users not included in any of the array items will be shown the full audit trail as per usual.

Action Requests

Controller Actions are automatically labelled using a naming convention. E.g ["fields","save-group"] will become "Fields Save Group". This is relevant for the "Action" search dropdown on the Logs page and for the Actions widget on the Statistics page. In addition the user can optionally override this convention by giving explicit labels to recorded actions under the Actions page.

Screenshot 2023-07-05 123908

Audit Trail UI

Requests can be viewed and filtered under the Activity Log page. Click the "Columns" button to add or remove columns from the table on the fly:

craft4 test_adminos_activity-logs_site=default

Note that most columns have a dedicated filter attached to them (except for date range at the top of the table).

Click the "+" sign on the left-hand side of each row to expand a child row containing the full request data:

craft4 test_adminos_activity-log_site=default (4)

Payload Filtering

The plugin automatically replaces the CSRF Token and any payload key which contains the word "password" with a "[filtered]" mask. You can add additional keys to be filtered in two ways:

a. General: Add it to the filterPayloadKeys on the setting file:

 'filterPayloadKeys'=>[
        'cvv','long_number'
    ]

b. Specific: If you only want to filter a certain key from specific requests you can use the filterPayloadCallbacks array instead, e.g:

 'filterPayloadCallbacks'=> [
     function(\craft\web\Request $request) {
        if (str_contains($request->getUrl(),'add-credit-card')) {
                return 'cvv';
         }

        // Don't add any key to the list
        return false;
      }
]

Payload Search

By default, searching in request payload is disabled in order to remove unnecessary clutter from the table controls. You can enable it in the Settings Page. Screenshot 2023-07-05 122958

Note that you need to press enter or leave the field for the search to be triggered.

Statistics

activity_logs_stats The statistics page provides some insights gleaned from the raw data. Similar to Craft's dashboard widgets, you can add and remove widgets, as well as change the order and the column span. The data can be filtered by:

  1. Date Range
  2. Site Id
  3. User Id
  4. Is Ajax?
  5. Is Cp? (Control Panel Request)

If you have an idea for additional widget(s) please open a new feature request.

Pruning Data

You can prune (delete) data before that last X days using the following console command:

php craft activity-logs/logs/prune --days=30

If omitted the days option defaults to 30 days.

Note: If you are running the command as a cron job add the --interactive=0 option to disable manual confirmation

License

You can try Activity Log in a development environment for as long as you like. Once your site goes live, you are required to purchase a license for the plugin. License is purchasable through the Craft Plugin Store.

For more information, see Craft's Commercial Plugin Licensing.