---
title: "Call Detail Records (CDR) Module Documentation"
description: "Documentation for Call Detail Records (CDR)"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [CDR Fields Reference](#4-cdr-fields-reference)
7. [Filtering Options](#5-filtering-options)
8. [Common Scenarios & Examples](#6-common-scenarios--examples)
9. [Limitations & Important Notes](#7-limitations--important-notes)
10. [Troubleshooting Tips](#8-troubleshooting-tips)
11. [Glossary](#9-glossary)
12. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration)
---

## Navigation & Access

To access the Call Detail Records reporting interface:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Reports**.
3. Under **CDR Reports**, click **Call Detail Records** (`/reports/cdr/cdr`).
4. Browse call sessions, apply date and extension filters, export CSV logs, stream embedded recordings, or request on-demand Post-Call AI summaries.

---

## Screenshots & Visual Interface

### Call Detail Records (CDR) Analytics Ledger
High-performance call history table showcasing inbound/outbound session timestamps, caller identification, destination routes, call durations, billable talk times, MOS quality ratings, and integrated audio playback actions.
![Call Detail Records Log](/screenshots/reports/cdr/cdr-list.png)

---

## 1. Module Overview (Technical)

### What Are Call Detail Records?

Call Detail Records (CDR) is a **call logging and reporting system** that captures comprehensive information about every call processed by the PBX. It includes caller/destination info, timestamps, duration, quality metrics, and recording access.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    CDR System Architecture                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Telephony Server                                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Call Processing                                   │   │
│  │                                                          │   │
│  │  Call Start → Processing → Answer → End                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ mod_cdr_pg (PostgreSQL CDR module)                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        cdr Database                                      │   │
│  │                                                          │   │
│  │  Tables:                                                 │   │
│  │  ├─ public.cdr (call records)                           │   │
│  │  ├─ public.cdr_leg_a (A-leg details)                    │   │
│  │  └─ public.cdr_leg_b (B-leg details)                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Backend API                                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        CdrRecordsPage.tsx                                │   │
│  │                                                          │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │ Filters:                                            │ │   │
│  │  │ [Date Range] [Call Type] [Caller] [Destination]     │ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  │                                                          │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │ Caller   │ Dest    │ Duration │ Status │ Recording │ │   │
│  │  ├──────────┼─────────┼──────────┼────────┼───────────┤ │   │
│  │  │ 1001     │ +1555.. │ 0:05:23  │ ✓      │ ▶️ 📥     │ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

CDR provides **complete call visibility**:

| Without CDR | With CDR |
|-------------|----------|
| No call history | Full audit trail |
| Unknown call quality | QoS metrics |
| Manual billing | Automatic logging |
| No recordings | Integrated playback |

### Use Cases

1. **Billing & Accounting**
   - Track billable seconds
   - Account code reporting

2. **Troubleshooting**
   - Identify failed calls
   - Analyze call quality

3. **Compliance**
   - Call recording access
   - Audit trail

4. **Analytics**
   - Call volume trends
   - Peak hour analysis

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Date Filters** | Historical queries |
| **Call Type Filter** | In/Out/Internal |
| **Search** | Find specific calls |
| **QoS Metrics** | MOS, jitter, packet loss |
| **Recording Access** | Play/download recordings |
| **Export** | Generate reports |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- View all call records
- Filter by date range
- Filter by call type
- Search by caller/destination
- Play call recordings
- Download recordings
- Analyze call quality

### CDR Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Call Detail Records                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Filters:                                                       │
│  ├─ Range: [Today ▼] [01/16/2026] to [01/16/2026]              │
│  ├─ Call Type: [All ▼]                                         │
│  ├─ Caller: [                  ]                               │
│  ├─ Destination: [             ]                               │
│  └─ [Apply Filters] [Refresh] [Clear]                          │
│                                                                 │
│  🔍 [Search by caller, destination, or domain...    ]          │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Time     │ Caller   │ Dest      │ Dir  │ Dur  │ Status │🎵│  │
│  ├──────────┼──────────┼───────────┼──────┼──────┼────────┼──┤  │
│  │ 10:30:45 │ 1001     │+1555123.. │ OUT  │ 5:23 │ ✓      │▶️│  │
│  │ 10:28:12 │+1555456..│ 1002     │ IN   │ 2:45 │ ✓      │▶️│  │
│  │ 10:25:00 │ 1003     │ 1004     │ INT  │ 0:30 │ ✓      │  │  │
│  │ 10:20:15 │ 1001     │+1555789..│ OUT  │ 0:00 │ ✗      │  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Showing 1-25 of 1,234 records                                  │
│  [< Previous] [Next >]                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Quick Date Ranges**: Use dropdown for Today, 7 Days, 15 Days, 30 Days.

> [!TIP]
> **Recording Playback**: Click the play icon to hear call recordings.

> [!CAUTION]
> **Large Date Ranges**: Limit to 30 days for performance.

---

## 4. CDR Fields Reference

### Call Information

| Field | Description |
|-------|-------------|
| **UUID** | Unique call identifier |
| **Caller Name** | Caller ID name |
| **Caller Number** | Caller phone/extension |
| **Destination** | Called number |
| **Direction** | Inbound/Outbound/Internal |
| **Context** | Telephony Server context |

### Timestamps

| Field | Description |
|-------|-------------|
| **Start Time** | Call initiated |
| **Answer Time** | Call answered |
| **End Time** | Call ended |
| **Duration** | Total duration (seconds) |
| **Billable Seconds** | Answered duration |

### Technical Details

| Field | Description |
|-------|-------------|
| **Hangup Cause** | Call termination reason |
| **SIP Disposition** | SIP status |
| **Gateway/Trunk** | Gateway used |
| **Account Code** | Billing code |
| **Authorization Code** | Auth code used |
| **Read/Write Codec** | Audio codecs |

### Quality Metrics

| Field | Description |
|-------|-------------|
| **MOS Score** | Mean Opinion Score (1-5) |
| **Packet Loss (%)** | Audio packet loss |
| **Jitter (ms)** | Audio jitter |
| **Max Delay (ms)** | Maximum delay |
| **PDD (ms)** | Post-dial delay |

### Recording & Storage Tracking

| Field | Description |
|-------|-------------|
| **Recording File** | Relative path to recording on disk (`/var/lib/freeswitch/recordings/...`). |
| **Recording Size** | Exact audio file size on disk in bytes (`recording_size_bytes`). Displayed dynamically in MB/KB. |
| **Play** | In-browser inline playback with waveform controls. |
| **Download** | Secure download of the recording audio file. |

#### Exact Per-Call Storage Accounting

Every completed call with an active recording triggers the Telephony Server post-processing hook `update_recording_storage.lua`:
- The exact file size is recorded directly on the CDR in `public.cdr.recording_size_bytes`.
- A dedicated partial index (`idx_cdr_recording_size ON public.cdr (domain_id, recording_size_bytes) WHERE recording_file IS NOT NULL`) enables instant domain-wide usage aggregation without costly full table scans.
- When an individual recording is purged or deleted via the UI or automated retention rules, the exact `recording_size_bytes` value is subtracted from the domain's `recording_storage_bytes` counter in `public.domains`, keeping the domain quota accurate in real time.
- Registered as an active field in the **CDR Settings** module (`public.cdr_fields`, sort order 34).

---

## 5. Filtering Options

### Date Range

| Option | Description |
|--------|-------------|
| **Today** | Current day |
| **7 Days** | Last week |
| **15 Days** | Last 2 weeks |
| **30 Days** | Last month |
| **Custom** | Select dates |

### Call Type

| Type | Description |
|------|-------------|
| **All** | All calls |
| **Inbound** | Incoming calls |
| **Outbound** | Outgoing calls |
| **Internal** | Extension to extension |
| **Transit** | Pass-through |

### Search Fields

| Field | Description |
|-------|-------------|
| **Caller** | Partial match on caller |
| **Destination** | Partial match on destination |
| **Saved Filters** | Apply CDR Filter templates |

---

## 6. Common Scenarios & Examples

### Scenario 1: View Today's Calls

1. Select **Today** from range dropdown
2. Click **Apply Filters**
3. Browse results

### Scenario 2: Find Failed Outbound

1. Set Call Type to **Outbound**
2. Look for calls with duration = 0
3. Check hangup cause

### Scenario 3: Listen to Recording

1. Find call in list
2. Click ▶️ play icon
3. Recording plays in browser

### Scenario 4: Analyze Call Quality

1. View MOS Score column
2. Check Packet Loss %
3. Review Jitter values

### Scenario 5: Export for Billing

1. Set date range
2. Apply filters
3. Export to CSV

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Real-time**: CDR records appear after call ends.

> [!NOTE]
> **Recording Depends**: Recording must be enabled for call.

> [!WARNING]
> **Performance**: Large date ranges may be slow.

### Data Retention

| Setting | Description |
|---------|-------------|
| **CDR Retention** | Configured per system |
| **Recording Retention** | Separate storage policy |

### Best Practices

1. **Limit Date Range**: Use shortest needed range
2. **Use Filters**: Narrow results before searching
3. **Save Filters**: Create CDR Filters for common queries
4. **Regular Export**: Archive important records
5. **Monitor Quality**: Review MOS scores regularly

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No records | Wrong date range | Adjust dates |
| Missing calls | Filter too restrictive | Clear filters |
| Recording won't play | File deleted | Check retention |
| Slow loading | Large date range | Reduce range |
| Quality metrics N/A | Codec issue | Check RTP settings |

### Diagnostic SQL

**Recent CDR records:**
```sql
SELECT 
  start_stamp,
  caller_id_number,
  destination_number,
  direction,
  duration,
  billsec,
  hangup_cause
FROM public.cdr
WHERE domain_id = [domain_id]
ORDER BY start_stamp DESC
LIMIT 20;
```

**Call quality summary:**
```sql
SELECT 
  AVG(rtp_audio_in_mos) as avg_mos,
  AVG(rtp_audio_in_packet_loss_percent) as avg_loss,
  AVG(rtp_audio_in_jitter_mean) as avg_jitter
FROM public.cdr
WHERE domain_id = [domain_id]
  AND start_stamp >= NOW() - INTERVAL '24 hours';
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **CDR** | Call Detail Record |
| **MOS** | Mean Opinion Score (quality 1-5) |
| **Jitter** | Variation in packet arrival time |
| **PDD** | Post-Dial Delay |
| **Billsec** | Billable seconds (answered time) |
| **Hangup Cause** | Reason call ended |
| **A-Leg** | Originating party |
| **B-Leg** | Destination party |

---

## 10. Model Context Protocol (MCP) AI Integration

The Ring2All Platform Copilot integrates directly with the Call Detail Records subsystem through the Model Context Protocol (MCP). Administrators, telecom engineers, and supervisors can conduct natural language call investigations, summarize daily traffic volume, inspect failed calls, and isolate audio quality degradation without manual SQL querying.

### Exposed MCP Tools

| Tool Name | Operation | Primary Parameters | Description |
|:---|:---|:---|:---|
| `query_cdrs` | CDR Search & Audit | `search` (string, optional), `status` (ANSWERED, MISSED, BUSY, FAILED), `direction` (inbound, outbound, local), `limit` (number) | Retrieves recent call records matching filters with timestamps, durations, and leg destinations. |
| `get_cdr_summary` | Traffic & QoS Summary | `period` ("24h", "7d", "30d") | Computes high-level telephony metrics: total call volume, answer rate, billable talk time, and mean MOS score. |
| `get_cdr_details` | In-Depth Session Diagnostic | `callUuid` (string) | Fetches complete diagnostic data for a specific call session, including SIP call ID, Telephony Server hangup cause, RTP jitter, and packet loss. |
| `diagnose_call_failure` | Forensic Failure RCA | `uuid`, `dialedNumber`, `extension`, `limit` | Performs deep forensic investigation on failed or dropped calls: parses SIP hangup causes (USER_BUSY, NO_ROUTE_DESTINATION, CALL_REJECTED), detects early media drops and 32-second NAT ACK drops, analyzes MOS packet loss, and matches engine error traces. |

### Operational Safeguards & Multi-Tenant Isolation

- **Domain Scoping**: All queries automatically filter against the authenticated user's `domain_id`. Cross-tenant call record visibility is blocked at the database query layer.
- **Read-Only Operations**: CDR diagnostic tools execute read-only queries against `ss_cdr.cdr` and cannot mutate or purge historic call data.
- **Data Protection**: Audio recording URLs and sensitive caller IDs adhere to RBAC profile restrictions defined in `admin_admin_user_profiles`.

### Example MCP Payloads

#### 1. Summarizing Today's Call Activity (`get_cdr_summary`)
```json
{
  "period": "24h"
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "period": "24h",
    "totalCalls": 1420,
    "answeredCalls": 1285,
    "missedCalls": 135,
    "answerRatePercent": 90.5,
    "totalBillableMinutes": 4820,
    "averageMosScore": 4.38
  }
}
```

#### 2. Investigating a Dropped Call (`get_cdr_details`)
```json
{
  "callUuid": "c8e41bf2-8812-4c22-9014-ef6a9281a033"
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "uuid": "c8e41bf2-8812-4c22-9014-ef6a9281a033",
    "callerNumber": "+13055550144",
    "destinationNumber": "1002",
    "direction": "inbound",
    "hangupCause": "NORMAL_CLEARING",
    "billsec": 145,
    "rtpMetrics": {
      "audioInMos": 4.41,
      "audioInJitterMs": 2.1,
      "packetLossPercent": 0.0
    }
  }
}
```

#### 3. Investigating Call Failures & Hangup Root Causes (`diagnose_call_failure`)
```json
{
  "dialedNumber": "+13055550199",
  "limit": 5
}
```

### Copilot Natural Language Prompts

- *"Give me a summary of all call traffic over the last 24 hours."*
- *"Show me the last 10 missed calls on extension 1001."*
- *"Why did the incoming call from +13055550144 fail this morning?"*
- *"Are there any outbound calls with an RTP MOS score below 3.5 in the past 7 days?"*

---

*Documentation last updated: January 2026*