Reports: Difference between revisions

From VoIPmonitor.org
(Add troubleshooting section for monthly reports failing due to database partition operations in distributed sensor setups)
(Rewrite: consolidated structure, removed redundancy, improved tables and troubleshooting organization)
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Reports}}
{{DISPLAYTITLE:Reports}}
Category:GUI manual
[[Category:GUI manual]]


== 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 ====
Reports maximum and average Calls Per Second (CPS) over the selected period.


CPS (Calls Per Second) report provides daily statistics of call volume rate. Reports maximum and average CPS over the selected period.
=== Daily Charts Report ===


* Navigate to '''GUI > Reports > Configure Daily Reports'''
Generates visual charts of call metrics filtered by criteria (SIP trunks, numbers, IP).
* Select '''CPS''' as the report type to receive periodic email summaries of maximum and average CPS


==== Daily Charts Report ====
'''Time Range Settings:'''
{| class="wikitable"
|-
! Period !! Configuration
|-
| Daily || <code>"last day 1"</code>
|-
| Weekly || <code>"this week from Monday"</code> + enable <code>"previous interval"</code>
|-
| Monthly || <code>"previous month"</code>
|}


Generates daily chart statistics. Create multiple charts per report, filtered by CDR criteria (e.g., SIP trunks).
'''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


[[File:report-dailychart.png|frame|center|Daily charts report configuration]]
{{Tip|Schedule resource-intensive reports (30-day charts) during off-peak hours to reduce database load.}}


Chart creation dialog allows custom charts with filters on numbers, IP, RTP stats.
=== CDR Summary Report ===


[[File:report-chartedit.png|frame|center|Chart creation dialog]]
Daily summary grouped by various criteria with optional billing costs.


Preview results or send test emails via buttons.
'''Summary Types:'''
{| class="wikitable"
|-
! 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 [[Groups|Telephone Number Groups]]
|}


[[File:report-chartbuttons.png|frame|center|Report preview and test buttons]]
'''Configuration:'''
[[File:report-preview.png|frame|center|Report preview result]]
# 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]])


==== CDR Summary Report ====
{{Note|1=For multiple SIP response codes, create '''separate reports''' for each code pattern. A single report cannot aggregate multiple response types.}}


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.
'''NPA-NXX Prefix Reporting:'''
# Create telephone number groups in '''GUI > Groups > Tel. numbers''' for each prefix
# Include country code variants (e.g., both <code>1202333</code> and <code>202333</code>)
# Use '''Called number group''' summary type
# Select groups in filter field


To generate a CDR summary report:
== Report Generator ==


# Navigate to '''GUI > Reports > Configure Daily Reports'''
'''GUI > Reports > Report Generator''' - Creates ad-hoc reports from historical data.
# 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
# Configure filters using the filter tabs:
:* In the '''Common tab''', set '''Last SIP response''' to specific codes (e.g., <code>404,603</code>) to filter by SIP response
# 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.
* '''"Only CDR with RTP"''' checkbox: Reports only connected calls (ASR always 100%)
* Filter by date range, IP, numbers, QoS parameters
* Export results to CSV


=== Report Generator ===
{{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.}}


Creates reports from historical data by criteria.
== Call Summary ==


* '''"Only CDR with RTP" checkbox''': Reports connected calls only (ASR always 100%) or all CDRs.
'''GUI > Reports > Call Summary''' - Overview grouped by source/destination IP.


[[File:report-generatorform.png|frame|center|Report generator form]]
'''Key Metrics:''' ASR, ACD, NER, total duration, call count.


Results table appears below form after selecting date, IP ranges, QoS parameters.
=== Export Column Reference ===
 
[[File:reports-results.png|frame|center|Report generator results]]
 
=== 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.
 
[[File:reports-callsummary.png|frame|center|Call summary report]]
 
==== Export Column Reference ====
 
The following tables describe columns available in CSV exports.


'''Basic Metrics:'''
'''Basic Metrics:'''
Line 135: 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)
|-
|-
| sip_hostname || Hostname from DB IP lookup (if enabled)
| Answer Seizure Ratio || <code>asr_all</code> || % of calls connecting successfully
|-
|-
| sip_hostname_color || Color setting from DB IP lookup
| Post Dial Delay || <code>pdd_all</code> || Call setup time (ms)
|-
|-
| id || IP address with underscores instead of dots
| Mean Opinion Score || <code>mos_all</code> || Voice quality (1-5)
|}
|}


=== 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]]
 
=== Call Detail Records ===


Simplified CDR interface showing IPs and numbers, with quick toolbar filters.
== Parallel Processing Configuration ==


[[File:reports-cdr.png|frame|center|Simplified CDR view]]
The <code>cron/reports</code> setting controls parallel report generation.


=== Controlling Parallel Report Processing ===
'''Location:''' GUI > Settings > System Configuration > Advanced
 
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:
 
* '''<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'''.
* '''<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.
 
