CDR-Stats Documentation Release 3.0.4 Arezqui Belaid October 05, 2015 Contents 1 Getting Started 3 1.1 Overview.................................................3 1.2 Dashboard................................................4 1.3 Admin Panel...............................................5 1.4 Architecture...............................................5 1.5 Features..................................................7 1.6 Utility...................................................7 2 Installation 9 2.1 Overview.................................................9 2.2 Install CDR-Stats............................................. 11 2.3 Configure Postgresql for Remote Access................................ 12 2.4 CDR-Pusher Installation......................................... 14 2.5 Configure Asterisk with CDR-Stats and CDR-Pusher.......................... 18 2.6 Configure FreeSWITCH with CDR-Stats and CDR-Pusher....................... 23 2.7 Configure Kamailio with CDR-Stats and CDR-Pusher......................... 26 3 Configuration and Defaults 31 3.1 General Configuration.......................................... 31 3.2 Country Reporting............................................ 33 3.3 Configuration for Asterisk........................................ 34 3.4 Realtime configuration for Asterisk................................... 35 3.5 Configuration for FreeSWITCH..................................... 35 3.6 Realtime configuration for FreeSWITCH................................ 36 3.7 Resetting CDR Data........................................... 36 3.8 Celery Configuration........................................... 37 3.9 ACL Control............................................... 39 4 Celery 41 4.1 Celery Installation............................................ 41 5 Troubleshooting 45 5.1 Where to find the log files........................................ 45 5.2 Run in debug mode............................................ 45 5.3 Celerymon................................................ 45 6 User Guide 47 6.1 Overview................................................. 47 i 7 PostgreSQL 69 7.1 Materialized views............................................ 69 8 Developer doc 71 8.1 Prerequisites............................................... 71 8.2 Coding Style & Structure........................................ 71 8.3 Database Design............................................. 72 8.4 Objects Description........................................... 72 8.5 Objects used by the VoIP Billing module................................ 75 8.6 CDR-Stats Views............................................. 77 8.7 CDR-Stats Tasks............................................. 80 8.8 Test Case Descriptions.......................................... 80 8.9 Javascript Files.............................................. 81 9 API Reference 83 9.1 SwitchSerializer ......................................... 83 9.2 VoIPRateList ............................................ 83 9.3 VoipCallResource ......................................... 84 10 Contributing 87 10.1 Community Code of Conduct...................................... 88 10.2 Reporting Bugs.............................................. 89 10.3 Versions................................................. 90 10.4 Branches................................................. 90 10.5 Tags.................................................... 91 10.6 Working on Features & Patches..................................... 91 10.7 Coding Style............................................... 93 10.8 Contacts................................................. 95 10.9 Release Procedure............................................ 96 11 Resources 97 11.1 Getting Help............................................... 97 11.2 Bug tracker................................................ 97 11.3 Documentation.............................................. 97 11.4 Support.................................................. 98 11.5 License.................................................. 98 12 Frequently Asked Questions 99 12.1 General.................................................. 99 12.2 CDR Import............................................... 99 12.3 Debugging................................................ 100 13 Indices and tables 103 Python Module Index 105 ii CDR-Stats Documentation, Release 3.0.4 Version 3.0 Release 3.0.4 Date October 05, 2015 Contents: Contents 1 CDR-Stats Documentation, Release 3.0.4 2 Contents CHAPTER 1 Getting Started Web http://www.cdr-stats.org/ Download http://www.cdr-stats.org/download/ Source https://github.com/cdr-stats/cdr-stats/ Keywords VoIP, Freeswitch, Asterisk, Django, Python, Call, Reporting, CDR – CDR-Stats is free and open source CDR (Call Detail Record) mediation, rating, analysis and reporting application for Freeswitch, Asterisk and other type of VoIP Switch. It allows you to interrogate your CDR to provide reports and statistics via a simple to use, yet powerful, web interface. It is based on the Django Python Framework, Celery, Gevent, PostgreSQL and InfluxDB. • Overview • Dashboard • Admin Panel • Architecture • Features • Utility 1.1 Overview CDR-Stats is an application that allows rating, browsing and analysing CDR. Different reporting tools are provided: • Dashboard: Overview of call activity • Search CDR: Search, filter, display and export CDR • Overview: Analyse call traffic by hour, day and month • Daily Comparison: Compare call traffic day on day • Country Report: Call statistics by country • World Map: Call statistics overlaid on a world map • Call Cost and Carrier Costs • Mail daily aggregated reports 3 CDR-Stats Documentation, Release 3.0.4 • Threat Control: Detect abnormal call patterns • Destination Alerts: Unexpected destination alerts CDR Stats uses PostgreSQL, a scalable, high performance database system used to analyse large quantities of CDR data. PostgreSQL provides Materialized views which make it perfect to build analytic application which do heavy aggregation and recently PostgreSQL cames with Jsonb field which make it easy to store custom data from variety of switch. Out of the box, CDR-Stats supports Freeswitch, Asterisk, Kamailio, SipWise, Veraz using connectors that get the CDRs and push them to centralized database. Connectors any switch systems can be built. For list of the last supported Switches, please refere to http://www.cdr-stats.org/pricing/switch-connectors/ 1.2 Dashboard User Dashboard provides realtime monitoring of the most relevant metrics of connected switches. 4 Chapter 1. Getting Started CDR-Stats Documentation, Release 3.0.4 1.3 Admin Panel The Admin Panel allows the administrators to configure the entire reporting platform, import CDR in CSV format, configure users, switch connections and automatic alarms. 1.4 Architecture CDR-Stats uses PostgreSQL as the underlying CDR store. PostgreSQL with Materialized view allows querying and analysis of many millions of records without noticeable loss of performance, and can easily be scaled as demand increases. Postgresql is used for managing CDR-Stats in terms of users and managing the web framework, Django. Celery, a task manager runs in the background, and monitors the CDR coming into the system, and alerts the systems administrator when unusual behaviour is discovered. What is determined as unusual behaviour is determined by the administrator who can configure alerts for increases in dropped calls, average length of calls, or calls to unusual destinations. 1.3. Admin Panel 5 CDR-Stats Documentation, Release 3.0.4 CDR-Stats works hand in hand with CDR-Pusher which has been built to create an totally independent, easy to install, high performance CDRs Collector. CDR-Pusher is installed on your local Telcoms Switch (e.g. Asterisk), the 6 Chapter 1. Getting Started CDR-Stats Documentation, Release 3.0.4 application will harvest CDRs in Realtime and push them to a central CDR-Stats Database. 1.5 Features Many features are provided on CDR-Stats, from browsing millions of CDRs, call rating, providing efficient search facilities to build reporting such as monthly reports and comparing call traffic with previous days. Telephony Leading open source switches Freeswitch, Asterisk, supported as standard. Reporting Multi-switch Monitor traffic from many switches in one location Multi-tenant Sllowing many customers to monitor their own CDR on one instance of CDR-Stats. Distributed Runs on one or more machines. Supports broker clustering and HA. New workers can be set up without central configuration. Fraud Visualise traffic which helps to identify unusual patterns. detection Fraud Alert Send emails to the administrator when fraud are or suspicious paterns occur Error Emails Can be configured to send emails to the administrator if a tasks fails. Import CDR Import CDR files in custom format World Map See where the traffic originates and terminates on a Map view Compare See how your traffic evolves, and patterns change. traffic Mail Send daily mail reports of telecoms traffic Reporting Realtime Traffic displayed in realtime Reporting Blacklist Blacklist Phone number patterns to receive alarms Geographic Set alert if calls go to disallowed countries alerts Call Rating Each call individually rated 1.6 Utility CDR-Stats is a simple-to-use tool to provide easy rating and analysis of calls. It is a recommended addition to tele- phony servers, whether it be a simple in-house PBX or large capacity VoIP switch. It shows in in near realtime what calls are going through, can detect errors and failures, and alert the systems administrator is unexpected traffic