Alerts: Difference between revisions

From VoIPmonitor.org
(Add SIP REGISTER RRD beta alert documentation for monitoring retransmissions and registration response times)
(Fix template syntax - remove curly braces from 'from' and 'to' field names)
 
(36 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Alerts & Reports}}
{{DISPLAYTITLE:Alerts & Reports}}
Category:GUI manual
[[Category:GUI manual]]


== Alerts & Reports ==
= Alerts & Reports =


Alerts & Reports generate email notifications based on QoS parameters or SIP error conditions. The system includes daily reports, ad hoc reports, and stores all generated items in history.
Email notifications triggered by QoS thresholds, SIP errors, or sensor health conditions. The system stores all alerts in history for review.
 
=== Overview ===
 
The alert system monitors call quality and SIP signaling in real-time, triggering notifications when configured thresholds are exceeded.


<kroki lang="plantuml">
<kroki lang="plantuml">
Line 14: Line 10:
skinparam shadowing false
skinparam shadowing false
skinparam defaultFontName Arial
skinparam defaultFontName Arial
 
rectangle "Sensor" as sensor
rectangle "VoIPmonitor\nSensor" as sensor
database "MySQL" as db
database "MySQL\nDatabase" as db
rectangle "Cron\n(1min)" as cron
rectangle "Cron Job\n(every minute)" as cron
rectangle "Alert\nProcessor" as processor
rectangle "Alert\nProcessor" as processor
rectangle "MTA\n(Postfix/Exim)" as mta
rectangle "MTA" as mta
actor "Admin" as admin
actor "Admin" as admin
 
sensor --> db : CDRs
sensor --> db : CDRs with\nQoS metrics
cron --> processor : Trigger
cron --> processor : Trigger
processor --> db : Query alerts\n& CDRs
processor --> db : Query
processor --> mta : Send email
processor --> mta : Email
mta --> admin : Alert notification
mta --> admin : Alert
@enduml
@enduml
</kroki>
</kroki>


=== Email Configuration Prerequisites ===
== Prerequisites ==


Emails are sent using PHP's <code>mail()</code> function, which relies on the server's Mail Transfer Agent (MTA) such as Exim, Postfix, or Sendmail. Configure your MTA according to your Linux distribution documentation.
=== Email Configuration ===


==== Setting Up the Cron Job ====
Alerts use PHP's <code>mail()</code> function via the server's MTA (Postfix/Exim/Sendmail).


Alert processing requires a cron job that runs every minute:
{| 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
|}


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Add to /etc/crontab (adjust path based on your GUI installation)
# Add cron job (required)
echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab
echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab
# Reload crontab
killall -HUP cron  # Debian/Ubuntu
killall -HUP cron  # Debian/Ubuntu
# or
# or: killall -HUP crond  # RHEL/CentOS
killall -HUP crond  # CentOS/RHEL
</syntaxhighlight>
</syntaxhighlight>


=== Configure Alerts ===
== Alert Types ==
 
Email alerts can trigger on SIP protocol events or RTP QoS metrics. Access alerts configuration via '''GUI > Alerts'''.


[[File:alertgrid.png|frame|center|Alert configuration grid]]
Access via '''GUI > Alerts'''.


==== Alert Types ====
=== RTP Alerts ===


===== RTP Alerts =====
Trigger on voice quality metrics:
 
* '''MOS''' - below threshold
RTP alerts trigger based on voice quality metrics:
* '''MOS''' (Mean Opinion Score) - below threshold
* '''Packet loss''' - percentage exceeded
* '''Packet loss''' - percentage exceeded
* '''Jitter''' - variation exceeded
* '''Jitter''' - variation exceeded
* '''Delay''' (PDV) - latency exceeded
* '''Delay''' (PDV) - latency exceeded
* '''One-way calls''' - answered but one RTP stream missing
* '''One-way calls''' - one RTP stream missing
* '''Missing RTP''' - answered but both RTP streams missing
* '''Missing RTP''' - both RTP streams missing


Configure alerts to trigger when:
Configure alerts to trigger when number of incidents OR percentage of CDRs exceeds threshold.
* Number of incidents exceeds a set value, OR
* Percentage of CDRs exceeds a threshold


[[File:alertrtpform.png|frame|center|RTP alert configuration form]]
=== RTP&CDR Alerts ===


