Translations of this page:

Osmius

Asterisk Osmius agent
Agent name: osm_ag_ASTERISK Agent code: ASTERISK
Subject: AMI able Asterisk Osmius agent User manual
Date: 30/09/2008 Revision date:

General Information

This agent can monitor several parameters of Asterisk servers. It has been tested on Asterisk 1.4.17 running over Ubuntu 8.04. However, we recommend checking its functionality before implanting it in a production environment.

Asterisk agent has been developed using functionalities and enhancements of Osmius framework and ACE libraries, so it is necessary to install the ACE libraries for the proper deployment and operation of agente de Osmius para Asterisk. See chapter: installation.

ASTERISK agent provides up to 4 basic events with configuration parameters to allow scaling of a very simple way.

All events are remote, so not intrusive. Monitoring is done through the network connection, by this reason you have to provide some connection information, see connection information. Events are based on Asterisk Manager Interface (AMI) calls. Asterisk agent checks data returned by Asterisk server through AMI nad then an answer is composed. Please, check AMI availability of your Asterisk server and obtain user/password with read and querying privileges.

Asterisk Instance

As a general rule each Osmius agent can monitor one instance type. If you are not familiar with these concepts check out the glossary. Each instance is individually defined in the configuration file (if you want further information go to agents and instances); depending on agent type is the instance type and depending on instance is the connection info.

CONNECTION_INFO

The connection information or connection_info is data that the agent needs to know to connect to the instance. (See more about the connection_info)

In this case the connection_info prototype would be:

CONNECTION_INFO= -i ASTERISK_IP -p AMI_PORT -u ASTERISK_USER -s SECRET

Replace the following:

  • ASTERISK_IP: Asterisk server IP address to monitor.
  • AMI_PORT: Asterisk Manager Interface port number.
  • ASTERISK_USER: user name with read and querying privileges.
  • SECRET: the password.

Examples:

CONNECTION_INFO= -i 192.168.15.46 -p 5038 -u user -s password

TYPE

The type defines the instance type to be monitored. Every declared instance must be associated with a type as you can see here

In this case:

TYPE= ASTERISK

Event summary table for Asterisk

Here is briefly the capabilities of this agent, further down on this page each event is described in more detail.

EVENT DESCRIPTION c w a tseconds Extra parameters / Remarks
AVAILABL Asterisk connection availability 1 0 0 300 Silent mode ( -s) recommmended
AKUPTIME Asterisk uptime in seconds 1 600 300 600 Silent mode ( -s) recommmended
AKEXST00 Extension status 1 0 -1 900 -E extension -C context
AKMCNT00 Mailbox total messages counter 0 25 100 86400 -E extension -C context

Information Events

Info events retieve general data about instance, usually this data does not change over time. This kind of events have no severity, simply provides instance details.

EVENT DESCRIPTION tseconds Remarks
AKINFVER Version 86400 (1 day) Asterisk version
AKINFDLP Dialplan 86400 (1 day) Asterisk dial plan
AKINFCHN Channels 86400 (1 day) Asterisk channel information
AKINFCDC Codecs 86400 (1 day) Asterisk codecs information
AKINFHNT Hints 86400 (1 day) Dialplan hints
AKINFMDL Modules 86400 (1 day) Asterisk modules information

Asterisk agent events

AVAILABL

AVAILABL event checks the connection availability with Asterisk AMI. A new connection is created, the authentication will be performed and then it waits for Asterisk reply.

Return values:

VALUE MEANING
1 Available
0 Unavailable
-1 Error

Recommended parameters:

Comparison type Inverse. The higher value the lower severity (-c 1)
Monitoring interval 300 seconds – 1 hour –> depends on instance importance
Warning threshold 0
Alert threshold 0

Parameter setting example:

AVAILABL = -t 300 -c 1 -w 0 -a 0 -T "Asterisk myenterpr.ise"

Remarks: This agent is capable of maintaining connections and reuse them, instead of creating and destroying them at every event.

AKUPTIME

AKUPTIME returns Asterisk uptime measured iun seconds.

Return values:

VALUE MEANING
-1 Error
X Uptime

Recommended parameters:

Comparison type Inverse. The higher value the lower severity (-c 1)
Monitoring interval 300 seconds – 1 hour –> depends on instance importance
Warning threshold Consult on Asterisk administrator
Alert threshold Consult on Asterisk administrator

Parameter setting example:

AKUPTIME = -t 600 -c 1 -w 600 -a 300 -T "asterisk002 uptime"

Remarks: The event text will show human readable format: [X] days [Y] hours [Z] minutes.

AKEXST00

AKEXST00 event returns current state of a phone extension.

Extra parameters:
This event need extra parameters to work:

PARAMETER MEANING Mandatory
-E extension identifier to monitor Yes
-C extension context Yes

Return values:

VALUE MEANING
-2 Deleted extension
-1 Error or Not found
0 Stopped extension
1 Extension in use
2 Busy
4 Unrecheable
8 Ringing

Recommended parameters:

Comparison type Inverse. The higher value the lower severity (-c 1)
Monitoring interval 600 seconds – 1 hour –> depends on extension relevance
Warning threshold 0
Alert threshold -1

Parameter setting example:

AKEXST00 = -t 600 -c 1 -w 0 -a -1 -T "boss extension" -E 9000 -C default

Remarks: You can monitor up to 4 extensions: AKEXST00, AKEXST01, AKEXST02 and AKEXST03. If you need more visit Osmius.com

AKMCNT00

AKMCNT00 event returns the number of messages (old + new) stored in an Asterisk Mailbox.

Extra parameters:
This event need extra parameters to work:

PARAMETER MEANING Mandatory
-E Mailbox identifier to monitor Yes
-C Mailbox context Yes

Return values:

VALUE MEANING
-1 Error
X Mailbox messages count

Recommended parameters:

Comparison type Direct. The higher value the higher severity (-c 0)
Monitoring interval 600 seconds – 1 day –> depends on mailbox relevance
Warning threshold consult on Asterisk administrator
Alert threshold consult on Asterisk administrator

Parameter setting example:

AKMCNT00 = -t 86400 -c 0 -w 50 -a 100 -T "Reception mailbox" -E 7000 -C default

Remarks: You can monitor up to 4 mailboxes: AKMCNT00, AKMCNT01, AKMCNT02 and AKMCNT03. If you need more visit Osmius.com.
The text associated with the event will detail how many messages are new and old.

Asterisk prerequisites

In order to compile, this agent requires a set of prerequisites, which are generic to compile any Osmius agent, you can see these prerequisites.

In this case, be sure that Asterisk Manager Interface (AMI) is available and working correctly. You need an username/pasword to query and read Asterisk AMI.

Asterisk agent makefiles and compilation

  • Make Project Creator (MPC) is used by Osmius, so creating Makefiles is a trivial task. If you want to learn more about MPC and Osmius check out the section of Makefiles on Osmius.
  • For this agent you can generate Makefile in this way:

From the agent directory using console or terminal.

Linux:

$ACE_ROOT/bin/mpc.pl -type make osm_ag_asterisk.mpc

HP-UX:

$ACE_ROOT/bin/mpc.pl -type gnuace osm_ag_asterisk.mpc
  • Now that you have created the Makefile, agent compiling is extremely simple.

Linux:

make -f Makefile.Osm_Ag_Asterisk_Osmius

HP-UX:

gmake -f Makefile.Osm_Ag_Asterisk_Osmius

Binaries are automatically installed in the bin directory of OSM_ROOT base directory.

Run Asterisk agent

Asterisk agent have the same running features of the other Osmius agents. You can check it out int he section Start and Stop Agents.

To run Asterisk agent without Osmius web console:

osm_ag_ASTERISK[.exe]1) -c osm_ag_ASTERISK.ini -m MASTERAG -p 1950 -d [>> osm_ag_asterisk.log]2)

Running in standalone mode

Asterisk Osmius agent, like the others Osmius agents, allows the execution in standalone mode. This option may be particularly useful when developing a new agent or to perform specific agent tests.

Basically you have to add a new value, called SNDCMD, to Asterisk Osmius agent configuration file (osm_ag_ASTERISK.ini) as shown here.

Then you have to run Asterisk agent setting Master Agent communications port to zero, for example:

osm_ag_ASTERISK[.exe]3) -c osm_ag_ASTERISK.ini -m 00000000 -p 0 -d

Tests list

Test performed to Asterisk Osmius agent.

Date: 26/09/2008
Test Result Remarks
Creating an instance with all its events in silent mode OK N/A
Creating an instance with all its events with custom text OK N/A
Creating an instance with all its events but no custom text OK N/A
Declaration of 3 instances with all its events to 5 seconds and keep it
running for 48 hours
OK No memory leaks
Declare 2 instances, cause a disconnect and then reconnectOK N/A
Declare 1 instance and test each event OK N/A
Elimination of general parameter and check unbootable OK PORTCM deleted
Elimination of instance CONN_INFO and check unbootable OK N/A
1) , 3) Add .exe extension if you are running on Windows
2) Optional, to store agent messages in a file
 
en/agentes/asterisk.txt · Last modified: 2012/12/05 19:06 by osmius
 
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki