Reports: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting section for missing daily_reports_sended table causing daily reports to be unconfigurable)
(Rewrite: consolidated structure, removed redundancy, improved tables and troubleshooting organization)
 
Line 4: Line 4:
= Reports =
= Reports =


Reports include daily reports, instant report generator, call summary, QoS report, and CDR simplified view.
VoIPmonitor provides multiple report types for analyzing call data, quality metrics, and generating scheduled summaries.


<kroki lang="plantuml">
<kroki lang="mermaid">
@startuml
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 25}}}%%
skinparam shadowing false
flowchart LR
skinparam defaultFontName Arial
    subgraph Sources
skinparam rectangle {
        CDR[(CDR DB)]
  BorderColor #4A90E2
        RTP[(RTP Stats)]
  BackgroundColor #FFFFFF
    end
}
    subgraph Types
        Daily[Daily Email]
        Gen[Report Generator]
        Sum[Call Summary]
        QoS[QoS Report]
    end
    subgraph Output
        Email[Email]
        CSV[CSV Export]
        GUI[GUI Display]
    end
    CDR --> Daily & Gen & Sum & QoS
    RTP --> Daily & QoS
    Daily --> Email
    Gen --> GUI & CSV
    Sum --> GUI & CSV
    QoS --> GUI
</kroki>


rectangle "Data Sources" as DS {
{| class="wikitable"
  database "CDR Database" as cdr
|-
  database "RTP Statistics" as rtp
! Report Type !! Purpose !! Output
}
|-
 
| Daily Email Reports || Scheduled summaries (RTP, CPS, charts, CDR summary) || Email
rectangle "Report Types" as RT {
|-
  rectangle "Daily Email Reports" as daily
| Report Generator || Ad-hoc historical analysis || GUI, CSV
  rectangle "Report Generator" as gen
|-
  rectangle "Call Summary" as sum
| Call Summary || Aggregated by IP (ASR, ACD, duration) || GUI, CSV
  rectangle "QoS Report" as qos
|-
}
| QoS Report || RTP quality metrics (MOS, jitter, loss) || GUI
 
|-
rectangle "Output" as OUT {
| CDR Simplified || Quick CDR view with filters || GUI
  rectangle "Email" as email
|}
  rectangle "CSV Export" as csv
  rectangle "GUI Display" as gui
}


cdr --> daily
== Prerequisites ==
cdr --> gen
cdr --> sum
cdr --> qos
rtp --> daily
rtp --> qos


daily --> email
Reports require a working cron job for scheduled delivery. See [[Alerts#Email_Configuration|Alerts - Email Configuration]] for cron setup and MTA requirements.
gen --> gui
gen --> csv
sum --> gui
sum --> csv
qos --> gui


note right of daily
{{Note|1=For scheduled reports, ensure <code>cleandatabase</code> in <code>/etc/voipmonitor.conf</code> exceeds your longest report period (e.g., >30 days for monthly reports). See [[Data_Cleaning]].}}
  Scheduled via
  Crontab Scheduler
end note
@enduml
</kroki>


== Daily Email Reports ==
== Daily Email Reports ==


Daily email reports resemble alerts but send once per day and can include daily charts based on criteria.
Navigate to '''GUI > Reports > Configure Daily Reports''' to create scheduled reports.
 
[[File:reports-daily.png|frame|center|Daily reports configuration]]


=== RTP Daily Report ===
=== RTP Daily Report ===


Summarizes RTP metrics: MOS, packet loss, jitter, delay (PDV), duration, one-way, and missing RTP.
Summarizes RTP metrics: MOS, packet loss, jitter, delay (PDV), duration, one-way, and missing RTP.
[[File:Alert-sentalerts.png|frame|center|RTP daily report example]]


=== CPS Daily Report ===
=== CPS Daily Report ===


CPS (Calls Per Second) report provides daily statistics of call volume rate. Reports maximum and average CPS over the selected period.
Reports maximum and average Calls Per Second (CPS) over the selected period.
 
* Navigate to '''GUI > Reports > Configure Daily Reports'''
* Select '''CPS''' as the report type to receive periodic email summaries of maximum and average CPS


=== Daily Charts Report ===
=== Daily Charts Report ===


Generates daily chart statistics. Create multiple charts per report, filtered by CDR criteria (e.g., SIP trunks).
Generates visual charts of call metrics filtered by criteria (SIP trunks, numbers, IP).


==== Report Time Range Settings ====
'''Time Range Settings:'''
 
{| class="wikitable"
When configuring a daily charts report, you can set the time range to generate regular daily, weekly, or monthly reports:
|-
 
! Period !! Configuration
* '''Daily reports:''' Use the '''"last day 1"''' time range setting.
|-
* '''Weekly reports:''' Select '''"this week from Monday"''' and enable the '''"previous interval"''' checkbox to report on the completed week.
| Daily || <code>"last day 1"</code>
* '''Monthly reports:''' Select '''"previous month"''' to generate reports for the previous calendar month.
|-
 
| Weekly || <code>"this week from Monday"</code> + enable <code>"previous interval"</code>
Multiple charts can be included in a single report (e.g., MOS, concurrent calls, jitter, and packet loss on the same SIP trunk).
|-
 
| Monthly || <code>"previous month"</code>
==== Creating and Using Chart Templates ====
|}
 
When creating a scheduled charts report, you must first create and save chart templates:
 
# Navigate to '''GUI > Reports > Configure Daily Reports'''
# Select '''"Charts"''' as the report type
# Click the chart creation button to open the chart configuration dialog
# Configure your desired chart with:
:** Filter by CDR criteria (SIP trunks, numbers, IP addresses)
:** Select metrics to display (MOS, packet loss, jitter, concurrent calls, etc.)
:** Set chart type and visualization options
# Save the chart configuration as a '''chart template'''
# Attach the saved chart templates to the scheduled report
 
[[File:report-dailychart.png|frame|center|Daily charts report configuration]]
 
Chart creation dialog allows custom charts with filters on numbers, IP, RTP stats.
 
[[File:report-chartedit.png|frame|center|Chart creation dialog]]
 
Preview results or send test emails via buttons.
 
[[File:report-chartbuttons.png|frame|center|Report preview and test buttons]]
[[File:report-preview.png|frame|center|Report preview result]]
 
==== Data Retention Requirements for Scheduled Reports ====
 
To ensure scheduled reports have complete data, verify that CDRs are retained for the entire reporting period. The <code>cleandatabase</code> option in <code>/etc/voipmonitor.conf</code> controls how long data is kept in the database.
 
{{Note|1=Check the <code>cleandatabase</code> setting in <code>/etc/voipmonitor.conf</code> and set it to a value greater than the longest report period. For example: set it to >30 days for monthly reports. This will increase database size in <code>/var/lib/mysql</code>.}}


{{Tip|Schedule resource-intensive reports (such as 30-day charts) to run during different off-peak nighttime hours to avoid performance issues. Spread large report tasks across multiple time slots to reduce database load.}}
'''Creating Chart Templates:'''
# Navigate to '''GUI > Reports > Configure Daily Reports > Charts'''
# Click chart creation button
# Configure filters (CDR criteria, IP addresses, numbers)
# Select metrics (MOS, packet loss, jitter, concurrent calls)
# Save as '''chart template'''
# Attach template to scheduled report


See [[Data_Cleaning]] for detailed information about data retention and cleanup.
{{Tip|Schedule resource-intensive reports (30-day charts) during off-peak hours to reduce database load.}}


=== CDR Summary Report ===
=== CDR Summary Report ===


The CDR Summary report provides a daily summary of call data that can be grouped by different criteria. This report type includes optional billing cost information and flexible aggregation options.
Daily summary grouped by various criteria with optional billing costs.
 
To generate a CDR summary report:
 
# Navigate to '''GUI > Reports > Configure Daily Reports'''
# Select '''CDR summary''' as the report type
# Choose the '''Summary type''' from the dropdown menu:
:* '''source IP''' - Group calls by source IP address (default)
:* '''source number''' - Group calls by source telephone number
:* '''destination IP''' - Group calls by destination IP address
:* '''destination number''' - Group calls by destination telephone number
:* '''Called number group''' - Group calls by telephone number groups for called numbers (requires [[Groups|Telephone Number Groups]])
:* '''Caller number group''' - Group calls by telephone number groups for caller numbers (requires [[Groups|Telephone Number Groups]])
# Configure filters using the filter tabs:
:* In the '''Common tab''', set '''Last SIP response''' to specific codes to filter by SIP response. Use patterns like <code>%OK%</code>, <code>487%</code>, or <code>486 Bu%</code> to match responses
# Configure the date range, schedule, and recipients
# (Optional) Enable the '''Price columns''' option to include billing costs (requires [[Billing|Billing Configuration]])
 
'''Note:''' For costs to appear in the report, the billing system must be configured and costs must be calculated for the CDRs in your database. See [[Call_Detail_Record_-_CDR|CDR View]] for how to verify costs are being calculated by enabling the PRICE column.
 
==== Using Number Group Summary Types ====
 
The '''Called number group''' and '''Caller number group''' summary types allow you to aggregate CDRs by predefined telephone number groups instead of individual numbers. This is useful for:
 
* Grouping calls by customer number ranges
* Reporting on NPA-NXX area code and exchange prefixes
* Aggregating traffic by service provider or trunk groups
* Creating summary reports for specific number patterns
 
'''Example: Reporting on NPA-NXX Prefixes'''
 
To generate a report showing the top NPA-NXX destinations (the first 6 digits of phone numbers):
 
# Navigate to '''GUI > Groups > Tel. numbers'''
# Create a telephone number group for each NPA-NXX prefix (e.g., "202333", "202555", etc.)
#* Add each prefix with its country code variant (e.g., enter both <code>1202333</code> and <code>202333</code> to match E.164 format numbers)
# Navigate to '''GUI > Reports > Configure Daily Reports'''
# Select '''CDR summary''' as the report type
# Set '''Summary type''' to '''Called number group'''
# In the '''Common tab''', select your NPA-NXX groups in the '''Called number group''' field
# Configure the date range and schedule
# Use '''Preview report''' to verify results
 
{{Note|1=This method requires knowing the NPA-NXX prefixes in advance and creating groups for each one. It cannot be used to dynamically discover the top N prefixes. For dynamic discovery, export CDRs via the [[#Report Generator|Report Generator]] and analyze using external tools like Excel or direct SQL queries.}}
 
=== Multiple SIP Response Codes in Separate Reports ===
 
If you need to analyze counts for multiple different SIP response codes (e.g., 200 OK, 404, 486, 487) grouped by called number, '''create multiple separate CDR summary reports''' - one for each response code pattern.
 
For example, to see counts for different SIP responses by called number:
* Create Report 1: Summary type = '''destination number''', Last SIP response = <code>%OK%</code>
* Create Report 2: Summary type = '''destination number''', Last SIP response = <code>404%</code>
* Create Report 3: Summary type = '''destination number''', Last SIP response = <code>486%</code>
* Create Report 4: Summary type = '''destination number''', Last SIP response = <code>487%</code>
 
Each report will show counts for a specific response type, grouped by the called number. View the reports individually or use the '''Preview report''' button to see results immediately without waiting for the scheduled delivery.
 
=== Using Preview Report for Instant Results ===
 
The '''Preview report''' button allows you to instantly view report results without waiting for the scheduled time. This is useful for testing report configuration before enabling automatic delivery.
 
== Regulatory Reporting ==
 
VoIPmonitor provides several metrics commonly required for regulatory telecommunications reports. These metrics are available in the Call Summary, Report Generator, and CDR Summary report types.
 
'''Available Regulatory Metrics:'''


'''Summary Types:'''
{| class="wikitable"
{| class="wikitable"
|-
|-
! Metric Name !! VoIPmonitor Column !! Description !! Report Locations
! Type !! Description
|-
|-
| Average Call Setup Success Ratio || <code>asr_all</code> || Answer Seizure Ratio - percentage of calls that connect successfully || Call Summary, Report Generator, CDR Summary (Export CSV)
| source IP / destination IP || Group by IP address
|-
|-
| Average Call Setup Time || <code>pdd_all</code> || Post Dial Delay - time from INVITE to 100/183 response in milliseconds || Report Generator (Export CSV)
| source number / destination number || Group by telephone number
|-
|-
| Average MOS || <code>mos_all</code> || Mean Opinion Score - voice quality rating (1=Poor to 5=Excellent) || Call Summary, Report Generator, CDR Summary (Export CSV)
| Called/Caller number group || Group by predefined [[Groups|Telephone Number Groups]]
|}
|}


'''Unsupported Metric:'''
'''Configuration:'''
# Select '''CDR summary''' as report type
# Choose '''Summary type''' from dropdown
# Filter by SIP response in '''Common tab''' (e.g., <code>%OK%</code>, <code>404%</code>)
# Enable '''Price columns''' for billing costs (requires [[Billing|Billing Configuration]])


* '''Average Dropped Call Ratio (DCR):''' This metric is '''not currently available''' in VoIPmonitor. Different regulators use different formulas for calculating dropped calls, and the software does not have a pre-existing implementation. If you require this metric for regulatory compliance, submit a feature request with your specific formula requirements so it can be added to the product roadmap.
{{Note|1=For multiple SIP response codes, create '''separate reports''' for each code pattern. A single report cannot aggregate multiple response types.}}


'''Exporting Regulatory Reports:'''
'''NPA-NXX Prefix Reporting:'''
 
# Create telephone number groups in '''GUI > Groups > Tel. numbers''' for each prefix
To create a regulatory audit report:
# Include country code variants (e.g., both <code>1202333</code> and <code>202333</code>)
 
# Use '''Called number group''' summary type
# Navigate to '''GUI > Reports > Call Summary''' or '''GUI > Reports > Report Generator'''
# Select groups in filter field
# Set the required time period matching your regulatory reporting interval
# Apply any necessary filters (IP ranges, numbers, QoS parameters)
# Click '''Show''' (Report Generator) or use the default view (Call Summary)
# Export to CSV using the '''Export CSV''' button for archival or compliance submission
# Alternatively, create a CDR Summary scheduled report for automated delivery
 
The CSV export includes all regulatory metrics in machine-readable format suitable for external validation and archival.


== Report Generator ==
== Report Generator ==


Creates reports from historical data by criteria.
'''GUI > Reports > Report Generator''' - Creates ad-hoc reports from historical data.


* '''"Only CDR with RTP" checkbox''': Reports connected calls only (ASR always 100%) or all CDRs.
* '''"Only CDR with RTP"''' checkbox: Reports only connected calls (ASR always 100%)
* Filter by date range, IP, numbers, QoS parameters
* Export results to CSV


[[File:report-generatorform.png|frame|center|Report generator form]]
{{Warning|1='''Limitation:''' Cannot combine "group by customer" AND "destination country" filters in one report. Create separate reports for each customer with both filters applied.}}
 
Results table appears below form after selecting date, IP ranges, QoS parameters.
 
[[File:reports-results.png|frame|center|Report generator results]]
 
=== Limitations on Grouping and Filtering ===
 
It is '''not possible''' to generate a single report that groups all international calls by customer (or multiple customers) simultaneously. The report filtering system does not support applying both a "group by customer" filter and a "destination country" filter in one combined view.
 
'''Workaround:'''
 
To obtain international call reports for specific customers:
 
# Navigate to '''GUI > Reports > Report Generator''' or '''GUI > Reports > Call Summary'''
# Create a separate report for EACH customer
# For each report, apply '''both''' filters:
:* Filter for the specific customer (via caller number, account code, or IP)
:* Filter to show only international calls (via destination country)
# Generate each report individually
 
This limitation applies to all report types: Report Generator, Call Summary, QoS Report, and CDR Summary. Each report can be filtered by customer OR filtered by international destination, but not both in a single aggregated view.


== Call Summary ==
== Call Summary ==


Overview grouped by source/destination IPs, focusing on signaling metrics: ASR, ACD, total duration, call count. Toolbar filters by date range, source/destination numbers.
'''GUI > Reports > Call Summary''' - Overview grouped by source/destination IP.


[[File:reports-callsummary.png|frame|center|Call summary report]]
'''Key Metrics:''' ASR, ACD, NER, total duration, call count.


=== Export Column Reference ===
=== Export Column Reference ===
The following tables describe columns available in CSV exports.


'''Basic Metrics:'''
'''Basic Metrics:'''
Line 263: Line 144:
! Column !! Description
! Column !! Description
|-
|-
| sipip / sip_ip || Source IP address
| <code>sipip</code> || Source IP address
|-
| cnt_all || Count of CDRs
|-
| cnt_connected || Count of connected CDRs
|-
| duration_all || Sum of connected seconds
|-
| acd_all || Average Call Duration
|-
| asr_all || Answer Seizure Ratio
|-
| ner_all || Network Effectiveness Ratio
|-
| seer_all || Session Establishment Effectiveness Ratio
|-
| short_60 || Ratio (%) of CDRs with connect duration < 60s
|-
|-
| short_20 || Ratio (%) of CDRs with connect duration < 20s
| <code>cnt_all</code> / <code>cnt_connected</code> || Total / connected CDR count
|-
|-
| mos_all || MOS average (min from caller/called)
| <code>duration_all</code> || Sum of connected seconds
|-
|-
| response_time_100_all || Response time from INVITE to 100/183 (ms)
| <code>asr_all</code> / <code>acd_all</code> / <code>ner_all</code> || Answer Seizure Ratio / Avg Call Duration / Network Effectiveness Ratio
|-
|-
| pdd_all || Post Dial Delay (time to hear announcement)
| <code>mos_all</code> || MOS average (min of caller/called)
|-
|-
| packets_lost_all || Lost packets count
| <code>pdd_all</code> || Post Dial Delay (ms)
|-
|-
| jitter_all || Average RTP jitter (max from caller/called)
| <code>jitter_all</code> / <code>delay_all</code> || Average jitter / median PDV
|-
|-
| delay_all || Average of median jitter (PDV in ms)
| <code>packets_lost_all</code> || Lost packets count
|}
|}


'''MOS XR Columns''' (from RTCP-XR reports):
'''RTCP Columns:''' <code>rtcp_maxfr</code>, <code>rtcp_avgfr</code>, <code>rtcp_maxjitter</code>, <code>rtcp_avgjitter</code>, <code>rtcp_maxrtd</code>, <code>rtcp_avgrtd</code>
{| class="wikitable"
 
|-
'''MOS XR Columns:''' <code>mos_xr_avg_all</code>, <code>mos_xr_min_all</code>, <code>mos_xr_avg_caller_all</code>, <code>mos_xr_avg_called_all</code>
! Column !! Description
 
|-
'''Silence/Clipping Columns''' (requires [[Silence_detection|silence detection]]): <code>mos_silence_avg_all</code>, <code>silence_all</code>, <code>silence_end_all</code>, <code>clipping_all</code>
| mos_xr_avg_all || MOS XR average (min of caller/called)
 
|-
== QoS Report ==
| mos_xr_avg_caller_all || MOS XR average for caller stream
 
|-
'''GUI > Reports > QoS''' - Similar to Call Summary but emphasizes RTP metrics.
| mos_xr_avg_called_all || MOS XR average for called stream
|-
| mos_xr_min_all || MOS XR minimal (caller/called)
|-
| mos_xr_min_caller_all || MOS XR minimal for caller stream
|-
| mos_xr_min_called_all || MOS XR minimal for called stream
|}


'''RTCP Columns:'''
'''Multi-hop Troubleshooting:'''
{| class="wikitable"
# Set time range for issue period
|-
# Use "per caller IP" or "per called IP" filter
! Column !! Description
# Compare MOS scores across IPs to identify degraded segment
|-
# Combine with dashboard MOS panels for visual timeline
| rtcp_maxfr || Maximum fraction loss reported in RTCP
|-
| rtcp_maxjitter || Maximum jitter reported in RTCP
|-
| rtcp_avgfr || Average fraction loss reported
|-
| rtcp_avgjitter || Average jitter reported in RTCP
|-
| rtcp_maxrtd || Max round trip delay (ms)
|-
| rtcp_avgrtd || Average round trip delay (ms)
|}


'''Silence/Clipping Columns''' (requires [[Silence_detection|silence detection]] enabled):
== Regulatory Reporting ==
{| class="wikitable"
|-
! Column !! Description
|-
| mos_silence_avg_all || MOS during silence periods (min of caller/called)
|-
| mos_silence_avg_caller_all || MOS during silence periods (caller stream)
|-
| mos_silence_avg_called_all || MOS during silence periods (called stream)
|-
| mos_silence_min_all || MOS minimal during silence
|-
| mos_silence_min_caller_all || MOS minimal during silence (caller stream)
|-
| mos_silence_min_called_all || MOS minimal during silence (called stream)
|-
| silence_all || Percentage of call that was silence
|-
| silence_end_all || Seconds of silence before BYE packet
|-
| clipping_all || Number of clipped frames (requires <code>clippingdetect=yes</code>)
|}


'''Other Columns:'''
{| class="wikitable"
{| class="wikitable"
|-
|-
! Column !! Description
! Metric !! Column !! Description
|-
| mos_lqo_caller_all || MOS listening quality objective (caller)
|-
|-
| mos_lqo_called_all || MOS listening quality objective (called)
| Answer Seizure Ratio || <code>asr_all</code> || % of calls connecting successfully
|-
|-
| sip_hostname || Hostname from DB IP lookup (if enabled)
| Post Dial Delay || <code>pdd_all</code> || Call setup time (ms)
|-
|-
| sip_hostname_color || Color setting from DB IP lookup
| Mean Opinion Score || <code>mos_all</code> || Voice quality (1-5)
|-
| id || IP address with underscores instead of dots
|}
|}


== QoS Report ==
{{Note|'''Dropped Call Ratio (DCR)''' is NOT available. Submit a feature request with your specific formula if needed.}}
 
Similar to call summary but emphasizes RTP stats: MOS, jitter, delay, packet loss. Toolbar filters by date range, IP range.
 
[[File:reports-qos.png|frame|center|QoS report]]
 
=== Using QoS Report for Multi-Hop Network Troubleshooting ===
 
The QoS Report provides powerful filtering capabilities to pinpoint voice quality degradation in multi-hop networks with multiple sniffers.
 
'''Filtering by Caller/Called IP:'''
 
When diagnosing voice quality issues across network segments, use the "per caller IP" or "per called IP" filter options in the QoS Report toolbar. These filters show aggregated quality metrics grouped by specific IP addresses, allowing you to identify which network segment shows degraded quality.
 
* '''per caller IP''': Groups results by the originating IP address of each call
* '''per called IP''': Groups results by the destination IP address of each call
 
'''Troubleshooting Workflow:'''
 
1. Set the time range to cover the period when voice quality degradation was reported
2. Apply a "per caller IP" or "per called IP" filter to see MOS trends by IP address
3. Compare MOS scores across different IP addresses in the call path
4. A significant MOS decrease for a specific IP helps identify the source of the issue
 
This approach is particularly effective when you have sniffers deployed at multiple network checkpoints (e.g., different VLANs monitored with <code>interface=voip0.209</code> or similar interface-specific configurations). By comparing the QoS reports from each sniffer location, you can determine exactly where in the network the quality degradation occurs.
 
=== Dashboard MOS Panels for Graphical Analysis ===
 
In addition to QoS Report tables, use the dashboard's MOS panels for detailed graphical analysis:
 
* Navigate to the dashboard and locate the MOS visualization panels
* Click on the charts around the time of the issue to drill down into detailed data
* This provides a quick visual timeline of when and where quality drops occurred
* The interactive charts help correlate MOS changes with specific network events or configuration changes
 
Combining QoS Report IP filtering with dashboard MOS panel analysis provides both detailed metric breakdowns and visual timeline views for efficient multi-hop troubleshooting.
 
== Call Detail Records ==
 
Simplified CDR interface showing IPs and numbers, with quick toolbar filters.
 
[[File:reports-cdr.png|frame|center|Simplified CDR view]]
 
== Controlling Parallel Report Processing ==
 
When reports are slow generating or cause database overload, you may need to adjust the number of parallel processes used for report generation.
 
=== cron/reports vs parallel tasks ===


VoIPmonitor has two independent parallel processing settings:
== Parallel Processing Configuration ==


* '''<code>cron/reports</code>''': Controls the number of parallel report and alert generation tasks (CLI-based). This is configured in '''GUI > Settings > System Configuration > Advanced'''.
The <code>cron/reports</code> setting controls parallel report generation.
* '''<code>parallel tasks</code>''': Controls parallel audio merging operations in the GUI (for recordings). This is not related to report generation.


These settings are independent and serve different purposes.
'''Location:''' GUI > Settings > System Configuration > Advanced
 
=== Increasing Parallel Processing for Delayed Reports ===
 
The '''default value''' for <code>cron/reports</code> is '''1''', which processes reports sequentially one at a time. If your database has sufficient capacity but reports are consistently delayed or take too long to generate, increasing this setting can significantly improve performance.
 
'''Symptoms of insufficient parallelism:'''
* Daily reports start significantly later than scheduled time
* Reports take excessive time to complete when database is idle
* Many reports queue waiting for the previous report to finish
* Database CPU and I/O are low during report generation
 
'''Solution: Increase the <code>cron/reports</code> setting'''
Navigate to '''GUI > Settings > System Configuration > Advanced''' and find the <code>cron/reports</code> option.
 
;Recommended values for sequential delay problems:
:* '''2-4''' for moderate report loads with standard database
:* '''4-8''' for heavy report loads with powerful dedicated database
:* Start with small increases (1→2, then 2→4, etc.) and monitor performance
 
{{Note|When increasing parallelism, always monitor database performance (CPU, I/O, SQL cache). If the database becomes saturated during report generation, you've reached the limit. Reduce the value slightly and consider upgrading database resources.}}
 
=== Reducing Database Load from Reports ===
 
If the MySQL database is hosted on the same machine as other services (or has limited resources), high parallel report processing can overwhelm the database and cause:
 
* Slow report generation
* Growing SQL cache files
* Increasing CDR queue (SQLq metric in sensor status)
 
'''Solution: Reduce the <code>cron/reports</code> setting'''
 
Navigate to '''GUI > Settings > System Configuration > Advanced''' and find the <code>cron/reports</code> option.
 
;Recommended values:
:* '''8 or less''' for shared environments (database on same machine as other services)
:* '''4 or less''' for severely resource-constrained environments
:* '''16-32''' for dedicated database servers with sufficient resources
 
'''Impact of <code>cron/reports</code> value:'''


{| class="wikitable"
{| class="wikitable"
|-
|-
! Value || Behavior || When to Use
! Value !! When to Use
|-
|-
| Too high (20+) || Many reports generate simultaneously, saturating database I/O and CPU || Dedicated database with powerful hardware
| '''1''' (default) || Sequential processing
|-
|-
| Moderate (8-16) || Balanced parallelism with acceptable database load || Standard dedicated VoIPmonitor servers
| '''2-4''' || Reports delayed, database has capacity
|-
|-
| Low (4-8) || Sequential or low-parallel processing, minimal database impact || Shared CPU or database hosting other services
| '''4-8''' || Heavy report load, standard database
|-
| '''8-16''' || Dedicated database server
|}
|}


'''Primary solution for performance issues:'''
{{Note|1=<code>cron/reports</code> controls report/alert generation. <code>parallel tasks</code> controls audio merging (unrelated).}}
 
If reducing <code>cron/reports</code> does not resolve performance problems, the optimal solution is to move the MySQL database to a separate, dedicated host. This eliminates I/O contention and allows higher parallel processing without resource conflicts.
 
== CSV Export via Crontab Scheduler ==
 
You can export CDRs to a local directory on a schedule instead of (or in addition to) receiving them via email. This is useful for automated processing, archiving, or integration with external systems.


=== Configuration Steps ===
== CSV Export via Crontab ==


;1. Set the Export Folder:
# Set '''Folder for export CSV''' in '''GUI > Settings > System Configuration > Advanced'''
:* Navigate to '''GUI > Settings > System Configuration > Advanced'''
# Create task in '''GUI > Settings > Crontab Scheduler'''
:* Set '''"Folder for export CSV"''' to your desired directory (e.g., <code>/var/backups/cdrs</code>)
# Ensure web server user has write access to export folder
:* Optionally set '''"CSV name prefix"''' for filename prefixes
:* Optionally set '''"Delete CSV after X days"''' for automatic cleanup


;2. Create a Crontab Scheduler Task:
For custom formats, use [[WEB_API|Web API]] instead.
:* Navigate to '''GUI > Settings > Crontab Scheduler'''
:* Create a new task with:
:** '''Type:''' Report type (Call Summary, Report Generator, etc.)
:** '''Schedule:''' Frequency (hourly, daily, weekly, or cron expression)
:** '''Report parameters:''' Date range, IP ranges, etc.


;3. Verify Permissions:
== Troubleshooting ==
:* Web server user (<code>www-data</code> or <code>apache</code>) must have write access to export folder
:* Ensure sufficient disk space for accumulated files


For custom export formats, consider using the [[WEB_API|Web API]] instead.
=== Reports Timeout for Large Date Ranges ===


== Troubleshooting Scheduled Reports ==
'''Symptom:''' Reports take 30+ seconds then timeout, especially with IP group filters.


If scheduled reports are not sent automatically but manual generation works, check these common causes:
'''Solution:''' Disable the '''"include proxy"''' checkbox next to caller/called IP group field in report configuration. This option causes expensive database joins.


=== Timezone Mismatch ===
=== Timezone Mismatch ===


The GUI and server OS must use the same timezone. If they differ, scheduled tasks may run at wrong times or appear to be skipped.
'''Symptom:''' Scheduled reports run at wrong time or don't trigger.
 
'''Symptoms:'''
* Manual report generation works immediately
* Scheduled reports appear configured but don't run at expected time


'''Solution:'''
'''Solution:'''
;1. Check GUI timezone:
:Navigate to '''GUI > Settings > System Configuration > National > Timezone'''
;2. Check OS timezone:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
date
# Check OS timezone
timedatectl
timedatectl
</syntaxhighlight>


;3. Align timezones:
# Align with GUI (Settings > System Configuration > National > Timezone)
<syntaxhighlight lang="bash">
# Change OS timezone to match GUI (example)
timedatectl set-timezone Europe/Prague
timedatectl set-timezone Europe/Prague
</syntaxhighlight>
</syntaxhighlight>


;4. Verify system cronjob:
=== Blank Reports During Daylight Savings Time ===
<syntaxhighlight lang="bash">
 
crontab -l
'''Symptom:''' Reports empty when using named timezones (e.g., <code>America/Los_Angeles</code>) during DST transitions.
# Should contain:
# * * * * * root php /var/www/html/php/run.php cron
</syntaxhighlight>


=== Daily Reports Cannot Be Enabled (Missing Table) ===
'''Workaround:''' Change GUI timezone to fixed UTC offset (e.g., <code>GMT-8</code> instead of <code>America/Los_Angeles</code>).


If the daily report feature cannot be enabled in the GUI (e.g., the enable checkbox does not work, reports cannot be created, or the feature appears disabled), this may be caused by a missing database table that tracks sent daily reports.
=== Monthly Reports Fail in Distributed Setups ===


'''Symptoms:'''
'''Symptom:''' Monthly reports don't generate in multi-sensor environments.
* Unable to create or enable daily reports in the GUI
* Changes to daily report settings do not save
* The "Configure Daily Reports" page does not function properly
* Manual report generation works but scheduled daily reports cannot be configured


'''Root Cause:'''
'''Solution:''' Configure partition operations to prevent database lock conflicts:


The <code>daily_reports_sended</code> table is required by the GUI to track which daily reports have been sent. This table may be missing if:
'''On sniffer sensors:'''
* The database was manually created or restored without the complete schema
<syntaxhighlight lang="ini">
* An incomplete upgrade/reinstallation was performed
# /etc/voipmonitor.conf
* The table was accidentally dropped
disable_partition_operations = yes
</syntaxhighlight>


'''Solution: Create the Missing Table'''
'''On main server:'''
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
disable_partition_operations = no
partition_operations_enable_fromto = 4-5
</syntaxhighlight>


To restore daily report functionality, create the missing table by running the following SQL command:
{{Warning|1=Avoid scheduling reports during partition maintenance window (default 01:00-01:10 AM). Schedule 15-30 minutes before or after.}}


;1. Access the MySQL/MariaDB server for your VoIPmonitor installation
=== Missing daily_reports_sended Table ===


;2. Connect to the <code>voipmonitor</code> database
'''Symptom:''' Cannot enable/create daily reports in GUI.
<syntaxhighlight lang="bash">
mysql -u root -p voipmonitor
</syntaxhighlight>


;3. Execute the SQL to create the missing table
'''Solution:'''
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
CREATE TABLE `daily_reports_sended` (
CREATE TABLE `daily_reports_sended` (
Line 583: Line 285:
   PRIMARY KEY (`id`),
   PRIMARY KEY (`id`),
   KEY `fk__daily_reports_sended__daily_reports` (`daily_reports_id`),
   KEY `fk__daily_reports_sended__daily_reports` (`daily_reports_id`),
   CONSTRAINT `fk__daily_reports_sended__daily_reports` FOREIGN KEY (`daily_reports_id`) REFERENCES `daily_reports` (`id`)
   CONSTRAINT `fk__daily_reports_sended__daily_reports`
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COLLATE=latin1_swedish_ci;
    FOREIGN KEY (`daily_reports_id`) REFERENCES `daily_reports` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;
</syntaxhighlight>
</syntaxhighlight>


;4. After creating the table, navigate to '''GUI > Reports > Configure Daily Reports''' and try creating or enabling a daily report
=== Email Shows "Sent" But Not Delivered ===
 
{{Warning|Make sure to connect to the correct database (typically <code>voipmonitor</code>). If you use a custom database name, replace <code>voipmonitor</code> with your actual database name.}}


=== Daily Reports Blank During Daylight Savings Time ===
'''Symptom:''' GUI shows success but email never arrives.


If daily reports appear blank or empty when using timezone names like <code>America/Los_Angeles</code> during Daylight Savings Time (DST) transitions, this is a known timezone handling issue affecting date ranges used by the report generator.
'''Solution:''' Check for missing MTA:
 
'''Symptoms:'''
* Daily reports show no data during DST transition periods
* Manual report queries with correct date ranges work fine
* Issue occurs specifically when GUI uses geographic timezone names that observe DST (e.g., <code>America/Los_Angeles</code>, <code>Europe/London</code>)
 
'''Solution: Use Fixed Offset Timezone'''
 
As a workaround for DST-related report generation issues, change the GUI timezone from a named timezone to a fixed UTC offset:
 
;1. Navigate to '''GUI > Settings > System Configuration > National > Timezone'''
;2. Change from geographic timezone (e.g., <code>America/Los_Angeles</code>) to appropriate fixed offset:
:** Pacific Time: <code>GMT-8</code> (standard) or <code>GMT-7</code> (DST)
:** Eastern Time: <code>GMT-5</code> (standard) or <code>GMT-4</code> (DST)
:** Central European Time: <code>GMT+1</code> (standard) or <code>GMT+2</code> (DST)
:** Or coordinate with your regional offset
;3. Save the configuration
;4. Generate a new daily report to verify the fix
 
{{Tip|Fixed offset timezones like <code>GMT-8</code> do not observe automatic DST changes. You may need to manually update the offset when DST starts or ends in your region. Alternatively, align both the GUI and OS to use the same named timezone, as described in the general troubleshooting section above.}}
 
=== Email Not Delivered Despite "Report Sent" Message ===
 
If the GUI displays "report sent" but no email arrives, the issue may be that the system's Mail Transfer Agent (MTA) or its sendmail binary is missing or misconfigured. This commonly occurs after a GUI upgrade on systems that were not explicitly configured with an MTA.
 
'''Symptoms:'''
* GUI shows "report sent" message but email never arrives
* Manual report generation shows success but email is not received
* Test emails do not arrive
 
'''Troubleshooting Steps:'''
 
;1. Check the web server error log:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Look for mail-related errors
# Check error log
tail -n 50 /var/log/httpd/error_log
tail -n 50 /var/log/httpd/error_log | grep sendmail


# On some systems, the log may be in a different location
# Install MTA if missing
# tail -n 50 /var/log/apache2/error_log
apt-get install postfix  # Debian/Ubuntu
yum install postfix      # RHEL/CentOS
</syntaxhighlight>
</syntaxhighlight>
If you see an error like:<pre>sh: 1: /usr/sbin/sendmail: not found</pre>
This indicates your system does not have an MTA package installed.
;2. Verify if sendmail binary exists:
<syntaxhighlight lang="bash">
which sendmail
ls -l /usr/sbin/sendmail
</syntaxhighlight>
If the command returns "sendmail not found" or the file does not exist, proceed to install an MTA.
;3. Install an MTA package:
The sendmail binary is provided by most MTA packages. Choose one appropriate for your system:
'''Debian/Ubuntu:'''
<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install exim4
# OR
sudo apt-get install postfix
# OR
sudo apt-get install sendmail
</syntaxhighlight>
'''RHEL/CentOS/AlmaLinux/Rocky:'''
<syntaxhighlight lang="bash">
sudo yum update
sudo yum install postfix
# OR
sudo yum install sendmail
</syntaxhighlight>
'''Alpine Linux:'''
<syntaxhighlight lang="bash">
apk add exim
# OR
apk add postfix
</syntaxhighlight>
Note: <code>postfix</code> is generally the most commonly used and well-documented MTA for Linux systems.
;4. Start and enable the MTA service:
<syntaxhighlight lang="bash">
# For Postfix
sudo systemctl start postfix
sudo systemctl enable postfix
# For Exim4 (Debian/Ubuntu)
sudo systemctl start exim4
sudo systemctl enable exim4
# For Sendmail
sudo systemctl start sendmail
sudo systemctl enable sendmail
</syntaxhighlight>
;5. Verify MTA is running:
<syntaxhighlight lang="bash">
# Check service status
sudo systemctl status postfix
# OR
sudo systemctl status exim4
# OR
sudo systemctl status sendmail
# Check mail queue (should be empty if working correctly)
mailq
</syntaxhighlight>
;6. Test email delivery:
After installation, try sending a test report or use the system's mail command to verify:
<syntaxhighlight lang="bash">
echo "Test email body" | mail -s "Test Subject" your-email@example.com
</syntaxhighlight>
If you receive this test email, the MTA is working correctly and VoIPmonitor reports should now be delivered.
=== Other Common Causes ===
* '''Email delivery issues (MTA configuration):''' Check MTA logs with <code>mailq</code> and <code>tail /var/log/mail.log</code> (or <code>tail /var/log/maillog</code> on RHEL/CentOS)
* '''Incorrect schedule:''' Verify task has valid "Next run" time in the future
* '''Stuck tasks:''' Edit and save the task again to reset its state
=== Reports Time Out When Generating for Large Date Ranges ===
When reports time out after running for an extended period (30+ seconds) without completing, this is typically caused by inefficient queries related to IP group resolution settings in the report configuration.
'''Symptoms:'''
* Reports take 30+ seconds to generate and then time out
* Issue occurs specifically when using caller or called IP group filters
* Large date ranges (weekly or monthly reports) are more likely to timeout
* Manual preview works for small date ranges but fails for larger ones
'''Root Cause:'''
Reports that include IP group filters (caller IP group, called IP group) with the "include proxy" option enabled require additional database joins to resolve proxy IPs. For large date ranges spanning many CDRs, these joins cause excessive query complexity and timeouts.
'''Solution: Disable "Include Proxy" Checkbox in Report Configuration'''
To fix report timeouts caused by IP group filters:
# Navigate to '''GUI > Reports > Configure Daily Reports''' or open the Report Generator
# Edit the report that is timing out
# Locate the caller or called IP group field in the filter settings
# Find the "include proxy" checkbox next to the IP group field
# **Disable (uncheck) the "include proxy" option**
# Save the report configuration
# Test the report using the '''Preview report''' button
{{Tip|The "include proxy" option expands the IP group filter to include proxy IPs detected during call processing. While useful for certain use cases, it significantly increases query complexity. Disable this option unless you specifically need proxy IP resolution.}}
{{Note|After enabling IP group filters, the "include proxy" setting should be disabled by default. If reports continue to timeout, consider reducing the date range or increasing the <code>cron/reports</code> parallel processing limit to reduce database load from concurrent reports.}}
=== Monthly Reports Fail Due to Database Partition Operations ===
In distributed sensor setups with multiple sniffer sensors, monthly reports may fail to generate if database partition maintenance operations conflict with report generation.
'''Symptoms:'''
* Monthly reports configured in GUI do not generate or send as scheduled
* Manual report generation works fine
* Issue occurs specifically in multi-sensor environments
'''Root Cause:'''
VoIPmonitor performs automatic database partition maintenance operations to manage data retention. In distributed setups, when multiple sensors attempt partition operations simultaneously, database locks can prevent monthly reports from being generated.
'''Solution: Configure Partition Operations to Prevent Conflicts'''
To avoid conflicts, disable partition operations on sniffer sensors and configure them to run only on the main server during off-peak hours.
;1. On all sniffer sensors:
Edit <code>/etc/voipmonitor.conf</code> and add:
<pre>disable_partition_operations = yes</pre>
;2. On the main server (GUI server):
Edit <code>/etc/voipmonitor.conf</code> and configure:
<pre>disable_partition_operations = no
partition_operations_enable_fromto = 4-5</pre>
The <code>partition_operations_enable_fromto</code> setting defines a maintenance window (in this example, 4:00 AM to 5:00 AM) when partition operations will run. Adjust this time to align with your least busy period.
;3. Restart the VoIPmonitor service on all affected sensors and the main server:
<syntaxhighlight lang="bash">
sudo systemctl restart voipmonitor
</syntaxhighlight>
;4. Verify the report configuration:
Navigate to '''GUI > Reports > Configure Daily Reports''' and verify that for each monthly report, the '''day of month''' field is set correctly for when the report should run.
;5. Check GUI timezone:
Ensure the GUI timezone (in '''GUI > Settings > System Configuration > National''') is set correctly so the scheduled time aligns with your intended local time.
This configuration ensures that partition maintenance runs only once during the off-peak window on the main server, preventing database lock conflicts with monthly report generation.
=== Avoid Scheduling Reports During Partition Maintenance Window ===
Database partition maintenance operations typically run during a daily maintenance window (by default, 01:00 AM - 01:10 AM, though this may vary based on your <code>partition_operations_enable_fromto</code> setting). Scheduling reports during this window can cause conflicts and failures.
{{Warning|Avoid setting monthly or large reports to run at times when database partition maintenance is active.}}
'''Best Practices for Report Scheduling:'''
* **Check your partition maintenance window:** Review the <code>partition_operations_enable_fromto</code> setting in <code>/etc/voipmonitor.conf</code> to identify the active maintenance window
* **Schedule reports outside the maintenance window:** Ensure monthly reports are configured to run at least 15-30 minutes before or after the partition maintenance window
* **Example:** If maintenance runs 01:00-01:10 AM, schedule monthly reports for 00:30 AM or 01:30 AM or later
* **Stagger multiple monthly reports:** If you have multiple monthly reports, distribute them across different hours to avoid concurrent database load
This prevents database lock conflicts and ensures reliable report generation.


== See Also ==
== See Also ==


* [[Alerts|Alerts & Reports]] - Email alert configuration
* [[Alerts]] - Email alert configuration and cron setup
* [[Silence_detection|Silence Detection]] - Enable silence/clipping metrics
* [[Data_Cleaning]] - Data retention settings
* [[WEB_API|Web API]] - Programmatic report access
* [[Silence_detection]] - Enable silence/clipping metrics
* [[WEB_API]] - Programmatic report access
* [[Groups]] - IP and telephone number groups


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


'''Summary:''' VoIPmonitor reports system provides daily email reports (RTP summaries, CPS reports with max/average calls per second, daily charts, CDR summary with flexible summary types including source/destination IP, source/destination telephone number, Called number group, and Caller number group, plus optional price columns for billing costs), a report generator for historical data analysis, call summary grouped by IP addresses, QoS reports emphasizing RTP metrics, simplified CDR views, and regulatory reporting capabilities. Key regulatory metrics available: ASR (asr_all - Answer Seizure Ratio), PDD (pdd_all - Post Dial Delay for call setup time), and MOS (mos_all - Mean Opinion Score). The Average Dropped Call Ratio (DCR) metric is NOT available and requires a feature request if needed. CSV exports can be automated via crontab scheduler. The <code>cron/reports</code> setting in GUI Settings (GUI > Settings > System Configuration > Advanced) controls parallel report and alert generation processes. The default value is 1 (sequential processing). For delayed reports with sufficient database capacity, INCREASE to 2-8 to allow parallel processing. To reduce database load, decrease this setting (8 or less for shared environments, 4 or less for resource-constrained, 16-32 for dedicated databases). This is independent from the <code>parallel tasks</code> setting which controls audio merging, not report generation. Common troubleshooting involves timezone alignment between GUI and OS settings. For daily reports appearing blank during Daylight Savings Time (DST) transitions with timezones like America/Los_Angeles, use a fixed UTC offset as a workaround (e.g., change GUI timezone from America/Los_Angeles to GMT-8). Fixed offset timezones do not automatically adjust for DST, so manual updates may be required when DST changes occur. For monthly reports failing in distributed sensor setups, configure <code>disable_partition_operations = yes</code> on sniffer sensors and <code>disable_partition_operations = no</code> with <code>partition_operations_enable_fromto = 4-5</code> on the main server to prevent database lock conflicts during maintenance. CRITICAL FIX: Reports timing out for large date ranges (30+ seconds) or when using caller/called IP group filters is fixed by disabling the "include proxy" checkbox next to the IP group field in report configuration. The "include proxy" option causes additional database joins that increase query complexity and cause timeouts. Navigate to GUI > Reports, edit the report, find the "include proxy" checkbox under caller/called IP group settings, uncheck it, and save. Test with Preview report button. Default recommendation: keep "include proxy" disabled unless proxy IP resolution is specifically needed. Also avoid scheduling reports during the database partition maintenance window (typically 01:00 AM - 01:10 AM default, but configurable via partition_operations_enable_fromto in /etc/voipmonitor.conf). Stagger monthly reports across different hours to avoid concurrent database load, and schedule reports at least 15-30 minutes before or after the maintenance window (e.g., if maintenance is 01:00-01:10 AM, schedule monthly reports for 00:30 AM or 01:30 AM). CDR Summary report includes Called number group and Caller number group summary types that aggregate CDRs by telephone number groups (defined in GUI -> Groups -> Tel. numbers). These are useful for grouping calls by customer number ranges, NPA-NXX area code prefixes, service provider groups, or trunk groups. To report on NPA-NXX prefixes (first 6 digits), create telephone number groups for each prefix with country code variants (e.g., both 1202333 and 202333), then use Called number group summary type and select the groups Called number group filter field. This method requires knowing prefixes in advance and cannot dynamically discover top N prefixes (for dynamic discovery, use Report Generator export to CSV or direct SQL queries). IMPORTANT LIMITATION: It is NOT possible to generate a single report that groups all international calls by customer simultaneously in one view. Reports can be filtered by customer OR filtered by international destination (country), but not both combined. Workaround: Create separate reports for each customer, applying both a customer filter and international destination filter to each report individually. For analyzing multiple SIP response codes grouped by called number, create separate CDR summary reports for each SIP response pattern (e.g., %OK%, 404%, 486%, 487%).
'''Summary:''' VoIPmonitor reports include Daily Email Reports (RTP, CPS, charts, CDR summary), Report Generator for ad-hoc analysis, Call Summary grouped by IP, QoS Report for RTP metrics, and simplified CDR view. CDR Summary supports grouping by source/destination IP, telephone numbers, or predefined number groups. Regulatory metrics available: ASR (<code>asr_all</code>), PDD (<code>pdd_all</code>), MOS (<code>mos_all</code>); DCR is NOT available. The <code>cron/reports</code> setting (GUI > Settings > Advanced) controls parallel report generation: default 1 (sequential), increase to 2-8 for delayed reports, or decrease for database load issues. Key limitation: cannot combine customer grouping AND country filtering in one report. Common fixes: disable "include proxy" checkbox for timeout issues, use fixed UTC offset for DST problems, configure <code>disable_partition_operations</code> for multi-sensor monthly report failures.


'''Keywords:''' reports, daily reports, RTP, CPS, calls per second, charts, CDR summary, summary type, source number, source IP, destination number, destination IP, Called number group, Caller number group, telephone number groups, NPA-NXX, area code prefixes, number ranges, country code, E.164, prefix groups, service provider groups, trunk groups, number patterns, price columns, billing costs, call summary, QoS, ASR, ACD, NER, MOS, CSV export, crontab scheduler, timezone, cron/reports, parallel tasks, parallel processing, database load, SQL queue, shared environments, monthly reports fail, distributed sensors, partition operations, disable_partition_operations, partition_operations_enable_fromto, regulatory reporting, regulatory metrics, PDD, call setup time, Post Dial Delay, Answer Seizure Ratio, DCR, dropped call ratio, international calls, grouping, customer grouping, filter limitations, destination country, multiple customers, report grouping, SIP response codes, multiple reports, separate reports, grouped by called number, daylight savings, daylight savings time, DST, America/Los_Angeles, GMT-8, GMT offset, fixed offset timezone, blank reports, DST transition, PST, EST, CET, GMT-7, GMT-4, GMT+1, GMT+2, report timeout, timeout 30 seconds, large date range, weekly reports, monthly reports, include proxy, include proxy checkbox, caller IP group, called IP group, IP group filter, proxy IP resolution, database partition maintenance, maintenance window, 01:00 AM, 01:10 AM, stagger schedules, off-peak hours, concurrent reports, database load from reports
'''Keywords:''' reports, daily reports, RTP report, CPS, charts, CDR summary, report generator, call summary, QoS report, ASR, ACD, NER, MOS, PDD, CSV export, cron/reports, parallel processing, regulatory reporting, timezone, DST, daylight savings, partition operations, include proxy, timeout, NPA-NXX, telephone number groups


'''Key Questions:'''
'''Key Questions:'''
* What types of reports does VoIPmonitor provide?
* What types of reports does VoIPmonitor provide?
* How to fix reports timing out for large date ranges?
* How to configure daily email reports?
* What is the include proxy checkbox in report configuration?
* How to fix report timeout for large date ranges?
* Why do reports timeout when using IP group filters?
* What is the include proxy checkbox and why disable it?
* How to disable include proxy checkbox in reports?
* How to configure parallel report processing (cron/reports)?
* When should keep include proxy disabled for reports?
* Why are reports blank during daylight savings time?
* What is the database partition maintenance window?
* How to fix monthly reports failing in distributed setups?
* When to avoid scheduling reports?
* What regulatory metrics are available (ASR, PDD, MOS)?
* How to avoid partition maintenance window conflicts?
* How to group CDR summary by telephone number groups?
* How to stagger monthly report schedules?
* How to export reports to CSV automatically?
* How to use Called number group and Caller number group summary types?
* How to report on NPA-NXX prefixes in CDR summary reports?
* Can I group CDRs by telephone number groups?
* How to create a report for specific number ranges?
* How to configure daily email reports with billing costs?
* Why are my daily reports blank during daylight savings time?
* How to fix blank daily reports when using America/Los_Angeles timezone?
* What is the workaround for DST-related report generation issues?
* Should I use GMT offset or named timezone for reports?
* How to enable price columns in CDR summary reports?
* What summary types are available in CDR summary reports?
* How to group CDR summary by source or destination telephone number?
* How to filter CDR summary by SIP response codes like 404 or 603?
* How to create multiple reports for multiple SIP response codes?
* How to analyze counts for different SIP responses grouped by called number?
* Why do I need to create separate reports for each SIP response code?
* How to use the preview report button for instant results?
* What regulatory metrics are available in VoIPmonitor?
* How to find Average Call Setup Success Ratio (ASR) in reports?
* How to find Average Call Setup Time (PDD) in reports?
* How to find Average MOS in reports?
* Is Average Dropped Call Ratio (DCR) available in VoIPmonitor?
* Can I generate a single report of international calls grouped by customer?
* How to get reports per customer for international calls?
* What is the difference between cron/reports and parallel tasks?
* How to reduce database load from report generation?
* What value should cron/reports be set to for shared environments?
* What is the default value for cron/reports?
* How to fix delayed reports due to sequential processing?
* When should I increase the cron/reports setting?
* How much should I increase cron/reports for delayed reports?
* What columns are available in CSV export?
* How to export CDRs to CSV automatically?
* Why are scheduled reports not being sent?
* Why do monthly reports fail to generate in distributed sensor setups?
* How to fix monthly reports failing due to partition operations?
* What is disable_partition_operations and when to use it?

Latest revision as of 16:48, 8 January 2026


Reports

VoIPmonitor provides multiple report types for analyzing call data, quality metrics, and generating scheduled summaries.

Report Type Purpose Output
Daily Email Reports Scheduled summaries (RTP, CPS, charts, CDR summary) Email
Report Generator Ad-hoc historical analysis GUI, CSV
Call Summary Aggregated by IP (ASR, ACD, duration) GUI, CSV
QoS Report RTP quality metrics (MOS, jitter, loss) GUI
CDR Simplified Quick CDR view with filters GUI

Prerequisites

Reports require a working cron job for scheduled delivery. See Alerts - Email Configuration for cron setup and MTA requirements.

ℹ️ Note: For scheduled reports, ensure cleandatabase in /etc/voipmonitor.conf exceeds your longest report period (e.g., >30 days for monthly reports). See Data_Cleaning.

Daily Email Reports

Navigate to GUI > Reports > Configure Daily Reports to create scheduled reports.

RTP Daily Report

Summarizes RTP metrics: MOS, packet loss, jitter, delay (PDV), duration, one-way, and missing RTP.

CPS Daily Report

Reports maximum and average Calls Per Second (CPS) over the selected period.

Daily Charts Report

Generates visual charts of call metrics filtered by criteria (SIP trunks, numbers, IP).

Time Range Settings:

Period Configuration
Daily "last day 1"
Weekly "this week from Monday" + enable "previous interval"
Monthly "previous month"

Creating Chart Templates:

  1. Navigate to GUI > Reports > Configure Daily Reports > Charts
  2. Click chart creation button
  3. Configure filters (CDR criteria, IP addresses, numbers)
  4. Select metrics (MOS, packet loss, jitter, concurrent calls)
  5. Save as chart template
  6. Attach template to scheduled report

💡 Tip: Schedule resource-intensive reports (30-day charts) during off-peak hours to reduce database load.

CDR Summary Report

Daily summary grouped by various criteria with optional billing costs.

Summary Types:

Type Description
source IP / destination IP Group by IP address
source number / destination number Group by telephone number
Called/Caller number group Group by predefined Telephone Number Groups

Configuration:

  1. Select CDR summary as report type
  2. Choose Summary type from dropdown
  3. Filter by SIP response in Common tab (e.g., %OK%, 404%)
  4. Enable Price columns for billing costs (requires Billing Configuration)

ℹ️ Note: For multiple SIP response codes, create separate reports for each code pattern. A single report cannot aggregate multiple response types.

NPA-NXX Prefix Reporting:

  1. Create telephone number groups in GUI > Groups > Tel. numbers for each prefix
  2. Include country code variants (e.g., both 1202333 and 202333)
  3. Use Called number group summary type
  4. Select groups in filter field

Report Generator

GUI > Reports > Report Generator - Creates ad-hoc reports from historical data.

  • "Only CDR with RTP" checkbox: Reports only connected calls (ASR always 100%)
  • Filter by date range, IP, numbers, QoS parameters
  • Export results to CSV

⚠️ Warning: Limitation: Cannot combine "group by customer" AND "destination country" filters in one report. Create separate reports for each customer with both filters applied.

Call Summary

GUI > Reports > Call Summary - Overview grouped by source/destination IP.

Key Metrics: ASR, ACD, NER, total duration, call count.

Export Column Reference

Basic Metrics:

Column Description
sipip Source IP address
cnt_all / cnt_connected Total / connected CDR count
duration_all Sum of connected seconds
asr_all / acd_all / ner_all Answer Seizure Ratio / Avg Call Duration / Network Effectiveness Ratio
mos_all MOS average (min of caller/called)
pdd_all Post Dial Delay (ms)
jitter_all / delay_all Average jitter / median PDV
packets_lost_all Lost packets count

RTCP Columns: rtcp_maxfr, rtcp_avgfr, rtcp_maxjitter, rtcp_avgjitter, rtcp_maxrtd, rtcp_avgrtd

MOS XR Columns: mos_xr_avg_all, mos_xr_min_all, mos_xr_avg_caller_all, mos_xr_avg_called_all

Silence/Clipping Columns (requires silence detection): mos_silence_avg_all, silence_all, silence_end_all, clipping_all

QoS Report

GUI > Reports > QoS - Similar to Call Summary but emphasizes RTP metrics.

Multi-hop Troubleshooting:

  1. Set time range for issue period
  2. Use "per caller IP" or "per called IP" filter
  3. Compare MOS scores across IPs to identify degraded segment
  4. Combine with dashboard MOS panels for visual timeline

Regulatory Reporting

Metric Column Description
Answer Seizure Ratio asr_all % of calls connecting successfully
Post Dial Delay pdd_all Call setup time (ms)
Mean Opinion Score mos_all Voice quality (1-5)

ℹ️ Note: Dropped Call Ratio (DCR) is NOT available. Submit a feature request with your specific formula if needed.

Parallel Processing Configuration

The cron/reports setting controls parallel report generation.

Location: GUI > Settings > System Configuration > Advanced

Value When to Use
1 (default) Sequential processing
2-4 Reports delayed, database has capacity
4-8 Heavy report load, standard database
8-16 Dedicated database server

ℹ️ Note: cron/reports controls report/alert generation. parallel tasks controls audio merging (unrelated).

CSV Export via Crontab

  1. Set Folder for export CSV in GUI > Settings > System Configuration > Advanced
  2. Create task in GUI > Settings > Crontab Scheduler
  3. Ensure web server user has write access to export folder

For custom formats, use Web API instead.

Troubleshooting

Reports Timeout for Large Date Ranges

Symptom: Reports take 30+ seconds then timeout, especially with IP group filters.

Solution: Disable the "include proxy" checkbox next to caller/called IP group field in report configuration. This option causes expensive database joins.

Timezone Mismatch

Symptom: Scheduled reports run at wrong time or don't trigger.

Solution: 

# Check OS timezone
timedatectl

# Align with GUI (Settings > System Configuration > National > Timezone)
timedatectl set-timezone Europe/Prague

Blank Reports During Daylight Savings Time

Symptom: Reports empty when using named timezones (e.g., America/Los_Angeles) during DST transitions.

Workaround: Change GUI timezone to fixed UTC offset (e.g., GMT-8 instead of America/Los_Angeles).

Monthly Reports Fail in Distributed Setups

Symptom: Monthly reports don't generate in multi-sensor environments.

Solution: Configure partition operations to prevent database lock conflicts:

On sniffer sensors: 

# /etc/voipmonitor.conf
disable_partition_operations = yes

On main server: 

# /etc/voipmonitor.conf
disable_partition_operations = no
partition_operations_enable_fromto = 4-5

⚠️ Warning: Avoid scheduling reports during partition maintenance window (default 01:00-01:10 AM). Schedule 15-30 minutes before or after.

Missing daily_reports_sended Table

Symptom: Cannot enable/create daily reports in GUI.

Solution: 

CREATE TABLE `daily_reports_sended` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `daily_reports_id` int(11) NOT NULL,
  `day` date NOT NULL,
  `subject` text DEFAULT NULL,
  `content` mediumtext DEFAULT NULL,
  `send_time` datetime DEFAULT NULL,
  `send_email` text DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `fk__daily_reports_sended__daily_reports` (`daily_reports_id`),
  CONSTRAINT `fk__daily_reports_sended__daily_reports`
    FOREIGN KEY (`daily_reports_id`) REFERENCES `daily_reports` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;

Email Shows "Sent" But Not Delivered

Symptom: GUI shows success but email never arrives.

Solution: Check for missing MTA: 

# Check error log
tail -n 50 /var/log/httpd/error_log | grep sendmail

# Install MTA if missing
apt-get install postfix  # Debian/Ubuntu
yum install postfix      # RHEL/CentOS

See Also

AI Summary for RAG

Summary: VoIPmonitor reports include Daily Email Reports (RTP, CPS, charts, CDR summary), Report Generator for ad-hoc analysis, Call Summary grouped by IP, QoS Report for RTP metrics, and simplified CDR view. CDR Summary supports grouping by source/destination IP, telephone numbers, or predefined number groups. Regulatory metrics available: ASR (asr_all), PDD (pdd_all), MOS (mos_all); DCR is NOT available. The cron/reports setting (GUI > Settings > Advanced) controls parallel report generation: default 1 (sequential), increase to 2-8 for delayed reports, or decrease for database load issues. Key limitation: cannot combine customer grouping AND country filtering in one report. Common fixes: disable "include proxy" checkbox for timeout issues, use fixed UTC offset for DST problems, configure disable_partition_operations for multi-sensor monthly report failures.

Keywords: reports, daily reports, RTP report, CPS, charts, CDR summary, report generator, call summary, QoS report, ASR, ACD, NER, MOS, PDD, CSV export, cron/reports, parallel processing, regulatory reporting, timezone, DST, daylight savings, partition operations, include proxy, timeout, NPA-NXX, telephone number groups

Key Questions:

  • What types of reports does VoIPmonitor provide?
  • How to configure daily email reports?
  • How to fix report timeout for large date ranges?
  • What is the include proxy checkbox and why disable it?
  • How to configure parallel report processing (cron/reports)?
  • Why are reports blank during daylight savings time?
  • How to fix monthly reports failing in distributed setups?
  • What regulatory metrics are available (ASR, PDD, MOS)?
  • How to group CDR summary by telephone number groups?
  • How to export reports to CSV automatically?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Reports&oldid=10114"