[Patch available] --enable-bots: Support Custom Dimensions as replacement for deprecated Custom Variables

[ManuShift]

--enable-bots does not work on Matomo 5.10 (Custom Variables deprecated)

On Matomo 5.10 the CustomVariables plugin is no longer part of core and must be installed separately from the Marketplace. When the plugin is not available, --enable-bots silently fails to store any bot information.. the flag still includes bot traffic, but the _cvar data is discarded by the tracker.

Proposed fix

Extend --enable-bots to optionally accept a Custom Dimension ID:

--enable-bots → existing behavior, backward compatible
--enable-bots=1 → stores the classified bot name in Custom Dimension 1 (recommended for Matomo 5.*)
This adds a built-in bot classification table (GPTBot, Bingbot, ClaudeBot, SemrushBot, etc.) and uses dimension{N} in the tracker request instead of _cvar.

Non-bot visits receive Not a Bot in the dimension, allowing easy segmentation.

Motivation

Custom Dimensions are the official replacement for Custom Variables in Matomo 5 (see deprecation notice). The log importer should reflect this.

[ManuShift]

--- a/import_logs.py
+++ b/import_logs.py
@@ -85,6 +85,7 @@ EXCLUDED_USER_AGENTS = (
     'adsbot-google',
+    'amazonbot',
+    'anthropic-ai',
     'ask jeeves',
     'baidubot',
     'bot-',
     'bot/',
+    'bytespider',
+    'ccbot',
     'ccooter/',
+    'chatgpt-user',
+    'claude-web',
+    'claudebot',
+    'cohere-ai',
     'crawl',
     'curl',
+    'dataforseobot',
+    'diffbot',
     'echoping',
     'exabot',
+    'facebookbot',
     'feed',
+    'google-extended',
     'googlebot',
+    'googleother',
     'ia_archiver',
     'java/',
     'libwww',
     'mediapartners-google',
     'msnbot',
     'netcraftsurvey',
+    'oai-searchbot',
     'panopta',
+    'petalbot',
+    'perplexitybot',
     'pingdom.com_bot_',
     'robot',
     'spider',
     'surveybot',
     'twiceler',
     'voilabot',
     'yahoo',
     'yandex',
+    'youbot',
     'zabbix',
     'googlestackdrivermonitoring',
 )
 
+# Known bot user agent patterns mapped to display names, used with --enable-bots=DIMENSION_ID.
+# Patterns must be lowercase substrings of the user agent string.
+BOT_CUSTOM_DIMENSION_NAMES = [
+    # AI / LLM bots
+    ('GPTBot',               'gptbot'),
+    ('ChatGPT-User',         'chatgpt-user'),
+    ('OAI-SearchBot',        'oai-searchbot'),
+    ('ClaudeBot',            'claudebot'),
+    ('Claude-Web',           'claude-web'),
+    ('Anthropic-AI',         'anthropic-ai'),
+    ('Google-Extended',      'google-extended'),
+    ('GoogleOther',          'googleother'),
+    ('PerplexityBot',        'perplexitybot'),
+    ('Bytespider',           'bytespider'),
+    ('CCBot',                'ccbot'),
+    ('AmazonBot',            'amazonbot'),
+    ('Cohere-AI',            'cohere-ai'),
+    ('YouBot',               'youbot'),
+    ('Diffbot',              'diffbot'),
+    ('FacebookBot',          'facebookbot'),
+    ('DataForSeoBot',        'dataforseobot'),
+    ('PetalBot',             'petalbot'),
+    # Search engine bots
+    ('Googlebot',            'googlebot'),
+    ('AdsBot-Google',        'adsbot-google'),
+    ('Mediapartners-Google', 'mediapartners-google'),
+    ('Bingbot',              'bingbot'),
+    ('MSNBot',               'msnbot'),
+    ('Yahoo-Slurp',          'slurp'),
+    ('DuckDuckBot',          'duckduckbot'),
+    ('Baiduspider',          'baiduspider'),
+    ('YandexBot',            'yandex'),
+    ('SogouBot',             'sogou'),
+    ('Exabot',               'exabot'),
+    ('Wayback-Machine',      'ia_archiver'),
+    # SEO bots
+    ('SemrushBot',           'semrushbot'),
+    ('AhrefsBot',            'ahrefsbot'),
+    ('MJ12bot',              'mj12bot'),
+    ('DotBot',               'dotbot'),
+    ('Rogerbot',             'rogerbot'),
+    ('Blexbot',              'blexbot'),
+    # Social media bots
+    ('FacebookExternalHit',  'facebookexternalhit'),
+    ('Twitterbot',           'twitterbot'),
+    ('LinkedInBot',          'linkedinbot'),
+    ('WhatsApp',             'whatsapp'),
+    ('TelegramBot',          'telegrambot'),
+    ('Slackbot',             'slackbot'),
+    ('Discordbot',           'discordbot'),
+    # Monitoring bots
+    ('Pingdom',              'pingdom'),
+    ('UptimeRobot',          'uptimerobot'),
+    ('Zabbix',               'zabbix'),
+    ('Panopta',              'panopta'),
+    ('NetcraftSurvey',       'netcraftsurvey'),
+    ('StackdriverMonitoring','googlestackdrivermonitoring'),
+]
+
+def _get_bot_name_for_custom_dimension(user_agent):
+    ua = user_agent.lower()
+    for name, pattern in BOT_CUSTOM_DIMENSION_NAMES:
+        if pattern in ua:
+            return name
+    return 'Other Bot'
+
 
 @@ -929,8 +979,13 @@ class OptionParser:
         parser.add_argument(
             '--enable-bots', dest='enable_bots',
-            action='store_true', default=False,
-            help="Track bots. Bot visits will have a Custom Variable set with "
-                 "name='Bot' and value='$Bot_user_agent_here$' (requires the CustomVariables plugin)"
+            nargs='?', const=True, default=None,
+            metavar='DIMENSION_ID',
+            help="Track bots. When used without a value (--enable-bots), bot visits will have a Custom Variable "
+                 "set with name='Bot' and value='$Bot_user_agent_here$' (requires the CustomVariables plugin). "
+                 "When used with a Custom Dimension ID (--enable-bots=1), the bot name is stored in that dimension "
+                 "instead, which is the recommended approach for Matomo 5+ where Custom Variables are deprecated. "
+                 "Non-bot visits receive 'Not a Bot' in the dimension."
         )
 
 @@ -2311,8 +2366,18 @@ class Recorder:
         # handle bot tracking
-        if config.options.enable_bots:
-            if hit.is_robot:
-                hit.add_visit_custom_var("Bot", hit.user_agent)
-            else:
-                hit.add_visit_custom_var("Not-Bot", hit.user_agent)
+        if config.options.enable_bots:
+            try:
+                dimension_id = int(config.options.enable_bots)
+            except (TypeError, ValueError):
+                dimension_id = None
+            if dimension_id is not None:
+                dim_key = 'dimension%d' % dimension_id
+                if hit.is_robot:
+                    hit.args[dim_key] = _get_bot_name_for_custom_dimension(hit.user_agent)
+                else:
+                    hit.args[dim_key] = 'Not a Bot'
+            else:
+                if hit.is_robot:
+                    hit.add_visit_custom_var("Bot", hit.user_agent)
+                else:
+                    hit.add_visit_custom_var("Not-Bot", hit.user_agent)