Switching 1C-Bitrix Agents to Cron

Switching 1C-Bitrix Agents to Cron

On a high-traffic website, Bitrix agents are not simply "background tasks." They are PHP code that executes synchronously during the processing of a user request. If several agents are scheduled to run at the moment a hit occurs, the user waits while they complete. On high-load projects this is one of the causes of "random" slow pages.

Switching agents to cron means moving their execution out of HTTP request processing into a separate process that runs on a schedule, independent of traffic.

The Problem with Hit-Based Agents

The standard Bitrix agent mechanism: the b_agent table is checked on every hit. The check code lives in /bitrix/modules/main/include/prolog_before.php — what you see in the profiler as CAgent::CheckAgents().

Performance consequences:

• The CSearch::ReIndexAll() agent (search reindexing) can run for 5–30 seconds — during which one PHP process is busy instead of serving a client.
• The 1C export agent creates a peak load at the moment of execution.
• Multiple agents hitting the same request — their times accumulate.

On a site with normal traffic this may be imperceptible. On a high-load site — it is degradation under load precisely during peak activity periods.

Two Agent Execution Modes

In Bitrix, under the main module settings (/bitrix/admin/settings.php?lang=ru&mid=main), there is an "Agents" parameter with two options:

"Agents run via hits" — the standard mode. Agents execute during HTTP requests.

"Agents run via cron" — a mode in which agents do NOT run on hits. Instead, a cron task calling /bitrix/modules/main/tools/cron_events.php is used to trigger them.

This is a global switch for all agents on the site. It is not possible to move "only some agents" through this interface.

How to Switch Agents to Cron

Step 1. Configure cron. Before switching modes, ensure the cron task is configured and working. Otherwise, after switching, agents will stop executing entirely.

* * * * * /usr/bin/php -f /var/www/site/bitrix/modules/main/tools/cron_events.php >> /var/log/bitrix_cron.log 2>&1

Verify that the script runs without errors: check the log, confirm that the NEXT_EXEC values of agents are being updated.

Step 2. Switch the mode. In /bitrix/admin/settings.php for the main module — enable the "Agents use cron" option. Save.

Step 3. Verify. After switching:

• Open several pages of the site. The profiler should not show CAgent::CheckAgents() with non-zero execution time.
• Wait a few minutes. In /bitrix/admin/agent_list.php, agent NEXT_EXEC values should be updating.
• Verify that critical agents (notification sending, 1C exchange) execute on schedule.

Crontab for the Bitrix Virtual Machine

The Bitrix VM (virtual machine) ships with a preconfigured crontab file. The script path in a standard VM:

*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1

In BitrixVM, agents run via cron by default at a frequency of once every 5 minutes. If a frequency of once per minute is needed — change /5 to an empty value for the first field.

Nuances and Pitfalls

Agents that should not be switched to cron. Some agents assume the context of a user or site session. In cron mode they execute without an HTTP context, which sometimes causes errors. Verify each critical agent individually.

Timezone. Cron uses the system timezone by default. Make sure it matches the timezone settings in Bitrix. An offset of one hour causes confusion when analyzing logs.

Execution permissions. The cron_events.php script runs as a system user (usually www-data or bitrix). This user must have read access to the site files and write access to /bitrix/cache/.

Load from cron. If cron_events.php runs every minute and there are many agents — check that parallel processes are not accumulating. Add a lock file:

* * * * * /usr/bin/flock -n /tmp/bitrix_cron.lock /usr/bin/php -f /var/www/site/bitrix/modules/main/tools/cron_events.php > /dev/null 2>&1

flock -n prevents parallel execution if the previous instance has not yet finished.

Case Study: Reducing Catalog Page Response Times

Client — a large online building materials store. Complaints: "pages sometimes take 5–10 seconds to load, but not always and not consistently." The profiler showed: in 10% of requests CAgent::CheckAgents() adds 3–8 seconds — these are the search reindexing agent CSearchIndex::ReIndexElement() and the notification queue processing agent.

These agents were heavy: the search reindexed a batch of products on every call, taking several seconds. When they landed on a user hit, the delay was felt as "slowness."

Solution: switch all agents to cron. After switching:

• CAgent::CheckAgents() disappeared from the profiler.
• The 99th percentile response time dropped from 8.2 seconds to 0.9 seconds.
• Reindexing agents began running once a minute via cron — imperceptible to users.

Timeframes

Switching agents to cron — 4–8 hours: crontab setup, verification of agent execution in the new mode, testing of critical functions (notifications, exports, indexing). With comprehensive diagnostics and optimization of slow agents — 1–3 working days.

