Alerts: Difference between revisions

From VoIPmonitor.org
(Add comprehensive troubleshooting section for email alerts including CLI testing, MTA status, mail logs, and queue inspection)
(Fix template syntax - remove curly braces from 'from' and 'to' field names)
 
(39 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Alerts & Reports ==
{{DISPLAYTITLE:Alerts & Reports}}
[[Category:GUI manual]]


Alerts & Reports generate email notifications based on QoS parameters or SIP error conditions. It includes daily reports, ad hoc reports, and stores all generated items in history.
= Alerts & Reports =


Emails use PHP's "mail" function, relying on the server's MTA (e.g., Exim, Postfix, Sendmail). Configure MTA per your Linux distribution documentation.
Email notifications triggered by QoS thresholds, SIP errors, or sensor health conditions. The system stores all alerts in history for review.


Process alerts via a PHP script in crontab:
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial
rectangle "Sensor" as sensor
database "MySQL" as db
rectangle "Cron\n(1min)" as cron
rectangle "Alert\nProcessor" as processor
rectangle "MTA" as mta
actor "Admin" as admin
sensor --> db : CDRs
cron --> processor : Trigger
processor --> db : Query
processor --> mta : Email
mta --> admin : Alert
@enduml
</kroki>


For CentOS & Debian:
== Prerequisites ==


echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab
=== Email Configuration ===


(Adjust path to run.php based on VoIPmonitor GUI installation.)
Alerts use PHP's <code>mail()</code> function via the server's MTA (Postfix/Exim/Sendmail).


Reload crontab: killall -HUP cron (or crond).
{| class="wikitable"
|-
! Setting !! Location !! Description
|-
| From Address || GUI > Settings > System Configuration > Email || <code>DEFAULT_EMAIL_FROM</code> - sender address for all alerts
|-
| Cron Job || <code>/etc/crontab</code> || Required for alert processing
|}


=== Configure Alerts ===
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>


Email alerts trigger on SIP protocol or RTP QoS metrics. Types: RTP alerts and SIP signaling.
== Alert Types ==


Common filters: Call duration, IP addresses, numbers, and email recipients.
Access via '''GUI > Alerts'''.


[[File:alertgrid.png]]
=== RTP Alerts ===


* '''RTP Alerts''': Trigger on MOS, packet loss, jitter, delay, one-way calls (answered but one RTP stream missing), or missing RTP (answered but both streams missing). Alert if thresholds exceeded and incidents > set value or CDR percent > threshold.
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


[[File:alertrtpform.png]]
Configure alerts to trigger when number of incidents OR percentage of CDRs exceeds threshold.


* '''SIP Response Alerts''': Trigger on SIP response codes. Empty response: All call attempts per filters. Response 0: Unreplied INVITEs.
=== RTP&CDR Alerts ===


[[File:alertsipform.png]]
Combine RTP metrics with CDR conditions including '''PDD (Post Dial Delay)'''.


* '''Sensors Alerts''': Built-in alert type for monitoring the status and health of VoIPmonitor probes and sniffer instances. This is the most reliable method to check if remote sensors are online and actively monitoring traffic. Unlike simple network port monitoring (which may show a port is open even if the process is frozen or unresponsive), sensors alerts verify that the sensor instance is actively communicating with the VoIPmonitor GUI server. Configure sensors in Settings > Sensors, then create a sensors alert to be notified when a probe goes offline or becomes unresponsive.
'''Using Filter Templates:'''
# Create CDR filter in '''GUI > CDR'''
# Save as template
# In alert config, select from '''Filter template''' dropdown


* '''Filters''':
{{Tip|1=Use filter templates for complex conditions like <code>duration > 14400</code> (calls over 4 hours) or <code>absolute_timeout</code> (truncated recordings).}}
  - IP/Number Group: Apply to defined groups (from Groups menu).
  - IP Addresses/Numbers: Individual IPs, numbers, or ranges (delimited by Enter).
  - Email Group: Send to group-defined emails.
  - Emails: Individual emails (delimited by Enter).


[[File:alertgroup.png]]
=== SIP Response Alerts ===


=== Sent Alerts ===
{| class="wikitable"
|-
! 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.)
|}


