tutorial

Monitoring Vtiger CRM with Vigilmon

Vtiger CRM is an open source CRM platform used by thousands of SMEs worldwide. This guide shows you how to monitor every critical layer — PHP app health, MySQL, cron jobs, email polling, workflows, and disk space — with Vigilmon.

Vtiger CRM is a full-featured open source customer relationship management platform managing contacts, leads, sales pipelines, support tickets, campaigns, and invoices for thousands of SMEs globally. It's a PHP web application with a deceptively complex operational profile: in addition to serving the CRM UI, Vtiger depends on MySQL for all CRM data, OS-level cron jobs for email polling and workflow automation, IMAP integration for inbox-to-ticket conversion, and a scheduled reporting engine. When any of these layers fails silently, CRM data goes stale, follow-up tasks are missed, and support cases created from emails never appear. Vigilmon gives you complete visibility across every Vtiger layer.

What You'll Set Up

  • Vtiger application HTTP health monitoring
  • MySQL database connectivity and slow-query alerting
  • Vtiger cron job heartbeat monitoring
  • Email (IMAP) polling health monitoring
  • Workflow execution success monitoring
  • Active user count monitoring
  • Scheduled report health monitoring
  • Disk space monitoring for CRM attachments
  • PHP session health monitoring
  • Vtiger version currency check

Prerequisites

  • Vtiger CRM 7.x (Community Edition or later) running on a Linux server (Apache or Nginx + PHP)
  • MySQL / MariaDB as the database backend
  • SSH access to the server
  • A free Vigilmon account

Why Monitoring Vtiger Matters

Vtiger CRM is where businesses manage their relationships and revenue pipeline. A failure in any layer has direct business consequences:

  • App goes down → salespeople can't access contacts or log calls; support staff can't respond to cases.
  • MySQL slow or unreachable → every CRM query fails; the app shows errors or timeouts.
  • Cron stops → email polling stops (no new cases from email); follow-up workflows don't trigger; campaign emails don't send.
  • IMAP polling fails → customer support emails pile up in the inbox, unprocessed, while customers wait for responses.
  • Disk full → document uploads fail; email attachments silently dropped; audit log truncated.
  • Session handler fails → users are intermittently logged out mid-work, losing unsaved data.

Vigilmon monitors each failure mode independently, giving you early warning before staff start reporting problems.

Step 1: Monitor Vtiger Application Health

Vtiger's PHP application should respond to HTTP requests on the server's configured domain. Set up a basic uptime check:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Vtiger URL: https://crm.yourcompany.com/.
  4. Set Expected HTTP status to 200.
  5. Set Check interval to 1 minute.
  6. Enable Response body contains and enter Vtiger (the login page contains this string).
  7. Click Save.

For a richer health check, add a dedicated PHP health endpoint that tests database connectivity:

<?php
// /var/www/vtiger/health.php
// Restrict to Vigilmon probe IPs or internal network in your web server config
header('Content-Type: application/json');

$config = parse_ini_file(dirname(__DIR__) . '/config/config.ini.php') ?:
    ['db_host' => 'localhost', 'db_name' => 'vtiger', 'db_username' => 'vtiger', 'db_password' => ''];

try {
    $pdo = new PDO(
        "mysql:host={$config['db_host']};dbname={$config['db_name']};charset=utf8",
        $config['db_username'],
        $config['db_password'],
        [PDO::ATTR_TIMEOUT => 3]
    );
    $pdo->query('SELECT 1 FROM vtiger_users LIMIT 1');
    http_response_code(200);
    echo json_encode(['status' => 'ok', 'db' => 'ok']);
} catch (Exception $e) {
    http_response_code(503);
    echo json_encode(['status' => 'error', 'db' => 'error']);
}

In Vigilmon, add a second monitor for https://crm.yourcompany.com/health.php. This checks both PHP application health and MySQL connectivity in one probe.

Step 2: Monitor MySQL Database Health