The question "why is an agent not running at the scheduled time" is one of the most common in Bitrix project diagnostics. You check the settings — the agent is active, the interval is set correctly. But it runs irregularly: sometimes every 5 minutes, sometimes every hour. The cause is almost always the same: agents are running in "hit" mode and site traffic is uneven.

Switching agents to cron is not a one-time operation. It is a change to the architecture of background task execution for the project.

The Problem with Hit Mode

When agents run on hits, every HTTP request to the site checks the b_agent table:

SELECT * FROM b_agent WHERE ACTIVE='Y' AND NEXT_EXEC <= NOW()

If such agents exist — they run within the same PHP process that is handling the HTTP request. This creates three simultaneous problems:

Unpredictable execution time. An agent with a 300-second (5-minute) interval in practice runs "when the next visitor arrives after the interval expires." During business hours — roughly on time. At 4 AM — after several hours.

Page slowdowns. The agent executes within the HTTP request. A heavy agent (e.g., syncing with 1C or sending a batch of emails) increases the response time for the specific user who "landed" on the agent execution.

Execution time limit. PHP's max_execution_time — typically 30–60 seconds. If the agent does not finish in time, it is interrupted, leaving work incomplete. The next run — when the next visitor arrives.

Switching to Cron: Full Algorithm

Step 1. Check the current state.

In the admin panel: "Settings → Module Settings → Main Module". The "Agent usage" parameter — if it is set to "In hit mode", switch it.

Step 2. Configure crontab.

Connect to the server via SSH. Open crontab:

crontab -e -u bitrix

Add lines:

# Bitrix agents — every minute
* * * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/agent_exec.php > /dev/null 2>&1

# Mail event queue — every 5 minutes
*/5 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/event_exec.php > /dev/null 2>&1

Verify the path to php using which php. On BitrixEnv — usually /usr/bin/php, sometimes /usr/local/bin/php7.4 or similar.

Step 3. Switch the mode in Bitrix.

After cron is configured and verified (confirmed that agent_exec.php runs without errors) — switch the mode in the settings. "Agent usage" → "Via cron". Save.

From this point, Bitrix stops running agents on hits — only cron.

Step 4. Verify execution.

Check b_agent after a few minutes:

SELECT NAME, LAST_EXEC, NEXT_EXEC, PERIOD
FROM b_agent
WHERE ACTIVE='Y'
ORDER BY LAST_EXEC DESC
LIMIT 20;

LAST_EXEC should be updating. If it is not — cron is not working. Check the system cron log (/var/log/cron) and PHP error output.

Common Issues During the Switch

Wrong path to PHP. agent_exec.php is called with the required interpreter. If the path is wrong — the script simply does not run. Verify:

/usr/bin/php -f /home/bitrix/www/bitrix/modules/main/tools/agent_exec.php

Should execute without errors.

Permissions. The script must run as the user who owns the site files. If cron runs as root but Bitrix files belong to bitrix — cache write errors may occur.

Multiple instances of one agent. If an agent is long-running (longer than 60 seconds) and cron launches it every minute — parallel instances may arise. Solution: protection against parallel execution via a lock file inside the agent, or increasing the cron interval for the specific agent.

Agents in hit mode after switching. Ensure there are no cached settings. After saving the option — clear the platform cache.

Monitoring and Alerts

For production projects, we recommend adding agent execution monitoring. A simple option: a script that runs every 10 minutes and checks that the LAST_EXEC of critical agents is not older than a threshold value. If an agent has not run for longer than PERIOD * 3 — send an alert via Telegram or email.

Case Study: Non-functional Overnight 1C Sync

Client — an online home appliance store. The stock sync agent with 1C was configured with a period of 3600 seconds (once per hour). In practice it ran irregularly: sometimes every 2–3 hours, sometimes skipping several iterations. At night, stock levels were not updated until morning.

Diagnosis: agents were running "on hits." At night traffic dropped to 1–2 hits per hour — the agent was "waiting" for a visitor.

Solution: switched agents to cron running every minute. The sync agent started executing strictly on schedule. Side effect: nighttime became a "window" for heavy tasks without impact on users.

Additionally discovered: the sync agent sometimes ran for longer than 60 seconds (the max_execution_time limit). After switching to cron, set_time_limit(0) was added at the beginning of the agent script — it now reliably completes its cycle.

Timeframes

Switching agents to cron — 4–8 hours of work: diagnosing the current mode, configuring crontab, testing, monitoring the first executions. For complex environments with multiple servers or specific agents — 1–2 working days.