Sent alerts are saved in history, matching email content.
==== "from all" Checkbox (Percentage Thresholds) ====


[[File:alert-sentalerts.png]]
{{Warning|1=This setting is critical for IP group monitoring.}}


Parameters table shows QoS metrics with bad values highlighted.
* '''CHECKED''': % calculated from ALL CDRs in database
* '''UNCHECKED''': % calculated only from filtered CDRs (correct for specific IP groups)


[[File:alert-perameters.png]]


CDR records table lists cases, with alert flags: (M)OS, (J)itter, (P)acket loss, (D)elay.


=== Troubleshooting Email Alerts ===
==== SIP Response vs Last SIP Response ====


If email alerts are not being sent, the issue is typically with the Mail Transfer Agent (MTA) rather than VoIPmonitor. Follow these steps to diagnose and fix the problem.
There are two different fields for matching SIP responses:


==== Test Email Delivery from Command Line ====
{| class="wikitable"
|-
! Field !! Location !! Supports % Threshold !! Use Case
|-
| '''SIP response''' || GUI > Alerts > SIP Response Alerts || {{Yes}} || Match by numeric code (e.g., 487, 503)
|-
| '''Last sip response''' || GUI > Alerts > Filter common || {{No}} || Match by full text (e.g., "487 Request Terminated")
|}


Before investigating complex issues, verify your server can send emails at all:
{{Warning|1=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.
# Test sending an email using the 'mail' command
=== International Call Alerts (Called Number Prefixes) ===
echo "Test email body" | mail -s "Test Subject" your.email@example.com
}}}


If this fails, the issue is with your MTA (Postfix, Exim, or Sendmail) and not with VoIPmonitor.
Monitor calls to international destinations using '''prefix-based matching''' (dialing patterns like 00, +).


==== Check Mail Transfer Agent (MTA) Status ====
{{Note|1=This uses phone number prefix detection, NOT IP geolocation. For GeoIP-based detection, see [[Anti-fraud|Anti-Fraud Rules]].}}


Ensure the MTA service is running:
'''Configuration:'''
# '''GUI > Settings > Country prefixes''' - Define international prefixes (00, +), local country, minimum digits
# '''GUI > Alerts > Filter common''' - Configure:


{{{
{| class="wikitable"
# For Postfix (most common)
|-
sudo systemctl status postfix
! 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
|}


# For Exim
=== Sensors Alerts ===
sudo systemctl status exim4


# For Sendmail
Monitor sensor health and status:
sudo systemctl status sendmail
* '''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)


If the service is not running or not installed, install and configure it according to your Linux distribution's documentation.
=== SIP REGISTER Alerts ===


==== Check Mail Logs ====
{| class="wikitable"
|-
! 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
|}


Examine the MTA logs for specific error messages that indicate why emails are failing:
{{Warning|1='''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.}}


{{{
# Debian/Ubuntu (default mail log location)
tail -f /var/log/mail.log


# RHEL/CentOS/Alma/Rocky
tail -f /var/log/maillog


# Look for errors such as:
==== Alert Output Fields ====
# - "Connection refused" - MTA not running or firewall blocking
# - "Relay access denied" - SMTP relay misconfiguration
# - "Authentication failed" - Incorrect credentials for external relay
# - "Host or domain name lookup failed" - DNS issues
# - "Greylisted" - Temporary rejection, may retry later
}}}


Common issues found in logs:
The '''multiple register (beta)''' and other SIP REGISTER alerts output the following fields in email notifications and GUI:
*'''Authentication Issues''': If relaying through an external SMTP server, verify your credentials in `/etc/postfix/sasl_passwd` or the Exim equivalent.
*'''Network Problems''': Check firewall rules (`iptables` or `firewalld`) to ensure outbound SMTP (port 25) is allowed.
*'''DNS Resolution''': If the MTA cannot resolve recipient domains, check `/etc/resolv.conf` and network connectivity.


==== Check Mail Queue ====
{| class="wikitable"
|-
! Field !! Source !! Description
|-
| '''username''' || SIP Contact header || The registered user identity
|-
| '''from''' fields || SIP From header || From-number, From-domain extracted from From header
|-
| '''to''' fields || SIP To header || To-number, To-domain extracted from To header
|-
| '''lookup name''' || Tools > Prefix Lookup || Custom label if phone number matches a configured prefix entry
|}


Emails may be stuck in the queue if delivery is failing:
{{Note|1=The '''lookup name''' column displays custom labels from [[Tools#Prefix_Lookup|Prefix Lookup]] when a phone number matches a configured prefix. If no match exists, the field remains empty or shows the raw number.}}
=== CDR Trends Alerts ===


{{{
Monitor metric deviations from historical baselines (e.g., ASR drops).
# View the mail queue
 
{| class="wikitable"
|-
! 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 <code>save_sip_history = responses</code>)
* '''External script''' - Custom script path for integrations
 
{{Warning|1=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., <code>/usr/local/bin/alert-webhook.sh</code>).
 
'''Arguments passed to script:'''
{| class="wikitable"
|-
! Arg !! Description
|-
| <code>$1</code> || Alert ID
|-
| <code>$2</code> || Alert name
|-
| <code>$3</code> || Unix timestamp
|-
| <code>$4</code> || JSON data with CDR IDs
|}
 
'''Example - Slack notification:'''
<syntaxhighlight lang="bash">
#!/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"'"}'
</syntaxhighlight>
 
{{Note|1=IP addresses in CDR table are decimal integers. Use <code>long2ip()</code> (PHP) or <code>INET_NTOA()</code> (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 <code>/etc/voipmonitor.conf</code>: <code>custom_headers = Max-Forwards</code>
# 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|1=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
 
<syntaxhighlight lang="bash">
# 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
mailq
</syntaxhighlight>
'''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:
<syntaxhighlight lang="bash">
# Verify queue manager is running
ps aux | grep qmgr
# Restart Postfix
systemctl restart postfix
# Force immediate delivery of queued emails
postfix flush
</syntaxhighlight>
=== Alerts Not Triggering ===
'''Enable debug logging:'''
<syntaxhighlight lang="php">
// Add to ./config/system_configuration.php
define('CRON_LOG_FILE', '/tmp/alert.log');
</syntaxhighlight>


# Force immediate delivery attempt
<syntaxhighlight lang="bash">
postqueue -f
# Monitor processing
}}}
tail -f /tmp/alert.log
</syntaxhighlight>


If the queue shows many deferred or failed messages, those messages contain error details explaining why delivery failed.
'''Common causes:'''
* Cron not running - verify with <code>crontab -l</code>
* PHP CLI version mismatch - use <code>update-alternatives --set php /usr/bin/php8.x</code>
* SQL queue growing - DB can't keep up (see [[Scaling]])
* Alert disabled or filter mismatch


==== Verify Cronjob ====
=== Concurrent Calls Alerts ===


Ensure the alert processing script runs every minute:
{| class="wikitable"
|-
! 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).
crontab -l
'''Investigating Fraud: Realtime Concurrent Calls Alerts'''
}}}


You should see a line similar to:
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'''
* * * * * root php /var/www/html/php/run.php cron
# 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 ===


If missing, add it:
# Use '''preview button''' to test alert triggers
{{{
# Verify absolute path (not relative)
crontab -e
# Check permissions: <code>chmod 755 /path/to/script.sh</code>
# Add this line:
# Include shebang: <code>#!/bin/bash</code>
* * * * * root php /var/www/html/php/run.php cron
# Use full command paths (e.g., <code>/usr/bin/curl</code>)
}}}
# For URLs, create script with curl/wget - cannot put URL directly in field


Reload the cron daemon:
=== "Crontab Log Too Old" Warning ===
{{{
killall -HUP cron
}}}


==== Verify Alert Configuration ====
'''Causes:'''
# Cron not running → Add cron entry
# PHP CLI version mismatch → <code>update-alternatives --set php /usr/bin/php8.x</code>
# Database overload → Check SQLq in '''GUI > Settings > Sensors''', see [[Scaling]]


After confirming the MTA works, check that alerts are configured correctly in the GUI:
== See Also ==


1. Navigate to '''GUI > Alerts'''
* [[Anti-fraud|Anti-Fraud Rules]] - Realtime fraud detection
2. Verify alert conditions are enabled
* [[Reports]] - Daily reports and report generator
3. Check that recipient email addresses are valid
* [[Groups]] - IP and number groups for filtering
4. Go to '''GUI > Alerts > Sent Alerts''' to see if alerts were triggered and handed off to the MTA


If entries appear in "Sent Alerts" but recipients never receive emails, the MTA is the issue. If no entries appear, check the alert conditions or cronjob.


==== Testing with PHP ====


You can test PHP's mail() function directly to isolate the issue:


{{{
php -r "mail('your.email@example.com', 'Test from PHP', 'This is a test email');"
}}}


If this works but VoIPmonitor alerts don't, check the GUI cronjob and alert configuration. If it fails, the issue is purely MTA-related.


=== AI Summary for RAG ===
== AI Summary for RAG ==


'''Summary:''' This article covers VoIPmonitor's Alerts & Reports for email notifications on QoS/SIP issues, daily/ad hoc reports, crontab setup, alert configuration (RTP/SIP/Sensors types, filters), viewing sent alerts with metrics and CDR details, and troubleshooting email delivery issues including MTA status, mail logs, queue inspection, and CLI/PHP email testing.
'''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, reports, email notifications, QoS metrics, SIP responses, crontab, RTP alerts, SIP alerts, sensors alerts, filters, history, MTA configuration, troubleshooting, email not working, mail command, postfix, exim, sendmail, mail queue, mail logs
'''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:'''
'''Key Questions:'''
* How do I set up email alerts in VoIPmonitor?
* How do I configure email alerts in VoIPmonitor?
* What are the types of alerts (RTP vs. SIP vs. Sensors)?
* What alert types are available (RTP, SIP, Sensors)?
* How do I configure crontab for alert processing?
* How do I configure international call alerts with prefix filtering?
* What filters can I use for alerts?
* What does the "from all" checkbox do in percentage alerts?
* How are sent alerts stored and viewed?
* How do I integrate alerts with webhooks (Slack, Datadog)?
* What do alert flags in CDR mean?
* Why are my alerts not triggering?
* How do I monitor the status of remote VoIPmonitor sensors and probes?
* How do I troubleshoot email delivery issues?
* Why are email alerts not being sent?
* What is the difference between fraud and regular concurrent calls alerts?
* How do I test email delivery from command line?
* How do I detect SIP registration attacks (brute-force)?
* How do I troubleshoot MTA (Postfix/Exim/Sendmail) email issues?
* Do alerts support AND logic between conditions?
* How do I check mail logs and mail queue?

Latest revision as of 10:34, 17 January 2026


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:

  1. Create CDR filter in GUI > CDR
  2. Save as template
  3. 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 ✓ Yes Match by numeric code (e.g., 487, 503)
Last sip response GUI > Alerts > Filter common ✗ 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:

  1. GUI > Settings > Country prefixes - Define international prefixes (00, +), local country, minimum digits
  2. 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.


Alert Output Fields

The multiple register (beta) and other SIP REGISTER alerts output the following fields in email notifications and GUI:

Field Source Description
username SIP Contact header The registered user identity
from fields SIP From header From-number, From-domain extracted from From header
to fields SIP To header To-number, To-domain extracted from To header
lookup name Tools > Prefix Lookup Custom label if phone number matches a configured prefix entry

ℹ️ Note: The lookup name column displays custom labels from Prefix Lookup when a phone number matches a configured prefix. If no match exists, the field remains empty or shows the raw number.

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:

  1. Capture header in /etc/voipmonitor.conf: custom_headers = Max-Forwards
  2. Enable in GUI > Settings > CDR Custom Headers
  3. Create filter in CDR view, save as template
  4. 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:

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

External Script Not Running

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

"Crontab Log Too Old" Warning

Causes:

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

See Also




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?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Alerts&oldid=10738"