Concurrency Count

A newer FreePBX/PBXact module is now available

A newer, GUI-integrated version of Concurrency Count is available as a FreePBX/PBXact module:

Concurrency Count 2 for FreePBX/PBXact

The new module adds Live View, Historical Reports and Live Wall directly within the FreePBX/PBXact GUI, with significantly expanded reporting, filtering, monitoring and alerting capabilities.

The new module is currently marked as not suitable for production while wider testing continues.

This original standalone Bash version remains available and can still be installed and used if you prefer the SSH/command-line workflow. Everything below applies to the standalone version.

Version: 1.0.0
Released: 1st July 2025
Author: 20tele.com
Licence: GNU General Public License v3.0
Compatibility: Asterisk 18, 20, and 22 (PJSIP only). Tested on FreePBX 16/17 and PBXact equivalents.

---

Previous IN1CLICK installation

Concurrency Count can no longer be installed using the IN1CLICK repository installer.

Before installing from this repository, remove any previous standalone installations:

rm -f /usr/local/bin/concurrency-count
rm -f /root/concurrency-count

This does not remove any shell function or local output masking customisation that may wrap the command.

---

Overview

Concurrency Count is a standalone Bash script that calculates the maximum number of concurrent PJSIP calls on a FreePBX or PBXact system over a specified time period.

It is designed for manual execution via SSH and supports diagnostics, capacity planning, and usage auditing. No integration with the FreePBX web interface is required.

Supported Modes

• Trunks mode – Calculates concurrent calls per named PJSIP trunk
• Extensions mode – Calculates concurrent calls per numeric extension
• Group mode – Calculates overall system concurrency (all numeric call legs counted)

All results are based on second-by-second analysis of answered calls (disposition = 'ANSWERED') from the Asterisk CDR database.

---

Features

• Compatible with Asterisk 18, 20, and 22 (PJSIP only)
• Works on FreePBX 16/17 and PBXact equivalents
• Interactive and unattended (flag-based) operation
• Accepts flexible input formats:
  • today, yesterday
  • Named months (e.g. June)
  • Shorthand dates (e.g. 24, 24-06, 24-6-1)
  • Custom full datetimes (e.g. 2024-05-10 14:30:00)
• Rejects invalid or future dates (with 3 retry attempts)
• Automatically clamps call legs to 24 hours
• Identifies and warns about trunks with numeric names
• Runtime estimation with live progress output
• 60-minute runtime limit with optional override
• Debug mode for detailed visibility

---

Requirements

• FreePBX or PBXact system using PJSIP (not chan_sip)

• MySQL table asteriskcdrdb.cdr must exist (standard FreePBX layout)

• Root SSH access

• MySQL credentials stored in /root/.my.cnf:

  [client]
  user=freepbxuser
  password=freepbxuser_password
  host=localhost

• Required system commands:

  • bash, mysql, awk, grep, sed, date, sort, printf, cut, wc

---

Installation

Run the following commands via SSH:

cd /root
git clone https://github.com/20telecom/concurrency-count.git
cd concurrency-count
chmod +x concurrency-count
cp concurrency-count /usr/local/bin/

This installs the script to /usr/local/bin/concurrency-count and makes it executable.

Verify installation:

concurrency-count --status

---

Updates

Run the following commands via SSH:

cd /root/concurrency-count
git pull
chmod +x concurrency-count
cp concurrency-count /usr/local/bin/

Uninstall

Run the following commands via SSH:

rm -f /usr/local/bin/concurrency-count
rm -rf /root/concurrency-count

Usage

Interactive Mode

concurrency-count

You will be prompted to:

1. Choose a mode: trunks, extensions, or group
2. Enter a date range (month name, shorthand, or custom range)

Flag-Based Mode

concurrency-count --extensions --debug

Available Flags

Flag	Description
--trunks	Run in trunk mode
--extensions	Run in extension mode
--group	Run in group (overall) mode
--debug	Enable verbose runtime debug output
--status	Display version and debug status
--help	Display usage instructions

---

Output Examples

Trunks or Extensions Mode

Maximum concurrent calls per PJSIP trunk between 2025-06-01 and 2025-06-30:

 INTRUNK1-DEMO              7
 OUTRUNK2-DEMO              5

Group Mode

Peaks occurred at the following time ranges:

  2025-06-12 10:40:55 to 2025-06-12 10:41:17
  2025-06-17 11:27:21 to 2025-06-17 11:28:02

Maximum concurrent calls overall: 14

---

Input Format Reference

Input Example	Interpreted As
today	From 00:00 to current time today
yesterday	Full previous day
April + 2024	1st to 30th April 2024
23	Full year 2023
24-06	June 2024
24-6-1	1st June 2024
2024-05-10 14:30:00	Specific date and time

The script allows up to three invalid input attempts before exiting.

---

How It Works

1. Queries the cdr table for answered PJSIP calls in the selected time range.
2. Calculates each call leg's start and end time.
3. Tracks every second the call was active.
4. Records peak concurrency per extension, trunk, or in total.
5. Clamps any call leg over 24 hours to prevent inflated figures.

---

Runtime Management

• Enforces a 60-minute maximum runtime
• If estimated time exceeds this, a warning is shown
• You may choose to continue or abort
• If no response is given, the script exits automatically

This protects the system and database under heavy load.

---

Debug Mode

To enable debug output:

concurrency-count --debug

Debug mode displays:

• SQL query details
• Identified trunks or extensions
• Row-by-row progress
• Estimated completion time
• Runtime diagnostics

---

Data Model & Assumptions

Item	Detail
Call filtering	Only ANSWERED calls are included
Protocol	PJSIP only (chan_sip not supported)
Extension detection	Based on numeric PJSIP/123-xxxxx format
Trunk detection	Names must contain at least one letter
Long call handling	Legs over 24 hours are clamped
Call duplication	Transfers/forks are counted individually
Billing, DID, direction	Not evaluated

---

Known Limitations

• Only works with PJSIP (not compatible with chan_sip)
• Trunks named numerically (e.g. 24700020) may be misidentified as extensions
• Requires root access (Asterisk CLI and MySQL credentials)
• Not intended for background automation (cron, GUI tools, etc.)

---

Output Behaviour

• Results printed to standard output
• No data is saved or logged
• Designed for manual execution via SSH
• Not suitable for unattended environments

---

Best Practice

Recommended uses:

• Audit SIP trunk/channel usage
• Investigate call path saturation
• Review historic concurrency during peak hours
• Assist with FreePBX/PBXact tuning or migrations

Avoid use in automated pipelines or system schedulers.

---

Troubleshooting

Problem	Solution
Low or missing results	Check for PJSIP usage, numeric trunk names, and populated CDR records
Script exits prematurely	Runtime limit reached; try reducing the date range
No output	Check MySQL access, CDR table existence, and .my.cnf configuration
Group mode is slow	Use a narrower date range or enable debug to monitor progress

---

License

Licensed under the GNU General Public License v3.0.
You are free to use, modify, and redistribute under the terms of the GPL.

Full licence text: https://www.gnu.org/licenses/gpl-3.0.en.html

---

Contact

For support, queries, or feedback:

Email: support@20tele.com
Website: https://20tele.com

---

AI Disclosure

This module has been developed with AI assistance for code generation, review, testing, and documentation. Changes should still be reviewed, tested, and accepted by a human maintainer before deployment.

---

About

Concurrency Count was developed by 20tele.com to provide visibility into real-time SIP channel usage on FreePBX and PBXact systems.

It is safe for production use, requires no external dependencies, and supports full user control. Contributions and forks are welcome.