===== SIP Response Alerts =====
Combine RTP metrics with CDR conditions including '''PDD (Post Dial Delay)'''.


SIP response alerts trigger based on SIP response codes:
'''Using Filter Templates:'''
* '''Empty response field''': Matches all call attempts per configured filters
# Create CDR filter in '''GUI > CDR'''
* '''Response code 0''': Matches unreplied INVITE requests (no response received)
# Save as template
* '''Specific codes''': Match exact codes like 404, 503, etc.
# In alert config, select from '''Filter template''' dropdown


[[File:alertsipform.png|frame|center|SIP response alert configuration form]]
{{Tip|1=Use filter templates for complex conditions like <code>duration > 14400</code> (calls over 4 hours) or <code>absolute_timeout</code> (truncated recordings).}}


===== Sensors Alerts =====
=== SIP Response Alerts ===


Sensors alerts monitor the health of VoIPmonitor probes and sniffer instances. This is the most reliable method to check if remote sensors are online and actively monitoring traffic.
{| 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.)
|}
 
==== "from all" Checkbox (Percentage Thresholds) ====


Unlike simple network port monitoring (which may show a port as open even if the process is frozen or unresponsive), sensors alerts verify that the sensor instance is actively communicating with the VoIPmonitor GUI server.
{{Warning|1=This setting is critical for IP group monitoring.}}


;Setup:
* '''CHECKED''': % calculated from ALL CDRs in database
:# Configure sensors in '''Settings > Sensors'''
* '''UNCHECKED''': % calculated only from filtered CDRs (correct for specific IP groups)
:# Create a sensors alert to be notified when a probe goes offline or becomes unresponsive


===== SIP REGISTER RRD Beta Alerts =====


The '''SIP REGISTER RRD beta''' alert type monitors SIP REGISTER response times and alerts when REGISTER packets do not receive a response within a specified threshold (in milliseconds). This is useful for detecting network latency issues, packet loss, or failing switches that cause SIP retransmissions.


This alert serves as an effective proxy to monitor for registration issues, as REGISTER retransmissions often indicate problems with network connectivity or unresponsive SIP servers.
==== SIP Response vs Last SIP Response ====


;Configuration:
There are two different fields for matching SIP responses:
:# Navigate to '''GUI > Alerts'''
:# Create a new alert with type '''SIP REGISTER RRD beta'''
:# Set the response time threshold in milliseconds (e.g., alert if REGISTER does not receive a response within 2000ms)
:# Configure recipient email addresses
:# Save the alert configuration


The system monitors REGISTER packets and triggers an alert when responses exceed the configured threshold, indicating potential SIP registration failures or network issues.
{| 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")
|}


[[File:alertgrid.png|frame|center|Alert configuration grid]]
{{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.}}


==== Common Filters ====
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) ===


All alert types support the following filters:
Monitor calls to international destinations using '''prefix-based matching''' (dialing patterns like 00, +).
 
{{Note|1=This uses phone number prefix detection, NOT IP geolocation. For GeoIP-based detection, see [[Anti-fraud|Anti-Fraud Rules]].}}
 
'''Configuration:'''
# '''GUI > Settings > Country prefixes''' - Define international prefixes (00, +), local country, minimum digits
# '''GUI > Alerts > Filter common''' - Configure:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Filter !! Description
! Setting !! Description
|-
| IP/Number Group || Apply alert to predefined groups (from '''Groups''' menu)
|-
|-
| IP Addresses || Individual IPs or ranges (one per line)
| Called number prefixes || Which prefixes trigger alert (uncheck ALL for all international)
|-
|-
| Numbers || Individual phone numbers or prefixes (one per line)
| Exclude called number || Country codes to exclude (e.g., +44, 0044 for UK)
|-
|-
| Email Group || Send alerts to group-defined email addresses
| Strict for prefixes || Require international prefix (00/+)
|-
|-
| Emails || Individual recipient emails (one per line)
| NANPA || North American Numbering Plan
|}
|}


[[File:alertgroup.png|frame|center|Alert filter configuration]]
=== Sensors Alerts ===


=== Sent 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)


All triggered alerts are saved in history and can be viewed via '''GUI > Alerts > Sent Alerts'''. The content matches what was sent via email.
=== SIP REGISTER Alerts ===


