Asterisk Monitoring

NetXMS can monitor Asterisk PBX systems through the Asterisk Manager Interface (AMI). This enables monitoring of call volumes, channel usage, peer status, and PBX health.

Overview

Asterisk monitoring provides:

  • Active channel and call monitoring

  • SIP/IAX peer status and registration

  • Queue statistics

  • PBX system resource usage

Configuration

Loading the Subagent

The Asterisk monitoring subagent connects to the Asterisk Manager Interface:

SubAgent = asterisk.nsm

AMI Connection Configuration

For a single local system, configure directly in the [Asterisk] section:

[Asterisk]
Login = netxms
Password = monitoring_secret
Hostname = localhost
Port = 5038

For monitoring multiple Asterisk systems, use named subsections:

[Asterisk/Systems/pbx1]
Login = netxms
Password = your_password
Hostname = pbx1.example.com
Port = 5038

[Asterisk/Systems/pbx2]
Login = netxms
Password = your_password
Hostname = pbx2.example.com
Port = 5038

Configuration parameters:

Parameter Default Description

Login

root

AMI user login

Password

AMI user password

Hostname

127.0.0.1

Asterisk server address

Port

5038

AMI port

AMI User Configuration

Create a monitoring user in Asterisk’s manager.conf:

[netxms]
secret = monitoring_secret
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = system,call,agent
write =

Grant read-only permissions for the metrics you need. The monitoring user does not need write access.

Metrics

Metrics take the target system name as the first argument. For the local system configured in the [Asterisk] section (named LOCAL), the system argument can be omitted — by dropping the argument entirely, not by passing an empty value:

  • Metrics whose only argument is the system name (Asterisk.AMI., Asterisk.Channels., Asterisk.CurrentCalls, Asterisk.Events.*, Asterisk.Version) are then used without arguments at all, e.g. Asterisk.CurrentCalls.

  • Asterisk.SIP.Peers.* metrics exist only in the parameterized form — for the local system use empty parentheses, e.g. Asterisk.SIP.Peers.Total().

  • Metrics with additional arguments (peer, task processor, and registration test metrics) are used with the system argument dropped, e.g. Asterisk.SIP.Peer.Status(peer1).

  • Asterisk.SIP.Peer.Details is the exception: it always requires all three arguments (system, peer, tag).

System Metrics

Parameter Description

Asterisk.AMI.Status(system)

AMI connection status (integer)

Asterisk.AMI.Version(system)

AMI protocol version

Asterisk.Version(system)

Asterisk version string

Asterisk.CurrentCalls(system)

Number of current active calls

Channel Metrics

Parameter Description

Asterisk.Channels.Active(system)

Number of active channels

Asterisk.Channels.Busy(system)

Number of channels in use (in call)

Asterisk.Channels.Dialing(system)

Number of channels in dialing state

Asterisk.Channels.OffHook(system)

Number of off-hook channels

Asterisk.Channels.Reserved(system)

Number of reserved channels

Asterisk.Channels.Ringing(system)

Number of ringing channels

Asterisk.Channels.Up(system)

Number of channels in up (connected) state

SIP Peer Metrics

Parameter Description

Asterisk.SIP.Peers.Total(system)

Total number of SIP peers

Asterisk.SIP.Peers.Connected(system)

Number of connected SIP peers

Asterisk.SIP.Peers.Unknown(system)

Number of peers in unknown state

Asterisk.SIP.Peers.Unmonitored(system)

Number of unmonitored SIP peers

Asterisk.SIP.Peers.Unreachable(system)

Number of unreachable SIP peers

Asterisk.SIP.Peer.Status(system,peer)

Status of a specific SIP peer

Asterisk.SIP.Peer.IPAddress(system,peer)

IP address of a specific SIP peer

Asterisk.SIP.Peer.Type(system,peer)

Type of a specific SIP peer

Asterisk.SIP.Peer.UserAgent(system,peer)

