Skip to content

Module Settings

Complete guide to configuring the Visitors module settings available in the admin interface.

Configuration Overview

Access module settings at: Configuration → System → Visitors (/admin/config/system/visitors)

Available Settings

Visitor Tracking

Track Visitors

Setting: disable_tracking Type: Boolean (radio buttons) Default: false (Enabled) Options: - Enabled: Track visitors to the site - Disabled: Turn off all visitor tracking

Controls whether visitor tracking is active globally.

Tracking Scope

Page Visibility Settings

Pages to Track

Setting: visibility.request_path_pages Type: Textarea Default: Empty

Specify which pages to track using Drupal path patterns. Enter one path per line.

Examples:

<front>
/blog
/blog/*
node/*

Path patterns: - * character is a wildcard - <front> is the front page - /blog for specific pages - /blog/* for all pages under /blog

Tracking Mode

Setting: visibility.request_path_mode Type: Radio buttons Options: - All pages except those listed (0) - Exclude specific pages - Only the listed pages (1) - Include only specific pages

Role Visibility Settings

Role-Based Tracking Mode

Setting: visibility.user_role_mode Type: Radio buttons Options: - Add to the selected roles only (0) - Add to every role except the selected ones (1)

Roles to Track

Setting: visibility.user_role_roles Type: Checkboxes Default: Empty array

Select which user roles should be tracked (or excluded, depending on the mode above).

User Account Settings

User Account Tracking Mode

Setting: visibility.user_account_mode Type: Radio buttons Options: - Track all users (0) - Track only users with opt-out permission (1) - Do not track users with opt-out permission (2)

Exclude User 1

Setting: visibility.exclude_user1 Type: Checkbox Default: false

Exclude the site's first user (admin) from tracking.

Privacy

Use analytics cookies

Setting: cookies Type: Checkbox Default: false

Off by default. When this is off, the tracker calls disableCookies() and does not set _pk_id, _pk_ses, or _pk_ref. An open visit is matched by browser fingerprint and IP, so people who share a browser and network can be counted as one visitor. IP anonymization makes that fingerprint weaker. Turn this on to store a visitor id in a cookie.

Anonymize IP addresses

Setting: ip_anonymize Type: Checkbox Default: false

Store a masked IP address on new visits. Existing visits keep the address already recorded. The selected location plugin receives that stored address.

IP mask length

Setting: ip_mask_length Type: Radio buttons Default: 1

How much of the address to remove when anonymization is on:

  • 1: last IPv4 octet (192.168.100.0), or an IPv6 /64
  • 2: last two IPv4 octets (192.168.0.0), or an IPv6 /48
  • 3: last three IPv4 octets (192.0.0.0), or an IPv6 /32

Location

Location plugin

Setting: location_plugin Type: Radio buttons Default: browser_language

How the place on a new visit is set.

  • None (none): store no country, city, or coordinates.
  • Browser language (browser_language): use the region on the first Accept-Language value. en-US stores the United States. A language with no region stores nothing.

Another module can add a location plugin. It appears in this list. IP geolocation is not included in Visitors.

Entity Counter Settings

Counter Status

Setting: counter.enabled Type: Checkbox Default: true

Enable or disable the entity visit counter functionality.

Entity Types to Count

Setting: counter.entity_types Type: Checkboxes Default: ['node']

Select which entity types should have visit counters: - Node: Content pages - User: User profiles - Term: Taxonomy terms - Other entity types: As available

Track User ID

Setting: track.userid Type: Checkbox Default: true

Track the user ID of authenticated users in visit data. When this is off, the tracker does not send a user id and the stored value is NULL.

Pseudo-anonymize User ID

Setting: track.userid_anonymize Type: Checkbox Default: false

Shown when user id tracking is on. Store a stable 32 character pseudonym instead of the Drupal user id. The same person keeps the same value on this site. Existing visits are left unchanged.

Data Retention

Log Retention Period

Setting: flush_log_timer Type: Select dropdown Default: 0 (Never)

Automatically discard visitor logs older than the specified time:

Options: - Never (0) - Keep all data - 1 hour (3600) - 3 hours (10800) - 6 hours (21600) - 9 hours (32400) - 12 hours (43200) - 1 day (86400) - 2 days (172800) - 3 days (259200) - 1 week (604800) - 2 weeks (1209600) - 1 month 3 weeks (4838400) - 3 months 3 weeks (9676800) - 1 year (31536000) - 13 months (34214400)

Note: Requires a correctly configured cron maintenance task.

Bot Data Retention

Setting: bot_retention_log Type: Select dropdown Default: 0

How to handle bot and crawler visits:

Options: - Keep bot data (0) - Store bot visits normally - Discard bot data (-1) - Don't store bot visits at all - Time-based retention - Same options as log retention above

Display Settings

Script Type

Setting: script_type Type: Select Default: minified

Which version of the tracking JavaScript to use: - Minified: Compressed version for production - Full: Uncompressed version for development

Configuration Examples

Basic Site Configuration

# Basic tracking setup
disable_tracking: false
flush_log_timer: 604800  # 1 week retention
bot_retention_log: 0     # Keep bot data
track:
  userid: true
counter:
  enabled: true
  entity_types: ['node']

High-Privacy Configuration

# Privacy-focused setup
disable_tracking: false
flush_log_timer: 86400   # 1 day retention only
bot_retention_log: -1    # Discard bot data
visibility:
  user_account_mode: 2   # Don't track users with opt-out
  exclude_user1: true    # Exclude admin user
track:
  userid: false          # Don't track user IDs

Content-Only Tracking

# Track only content pages
visibility:
  request_path_mode: 1   # Only listed pages
  request_path_pages: |
    <front>
    node/*
  user_role_mode: 1      # Exclude selected roles
  user_role_roles:
    administrator: administrator
counter:
  enabled: true
  entity_types: ['node']

Development Configuration

# Development site setup
disable_tracking: false
flush_log_timer: 3600    # 1 hour retention
bot_retention_log: 0     # Keep bot data for testing
script_type: full        # Unminified JavaScript

Configuration Management

Export Current Settings

# Export visitors configuration
drush config:export --destination=/tmp/config

# View current settings
drush config:get visitors.settings

Import Configuration

# Import configuration
drush config:import --source=/path/to/config

# Set individual values
drush config:set visitors.settings disable_tracking false

Settings in Code

// Get configuration
$config = \Drupal::config('visitors.settings');
$tracking_disabled = $config->get('disable_tracking');

// Programmatically update settings
\Drupal::configFactory()->getEditable('visitors.settings')
  ->set('flush_log_timer', 86400)
  ->save();

Validation and Constraints

Required Settings

  • All settings have sensible defaults
  • No settings are strictly required
  • Tracking can be completely disabled

Setting Interactions

  • Page visibility: Mode determines how the pages list is interpreted
  • Role visibility: Mode determines how the roles list is interpreted
  • User tracking: Account mode overrides role settings
  • Data retention: Requires cron to be configured

Performance Considerations

High-Traffic Sites

  • Shorter retention periods: Reduce database size
  • Exclude admin users: Focus on visitor data
  • Limit entity types: Track only necessary entities
  • Discard bot data: Reduce noise in analytics

Storage Management

  • Regular cleanup: Configure appropriate retention periods
  • Monitor database growth: Especially with high traffic
  • Cron scheduling: Ensure cleanup tasks run regularly

Troubleshooting Settings

Common Issues

No Data Being Collected

  • Check disable_tracking is set to false
  • Verify page visibility settings aren't too restrictive
  • Confirm user/role visibility allows tracking
  • Check cron is running for data processing

Too Much Data

  • Reduce flush_log_timer for shorter retention
  • Set bot_retention_log to -1 to discard bot data
  • Limit counter.entity_types to essential types only
  • Exclude admin users with exclude_user1

Performance Problems

  • Implement shorter data retention periods
  • Consider excluding high-traffic user roles
  • Monitor database size and optimize accordingly

Next Steps


Note: All settings are stored in the visitors.settings configuration object and can be managed through the admin interface or programmatically via Drupal's configuration API.