Matomo использует конфигурационные файлы для управления поведением системы, настройки параметров окружения и контроля работы плагинов и встроенных функций.
Основным конфигурационным файлом является Matomo Core config — он выступает «скелетом» всей установки Matomo и задает базовые параметры работы системы. Поверх этих значений могут применяться настройки отдельных плагинов.
В этой статье разберем:
- где находятся основные конфигурационные файлы Matomo;
- как устроена структура конфигурации;
- как задаются параметры для плагинов;
- как правильно переопределять значения по умолчанию.
Это поможет лучше понимать внутреннюю архитектуру Matomo и безопасно настраивать систему под свои задачи. К сожалению, описать все настройки не представляется возможным — в статье освещу только самые главные и важные, с которыми столкнется примерно 80% разработчиков и настройщиков Matomo Tag Manager.
Настройки Matomo Core
Основной конфигурационный файл Matomo называется config.ini.php. Он создается автоматически во время установки системы. Этот файл содержит пользовательские настройки и переопределяет значения из более обширного системного файла global.ini.php, который поставляется вместе с Matomo. Расположение config.ini.php зависит от того, как именно развернута система.
Matomo Cloud
В облачной версии Matomo серверная конфигурация управляется самой платформой. Если необходимо изменить какие-то параметры и такая возможность поддерживается в Cloud-версии, следует обратиться в поддержку Matomo.
Matomo On-Premise
При самостоятельном размещении Matomo файл конфигурации обычно находится в каталоге:
/config/config.ini.php
Например, на типичном Linux-сервере путь может выглядеть так:
/var/www/html/matomo/config/config.ini.php
Если Matomo запускается в контейнерной инфраструктуре (например, Docker), файл конфигурации может храниться вне директории приложения — например, в отдельном volume.
Важно! Файл config.ini.php содержит чувствительные параметры системы (ключи, настройки подключения к базе данных и др.). Редактировать его должен только администратор сервера. Кроме того, рекомендуется:
- ограничить права доступа к файлу;
- запретить его чтение веб-сервером извне;
- не размещать резервные копии конфигурации в публичных каталогах.
Списки плагинов в конфигурации
Помимо основных параметров системы, файл config.ini.php содержит два списка плагинов:
[PluginsInstalled] — раздел показывает все плагины, установленные в системе.
[Plugins] — содержит только активированные, реально используемые плагины.
Как устроена конфигурация плагинов Matomo
На первый взгляд конфигурация плагинов может показаться немного технической, поскольку она напрямую связана с PHP-кодом Matomo.
В исходниках плагинов параметры конфигурации обычно задаются через константы вида:
KEY_…
DEFAULT_…
Эти константы используются только внутри PHP-кода и не копируются напрямую в config.ini.php.
В конфигурации нужно использовать значение, указанное после знака равенства. Чаще всего это число, строка, имя переменной в формате snake_case.
Например:
show_unique_visitors
custom_reports_max_dimensions
Как устроены пары KEY/DEFAULT
Во внутреннем коде Matomo параметры часто задаются парами:
KEY_… → имя настройки.
DEFAULT_… → значение по умолчанию.
При переопределении настройки в config.ini.php нужно использовать имя параметра из KEY и новое значение вместо DEFAULT.
Формат строки конфигурации всегда одинаковый: имя_параметра = значение
Пример 1: отключение уникальных посетителей в плагине
Допустим, плагин содержит следующие настройки:
KEY_SHOW_UNIQUE_VISITOR = show_unique_visitors
DEFAULT_SHOW_UNIQUE_VISITOR = 1
Значение 1 означает, что отображение уникальных посетителей включено.
Чтобы отключить его, нужно добавить в config.ini.php:
[PluginName]
show_unique_visitors = 0
После этого соответствующая функция будет отключена.
Пример 2: ограничение количества измерений в Custom Reports
Рассмотрим другой пример: ограничение количества измерений (dimensions) в плагине Custom Reports.
В исходниках плагина есть следующие настройки:
KEY_MAX_DIMENSIONS = custom_reports_max_dimensions
DEFAULT_MAX_DIMENSIONS = 3
По умолчанию пользователь может добавить до трех измерений в кастомный отчет. Если нужно ограничить это число до двух, в config.ini.php добавляется:
[CustomReports]
custom_reports_max_dimensions = 2
После сохранения файла перезапуск Matomo не требуется — система проверяет конфигурацию при каждом запуске. Теперь пользователи смогут добавлять не более двух измерений в Custom Reports.
Конфигурация плагинов Matomo
Ниже приведены параметры конфигурации для отдельных плагинов Matomo. Все настройки добавляются в файл config.ini.php в соответствующем разделе плагина.
Плагин Crash Analytics
Плагин Crash Analytics используется для отслеживания и анализа сбоев приложений. Он помогает находить проблемы стабильности и улучшать качество программного обеспечения.
Delete Crash Data Older Than
Определяет срок хранения данных о сбоях. Старые записи автоматически удаляются, чтобы не разрасталась база данных.
По умолчанию данные хранятся 90 дней.
KEY_DELETE_CRASH_DATA_OLDER_THAN = delete_crash_data_older_than
DEFAULT_DELETE_CRASH_DATA_OLDER_THAN = 90
Datatable Archiving Maximum Rows Crashes
Определяет максимальное количество строк в основных отчетах по сбоям.
KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASHES =
datatable_archiving_maximum_rows_crashes
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASHES = 500
Datatable Archiving Maximum Rows Crash Toptable
Ограничивает количество строк в основной таблице топ-сбоев. Например:
- наиболее частые типы ошибок;
- самые распространенные причины падения приложения.
KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_TOPTABLE =
datatable_archiving_maximum_rows_crash_toptable
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_TOPTABLE = 500
Datatable Archiving Maximum Rows Crash Subtable
Определяет максимальное количество строк во вложенных таблицах отчета (subtables), например для детальной информации по конкретному типу ошибки.
KEY_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_SUBTABLE =
datatable_archiving_maximum_rows_crash_subtable
DEFAULT_DATATABLE_ARCHIVING_MAXIMUM_ROWS_CRASH_SUBTABLE = 100
Consider Crash New After N Days
Определяет, сколько времени сбой считается новым. Это удобно для разделения:
- недавно появившихся ошибок,
- старых, уже известных проблем.
По умолчанию 2 года.
KEY_CONSIDER_CRASH_NEW_AFTER_N_DAYS = consider_crash_new_after_n_days
DEFAULT_CONSIDER_CRASH_NEW_AFTER_N_DAYS = 365 * 2
Crash Ranking Query Limit
Определяет лимит строк для SQL-запросов при построении рейтингов сбоев. Этот параметр влияет:
- на полноту анализа,
- производительность архивации.
KEY_CRASH_RANKING_QUERY_LIMIT = crash_archiving_ranking_query_row_limit
DEFAULT_CRASH_RANKING_QUERY_LIMIT = 50000
Плагин Custom Reports
Плагин Custom Reports позволяет создавать собственные аналитические отчеты на основе выбранных метрик и измерений. Это полезно, когда стандартных отчетов Matomo недостаточно для решения задач аналитики или BI.
Always Show Unique Visitor
Определяет, должны ли уникальные посетители всегда отображаться в кастомных отчетах. По умолчанию эта функция отключена.
KEY_ALWAYS_SHOW_UNIQUE_VISITORS = custom_reports_always_show_unique_visitors
DEFAULT_ALWAYS_SHOW_UNIQUE_VISITORS = 0
Max Execution Time
Определяет максимальное время выполнения запроса при генерации кастомного отчета. Если значение равно 0, ограничение по времени отсутствует. Это может быть полезно для защиты сервера от слишком тяжелых запросов.
KEY_MAX_EXECUTION_TIME = custom_reports_max_execution_time
DEFAULT_MAX_EXECUTION_TIME = 0
Disabled Dimensions
Позволяет отключить определенные измерения (dimensions) для использования в кастомных отчетах. По умолчанию все измерения доступны.
KEY_DISABLED_DIMENSIONS = custom_reports_disabled_dimensions
DEFAULT_DISABLED_DIMENSIONS = ""
Evolution Unique Force Aggregation
Принудительно включает агрегацию уникальных метрик при построении отчетов динамики (evolution reports) для нескольких временных периодов. По умолчанию отключено.
KEY_EVOLUTION_UNIQUE_FORCE_AGGREGATION =
custom_reports_periods_force_aggregate_report_unique_metrics_evolution
DEFAULT_EVOLUTION_UNIQUE_FORCE_AGGREGATION = ""
Validate Report Content All Websites
Определяет, должна ли система проверять корректность содержимого отчетов для всех сайтов в Matomo. По умолчанию включено.
KEY_VALIDATE_REPORT_CONTENT_ALL_WEBSITES =
custom_reports_validate_report_content_all_websites
DEFAULT_VALIDATE_REPORT_CONTENT_ALL_WEBSITES = 1
Rearchive Reports in Past Last N Months
Определяет, за сколько прошедших месяцев Matomo должен пересчитать архивы отчетов, если структура отчета была изменена.
Например:
custom_reports_rearchive_reports_in_past_last_n_months = 6
В этом случае будут пересчитаны отчеты за последние 6 месяцев.
KEY_REARCHIVE_REPORTS_IN_PAST_LAST_N_MONTHS =
custom_reports_rearchive_reports_in_past_last_n_months
Max Dimensions
Определяет максимальное количество измерений (dimensions), которые можно использовать в одном кастомном отчете.
По умолчанию три измерения.
KEY_MAX_DIMENSIONS = custom_reports_max_dimensions
DEFAULT_MAX_DIMENSIONS = 3
Archive Maximum Rows Custom Dimensions Default
Определяет максимальное количество строк, сохраняемых в таблицах измерений кастомных отчетов.
По умолчанию 50 строк.
KEY_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS_DEFAULT =
datatable_archiving_maximum_rows_custom_reports_dimensions_default
DEFAULT_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS_DEFAULT = 50
Archive Maximum Rows Sub Table Custom Dimensions Default
Определяет максимальное количество строк во вложенных таблицах (subtables) кастомных отчетов.
По умолчанию 10 строк.
KEY_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS_DEFAULT =
datatable_archiving_maximum_rows_subtable_custom_reports_dimensions_default
DEFAULT_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS_DEFAULT = 10
Archive Maximum Rows Custom Dimensions
Позволяет задавать лимиты строк для отдельных измерений кастомных отчетов. Это расширяемый параметр, который задается для каждого измерения отдельно.
KEY_ARCHIVE_MAXIMUM_ROWS_CUSTOM_DIMENSIONS =
datatable_archiving_maximum_rows_custom_reports_dimensions_
Archive Maximum Rows Sub Table Custom Dimensions
Определяет максимальное количество строк во вложенных таблицах для конкретных измерений. Кроме того, задается отдельно для каждого измерения.
KEY_ARCHIVE_MAXIMUM_ROWS_SUB_TABLE_CUSTOM_DIMENSIONS =
datatable_archiving_maximum_rows_subtable_custom_reports_dimensions_
Preview Report Iterations
Определяет временные интервалы, которые используются при генерации предварительного просмотра отчета (preview). Можно задать несколько значений через запятую.
По умолчанию:
KEY_PREVIEW_REPORT_ITERATIONS = custom_reports_preview_report_timeframes
DEFAULT_PREVIEW_REPORT_ITERATIONS = -15 minutes,-1 hour,-3 hours,-6 hours
Это означает, что Matomo будет искать данные:
- за последние 15 минут,
- за последний час,
- за последние 3 часа,
- за последние 6 часов.
Preview Report Min Rows Required
Определяет минимальное количество строк, необходимых для отображения превью отчета. Если данных меньше, предпросмотр не будет отображаться.
По умолчанию три строки.
KEY_PREVIEW_REPORT_MIN_ROWS_REQUIRED =
custom_reports_preview_report_min_rows_required
DEFAULT_PREVIEW_REPORT_MIN_ROWS_REQUIRED =
Плагин Custom Variables
Плагин Custom Variables позволяет сохранять дополнительные параметры визитов или действий в виде пар «ключ-значение». Такие переменные могут использоваться:
- для расширенной сегментации,
- фильтрации данных,
- создания дополнительных отчетов.
Num CustomVars Cache Key
По умолчанию Matomo поддерживает до пяти пользовательских переменных на один scope:
- визит (visit),
- действие (action).
Этот параметр позволяет увеличить максимальное количество переменных. Например:
CustomVariables.MaxNumCustomVariables = 8
Однако стоит учитывать, что увеличение количества переменных:
- увеличивает размер базы данных;
- может повлиять на производительность системы.
MAX_NUM_CUSTOMVARS_CACHEKEY = CustomVariables.MaxNumCustomVariables
Form Analytics
Настройки Form Analytics определяют ограничения на количество запросов форм, отправок и полей, которые могут обрабатываться системой. Эти лимиты помогают сохранить баланс между функциональностью и производительностью сервера.
Максимальное количество запросов форм
Определяет максимальное количество запросов форм, которые может отслеживать система. Ограничение предотвращает перегрузку сервера при чрезмерной активности форм или автоматических запросах.
KEY_MAX_NO_OF_FORM_REQUEST_ALLOWED = max_no_of_form_requests_allowed
DEFAULT_MAX_NO_OF_FORM_REQUEST_ALLOWED = 500
Максимальное количество запросов отправки форм
Задает максимальное количество отправок форм, которые могут быть обработаны системой. Это позволяет сохранить стабильность работы даже на сайтах с высокой посещаемостью.
KEY_MAX_NO_OF_FORM_SUBMISSION_REQUEST_ALLOWED =
max_no_of_form_submission_requests_allowed
DEFAULT_MAX_NO_OF_FORM_SUBMISSION_REQUEST_ALLOWED = 500
Максимальное количество полей форм
Определяет максимальное количество полей, которые могут отслеживаться во всех формах сайта. Ограничение помогает избежать чрезмерного сбора данных и снижает нагрузку на систему.
KEY_MAX_NO_OF_FORM_FIELDS_ALLOWED = max_no_of_form_fields_allowed
DEFAULT_MAX_NO_OF_FORM_FIELDS_ALLOWED = 2000
Marketing Campaigns Reporting
Чтобы использовать пользовательские параметры кампаний, их необходимо указать одновременно в разделах:
- [MarketingCampaignsReporting]
- [Tracker]
Это необходимо для корректного:
- распознавания кампаний,
- обработки ключевых слов,
- формирования отчетов.
Если параметры указаны только в [MarketingCampaignsReporting], Matomo продолжит использовать стандартные параметры.
Все имена параметров чувствительны к регистру.
campaign_name = "matomo_campaign,utm_campaign"
campaign_keyword = "mtm_keyword,matomo_kwd,mtm_kwd,utm_term"
campaign_source = "mtm_source,utm_source"
campaign_medium = "mtm_medium,utm_medium"
campaign_content = "mtm_content,utm_content"
campaign_id = "mtm_cid,utm_id"
campaign_group = "mtm_group"
campaign_placement = "mtm_placement"
Multi-Channel Conversion Attribution
Модуль Multi-Channel Conversion Attribution позволяет распределять конверсии между несколькими каналами трафика с использованием различных моделей атрибуции. Эти настройки определяют:
- сколько строк сохраняется в отчетах;
- какие окна атрибуции доступны пользователю;
- могут ли отчеты автоматически пересчитываться при изменении данных.
Максимальное количество строк в таблице
Определяет максимальное количество строк в основных отчетах атрибуции. По умолчанию при архивировании сохраняется до 500 строк.
KEY_MAXIMUM_ROWS_IN_DATATABLE = datatable_archiving_maximum_rows
DEFAULT_MAXIMUM_ROWS_IN_DATATABLE = 500
Максимальное количество строк в подтаблицах
Определяет максимальное количество строк во вложенных таблицах (например, при детализации отчета). По умолчанию также сохраняется до 500 строк.
KEY_MAXIMUM_ROWS_IN_SUBTABLE = datatable_archiving_maximum_rows_subtable
DEFAULT_MAXIMUM_ROWS_IN_SUBTABLE = 500
Доступные окна атрибуции до конверсии
Список периодов (в днях), которые пользователь может выбрать в интерфейсе для анализа атрибуции. По умолчанию доступны следующие варианты:
- 7 дней,
- 30 дней,
- 60 дней,
- 90 дней.
KEY_AVAILABLE_DAYS_PRIOR_CONVERSION = available_days_prior_to_conversion
DEFAULT_AVAILABLE_DAYS_PRIOR_CONVERSION = 7,30,60,90
Окно атрибуции по умолчанию
Определяет количество дней, используемое по умолчанию для анализа атрибуции, если пользователь не выбрал значение вручную. По умолчанию используется 30 дней.
KEY_DAY_PRIOR_CONVERSION = default_day_prior_to_conversion
DEFAULT_DAY_PRIOR_CONVERSION = 30
Инвалидация отчетов
Определяет, могут ли отчеты автоматически пересчитываться, если меняются параметры атрибуции или данные. По умолчанию функция включена.
KEY_CAN_INVALIDATE_REPORTS_GENERAL = can_invalidate_reports
Если установить значение 0, пересчет отчетов будет отключен.
Tag Manager
Настройки Matomo Tag Manager позволяют включать или отключать отдельные компоненты системы управления тегами.
Отключение тегов:
KEY_DISABLED_TAGS = disable_tags
Отключение триггеров:
KEY_DISABLED_TRIGGERS = disable_triggers
Отключение переменных:
KEY_DISABLED_VARIABLES = disable_variables
Эти параметры позволяют ограничить использование определенных типов компонентов в Tag Manager.
Tracking Spam Prevention
Модуль Tracking Spam Prevention блокирует нежелательный трафик от ботов и спам-источников до его попадания в аналитику. Настройки управляют обработкой IP-диапазонов и блокировкой организаций.
Исключение при ошибке синхронизации диапазонов IP
Определяет, будет ли генерироваться исключение при ошибке синхронизации IP-диапазонов. По умолчанию ошибки не вызывают исключение, а просто записываются в лог.
KEY_RANGE_THROW_EXCEPTION = block_cloud_sync_throw_exception_on_error
DEFAULT_RANGE_THROW_EXCEPTION = 0
Белый список IP-диапазонов
Определяет диапазоны IP-адресов, которые всегда разрешены и не подпадают под правила антиспама. По умолчанию список пуст.
KEY_RANGE_ALLOW_LIST = iprange_allowlist
DEFAULT_RANGE_ALLOW_LIST = ['']
Блокировка по организациям (GeoIP)
Определяет список организаций или хостинг-провайдеров, трафик которых может блокироваться. По умолчанию включены распространенные облачные провайдеры, часто используемые ботами.
KEY_GEOIP_MATCH_PROVIDERS = block_geoip_organisations
DEFAULT_GEOIP_MATCH_PROVIDERS =
['alicloud', 'alibaba cloud', 'digitalocean', 'digital ocean']
Заключение: когда имеет смысл изменять настройки Matomo
Большинство параметров в config.ini.php и конфигурационных файлах плагинов уже оптимизированы для стандартной установки Matomo. Именно поэтому в обычных условиях менять их не требуется. Однако при росте нагрузки, расширении аналитики или интеграции с внешними системами корректировка этих настроек может значительно улучшить производительность и точность данных.
Важное правило! Перед изменением параметров рекомендуется:
- сделать резервную копию
config.ini.php; - протестировать изменения на тестовой среде;
- постепенно увеличивать значения параметров.
Это позволит избежать проблем с производительностью и стабильностью системы.