[[File:alert-sentalerts.png|frame|center|Sent alerts history]]
{| 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
|}


==== Parameters Table ====
{{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.}}


The parameters table shows QoS metrics with problematic values highlighted for quick identification.


[[File:alert-perameters.png|frame|center|Alert parameters with highlighted bad values]]


==== CDR Records Table ====
==== Alert Output Fields ====


The CDR records table lists all calls that triggered the alert. Each row includes alert flags indicating which thresholds were exceeded:
The '''multiple register (beta)''' and other SIP REGISTER alerts output the following fields in email notifications and GUI:
* '''(M)''' - MOS below threshold
* '''(J)''' - Jitter exceeded
* '''(P)''' - Packet loss exceeded
* '''(D)''' - Delay exceeded


=== Anti-Fraud Alerts ===
{| 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
|}


VoIPmonitor includes specialized anti-fraud alert rules for detecting attacks and fraudulent activity. These include:
{{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.}}
* Realtime concurrent calls monitoring
=== CDR Trends Alerts ===
* SIP REGISTER flood/attack detection
* SIP PACKETS flood detection
* Country/Continent destination alerts
* CDR/REGISTER country change detection


For detailed configuration of anti-fraud rules and custom action scripts, see [[Anti-fraud|Anti-Fraud Rules]].
Monitor metric deviations from historical baselines (e.g., ASR drops).


=== Alerts Based on Custom Reports ===
{| 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
|}


In addition to native alert types (RTP, SIP response, Sensors), VoIPmonitor supports generating alerts from custom reports. This workflow enables alerts based on criteria not available in native alert types, such as SIP header values captured via CDR custom headers.
== Common Filters ==


==== Workflow Overview =====
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


1. [[Settings#CDR_Custom_Headers|Capture custom SIP headers]] in the database
{{Warning|1=Alerts use '''OR logic''' between conditions. AND logic is NOT supported. Workaround: create separate alerts and correlate manually.}}
2. Create a custom report filtered by the custom header values
3. Generate an alert from that report
4. Configure alert email options (e.g., limit email size)


==== Example: Alert on SIP Max-Forwards Header Value =====
=== Caller vs Called Filtering ===


This example shows how to receive an alert when the SIP <code>Max-Forwards</code> header value drops below 15.
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]].


'''Step 1: Configure Sniffer Capture'''
== External Scripts ==


Add the header to your <code>/etc/voipmonitor.conf</code> configuration file:
Enable webhook integration (Datadog, Slack, custom systems).


<syntaxhighlight lang="ini">
'''Configuration:''' Enter full absolute path in '''External script''' field (e.g., <code>/usr/local/bin/alert-webhook.sh</code>).
# Capture Max-Forwards header
custom_headers = Max-Forwards
</syntaxhighlight>


Restart the sniffer to apply changes:
'''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">
<syntaxhighlight lang="bash">
service voipmonitor restart
#!/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>
</syntaxhighlight>


'''Step 2: Configure Custom Header in GUI'''
{{Note|1=IP addresses in CDR table are decimal integers. Use <code>long2ip()</code> (PHP) or <code>INET_NTOA()</code> (MySQL) for conversion.}}


1. Navigate to '''GUI > Settings > CDR Custom Headers'''
== Sent Alerts ==
2. Select <code>Max-Forwards</code> from the available headers
3. Enable '''Show as Column''' to display it in CDR views
4. Save configuration


'''Step 3: Create Custom Report'''
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


1. Navigate to '''GUI > CDR Custom Headers''' or use the Report Generator
== Custom Report Alerts ==
2. Create a filter for calls where <code>Max-Forwards</code> is less than 15
3. Since custom headers store string values, use a filter expression that matches the desired values:
<syntaxhighlight lang="text">
15 14 13 12 11 10 0_ _
</syntaxhighlight>
  Include additional space-separated values or use NULL to match other ranges as needed.


4. Run the report to verify it captures the expected calls
Alert on criteria not in native types (e.g., custom SIP headers).


'''Step 4: Generate Alert from Report'''
'''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'''


You can create an alert based on this custom report using the Daily Reports feature:
{{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.}}


1. Navigate to '''GUI > Reports > Configure Daily Reports'''
== Troubleshooting ==
2. Click '''Add Daily Report'''
3. Configure the filter to target the custom header criteria (e.g., Max-Forwards < 15)
4. Set the schedule (e.g., run every hour)
5. Save the daily report configuration


'''Step 5: Limit Alert Email Size (Optional)'''
=== Email Not Sent ===


If the custom report generates many matching calls, the alert email can become large. To limit the email size:
'''Diagnosis:'''
* Entries in "Sent Alerts" but no email → MTA issue
* No entries in "Sent Alerts" → Alert conditions or cron issue


1. Edit the daily report
<syntaxhighlight lang="bash">
2. Go to the '''Basic Data''' tab
# Test MTA
3. Set the '''max-lines in body''' option to the desired limit (e.g., 100 lines)
echo "Test" | mail -s "Test" your@email.com


==== Additional Use Cases =====
# Check MTA status
systemctl status postfix  # or exim4/sendmail


This workflow can be used for various custom monitoring scenarios:
# Check logs
tail -f /var/log/mail.log  # Debian/Ubuntu
tail -f /var/log/maillog  # RHEL/CentOS


* '''SIP headers beyond standard SIP response codes''' - Monitor any custom SIP header
# Check mail queue
* '''Complex filtering logic''' - Create reports based on multiple custom header filters
mailq
* '''Threshold monitoring for string fields''' - When numeric comparison is not available, use string matching
</syntaxhighlight>


For more information on configuring custom headers, see [[Settings#CDR_Custom_Headers|CDR Custom Headers]].
'''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:


=== Troubleshooting Email Alerts ===
<syntaxhighlight lang="bash">
# Verify queue manager is running
ps aux | grep qmgr


If email alerts are not being sent, the issue is typically with the Mail Transfer Agent (MTA) rather than VoIPmonitor.
# Restart Postfix
systemctl restart postfix


==== Step 1: Test Email Delivery from Command Line ====
# Force immediate delivery of queued emails
 
postfix flush
Before investigating complex issues, verify your server can send emails:
</syntaxhighlight>
=== Alerts Not Triggering ===


<syntaxhighlight lang="bash">
'''Enable debug logging:'''
# Test using the 'mail' command
<syntaxhighlight lang="php">
echo "Test email body" | mail -s "Test Subject" your.email@example.com
// Add to ./config/system_configuration.php
define('CRON_LOG_FILE', '/tmp/alert.log');
</syntaxhighlight>
</syntaxhighlight>
If this fails, the issue is with your MTA configuration, not VoIPmonitor.
==== Step 2: Check MTA Service Status ====
Ensure the MTA service is running:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# For Postfix (most common)
# Monitor processing
sudo systemctl status postfix
tail -f /tmp/alert.log
 
# For Exim (Debian default)
sudo systemctl status exim4
 
# For Sendmail
sudo systemctl status sendmail
</syntaxhighlight>
</syntaxhighlight>


If the service is not running or not installed, install and configure it according to your Linux distribution's documentation.
'''Common causes:'''
 
* Cron not running - verify with <code>crontab -l</code>
==== Step 3: Check Mail Logs ====
* 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


Examine the MTA logs for specific error messages:
=== Concurrent Calls Alerts ===


<syntaxhighlight lang="bash">
# Debian/Ubuntu
tail -f /var/log/mail.log
# RHEL/CentOS/AlmaLinux/Rocky
tail -f /var/log/maillog
</syntaxhighlight>
Common errors and their meanings:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Error Message !! Cause !! Solution
! Type !! Data Source !! Aggregation !! Timing
|-
| Connection refused || MTA not running or firewall blocking || Start MTA service, check firewall rules
|-
| Relay access denied || SMTP relay misconfiguration || Configure proper relay settings
|-
|-
| Authentication failed || Incorrect credentials || Verify credentials in sasl_passwd
| '''Fraud concurrent calls''' || SIP INVITEs (realtime) || Source IP only || Immediate
|-
|-
| Host or domain name lookup failed || DNS issues || Check /etc/resolv.conf
| '''Regular concurrent calls''' || CDRs (database) || Source/Dest IP, Domain, Custom || Delayed
|-
| Greylisted || Temporary rejection || Wait and retry, or whitelist sender
|}
|}


==== Step 4: Check Mail Queue ====
Use regular concurrent calls for destination IP monitoring (trunk capacity).
 
'''Investigating Fraud: Realtime Concurrent Calls Alerts'''
Emails may be stuck in the queue if delivery is failing:
 
<syntaxhighlight lang="bash">
# View the mail queue
mailq
 
# Force immediate delivery attempt
postqueue -f
</syntaxhighlight>
 
Deferred or failed messages in the queue contain error details explaining why delivery failed.
 
==== Step 5: Verify Cronjob ====
 
Ensure the alert processing script runs every minute:
 
<syntaxhighlight lang="bash">
# Check current crontab
crontab -l
</syntaxhighlight>


You should see:
Since this alert type triggers before CDRs are written, use the following procedure to investigate the calls that triggered the alert:
<syntaxhighlight lang="bash">
# Navigate to '''GUI → CDR'''
* * * * * root php /var/www/html/php/run.php cron
# Use the filter form to add the '''is international''' filter
</syntaxhighlight>
# 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
<syntaxhighlight lang="bash">
# Verify absolute path (not relative)
crontab -e
# Check permissions: <code>chmod 755 /path/to/script.sh</code>
# Add the line above, then reload cron
# Include shebang: <code>#!/bin/bash</code>
killall -HUP cron
# Use full command paths (e.g., <code>/usr/bin/curl</code>)
</syntaxhighlight>
# For URLs, create script with curl/wget - cannot put URL directly in field


==== Step 6: Verify Alert Configuration in GUI ====
=== "Crontab Log Too Old" Warning ===


After confirming the MTA works:
'''Causes:'''
# Navigate to '''GUI > Alerts'''
# Cron not running → Add cron entry
# Verify alert conditions are enabled
# PHP CLI version mismatch → <code>update-alternatives --set php /usr/bin/php8.x</code>
# Check that recipient email addresses are valid
# Database overload → Check SQLq in '''GUI > Settings > Sensors''', see [[Scaling]]
# Go to '''GUI > Alerts > Sent Alerts''' to see if alerts were triggered


'''Diagnosis:'''
== See Also ==
* Entries in "Sent Alerts" but no emails received → MTA issue
* No entries in "Sent Alerts" → Check alert conditions or cronjob


==== Step 7: Test PHP mail() Function ====
* [[Anti-fraud|Anti-Fraud Rules]] - Realtime fraud detection
* [[Reports]] - Daily reports and report generator
* [[Groups]] - IP and number groups for filtering


Isolate the issue by testing PHP directly:


<syntaxhighlight lang="bash">
php -r "mail('your.email@example.com', 'Test from PHP', 'This is a test email');"
</syntaxhighlight>


* If this works but VoIPmonitor alerts don't → Check GUI cronjob and alert configuration
* If this fails → MTA or PHP configuration issue


=== See Also ===


* [[Anti-fraud|Anti-Fraud Rules]] - Detailed fraud detection configuration
* [[Reports|Reports]] - Daily reports and report generator
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - General troubleshooting


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


'''Summary:''' VoIPmonitor Alerts & Reports system for email notifications on QoS and SIP issues. Covers RTP alerts (MOS, jitter, packet loss), SIP response alerts, sensors health monitoring, SIP REGISTER RRD beta alerts for monitoring registration response times, and creating alerts from custom reports based on CDR custom headers. Includes email troubleshooting for MTA configuration.
'''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, sensors monitoring, SIP REGISTER RRD beta, REGISTER retransmissions, registration monitoring, crontab, MTA, Postfix, Exim, troubleshooting, custom headers, custom reports, Max-Forwards, daily reports
'''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 types of alerts are available (RTP, SIP, Sensors, REGISTER RRD beta)?
* What alert types are available (RTP, SIP, Sensors)?
* How do I monitor and alert on SIP REGISTER retransmissions?
* How do I configure international call alerts with prefix filtering?
* How do I detect registration response time issues?
* What does the "from all" checkbox do in percentage alerts?
* How can I use SIP REGISTER RRD beta alert for detecting switch problems?
* How do I integrate alerts with webhooks (Slack, Datadog)?
* How do I configure crontab for alert processing?
* Why are my alerts not triggering?
* How do I monitor remote sensor health?
* 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 troubleshoot MTA email issues?
* How do I detect SIP registration attacks (brute-force)?
* How can I create alerts based on SIP headers like Max-Forwards?
* Do alerts support AND logic between conditions?
* How do I use CDR custom headers for custom reports?
* How do I limit the size of alert emails from custom reports?

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"