Alerts & Reports

Email notifications triggered by QoS thresholds, SIP errors, or sensor health conditions. The system stores all alerts in history for review.

Prerequisites

Email Configuration

Alerts use PHP's mail() function via the server's MTA (Postfix/Exim/Sendmail).

Setting	Location	Description
From Address	GUI > Settings > System Configuration > Email	`DEFAULT_EMAIL_FROM` - sender address for all alerts
Cron Job	`/etc/crontab`	Required for alert processing

# Add cron job (required)
echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab
killall -HUP cron   # Debian/Ubuntu
# or: killall -HUP crond  # RHEL/CentOS

Alert Types

Access via GUI > Alerts.

RTP Alerts

Trigger on voice quality metrics:

MOS - below threshold
Packet loss - percentage exceeded
Jitter - variation exceeded
Delay (PDV) - latency exceeded
One-way calls - one RTP stream missing
Missing RTP - both RTP streams missing

Configure alerts to trigger when number of incidents OR percentage of CDRs exceeds threshold.

RTP&CDR Alerts

Combine RTP metrics with CDR conditions including PDD (Post Dial Delay).

Using Filter Templates:

Create CDR filter in GUI > CDR
Save as template
In alert config, select from Filter template dropdown

💡 Tip: Use filter templates for complex conditions like duration > 14400 (calls over 4 hours) or absolute_timeout (truncated recordings).

SIP Response Alerts

Response Code	Meaning
Empty	All call attempts per filters
0	No response received (routing loops)
408	Timeout after provisional response (server unresponsive)
Specific	Exact codes (404, 503, etc.)

"from all" Checkbox (Percentage Thresholds)

⚠️ Warning: This setting is critical for IP group monitoring.

CHECKED: % calculated from ALL CDRs in database
UNCHECKED: % calculated only from filtered CDRs (correct for specific IP groups)

SIP Response vs Last SIP Response

There are two different fields for matching SIP responses:

Field	Location	Supports % Threshold	Use Case
SIP response	GUI > Alerts > SIP Response Alerts	Template:Yes	Match by numeric code (e.g., 487, 503)
Last sip response	GUI > Alerts > Filter common	Template:No	Match by full text (e.g., "487 Request Terminated")

⚠️ Warning: The GUI cannot trigger alerts based on percentage of full textual response strings. If you need percentage-based triggering for SIP response codes, use the SIP response numeric field instead.

The Last sip response field supports wildcard patterns (%, %Request Terminated%, %487%) but only triggers based on count thresholds, not percentages.

International Call Alerts (Called Number Prefixes)

Monitor calls to international destinations using prefix-based matching (dialing patterns like 00, +).

ℹ️ Note: This uses phone number prefix detection, NOT IP geolocation. For GeoIP-based detection, see Anti-Fraud Rules.

Configuration:

GUI > Settings > Country prefixes - Define international prefixes (00, +), local country, minimum digits
GUI > Alerts > Filter common - Configure:

Setting	Description
Called number prefixes	Which prefixes trigger alert (uncheck ALL for all international)
Exclude called number	Country codes to exclude (e.g., +44, 0044 for UK)
Strict for prefixes	Require international prefix (00/+)
NANPA	North American Numbering Plan

Sensors Alerts

Monitor sensor health and status:

Offline detection - Sensor not communicating
Old CDR - No recent CDRs written (capture or DB issue)
Big SQL queue stat - Growing queue indicates DB bottleneck (warning: >20 files, critical: >100)

SIP REGISTER Alerts

Alert Type	Purpose	Use Case
SIP REGISTER RRD beta	Response time monitoring	Network latency, packet loss
SIP failed Register (beta)	Failed registrations by IP	Brute-force, credential stuffing
multiple register (beta)	Same account from multiple IPs	Credential compromise detection

⚠️ Warning: multiple register (beta) detects SIMULTANEOUS registrations from multiple IPs (security). For detecting IP changes when device moves networks, use CDR&RTP alert with external script.

CDR Trends Alerts

Monitor metric deviations from historical baselines (e.g., ASR drops).

Parameter	Description
Type	Metric to monitor (ASR, ACD, etc.)
Offset	Historical baseline (1 week, 1 day)
Range	Current evaluation window (1 hour)
Method	Deviation (%) or Threshold (absolute)
Limit Inc./Dec.	Trigger threshold percentage

Common Filters

All alert types support:

IP/Number Group - Predefined groups from Groups menu
IP Addresses / Numbers - Individual values (one per line)
Email Group / Emails - Recipients
Last sip response - Filter by response text (requires save_sip_history = responses)
External script - Custom script path for integrations

⚠️ Warning: Alerts use OR logic between conditions. AND logic is NOT supported. Workaround: create separate alerts and correlate manually.

Caller vs Called Filtering

The Numbers filter matches against both caller and called fields. You cannot create alerts that trigger only when a number is the caller or only the called. Use IP Groups with Trunk/Server checkboxes for direction-based filtering. See Groups.

External Scripts

Enable webhook integration (Datadog, Slack, custom systems).

Configuration: Enter full absolute path in External script field (e.g., /usr/local/bin/alert-webhook.sh).

Arguments passed to script:

Arg	Description
`$1`	Alert ID
`$2`	Alert name
`$3`	Unix timestamp
`$4`	JSON data with CDR IDs

Example - Slack notification:

#!/bin/bash
# /usr/local/bin/slack-alert.sh
SLACK_WEBHOOK="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
curl -X POST "$SLACK_WEBHOOK" -H "Content-Type: application/json" \
  -d '{"text": "VoIPmonitor Alert: '"$2"'"}'

ℹ️ Note: IP addresses in CDR table are decimal integers. Use long2ip() (PHP) or INET_NTOA() (MySQL) for conversion.

Sent Alerts

View triggered alerts via GUI > Alerts > Sent Alerts. Shows:

Parameters table - QoS metrics with highlighted bad values
CDR records - Calls that triggered alert with flags: (M)OS, (J)itter, (P)acket loss, (D)elay

Custom Report Alerts

Alert on criteria not in native types (e.g., custom SIP headers).

Workflow:

Capture header in /etc/voipmonitor.conf: custom_headers = Max-Forwards
Enable in GUI > Settings > CDR Custom Headers
Create filter in CDR view, save as template
Create Daily Report with filter in GUI > Reports > Configure Daily Reports

ℹ️ Note: Custom report alerts cannot group by caller/called for threshold detection (e.g., "alert if same caller has >X failures"). Use CDR Summary reports for aggregated data.

Troubleshooting

Email Not Sent

Diagnosis:

Entries in "Sent Alerts" but no email → MTA issue
No entries in "Sent Alerts" → Alert conditions or cron issue

# Test MTA
echo "Test" | mail -s "Test" your@email.com

# Check MTA status
systemctl status postfix  # or exim4/sendmail

# Check logs
tail -f /var/log/mail.log  # Debian/Ubuntu
tail -f /var/log/maillog   # RHEL/CentOS

# Check mail queue
mailq

Status 250 or "Queued mail for delivery" = Your server delivered successfully. If recipient didn't receive, issue is on their side (spam folder, quarantine, blacklisting). Mail Queue Not Delivering: If emails accumulate in the queue but are not being sent:

# Verify queue manager is running
ps aux | grep qmgr

# Restart Postfix
systemctl restart postfix

# Force immediate delivery of queued emails
postfix flush

Alerts Not Triggering

Enable debug logging:

// Add to ./config/system_configuration.php
define('CRON_LOG_FILE', '/tmp/alert.log');

# Monitor processing
tail -f /tmp/alert.log

Common causes:

Cron not running - verify with crontab -l
PHP CLI version mismatch - use update-alternatives --set php /usr/bin/php8.x
SQL queue growing - DB can't keep up (see Scaling)
Alert disabled or filter mismatch

Concurrent Calls Alerts

Type	Data Source	Aggregation	Timing
Fraud concurrent calls	SIP INVITEs (realtime)	Source IP only	Immediate
Regular concurrent calls	CDRs (database)	Source/Dest IP, Domain, Custom	Delayed

Use regular concurrent calls for destination IP monitoring (trunk capacity). Investigating Fraud: Realtime Concurrent Calls Alerts

Since this alert type triggers before CDRs are written, use the following procedure to investigate the calls that triggered the alert:

Navigate to GUI → CDR
Use the filter form to add the is international filter
Set the from and to date range to match the time the alert was sent
Go to the bottom of the CDR view and enable grouping by country
Analyze the traffic by country to identify the source of the fraudulent activity

External Script Not Running

Use preview button to test alert triggers
Verify absolute path (not relative)
Check permissions: chmod 755 /path/to/script.sh
Include shebang: #!/bin/bash
Use full command paths (e.g., /usr/bin/curl)
For URLs, create script with curl/wget - cannot put URL directly in field

"Crontab Log Too Old" Warning

Causes:

Cron not running → Add cron entry
PHP CLI version mismatch → update-alternatives --set php /usr/bin/php8.x
Database overload → Check SQLq in GUI > Settings > Sensors, see Scaling

AI Summary for RAG

Summary: VoIPmonitor Alerts system provides email notifications for QoS thresholds (RTP: MOS, jitter, packet loss), SIP response codes (0=no response, 408=timeout), sensor health, and registration monitoring. Alert types include RTP, RTP&CDR (with filter templates for duration/absolute_timeout), SIP Response (use "from all" unchecked for IP group percentages), International Calls (prefix-based, NOT GeoIP), Sensors, SIP REGISTER alerts (RRD beta for latency, failed Register beta for brute-force, multiple register beta for credential compromise), and CDR Trends (ASR deviation monitoring). External scripts enable webhook integrations. CRITICAL: Alerts use OR logic only - AND not supported. IP addresses stored as integers - use long2ip()/INET_NTOA() for conversion.

Keywords: alerts, email notifications, QoS, MOS, jitter, packet loss, SIP response, 408 timeout, sensors monitoring, SIP REGISTER, brute force, credential stuffing, international calls, called number prefixes, CDR trends, ASR, external scripts, webhooks, from all checkbox, OR logic, crontab, MTA, Postfix, CRON_LOG_FILE, concurrent calls, SQL queue

Key Questions:

How do I configure email alerts in VoIPmonitor?
What alert types are available (RTP, SIP, Sensors)?
How do I configure international call alerts with prefix filtering?
What does the "from all" checkbox do in percentage alerts?
How do I integrate alerts with webhooks (Slack, Datadog)?
Why are my alerts not triggering?
How do I troubleshoot email delivery issues?
What is the difference between fraud and regular concurrent calls alerts?
How do I detect SIP registration attacks (brute-force)?
Do alerts support AND logic between conditions?