--- title: "Call Detail Records (CDRs)" description: "Documentation for Call Detail Records" --- ## Table of Contents 1. [Overview & Accounting Architecture](#1-overview--accounting-architecture) 2. [Business & Operational Significance](#2-business--operational-significance) 3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities) 4. [Visual Interface & Layout](#4-visual-interface--layout) 5. [Field & Telemetry Reference](#5-field--telemetry-reference) 6. [Kamailio Core Accounting Mechanics](#6-kamailio-core-accounting-mechanics) 7. [Search, Filtering & CSV Export](#7-search-filtering--csv-export) 8. [Database Maintenance & High-Volume Partitioning](#8-database-maintenance--high-volume-partitioning) 9. [Troubleshooting & Verification](#9-troubleshooting--verification) 10. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration) 11. [Glossary](#11-glossary) --- ## 1. Overview & Accounting Architecture In **Ring2All SBC**, the **Call Detail Records (CDRs)** module provides carrier-grade session accounting, duration measurement, and termination analytics for all SIP traffic transiting the perimeter. Powered by Kamailio's native dialog-aware accounting engine (`acc` module configured with `cdr_enable`), the SBC automatically correlates session establishment (`INVITE` / `200 OK`) and session teardown (`BYE` / `CANCEL`), computing exact billable durations and associating real-time media quality metrics. ``` External Carrier / PBX Ring2All SBC (Kamailio Core) PostgreSQL Storage β”‚ β”‚ β”‚ │─────── SIP INVITE (Initial) ─────────>β”‚ β”‚ β”‚<────── 100 Trying / 180 Ringing ──────│ β”‚ β”‚<────── 200 OK (Call Answered) ────────│─── Create Dialog Context ──────────>β”‚ β”‚ β”‚ Record start_time & src_ip β”‚ │═══════ Active RTP Audio Media ════════│ β”‚ β”‚ β”‚ β”‚ │─────── SIP BYE (Call Terminated) ────>β”‚ β”‚ β”‚<────── 200 OK (Teardown Ack) ─────────│─── Calculate Duration ─────────────>β”‚ β”‚ β”‚ Attach RTPEngine MOS/Jitter β”‚ β”‚ β”‚ INSERT INTO acc_cdrs ────────────>β”‚ ``` Unlike basic SIP proxy loggers that produce disjointed message rows, Ring2All SBC provides: 1. **Consolidated Session Records**: Each row represents a complete end-to-end telephone call with unified start time, end time, and duration. 2. **Dual-Perspective Tracking**: Dedicated accounting views for successfully answered sessions (`acc_cdrs`) versus early rejects, timeouts, and uncompleted calls (`missed_calls`). 3. **Integrated Voice Quality Forensics**: Continuous Mean Opinion Score (MOS), network jitter, and packet loss measurements captured directly from RTPEngine media relays. --- ## 2. Business & Operational Significance * **Carrier Interconnect Settlement**: Supplies indisputable, microsecond-accurate session records required for carrier billing reconciliation, dispute defense, and LCR cost auditing. * **Service Level Agreement (SLA) Verification**: Empowers Network Operations Center (NOC) teams to track answer-seizure ratios (ASR), average call durations (ACD), and post-dial delay across specific SIP trunks and domains. * **Rapid Fault Isolation**: Differentiates between normal subscriber hang-ups (`200 OK` / `487 Request Terminated`) and upstream provider outages (`503 Service Unavailable`, `404 Not Found`, `486 Busy Here`). * **Compliance & Legal Auditing**: Maintains an immutable evidentiary trail of all caller identities, dialed digits, source IP addresses, and routing destinations in accordance with telecom data retention regulations. --- ## 3. 🎯 User Roles & Key Capabilities | Role | Primary Use Case | Key Capabilities | | :--- | :--- | :--- | | **Carrier NOC Engineer** | Live Traffic Monitoring & Incident Triage | Track real-time call volume, investigate sudden spikes in failed or rejected calls, and verify trunk interconnect stability. | | **Interconnect Billing Analyst** | Inter-Carrier Settlement & Reconciliation | Export filtered CDR streams in CSV format, audit billable duration aggregates, and verify per-minute cost attribution. | | **SBC Administrator** | System Health & Retention Governance | Configure PostgreSQL database retention policies, optimize accounting indexes, and verify Kamailio database flushing queues. | | **Compliance Auditor** | Regulatory Verification | Inspect historical call records, verify caller ID integrity, and generate time-bounded telecom access reports. | | **AI Platform Copilot / NOC Diagnostic Agent** | Autonomous CDR Triage & Anomaly Detection | Inspect high-failure CDR bursts, analyze SIP response codes (503/486/404), evaluate ASR/ACD trends, and pinpoint carrier interconnect degradations. | --- ## 4. Visual Interface & Layout The CDR interface is structured with executive KPI telemetry cards at the top, a dual-tab navigation selector (`CDR` vs `Missed Calls`), an advanced filtering bar, and a high-density DataGrid. ### 4.1 Completed Call Detail Records View The primary CDR tab displays all successfully established and answered sessions with duration, SIP termination code, ingress domain, and voice quality metrics. ![Call Detail Records List View](/screenshots/sbc/reports/cdr/cdrs/cdrs-list.png) ### 4.2 Missed & Unanswered Calls View The Missed Calls tab captures all call attempts that terminated prior to an answer (e.g., caller cancellation, busy subscriber, route unreachability, or authentication failures). ![Missed Calls List View](/screenshots/sbc/reports/cdr/cdrs/cdrs-missed.png) --- ## 5. Field & Telemetry Reference ### Executive Summary Cards | Card Metric | Calculation / Origin | Operational Meaning | | :--- | :--- | :--- | | **Total Calls** | Total count of recorded sessions in selected scope | Aggregate traffic volume across the entire SBC cluster. | | **Calls Today** | Count of sessions initiated since midnight local time | Daily volume tracking for capacity planning and peak load monitoring. | | **Average Duration** | Sum of billable seconds divided by answered calls | Reflects typical customer call length (ACD). Sudden drops indicate routing anomalies. | | **Answered** | Percentage of calls terminating with `200 OK` | Answer-Seizure Ratio (ASR). Healthy enterprise traffic typically benchmarks above 70%. | | **Failed** | Percentage of calls resulting in 4xx, 5xx, or 6xx errors | Immediate indicator of carrier trunk congestion, destination misconfigurations, or network dropouts. | ### CDR DataGrid Columns | Column | Data Type | Source | Description | | :--- | :--- | :--- | :--- | | **Result** | Badge | `acc_cdrs.sip_code` | Color-coded SIP final response code (`200` Green, `486` Amber, `487` Gray, `404`/`503` Red). | | **From URI** | String | `acc_cdrs.from_uri` | Originating caller identity and display name (e.g., `sip:2000@192.168.11.130:5060`). | | **To URI** | String | `acc_cdrs.to_uri` | Dialed destination number or target extension (e.g., `sip:mod_sofia@192.168.10.31:5080`). | | **Domain** | String | `acc_cdrs.domain` | Ingress or tenant SIP domain associated with the session. | | **Duration** | Formatted | `acc_cdrs.duration` | Total billable conversational duration formatted as minutes and seconds (e.g., `45s`, `3m 12s`). | | **MOS** | Float | RTPEngine RTCP XR | Estimated Mean Opinion Score for voice quality (scale `1.0` to `5.0`). | | **Jitter** | Milliseconds | RTPEngine RTCP XR | Average inter-arrival packet variation measured across the audio stream. | | **Loss** | Percentage | RTPEngine RTCP XR | Cumulative audio packet loss percentage throughout the session. | | **Source IP** | IPv4 / IPv6 | `acc_cdrs.src_ip` | Remote IP address of the signaling endpoint or carrier trunk initiating the request. | | **Start Time** | Timestamp | `acc_cdrs.start_time` | UTC timestamp when the initial `INVITE` was processed by the SBC. | --- ## 6. Kamailio Core Accounting Mechanics Ring2All SBC utilizes Kamailio's `acc` module linked with the `dialog` module. Rather than writing individual transaction records to disk, Kamailio maintains stateful dialog structures in memory and writes CDR rows upon receipt of teardown signaling: ```text # Kamailio acc module configuration snippet loadmodule "acc.so" modparam("acc", "db_url", "postgres://kamailio:SECRET@localhost/kamailio") modparam("acc", "cdr_enable", 1) modparam("acc", "cdrs_table", "acc_cdrs") modparam("acc", "failed_transaction_flag", 3) modparam("acc", "cdr_start_on_confirmed", 1) modparam("acc", "cdr_extra", "from_uri=$fu;to_uri=$ru;src_ip=$si;domain=$rd") ``` ### Dialog Lifecycle Stages 1. **Dialog Creation**: Triggered upon receipt of valid `INVITE`. Kamailio allocates a memory tracking block keyed by `Call-ID`, `From-tag`, and `To-tag`. 2. **Confirmation**: Upon receiving `200 OK`, `cdr_start_on_confirmed` records the microsecond answer timestamp. 3. **Termination**: When `BYE` passes through the SBC, Kamailio calculates `duration = end_time - start_time`, flushes the accumulated extra variables, and dispatches an asynchronous SQL insert to PostgreSQL. 4. **Early Termination (Missed Calls)**: If the dialog terminates before `200 OK` (e.g., `CANCEL`, `486 Busy`, or `404 Not Found`), Kamailio routes the event into the `missed_calls` table with the exact `sip_code` and `sip_reason`. --- ## 7. Search, Filtering & CSV Export The CDR interface incorporates carrier-grade filtering controls to quickly isolate specific sessions across millions of database rows: * **Date Range Picker**: Quick presets for *Today*, *Yesterday*, *Last 7 Days*, *Last 30 Days*, or custom calendar time-bounds. * **SIP Domain Filter**: Multi-tenant selector allowing operators to isolate traffic for a specific enterprise client or PBX cluster. * **Full-Text Search Engine**: Real-time matching against `Call-ID`, caller phone numbers, dialed digits, or IP addresses. * **CSV Streaming Export**: Clicking the **Export** button invokes `/api/cdrs/export`, streaming zipped or plaintext CSV datasets directly from PostgreSQL without exhausting web application memory. --- ## 8. Database Maintenance & High-Volume Partitioning In high-throughput environments processing millions of minutes per month, standard single-table storage will degrade query performance. Ring2All SBC leverages native PostgreSQL 17 table partitioning: ```sql -- PostgreSQL 17 Table Partitioning Strategy CREATE TABLE acc_cdrs ( id BIGSERIAL, call_id VARCHAR(255) NOT NULL, from_uri VARCHAR(255) NOT NULL, to_uri VARCHAR(255) NOT NULL, start_time TIMESTAMP WITH TIME ZONE NOT NULL, end_time TIMESTAMP WITH TIME ZONE, duration INTEGER DEFAULT 0, sip_code VARCHAR(10), src_ip INET, domain VARCHAR(128), mos NUMERIC(3,2), jitter NUMERIC(5,2), packet_loss NUMERIC(5,2), PRIMARY KEY (id, start_time) ) PARTITION BY RANGE (start_time); -- Example Monthly Partition CREATE TABLE acc_cdrs_2026_09 PARTITION OF acc_cdrs FOR VALUES FROM ('2026-09-01 00:00:00+00') TO ('2026-10-01 00:00:00+00'); CREATE INDEX idx_cdrs_start_time ON acc_cdrs_2026_09 (start_time DESC); CREATE INDEX idx_cdrs_call_id ON acc_cdrs_2026_09 (call_id); CREATE INDEX idx_cdrs_domain ON acc_cdrs_2026_09 (domain); ``` --- ## 9. Troubleshooting & Verification ### Inspecting Live Accounting Tables via CLI Verify that Kamailio is actively writing records to PostgreSQL: ```bash # Connect to SBC Kamailio database psql -U kamailio -d kamailio -c " SELECT id, start_time, duration, sip_code, from_uri, to_uri FROM acc_cdrs ORDER BY id DESC LIMIT 5;" ``` ### Checking Dialog Module Memory Ensure active dialogs are tracking properly in Kamailio memory: ```bash # Query active dialog count via kamcmd kamcmd dlg.profile_get_size global ``` ### Verifying Failed / Missed Calls Investigate the most frequent failure causes over the last hour: ```bash psql -U kamailio -d kamailio -c " SELECT sip_code, sip_reason, count(*) FROM missed_calls WHERE time > NOW() - INTERVAL '1 hour' GROUP BY sip_code, sip_reason ORDER BY count DESC;" ``` --- ## 10. Model Context Protocol (MCP) AI Integration The Call Detail Records (CDRs) subsystem is natively integrated with the Ring2All SBC Model Context Protocol (MCP) server. Autonomous AI agents, NOC triage copilots, and billing reconciliation models use the following tools to inspect traffic patterns, investigate failed call bursts, and audit carrier interconnect volume. ### Available MCP Tools | Tool Name | Operation Type | Risk Level | Description | | :--- | :--- | :--- | :--- | | `get_sbc_cdrs` | Read / Forensic Query | `read` | Query and filter recent CDRs passing through the SBC by telephone number, SIP response code, direction, or Call-ID. | | `get_traffic_analytics` | Aggregate Analytics | `read` | Retrieve aggregated SIP traffic volume, ASR percentage, ACD duration, and SIP code distribution over a specified time window. | | `get_top_destinations` | Aggregated Telemetry | `read` | Retrieve the highest-volume dialed destination numbers and prefix groups with attempt counts and completion rates. | --- ### Tool Schemas & Payloads #### 1. `get_sbc_cdrs` ##### Input Schema ```json { "type": "object", "properties": { "search": { "type": "string", "description": "Filter by phone number, URI, or Call-ID string." }, "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Filter by session direction relative to the perimeter." }, "sipCode": { "type": "string", "description": "Filter by SIP final status code (e.g. '200', '486', '503', '404')." }, "limit": { "type": "number", "description": "Number of records to return (default: 20, max: 100)." } } } ``` ##### Output Payload Example ```json { "success": true, "count": 2, "cdrs": [ { "id": "184029", "call_id": "4d90a1-89e4-41bf-a81b-789a65c2e912@sbc.carrier.net", "from_uri": "sip:+17865550199@192.168.11.130:5060", "to_uri": "sip:+18005550100@sbc.ring2all.com:5060", "start_time": "2026-09-08T15:20:11.182Z", "end_time": "2026-09-08T15:24:26.419Z", "duration_seconds": 255, "sip_code": "200", "sip_reason": "OK", "direction": "inbound", "mos": 4.38, "jitter_ms": 12.4, "packet_loss_pct": 0.0, "source_ip": "192.168.11.130", "destination_ip": "192.168.10.31" }, { "id": "184030", "call_id": "c88f12-0012-4cf3-94df-66b93e8172da@gw01.telco.net", "from_uri": "sip:+13055550144@192.168.11.140:5060", "to_uri": "sip:+18885559988@sbc.ring2all.com:5060", "start_time": "2026-09-08T15:22:04.090Z", "end_time": "2026-09-08T15:22:05.110Z", "duration_seconds": 0, "sip_code": "503", "sip_reason": "Service Unavailable", "direction": "outbound", "mos": null, "jitter_ms": null, "packet_loss_pct": null, "source_ip": "192.168.10.31", "destination_ip": "203.0.113.50" } ] } ``` --- #### 2. `get_traffic_analytics` ##### Input Schema ```json { "type": "object", "properties": { "period": { "type": "string", "enum": ["1h", "6h", "24h", "7d"], "description": "Time window for analytics calculation (default: '24h')." } } } ``` ##### Output Payload Example ```json { "period": "24h", "total_attempts": 28490, "answered_calls": 21940, "failed_calls": 6550, "asr_pct": 77.01, "acd_seconds": 184, "sip_distribution": { "200_OK": 21940, "486_Busy_Here": 2410, "487_Request_Terminated": 2890, "404_Not_Found": 840, "503_Service_Unavailable": 410 }, "peak_cps": 34.2, "average_mos": 4.31 } ``` --- #### 3. `get_top_destinations` ##### Input Schema ```json { "type": "object", "properties": { "limit": { "type": "number", "description": "Number of top destinations to return (default: 10, max: 50)." } } } ``` ##### Output Payload Example ```json { "top_destinations": [ { "destination_prefix": "+1800", "country": "United States (Toll-Free)", "total_calls": 8450, "answered": 7120, "asr_pct": 84.26, "total_duration_minutes": 26890 }, { "destination_prefix": "+1305", "country": "United States (Florida)", "total_calls": 4210, "answered": 3180, "asr_pct": 75.53, "total_duration_minutes": 9840 } ] } ``` --- ### Natural Language AI Prompts #### English Examples * *"Show me the last 15 failed calls with SIP code 503 that occurred in the past hour."* * *"Analyze our traffic volume over the last 24 hours and report the current ASR and average call duration."* * *"Which destination prefixes are generating the highest volume of calls and what is their completion rate?"* #### Spanish Examples (EspaΓ±ol) * *"MuΓ©strame las ΓΊltimas 15 llamadas fallidas con cΓ³digo SIP 503 ocurridas en la ΓΊltima hora."* * *"Analiza el volumen de trΓ‘fico de las ΓΊltimas 24 horas e infΓ³rmame el ASR actual y la duraciΓ³n promedio de llamada."* * *"ΒΏCuΓ‘les son los prefijos de destino con mayor volumen de trΓ‘fico y cuΓ‘l es su tasa de completamiento?"* --- ### Enterprise Safeguards & Access Governance 1. **Read-Only Telemetry Queries**: CDR analytic tools strictly query relational accounting partitions (`acc_cdrs`, `missed_calls`) using bounded `LIMIT` and indexed `start_time` ranges. No SQL mutations or table locks are issued. 2. **Strict Limit Enforcement**: The `limit` parameter is clamped to a maximum of 100 records per tool invocation to prevent memory exhaustion in Fastify and Kamailio pools. 3. **Role-Based Execution Isolation**: Tools are governed by MCP Role Profiles. Only roles containing `cdr_analytics` permissions (such as `noc_network_engineer`, `lcr_carrier_manager`, and `security_auditor`) can invoke CDR inspection tools. --- ## 11. Glossary * **ACD (Average Call Duration)**: Statistical benchmark measuring the average length of answered telephone conversations. * **ASR (Answer-Seizure Ratio)**: Percentage of call attempts that result in a successful `200 OK` answer state. * **Call-ID**: Globally unique string identifier generated by SIP endpoints to distinguish a specific dialog. * **Dialog**: A peer-to-peer SIP relationship between two user agents that persists for the lifetime of a session. * **RTCP XR (Extended Reports)**: Protocol standard for exchanging voice quality telemetry (MOS, jitter, packet loss) between RTP endpoints.