CEL (Channel Event Logging)

Channel event logging (CEL) is a new system that was created to provide a more flexible means of logging the details of complex call scenarios. Instead of collapsing a call down to a single log entry, a series of events are logged for the call. This provides a more accurate picture of what has happened to the call, at the expense of a more complex log.

Channel Event Types

Each CEL record represents an event that occurred for a channel in the Asterisk system. Table 24.7, “CEL event types” lists the events that are generated by Asterisk as calls are processed.

Table 24.7. CEL event types

CEL event typeDescription
CHAN_STARTA channel has been created.
CHAN_ENDA channel has been destroyed.
LINKEDID_ENDThe last channel with a given linkedid has been destroyed.
ANSWERA channel has been answered. On a channel created for an outbound call, this event will be generated when the remote end answers.
HANGUPA channel has hung up. Generally, this event will be followed very shortly by a CHAN_END event. The difference is that this event occurs as soon as a hangup request is received, whereas CHAN_END occurs after Asterisk has completed post-call cleanup and all resources associated with that channel have been released.
APP_STARTA tracked application has started executing on a channel. Tracked applications are set in the main CEL configuration file, which is covered in the section called “cel.conf”.
APP_ENDA tracked application has stopped executing on a channel.
PARK_STARTA channel has been parked.
PARK_ENDA channel has left the parking lot.
BRIDGE_STARTA channel bridge has started. This event occurs when two channels are bridged together by an application such as Dial() or Queue().
BRIDGE_ENDA channel bridge has ended.
BRIDGE_UPDATEAn update to a bridge has occurred. This event will reflect if a channel’s name or other information has changed during a bridge.
BLINDTRANSFERA channel has executed a blind transfer.
ATTENDEDTRANSFERA channel has executed an attended transfer.
USER_DEFINEDA user-defined channel event has occurred. These events are generated by using the CELGenUserEvent() application.

There are some more events that have been defined, but are not yet used anywhere in the Asterisk code. Presumably, some future version will generate these events in the right place. They are listed in Table 24.8, “Defined but unused CEL event types”.[172]

Table 24.8. Defined but unused CEL event types

CEL event typeDescription
CONF_ENTERA channel has connected to a conference room.
CONF_EXITA channel has left a conference room.
CONF_STARTA conference has started. This event occurs at the time the first channel enters a conference room.
CONF_ENDA conference has ended. This event occurs at the time the last channel leaves a conference room.
3WAY_STARTA three-way call has started.
3WAY_ENDA three-way call has ended.
TRANSFERA generic transfer has been executed.
HOOKFLASHA channel has reported a hookflash event.

Channel Event Contents

Each CEL event contains the fields listed in Table 24.9, “CEL event fields”:

Table 24.9. CEL event fields

Field nameValue/ExampleNotes
eventtypeCHAN_STARTThe name of the event. The list of events that may occur can be found in Table 24.7, “CEL event types”.
eventtime2010-08-19 07:27:19The time that the event occurred.
cidnameJulie BryantThe caller ID name set on the channel associated with this event.
cidnum18435551212The caller ID number set on the channel associated with this event.
cidani18435551212The Automatic Number Identification (ANI) number set on the channel associated with this event.
cidrdnis18435551234The redirecting number set on the channel associated with this event.
ciddnid18435550987The dialed number set on the channel associated with this event.
exten101The extension in the dialplan that is currently being executed.
contextLocalSetsThe context for the extension in the dialplan that is currently being executed.
channameSIP/0004F2060EB4-00000010The name of the channel associated with this event.
appnameDialThe name of the dialplan application currently being executed.
appdataSIP/0004F2060E55The arguments that were passed to the dialplan application that is currently being executed.
amaflagsDOCUMENTATIONThe Automatic Message Accounting (AMA) flag associated with this call. This may be one of the following: OMIT, BILLING, DOCUMENTATION, or Unknown.
accountcode1234An account ID. This field is user-defined and is empty by default.
uniqueid1282218999.18The unique ID for the channel that is associated with this event.
userfieldI like waffles!User-defined event content.
linkedid1282218999.18The per-call ID. This ID helps tie together multiple events from multiple channels that are all a part of the same logical call. The ID comes from the uniqueid of the first channel in the call.
peerSIP/0004F2060E55-00000020The name of the channel bridged to the channel identified by channame.

Some of the contents of a CEL event are user-defined. For example, the userfield is user-defined and will be empty by default. To set it to something, use the CHANNEL() dialplan function. Here is an example of setting the userfield for a channel:

exten => 101,1,Set(CHANNEL(userfield)=I like waffles!)

Dialplan Applications

The CEL system includes a single dialplan application that lives in the app_celgenuserevent.so module. This application is used to generate custom user-defined events of the type EV_USER_EVENT. A practical example of using this would be for logging a caller’s choices in a menu:

exten => 7,1,CELGenUserEvent(MENU_CHOICE,Caller chose option 7)

For full current details on the syntax of the CELGenUserEvent() application, use the built-in documentation from the Asterisk CLI:

*CLI> core show application CELGenUserEvent


The CEL system has a single configuration file, /etc/asterisk/cel.conf. All options set here affect CEL processing, regardless of which logging backend modules are in use. Table 24.10, “cel.conf [general] section options” shows the options that exist in this file. All options should be set in the [general] section of the configuration file.

Table 24.10. cel.conf [general] section options

enableyesEnables/disables CEL. The default is no.
appsdial,queueSets which dialplan applications to track. The default is to track no applications. EV_APP_START and EV_APP_END events will be generated when channels start and stop executing any tracked application.
eventsCHAN_START,CHAN_END, ANSWER,HANGUPLists which events to generate. This is useful if you are only interested in a subset of the events generated by CEL. If you would like to see all events, set this option to ALL. The default value is to generate no events.
dateformat%F %TSpecifies the format for the date when a CEL event includes a timestamp. For syntax information, see the manpage for strftime by running man strftime at the command line. The default format for the CEL timestamp is seconds.microseconds since the epoch.


At a minimum, to start using CEL, you must set the enable and events options in /etc/asterisk/cel.conf.


As with the CDR system, there are a number of backend modules available for logging CEL events. In fact, all of the CEL backend modules were derived from CDR modules, so their configuration is very similar. In addition to the configuration options for cel.conf, which were described in the previous section, these modules require configuration to make them operate.


The cel_odbc.so module provides the ability to log CEL events to a database using ODBC. This module is not quite as adaptive as the CDR adaptive ODBC backend. For CEL events, there are no custom variables. However, this module will still adapt to the structure of the database, in that it will log the fields of CEL events for which there are corresponding columns and will not produce an error if there is not a column for every field. The configuration for this module goes in /etc/asterisk/cel_odbc.conf.

Multiple tables may be configured in the cel_odbc configuration file. Each goes into its own configuration section. The name of the section can be anything; the module does not use it. Here is an example of a simple table configuration:


connection = asterisk
table = asterisk_cel

The cel_odbc module will use the following columns, if they exist (see the table following this list for a set of mappings between event types and their integer value that will be inserted into the database):

  • eventtype

  • eventtime

  • userdeftype

  • cid_name

  • cid_num

  • cid_ani

  • cid_rdnis

  • cid_dnid

  • exten

  • context

  • channame

  • appname

  • appdata

  • accountcode

  • peeraccount

  • uniqueid

  • linkedid

  • amaflags

  • userfield

  • peer

Table 24.11, “Event type to integer value mappings for the eventtype column” shows the mapping between event types and their integer values that will be inserted into the eventtype column of the database.

Table 24.11. Event type to integer value mappings for the eventtype column

Event typeInteger value

Table 24.12, “cel_odbc.conf table configuration” shows the options that can be specified in a table configuration section in the cel_odbc.conf file.

Table 24.12. cel_odbc.conf table configuration

connectionpgsql1Specifies the database connection to be used. This is a reference to the configured connection in res_odbc.conf. This field is required.
tableasterisk_cdrSpecifies the table name. This field is required.
usegmtimenoEnables/disables logging of timestamps using GMT instead of local time. The default value for this option is no.

In addition to the key/value pair fields that are shown in the previous table, cel_odbc.conf allows for a few other configuration items. The first is a column alias. Normally, CEL fields are logged to columns of the same name. An alias allows the variable name to be mapped to a column with a different name. The syntax is:

alias <CEL field> => <column name>

Here is an example column mapping using the alias option:

alias exten => extension

It is also possible to specify a content filter. This allows you to specify criteria that must match for records to be inserted into the table. The syntax is:

filter <CEL field> => <content>

Here is an example content filter:

filter appname => Dial

Finally, cel_odbc.conf allows static content to be specified for a column. This can be useful when used along with a set of filters. This static content can help differentiate records that were inserted into the same table by different configuration sections. The syntax for static content is:

static <"Static Content Goes Here"> => <column name>

Here is an example of specifying static content to be inserted with a CEL event:

static "My Content" => my_identifier


This CEL backend allows for custom formatting of CEL events in a log file. It is most commonly used for customized CSV output. The configuration file used for this module is /etc/asterisk/cel_custom.conf. A single section called [mappings] should exist in this file. This section contains mappings between filenames and the custom templates for CEL events. The templates are specified using Asterisk dialplan functions and a few special CEL variables.

The following example shows a sample configuration for cel_custom that enables a single CEL log file, Master.csv. This file will be created as /var/log/asterisk/cel-custom/Master.csv. The template that has been defined uses the CHANNEL(), CALLERID(), and CSV_QUOTE() dialplan functions. The CSV_QUOTE() function ensures that the values are properly escaped for the CSV file format. This example also references some special CEL variables, which are listed in Table 24.13, “CEL variables available for use in [mappings]”.

Table 24.13. CEL variables available for use in [mappings]

CEL variableValue/ExampleDescription
${eventtype}CHAN_STARTThe name of the CEL event.
${eventtime}1281980238.660403The timestamp of the CEL event. The timestamp is given in the default format in this example.
${eventextra}Whiskey Tango FoxtrotCustom data included with a CEL event. Extra data is usually included when CELGenUserEvent() is used.

Here is the example /etc/asterisk/cel_custom.conf file:


Master.csv => ${CSV_QUOTE(${eventtype})},${CSV_QUOTE(${eventtime})},


In the actual configuration file, the value in the Master.csv mapping should be on a single line.


The cel_manager backend emits CEL events on the Asterisk Manager Interface (we discussed the AMI in detail in Chapter 20, Asterisk Manager Interface (AMI)). This module is configured in the /etc/asterisk/cel.conf file. This file should contain a single section called [manager], which contains a single option to enable this module. The default value is no, but you can enable it as follows:


enabled = yes

With this configuration in place, CEL events will appear as events on the manager interface. To generate example manager events, we will use the following dialplan example:

exten => 111,1,Answer()
    same => n,CELGenUserEvent(Custom Event,Whiskey Tango Foxtrot)
    same => n,Hangup()

This is the command used to execute this extension and generate sample CEL events:

*CLI> console dial 111@testing

Finally, this is one of the example manager events produced as a result of this test call:

Event: CEL
Privilege: call,all
Exten: 111
Context: testing
Channel: Console/dsp
EventTime: 2010-08-23 08:14:51
UniqueID: 1282569291.1
LinkedID: 1282569291.1


This module allows posting of CEL events to a PostgreSQL database. We recommend that new installations use cel_odbc instead.


The cel_radius backend allows posting of CEL events to a RADIUS server. When using this module, each CEL event is reported to the RADIUS server as a single stop event. This module is configured in the /etc/asterisk/cel.conf file. The options for this module, listed in Table 24.14, “Available options in the cel.conf [radius] section”, are placed in a section called [radius].

Table 24.14. Available options in the cel.conf [radius] section

usegmtimenoLogs timestamps using GMT instead of local time. The default is yes.
radiuscfg /etc/ radius client -ng/ radius client .confSets the location of the radiusclient-ng configuration file. The default is /etc/radiusclient-ng/radiusclient.conf.


This CEL backend inserts CEL events into a SQLite database using SQLite version 3. The database created by this module lives at /var/log/asterisk/master.db. The configuration file for this module, /etc/asterisk/cel_sqlite3_custom.conf, identifies the table name, as well as customizes which CEL variables will be inserted into the database. It looks like this:


table = cel

; List the column names to use when inserting CEL events.
columns => eventtype, eventtime, cidname, cidnum, cidani, cidrdnis, ciddnid,
    context, exten, channame, appname, appdata, amaflags, accountcode, uniqueid,
    userfield, peer

; Map CEL event contents to the previously specified columns.
values => '${eventtype}','${eventtime}','${CALLERID(name)}','${CALLERID(num)}',


In the cel_sqlite3_custom.conf file, the contents of the columns and values options must appear on a single line.


The cel_tds module uses the FreeTDS library to post CEL events to a Microsoft SQL Server or Sybase database. It is possible to use FreeTDS with unixODBC, so we recommend using cel_odbc instead of this module.

Example Channel Events

Now we will show you some example sets of call events from the CEL system. The cel_custom module will be used for its simplicity. The configuration used for /etc/asterisk/cel_custom.conf is the same as shown in the section called “cel_custom”. Additionally, the following configuration was used for /etc/asterisk/cel.conf:


enable = yes
apps = Dial,Playback
events = ALL

Single-party call

In this example, a single phone calls into an extension that plays back a prompt that says “Hello World.” This is the dialplan:

exten => 200,1,Answer()
    same => n,Playback(hello-world)
    same => n,Hangup()

Here are the CEL events that are logged as a result of making this call:

"CHAN_START","1282062437.436130","Julie Bryant","12565553333","","","","200",

"ANSWER","1282062437.436513","Julie Bryant","12565553333","12565553333","",

"APP_START","1282062437.501868","Julie Bryant","12565553333","12565553333",

"APP_END","1282062439.008997","Julie Bryant","12565553333","12565553333","",

"HANGUP","1282062439.009127","Julie Bryant","12565553333","12565553333","",

"CHAN_END","1282062439.009666","Julie Bryant","12565553333","12565553333",

"LINKEDID_END","1282062439.009707","Julie Bryant","12565553333",

Two-party call

For the second example, one phone will call another via extension 101. This results in a call that has two channels that are bridged together. Here is the extension that was called in the dialplan:

exten => 101,1,Dial(SIP/0000FFFF0001)

Here are the CEL events that are generated as a result of making this call:

"CHAN_START","1282062455.574611","Julie Bryant","12565553333","","","","101",

"APP_START","1282062455.574872","Julie Bryant","12565553333","12565553333","",

"CHAN_START","1282062455.575044","Candice Yant","12565551111","","","","s",

   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",

"ANSWER","1282062458.068361","Julie Bryant","12565553333","12565553333","",

"BRIDGE_START","1282062458.068388","Julie Bryant","12565553333",

"BRIDGE_END","1282062462.965704","Julie Bryant","12565553333","12565553333",

   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",

   "SIP/0000FFFF0001-00000012","AppDial","(Outgoing Line)","3","",

"APP_END","1282062462.966156","Julie Bryant","12565553333","12565553333","",

"HANGUP","1282062462.966215","Julie Bryant","12565553333","12565553333",

"CHAN_END","1282062462.966418","Julie Bryant","12565553333","12565553333",

"LINKEDID_END","1282062462.966441","Julie Bryant","12565553333",

Blind transfer

In this final example, a transfer will be executed. The call is started by calling a phone via extension 102. That call is then transferred to another phone at extension 101. Here is the relevant dialplan:

exten => 101,1,Dial(SIP/0000FFFF0001)
exten => 102,1,Dial(SIP/0000FFFF0002)

Here are the CEL events logged as a result of this call scenario:

"CHAN_START","1282062488.028200","Julie Bryant","12565553333","","","",

"APP_START","1282062488.028464","Julie Bryant","12565553333","12565553333",

"CHAN_START","1282062488.028762","Brooke Brown","12565552222","","","",

   "SIP/0000FFFF0002-00000014","AppDial","(Outgoing Line)","3","",

"ANSWER","1282062492.565973","Julie Bryant","12565553333","12565553333","",

"BRIDGE_START","1282062492.566001","Julie Bryant","12565553333",


"BLINDTRANSFER","1282062497.940925","Julie Bryant","12565553333","12565553333","",

"BRIDGE_END","1282062497.940961","Julie Bryant","12565553333","12565553333","",


"CHAN_START","1282062497.941207","Candice Yant","12565551111","","","","s",

   "(Outgoing Line)","3","","1282062488.21","1282062488.20","",""

   "AsyncGoto/SIP/0000FFFF0002-00000014<ZOMBIE>","AppDial","(Outgoing Line)",

"APP_END","1282062497.941415","Julie Bryant","12565553333","12565553333","",

"HANGUP","1282062497.941453","Julie Bryant","12565553333","12565553333",

"CHAN_END","1282062497.941474","Julie Bryant","12565553333","12565553333",

   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","",



   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","","1282062497.23",

   "SIP/0000FFFF0001-00000015","AppDial","(Outgoing Line)","3","","1282062497.23",





[172] If you submit a patch to add any of these events to the code and reference this footnote, Russell will send you a free Asterisk t-shirt. Footnote bribery!