==== 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
|-
| '''1''' (default) || Sequential processing
|-
|-
| Too high (20+) || Many reports generate simultaneously, saturating database I/O and CPU || Dedicated database with powerful hardware
| '''2-4''' || Reports delayed, database has capacity
|-
|-
| Moderate (8-16) || Balanced parallelism with acceptable database load || Standard dedicated VoIPmonitor servers
| '''4-8''' || Heavy report load, standard database
|-
|-
| Low (4-8) || Sequential or low-parallel processing, minimal database impact || Shared CPU or database hosting other services
| '''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 ===
== CSV Export via Crontab ==


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.
# Set '''Folder for export CSV''' in '''GUI > Settings > System Configuration > Advanced'''
# Create task in '''GUI > Settings > Crontab Scheduler'''
# Ensure web server user has write access to export folder


==== Configuration Steps ====
For custom formats, use [[WEB_API|Web API]] instead.


;1. Set the Export Folder:
== Troubleshooting ==
:* Navigate to '''GUI > Settings > System Configuration > Advanced'''
:* Set '''"Folder for export CSV"''' to your desired directory (e.g., <code>/var/backups/cdrs</code>)
:* Optionally set '''"CSV name prefix"''' for filename prefixes
:* Optionally set '''"Delete CSV after X days"''' for automatic cleanup


;2. Create a Crontab Scheduler Task:
=== Reports Timeout for Large Date Ranges ===
:* 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:
'''Symptom:''' Reports take 30+ seconds then timeout, especially with IP group filters.
:* 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.
'''Solution:''' Disable the '''"include proxy"''' checkbox next to caller/called IP group field in report configuration. This option causes expensive database joins.


=== Troubleshooting Scheduled Reports ===
=== Timezone Mismatch ===


If scheduled reports are not sent automatically but manual generation works, check these common causes:
'''Symptom:''' Scheduled reports run at wrong time or don't trigger.
 
==== 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.
 
'''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>


==== Other Common Causes ====
'''Workaround:''' Change GUI timezone to fixed UTC offset (e.g., <code>GMT-8</code> instead of <code>America/Los_Angeles</code>).


* '''Email delivery issues:''' Check MTA logs with <code>mailq</code> and <code>tail /var/log/mail.log</code>
=== Monthly Reports Fail in Distributed Setups ===
* '''Incorrect schedule:''' Verify task has valid "Next run" time in the future
* '''Stuck tasks:''' Edit and save the task again to reset its state


==== Monthly Reports Fail Due to Database Partition Operations ====
'''Symptom:''' Monthly reports don't generate in multi-sensor environments.


In distributed sensor setups with multiple sniffer sensors, monthly reports may fail to generate if database partition maintenance operations conflict with report generation.
'''Solution:''' Configure partition operations to prevent database lock conflicts:


'''Symptoms:'''
'''On sniffer sensors:'''
* Monthly reports configured in GUI do not generate or send as scheduled
<syntaxhighlight lang="ini">
* Manual report generation works fine
# /etc/voipmonitor.conf
* Issue occurs specifically in multi-sensor environments
disable_partition_operations = yes
</syntaxhighlight>


'''Root Cause:'''
'''On main server:'''
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
disable_partition_operations = no
partition_operations_enable_fromto = 4-5
</syntaxhighlight>


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.
{{Warning|1=Avoid scheduling reports during partition maintenance window (default 01:00-01:10 AM). Schedule 15-30 minutes before or after.}}


'''Solution: Configure Partition Operations to Prevent Conflicts'''
=== Missing daily_reports_sended Table ===


To avoid conflicts, disable partition operations on sniffer sensors and configure them to run only on the main server during off-peak hours.
'''Symptom:''' Cannot enable/create daily reports in GUI.


;1. On all sniffer sensors:
'''Solution:'''
Edit <code>/etc/voipmonitor.conf</code> and add:
<syntaxhighlight lang="sql">
<pre>disable_partition_operations = yes</pre>
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;
</syntaxhighlight>


;2. On the main server (GUI server):
=== Email Shows "Sent" But Not Delivered ===
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.
'''Symptom:''' GUI shows success but email never arrives.


;3. Restart the VoIPmonitor service on all affected sensors and the main server:
'''Solution:''' Check for missing MTA:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo systemctl restart voipmonitor
# 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
</syntaxhighlight>
</syntaxhighlight>


;4. Verify the report configuration:
== See Also ==
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.
 
=== 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 and source/destination telephone number, 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, and simplified CDR views. CSV exports can be automated via crontab scheduler. The <code>cron/reports</code> setting in GUI Settings controls parallel report and alert generation processes; reduce it to 8 or less for shared environments (database on same machine as other services) to prevent database overload. 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 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.
'''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, 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
'''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 configure daily email reports with billing costs?
* How to configure daily email reports?
* How to enable price columns in CDR summary reports?
* How to fix report timeout for large date ranges?
* What summary types are available in CDR summary reports?
* What is the include proxy checkbox and why disable it?
* How to group CDR summary by source or destination telephone number?
* How to configure parallel report processing (cron/reports)?
* How to filter CDR summary by SIP response codes like 404 or 603?
* Why are reports blank during daylight savings time?
* What is the difference between cron/reports and parallel tasks?
* How to fix monthly reports failing in distributed setups?
* How to reduce database load from report generation?
* What regulatory metrics are available (ASR, PDD, MOS)?
* What value should cron/reports be set to for shared environments?
* How to group CDR summary by telephone number groups?
* What columns are available in CSV export?
* How to export reports to CSV automatically?
* 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"