Vtiger stores all CRM data in MySQL — contacts, leads, opportunities, cases, activities, email templates, and workflow rules — in a highly normalized schema centered on the vtiger_crmentity table. Any MySQL degradation immediately affects CRM responsiveness.

Extend the health endpoint to report query latency:

<?php
// /var/www/vtiger/health/db.php
header('Content-Type: application/json');

$dsn = sprintf(
    'mysql:host=%s;dbname=%s;charset=utf8',
    getenv('VTIGER_DB_HOST') ?: 'localhost',
    getenv('VTIGER_DB_NAME') ?: 'vtiger'
);

try {
    $start = microtime(true);
    $pdo = new PDO($dsn, getenv('VTIGER_DB_USER') ?: 'vtiger', getenv('VTIGER_DB_PASS') ?: '', [PDO::ATTR_TIMEOUT => 3]);
    // Test a representative CRM query against the central entity table
    $count = $pdo->query('SELECT COUNT(*) FROM vtiger_crmentity WHERE deleted = 0')->fetchColumn();
    $latency_ms = round((microtime(true) - $start) * 1000, 1);

    $healthy = $latency_ms < 500;
    http_response_code($healthy ? 200 : 503);
    echo json_encode(['db' => 'ok', 'latency_ms' => $latency_ms, 'entity_count' => $count]);
} catch (Exception $e) {
    http_response_code(503);
    echo json_encode(['db' => 'error', 'message' => $e->getMessage()]);
}

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/db.php. Alert on any non-200 response. Set a Response time alert at 2000 ms — slow response time from this endpoint often precedes full application timeouts.

Enable MySQL slow query logging for deeper diagnostics:

# /etc/mysql/conf.d/vtiger.cnf
slow_query_log = 1
slow_query_log_file = /var/log/mysql/vtiger-slow.log
long_query_time = 2
log_queries_not_using_indexes = 1

Step 3: Monitor Vtiger Cron Jobs with Heartbeats

Vtiger's automation engine runs entirely on OS-level cron. The cron entry looks like:

* * * * * www-data php /var/www/vtiger/cron/modules/Vtiger/ProcessTasks.php

This single cron job drives: IMAP email polling, workflow execution, campaign sending, report scheduling, and other background tasks. If cron stops — due to a PHP fatal error, a permission change, or a missed cron entry after a server rebuild — all automation silently halts.

Set up a Vigilmon heartbeat for the main cron process:

  1. In Vigilmon, click Add Monitor → Cron / Heartbeat.
  2. Name it Vtiger Cron.
  3. Set Expected interval to 3 minutes (slightly more than the 1-minute cron interval, to absorb occasional slow runs).
  4. Copy the heartbeat ping URL.

Create a cron wrapper:

#!/bin/bash
# /usr/local/bin/vtiger-cron-wrapper.sh
cd /var/www/vtiger
php cron/modules/Vtiger/ProcessTasks.php 2>&1 | logger -t vtiger-cron
if [ ${PIPESTATUS[0]} -eq 0 ]; then
    curl -fsS "https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_TOKEN" > /dev/null
fi

Update crontab:

* * * * * www-data /usr/local/bin/vtiger-cron-wrapper.sh

Vigilmon alerts if no ping arrives within 3 minutes, giving you early warning of cron failure before workflows and email polling stop.

Step 4: Monitor Email Polling Health

One of Vtiger's most valuable features is converting inbound emails into CRM cases. A failure in IMAP polling means customer emails pile up in the inbox while Vtiger reports no new support cases — a silent support SLA breach.

<?php
// /var/www/vtiger/health/email_poll.php
header('Content-Type: application/json');

