Configuration
Learn about all available configuration options for the Insights plugin.
Control Panel
You can manage configuration settings through the Control Panel by visiting Settings → Insights.
Settings
You can define a multi environment aware config in /config/insights.php. Settings defined in the config file override control panel settings.
enabled
Enable or disable all tracking globally.
return [
'*' => [
'enabled' => true,
],
'staging' => [
'enabled' => false, // disable tracking on staging
],
]
respectDoNotTrack
Honor the browser's Do Not Track (DNT) header. When enabled, requests with DNT: 1 header are not tracked.
return [
'*' => [
'respectDoNotTrack' => true, // default
],
]
excludeLoggedInUsers
Skip tracking for authenticated Craft users. Useful to exclude your own team from analytics.
return [
'*' => [
'excludeLoggedInUsers' => false, // default
],
'production' => [
'excludeLoggedInUsers' => true, // don't track logged in users in production
],
]
excludedIpRanges Pro
IP addresses or CIDR ranges to exclude from tracking.
return [
'*' => [
'excludedIpRanges' => [
'192.168.1.1', // single IP
'10.0.0.0/8', // CIDR range
'172.16.0.0/12', // private network
],
],
]
excludedPaths
URL paths to exclude from tracking. Uses prefix matching.
return [
'*' => [
'excludedPaths' => [
'/admin', // matches /admin, /admin/*, etc.
'/cpresources',
'/actions',
'/api', // exclude API endpoints
'/preview', // exclude preview pages
],
],
]
geoIpDatabasePath
Path to the MaxMind GeoLite2-Country database for country tracking.
return [
'*' => [
'geoIpDatabasePath' => '@storage/geoip/GeoLite2-Country.mmdb', // default
],
]
Country data is collected for all editions. Lite users who upgrade to Pro will have historical data available. Without the GeoIP database, country tracking will be silently skipped. See Installation for setup instructions.
dataRetentionDays
Number of days to retain analytics data. Valid range: 1-730 days.
return [
'*' => [
'dataRetentionDays' => 365, // default: keep data for 1 year
],
]
autoCleanup
Automatically delete data older than dataRetentionDays. Cleanup runs daily via Craft's garbage collection.
return [
'*' => [
'autoCleanup' => true, // default
],
]
Cleanup is irreversible. Old data is permanently deleted.
useQueue
Process tracking events asynchronously via Craft's queue system. Recommended for production to minimize page load impact.
return [
'*' => [
'useQueue' => true, // default
],
'dev' => [
'useQueue' => false, // process synchronously in development
],
]
queueJobTtr
Time to reserve (TTR) for queue jobs in seconds. This is the maximum time a job can run before being considered stalled. Valid range: 60-3600 seconds.
return [
'*' => [
'queueJobTtr' => 300, // default: 5 minutes
],
]
processTrackingJobPriority
Priority for tracking queue jobs. Lower number = higher priority. Craft's default priority is 1024.
return [
'*' => [
'processTrackingJobPriority' => 20, // default
],
]
maxRetryAttempts
Maximum number of retry attempts for failed queue jobs. Valid range: 0-10.
return [
'*' => [
'maxRetryAttempts' => 3, // default
],
]
realtimeTtl
How long (in seconds) a visitor is considered "active" for real-time tracking. Valid range: 60-900 seconds.
return [
'*' => [
'realtimeTtl' => 300, // default: 5 minutes
],
]
defaultDateRange
Default date range for the analytics dashboard. Available values: today, 7d, 30d, 90d, 12m.
return [
'*' => [
'defaultDateRange' => '30d', // default
],
]
showRealtimeWidget
Show the real-time visitors widget on the dashboard.
return [
'*' => [
'showRealtimeWidget' => true, // default
],
]
showEntrySidebar
Display analytics statistics in the entry editor sidebar.
return [
'*' => [
'showEntrySidebar' => true, // default
],
]
logLevel
Control the verbosity of plugin logging. Available values: default, debug.
return [
'*' => [
'logLevel' => 'default',
],
'dev' => [
'logLevel' => 'debug', // more detailed logs in development
],
]
Custom Queue
By default, Insights uses Craft's main queue. For high-traffic sites, you can configure a separate queue to prevent analytics jobs from blocking other important jobs.
Add the insightsQueue component to your config/app.php:
<?php
// config/app.php
return [
'bootstrap' => ['insightsQueue'],
'components' => [
'insightsQueue' => [
'class' => \craft\queue\Queue::class,
],
],
];
Then run the custom queue separately:
# Run once
php craft insights-queue/run
# Run as daemon
php craft insights-queue/listen --verbose
If insightsQueue is not configured, Insights automatically falls back to Craft's default queue. No additional configuration required.
External Database Pro
Store analytics data in a separate database to keep your main Craft database lean. This is useful for high-traffic sites or when you want to isolate analytics data.
Configuration
- Add the
insightsDbcomponent to yourconfig/app.php:
<?php
// config/app.php
use craft\helpers\App;
return [
'components' => [
'insightsDb' => [
'class' => \craft\db\Connection::class,
'dsn' => App::env('INSIGHTS_DB_DSN'),
'username' => App::env('INSIGHTS_DB_USER'),
'password' => App::env('INSIGHTS_DB_PASSWORD'),
'tablePrefix' => App::env('INSIGHTS_DB_TABLE_PREFIX') ?: '',
],
],
];
- Add environment variables to your
.env:
INSIGHTS_DB_DSN="mysql:host=localhost;port=3306;dbname=insights"
INSIGHTS_DB_USER="insights_user"
INSIGHTS_DB_PASSWORD="secret"
INSIGHTS_DB_TABLE_PREFIX=""
- Enable external database in
config/insights.php:
return [
'*' => [
'useExternalDatabase' => true,
],
]
Database Commands
# Test connection
php craft insights/database/test
# Show connection status
php craft insights/database/status
# Create tables in external database
php craft insights/database/migrate
# Migrate existing data from Craft DB to external DB
php craft insights/database/migrate-data
php craft insights/database/migrate-data --force # Clear target first
php craft insights/database/migrate-data --delete-source # Remove from Craft DB after
External database is a Pro feature. The insightsDb component must be configured before enabling useExternalDatabase.
Multi-Environment Example
A complete example showing environment-specific configuration:
<?php
// config/insights.php
use craft\helpers\App;
return [
'*' => [
'enabled' => true,
'respectDoNotTrack' => true,
'excludeLoggedInUsers' => false,
'excludedPaths' => ['/admin', '/cpresources', '/actions'],
'dataRetentionDays' => 365,
'autoCleanup' => true,
'useQueue' => true,
'defaultDateRange' => '30d',
],
'dev' => [
'useQueue' => false,
'logLevel' => 'debug',
],
'staging' => [
'enabled' => App::env('INSIGHTS_ENABLED') ?? false,
],
'production' => [
'excludeLoggedInUsers' => true,
],
];