User agent of a specific SIP peer

Asterisk.SIP.Peer.VoiceMailbox(system,peer)

Voice mailbox of a specific SIP peer

Asterisk.SIP.Peer.Details(system,peer,tag)

Raw AMI tag value for a SIP peer (3rd arg is AMI tag name, e.g. SIP-Useragent)

Event Counters

Parameter Description

Asterisk.Events.CallBarred(system)

Call barred event count (counter)

Asterisk.Events.CallRejected(system)

Call rejected event count (counter)

Asterisk.Events.ChannelUnavailable(system)

Channel unavailable event count (counter)

Asterisk.Events.Congestion(system)

Congestion event count (counter)

Asterisk.Events.NoRoute(system)

No route event count (counter)

Asterisk.Events.SubscriberAbsent(system)

Subscriber absent event count (counter)

RTCP Statistics (Per Peer)

Parameter Description

Asterisk.Peer.RTCP.AverageJitter(system,peer)

Average jitter

Asterisk.Peer.RTCP.AveragePacketLoss(system,peer)

Average packet loss

Asterisk.Peer.RTCP.AverageRTT(system,peer)

Average round-trip time

Asterisk.Peer.RTCP.LastJitter(system,peer)

Last measured jitter

Asterisk.Peer.RTCP.LastPacketLoss(system,peer)

Last measured packet loss

Asterisk.Peer.RTCP.LastRTT(system,peer)

Last measured round-trip time

Asterisk.Peer.RTCP.MaxJitter(system,peer)

Maximum jitter

Asterisk.Peer.RTCP.MaxPacketLoss(system,peer)

Maximum packet loss

Asterisk.Peer.RTCP.MaxRTT(system,peer)

Maximum round-trip time

Asterisk.Peer.RTCP.MinJitter(system,peer)

Minimum jitter

Asterisk.Peer.RTCP.MinPacketLoss(system,peer)

Minimum packet loss

Asterisk.Peer.RTCP.MinRTT(system,peer)

Minimum round-trip time

Task Processor Metrics

Parameter Description

Asterisk.TaskProcessor.HighWatermark(system,processor)

Task processor high watermark

Asterisk.TaskProcessor.LowWatermark(system,processor)

Task processor low watermark

Asterisk.TaskProcessor.MaxDepth(system,processor)

Maximum queue depth

Asterisk.TaskProcessor.Processed(system,processor)

Total tasks processed (counter)

Asterisk.TaskProcessor.Queued(system,processor)

Currently queued tasks

SIP Registration Tests

SIP registration tests perform real SIP REGISTER operations against the PBX to verify SIP connectivity.

Test Configuration

Configure tests in the agent config file under the Asterisk system section:

[Asterisk/SIPRegistrationTests/104]
Login = 104
Password = 12345
Domain = demo.netxms
Interval = 300
Timeout = 30

[Asterisk/Systems/Remote1/SIPRegistrationTests/120]
Login = 120
Password = 12345
Domain = remote.netxms

Test configuration parameters:

Parameter Default Description

Login

netxms

SIP login name

Password

netxms

SIP password

Domain

Domain name used for registration

Proxy

sip:<Asterisk IP>

SIP proxy address (with or without sip: prefix)

Interval

300

Check interval in seconds

Timeout

30

Registration request timeout in seconds

Test Metrics

Parameter Description

Asterisk.SIP.TestRegistration(system,login,password,domain)

Ad-hoc SIP registration test; returns elapsed time in ms or -1 on failure. Uses the Asterisk system’s own IP address as SIP proxy and a fixed 5 second timeout

Asterisk.SIP.RegistrationTest.Status(system,test)

SIP status code of last run (e.g. 200, 401, 408)

Asterisk.SIP.RegistrationTest.StatusText(system,test)

Human-readable SIP status text (e.g. OK, Unauthorized)

Asterisk.SIP.RegistrationTest.ElapsedTime(system,test)

Last test elapsed time in ms; -1 if failed

Asterisk.SIP.RegistrationTest.Timestamp(system,test)

Unix timestamp of last test run

Per-Peer Event Counters

In addition to the global event counters, per-peer counters are available. They use the same counter names with a Peer. prefix and take two arguments: system and peer name.

Parameter Description

Asterisk.Peer.Events.CallBarred(system,peer)

Per-peer call barred events

Asterisk.Peer.Events.CallRejected(system,peer)

Per-peer call rejected events

Asterisk.Peer.Events.ChannelUnavailable(system,peer)

Per-peer channel unavailable events

Asterisk.Peer.Events.Congestion(system,peer)

Per-peer congestion events

Asterisk.Peer.Events.NoRoute(system,peer)

Per-peer no route events

Asterisk.Peer.Events.SubscriberAbsent(system,peer)

Per-peer subscriber absent events

Tables

Table Description

Asterisk.Channels(system)

Active channels with state, caller/connected ID, context, extension, bridge, codec, and duration (23 columns)

Asterisk.SIP.Peers(system)

SIP peers with type, IP, port, status, and related properties. 15 columns when Asterisk uses chan_sip, 10 columns for PJSIP (the SIP stack is detected automatically)

Asterisk.SIP.RegistrationTests(system)

Configured SIP registration tests with status, elapsed time, and timestamp (9 columns)

Asterisk.TaskProcessors(system)

Task processors with queue stats (6 columns)

Lists

List Description

Asterisk.Channels(system)

Active channel names

Asterisk.CommandOutput(system,command)

Output lines from an Asterisk CLI command

Asterisk.SIP.Peers(system)

SIP peer names

Asterisk.SIP.RegistrationTests(system)

Configured SIP registration test names

Asterisk.Systems

Names of all configured Asterisk systems (no arguments)

Asterisk.TaskProcessors(system)

Task processor names

Multi-System Configuration Example

SubAgent = asterisk.nsm

[Asterisk]
Login = root
Password = password1

[Asterisk/SIPRegistrationTests/104]
Login = 104
Password = 12345
Domain = demo.netxms

[Asterisk/Systems/Remote1]
Hostname = 10.0.0.1
Login = root
Password = password1

[Asterisk/Systems/Remote1/SIPRegistrationTests/120]
Login = 120
Password = 12345
Domain = remote.netxms
Interval = 60

The default local system uses the name LOCAL. For it, the system argument can be omitted from metrics as described at the beginning of the Metrics section above.

Monitoring Examples

PBX Health Dashboard

Key metrics for an Asterisk health dashboard:

  • Asterisk.Channels.Active and Asterisk.CurrentCalls — shows current PBX load

  • Asterisk.SIP.Peers.Connected() / Asterisk.SIP.Peers.Total() — shows connectivity status

  • Asterisk.Events.Congestion — shows capacity problems

  • Asterisk.Peer.RTCP.AverageJitter(peer) — shows call quality for a specific peer

SIP Trunk Monitoring

Monitor SIP trunk health:

  1. Create DCIs for each SIP trunk peer:

    • Asterisk.SIP.Peer.Status(trunk-provider) — availability

    • Asterisk.Peer.RTCP.AverageRTT(trunk-provider) — latency

  2. Set thresholds:

    • Alert when peer status changes to unreachable

    • Warning when RTT exceeds 200ms

Troubleshooting

AMI Connection Failed

  1. Verify AMI is enabled in Asterisk (manager.conf: enabled = yes)

  2. Check the AMI port is accessible from the agent host

  3. Verify login credentials

  4. Check AMI IP access restrictions in the user configuration

Metrics Return Empty Values

  1. Verify the AMI user has sufficient read permissions

  2. Check that the Asterisk module providing the metrics is loaded

  3. Verify the peer or queue name used in the parameter exactly matches Asterisk’s configuration