$dsn = sprintf('mysql:host=%s;dbname=%s;charset=utf8', getenv('VTIGER_DB_HOST') ?: 'localhost', getenv('VTIGER_DB_NAME') ?: 'vtiger');
try {
    $pdo = new PDO($dsn, getenv('VTIGER_DB_USER'), getenv('VTIGER_DB_PASS'), [PDO::ATTR_TIMEOUT => 3]);

    // Check when email polling last ran — Vtiger logs this in vtiger_inbound_email
    $stmt = $pdo->query("
        SELECT MAX(last_scan_timestamp) as last_poll
        FROM vtiger_inbound_email
        WHERE active = 1
    ");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    $lastPoll = (int)($row['last_poll'] ?? 0);
    $minutesSinceLastPoll = $lastPoll > 0 ? round((time() - $lastPoll) / 60, 1) : 9999;

    // Alert if email hasn't been polled in more than 15 minutes
    $healthy = $minutesSinceLastPoll < 15;
    http_response_code($healthy ? 200 : 503);
    echo json_encode([
        'email_poll' => $healthy ? 'ok' : 'stale',
        'minutes_since_last_poll' => $minutesSinceLastPoll
    ]);
} catch (Exception $e) {
    http_response_code(503);
    echo json_encode(['email_poll' => 'db_error']);
}

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/email_poll.php with a 5-minute check interval. Alert on non-200 — if email polling hasn't run in 15 minutes, inbound cases from email are already delayed.

Step 5: Monitor Workflow Execution Success

Vtiger workflows automate follow-up tasks, field updates, and notifications. Silent workflow failures mean sales follow-ups are missed and support SLA escalations don't trigger.

<?php
// /var/www/vtiger/health/workflows.php
header('Content-Type: application/json');

$dsn = sprintf('mysql:host=%s;dbname=%s;charset=utf8', getenv('VTIGER_DB_HOST') ?: 'localhost', getenv('VTIGER_DB_NAME') ?: 'vtiger');
try {
    $pdo = new PDO($dsn, getenv('VTIGER_DB_USER'), getenv('VTIGER_DB_PASS'), [PDO::ATTR_TIMEOUT => 3]);

    // Check for workflow queue items stuck for > 30 minutes
    $stuck = $pdo->query("
        SELECT COUNT(*) FROM com_vtiger_workflow_tasklogs
        WHERE status IN ('Pending', 'Running')
        AND createdtime < DATE_SUB(NOW(), INTERVAL 30 MINUTE)
    ")->fetchColumn();

    $healthy = (int)$stuck === 0;
    http_response_code($healthy ? 200 : 503);
    echo json_encode(['workflows' => $healthy ? 'ok' : 'stuck', 'stuck_count' => (int)$stuck]);
} catch (Exception $e) {
    http_response_code(503);
    echo json_encode(['workflows' => 'db_error']);
}

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/workflows.php with a 10-minute check interval. Alert when stuck workflows appear — this indicates cron has stopped or PHP is throwing errors during workflow execution.

Step 6: Monitor Active User Count

Abnormal active user counts can indicate a stuck session preventing login, a botnet probing the login form, or a configuration issue with session expiry.

<?php
// /var/www/vtiger/health/sessions.php
header('Content-Type: application/json');

$dsn = sprintf('mysql:host=%s;dbname=%s;charset=utf8', getenv('VTIGER_DB_HOST') ?: 'localhost', getenv('VTIGER_DB_NAME') ?: 'vtiger');
try {
    $pdo = new PDO($dsn, getenv('VTIGER_DB_USER'), getenv('VTIGER_DB_PASS'), [PDO::ATTR_TIMEOUT => 3]);

    // Active users with a session in the last 30 minutes
    $active = $pdo->query("
        SELECT COUNT(DISTINCT user_name) FROM vtiger_audit_trial
        WHERE actiontype = 'Login'
        AND changedon > DATE_SUB(NOW(), INTERVAL 30 MINUTE)
    ")->fetchColumn();

    http_response_code(200);
    echo json_encode(['active_users_30min' => (int)$active]);
} catch (Exception $e) {
    http_response_code(503);
    echo json_encode(['sessions' => 'db_error']);
}

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/sessions.php. Set a Response body value alert if active_users_30min unexpectedly drops to zero during business hours — this indicates a session or authentication failure.

Step 7: Monitor Disk Space for Attachments

Vtiger stores document attachments, email attachments, and imported files on disk. When disk space runs out, document uploads silently fail and email attachments are dropped from inbound cases.

<?php
// /var/www/vtiger/health/disk.php
header('Content-Type: application/json');

$uploadPath = '/var/www/vtiger/storage';
$total = disk_total_space($uploadPath);
$free = disk_free_space($uploadPath);
$usedPct = round(($total - $free) / $total * 100, 1);

$healthy = $usedPct < 80;
http_response_code($healthy ? 200 : 503);
echo json_encode([
    'disk_used_pct' => $usedPct,
    'free_gb' => round($free / 1024**3, 1)
]);

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/disk.php with a 15-minute check interval. Alert when disk usage exceeds 80% — this gives you time to archive old documents or expand storage before upload failures begin.

Step 8: Monitor PHP Session Handler Health

Vtiger uses PHP sessions for authentication. If the session handler is misconfigured (wrong permissions on session directory, or Redis session backend unavailable), users are intermittently logged out.

<?php
// /var/www/vtiger/health/session.php
header('Content-Type: application/json');

// Verify PHP session directory is writable
$sessionPath = session_save_path() ?: sys_get_temp_dir();
$writable = is_writable($sessionPath);

// Try creating and destroying a test session
session_start();
$_SESSION['health_test'] = time();
$sessionId = session_id();
session_write_close();

$healthy = $writable && !empty($sessionId);
http_response_code($healthy ? 200 : 503);
echo json_encode([
    'sessions' => $healthy ? 'ok' : 'error',
    'session_path_writable' => $writable,
    'session_id_generated' => !empty($sessionId)
]);

In Vigilmon, add a monitor for https://crm.yourcompany.com/health/session.php. Alert on non-200 — session handler failures cause inconsistent authentication behavior that's difficult to diagnose without a dedicated check.

Step 9: Monitor Scheduled Report Generation

Vtiger's reporting engine generates scheduled reports for management dashboards and pipeline reviews. A failed report generation means stakeholders receive no data, or worse, stale data from the last successful run.

Set up a heartbeat monitor for your most critical scheduled report:

  1. In Vigilmon, create a Cron / Heartbeat monitor.
  2. Name it Vtiger Weekly Pipeline Report.
  3. Set Expected interval to 7 days (or match your report schedule).
  4. Copy the heartbeat URL.

Add the ping to Vtiger's report cron task or to a custom report export script:

#!/bin/bash
# /usr/local/bin/vtiger-report.sh
php /var/www/vtiger/modules/Reports/GenerateReport.php --report-id=YOUR_REPORT_ID 2>&1
if [ $? -eq 0 ]; then
    curl -fsS "https://vigilmon.online/heartbeat/YOUR_REPORT_HEARTBEAT_TOKEN" > /dev/null
fi

Recommended Alert Configuration

| Monitor | Alert Condition | Severity | |---|---|---| | Vtiger application health | Non-200 or body missing Vtiger | Critical | | MySQL health endpoint | Non-200 or latency > 500ms | Critical | | Vtiger cron heartbeat | Missed 3-minute interval | Critical | | Email poll health | > 15 min since last poll | High | | Workflow execution | Stuck workflows > 0 | High | | Active user sessions | Zero during business hours | High | | Disk space | > 80% used | High | | PHP session handler | Non-200 | High | | Report generation heartbeat | Missed scheduled interval | Medium |

Conclusion

Vtiger CRM appears simple on the surface — a PHP web application with MySQL behind it — but its operational health depends on multiple layers working correctly: the cron engine, IMAP polling, PHP session management, MySQL query performance, and adequate disk space for attachments. With Vigilmon monitoring each of these layers, you get early warning on every failure mode before staff start reporting that their workflows aren't triggering, new cases from email aren't appearing, or documents aren't uploading.

Start monitoring your Vtiger CRM at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles