Event tracking

This feature is experimental.

Uniloader can be used to connect to an Asterisk server and generate queue events that Asterisk would not normally produce. This works by opening a stream of events from the Asterisk system through AMI and tracking call progress in real-time.

$ uniloader track -?

NAME:
   uniloader track - Tracks Asterisk events and creates relevant queue_log entries.

USAGE:
   uniloader track [command options] [arguments...]

OPTIONS:
   --host value                 Your Asterisk server (default: "127.0.0.1")
   --port value                 The AMI port on Asterisk (default: 5038)
   --login value                The AMI user as defined in manager.conf
   --secret value               The AMI secret [$AMISECRET]
   --rewriteuniqueids value     If 1 rewrites UniqueIds; else leave them unchanged (default: 1)
   --debugfile value            A debug file to dump AMI data to
   --moh value                  When set to 1, tracks Music-on-Hold events on queues. (default: 1)
   --parkedcalls value          When set to 1, tracks parked calls. (default: 0)
   --outboundcalls value        When set to 1, tracks outbound calls. (default: 0)
   --hotdesking value           When set to 1, rewrites hotdesking information. (default: 0)
   --outboundthreshold value    The answer threshold (in ms) for calls to be tracked as outbound. (default: 300)
   --noeventblacklisting value  When 1, AMI events are not blacklisted. Useful for taking traces. (default: 0)
   --hidden-channels value      A regexp for outbound channels to be logged as hidden queues.
   --pid value                  The PID file to write. If already present, won't start.

This is meant to be run as a separate Uniloader process, parallel to the one that does data loading, with a separate PID, so that it can be started and stopped separately from the main process.

You should make sure that only one instance of the tracker is running for each Asterisk server, otherwise you will find duplicate events logged.

Restarting the tracker while calls are in progress will in general lead to incorrect data being logged, as some events may be lost. So event tracking should run unattended and be started as soon as Asterisk becomes available.

You can enable or disable different trackers at once, for example if you run:

./uniloader track .... --moh=1 --parkedcalls=1

It means you want both parked calls and MOH events tracked.

Generally speaking, calls will be tracked with their native Asterisk UniqueID prefixed with a colon; this avoids any possible conflict with manual call outbound or tracked calls that end up traversing queues. This prefix is automatically stripped by QueueMetrics when performing call actions, e.g. listening to recordings or hanging up calls.

This behavior is default after Uniloader 23.09.4 and should be completely transparent. If you don’t want this behavior, just set --rewriteuniqueids=0 to go back to logging unmodified Unique-Ids.

Installing event tracking through RPM

When installing the RPM package of Uniloader, two distinct services will be installed. Both of them rely on the same binary of Uniloader, but are otherwise completely separate.

As event tracking is still experimental, it is NOT started automatically.
Table 1. Services installed in RPM
Service Description Configuration file Started on install? Starts on reboot?

uniloader

Uploads queue_log

/etc/sysconfig/uniloader

Yes

Yes

unitracker

Tracks events

/etc/sysconfig/unitracker

No

No

In order to start tracking of events you need to:

  • Configure which features you want enabled (see below)

  • Make the service restart on reboots: chkconfig unitracker on

  • Start the service: service unitracker start

  • Check its logs in /var/log/asterisk/unitracker.log

The configuration file lets you set the credentials to use to connect to Asterisk and it lets you turn on specific features. By defaut, only MOH tracking is turned on by default.

These are the defaults - feel free to edit them as needed.

LOGFILE=/var/log/asterisk/unitracker.log
LOCKFILE=/var/lock/subsys/unitracker
PIDFILE=/var/run/unitracker.pid

AMIHOST=127.0.0.1
AMIPORT=5038
AMIUSER=admin
AMISECRET=amp123

#Uncomment to enable event logging
#DEBUGFILE=/var/log/asterisk/unitracker_events.log

#Ony MOH tracking is enabled by default
ENABLEMOH=1
ENABLEPARK=0
ENABLEOUTBOUND=0

OUTBOUNDTHRESHOLD=300

Tracking Music-on-Hold

Uniloader can be used to detect and generate Music-on-Hold events for calls that are being handled on Asterisk queues.

In order to use it, you can launch it as:

./uniloader track --login admin --secret amp123 --moh=1

Where 'admin' and 'amp123' are the current AMI credentials for your local Asterisk system. At this point, you should:

  • Send a call to an Asterisk queue

  • Have an agent handle the call

  • Have the agent start and stop music-on-hold

The event will appear in QueueMetrics on the real-time page.

When enabled, MOH events should appear correctly even when tracking calls in parking lots or for automated outbound.

Tracking Parking lots as queues

Uniloader can be used to track parked calls "as if" they were calls handled on a queue.

Parked calls are in a sense very similar to calls in a queue, because:

  • You can define one or more separate parking spaces in the PBX

  • Calls are parked at some period in time, and are waiting since then.

  • The caller might decide to hang up before the call is served

  • The call might time-out and be re-routed after a maximum wait time.

  • Instead of being distribuited by the ACD, calls are "picked up" by the agent who is willing to serve them. Agents are not "logged on" to a parking space in the same way as they are members of a queue.

  • An agent may want to transfer a call back to the same (or a different) parking lot for further handling

So by converting events from parked calls to logs that "look like" logs from a queue, it may be possible to:

  • See those calls on the Real-time page of QueueMetrics

  • Run a wallboard on them

  • Run reports on them

The main differences from actual queues are that:

  • Agents must be able to see the 'park access code' to fetch a call back from the parking lot. This is handled by prepending the caller’s number with the park code. By using the wallboard or real-time pages in QM you can then see who is parked.

  • The 'queue name' comes from the name of the parking lot prepended with a string that means it’s a parking lot; for example, calls on lot "default" will be tracked as belonging to queue "pk-default". Queue security features of QM can be used as usual.

  • The feeding of a parking lot is usually by some agent transferring the call from an inbound queue. It is important that such transfer produces a call closure record on the queue, so that we can track the call correctly and the first call ends before the parking lot starts. This usually works in FreePBX if the physical interface that is connected to a queue is a SIP extension.

  • As the agent is not logged on to the parking lot when they pick a call, and QueueMetrics works best when agents are logged in to handle calls, we write a log-in record when the call is picked and we produce a log-off record when the call completes.

  • If a call is 'transferred' from a parking lot to a different one, we write call and session closure records before opening new ones.

  • In Asterisk, calls transferred (on parking lots, or elsewhere) will usually have a different Unique-id from their previous one. At the moment we make no provision to "reuse" the same Unique-id across multiple trasfers.

In order to use it, you can launch it as:

./uniloader track --login admin --secret amp123 --parkedcalls=1

Where 'admin' and 'amp123' are the current AMI credentials for your local Asterisk system. At this point, you should:

  • Create a queue in QueueMetrics with the name of your parking lot (e.g. "pk-default" for the default lot)

  • Transfer a call to the parking lot

  • Have an agent pick up the call

The call should appear on the real-time page of QueueMetrics with ts pick-up code as if it was a call on a queue.

Automatically Tracking Outbound Calls

Uniloader is able to track all calls on the system "as if" they were calls made on a queue, so that they become visible to QueueMetrics.

In order to use it, you can launch it as:

uniloader track --login admin --secret amp123 --outboundcalls=1 --outboundthreshold=300

In order to "trim down" the number of calls tracked, a call is only tracked if there is a slight delay between its set-up and someone answering it. This way calls to internal PBX "service" numbers are not tracked. You can adjust the threshold as needed though the outboundtheshold parameter.

As all calls must belong to a "campaign" in order to be tracked, Uniloader tries to determine the "campaign" based on the account code of the extension currently calling. This way, by setting up different account codes for different groups of people, you can control reporting and visibility of calls in QueueMetrics. If an account code is set, the call appears on campaign q-ACCOUNTCODE; if no account code is set, it appears on q-outbound.

If a tracked call enters a queue on your PBX; then its logs are closed an the rest of the call is tracked as a normal inbound call.

Uniloader will also join the agent to the supposed queue and log her off by the end of the call, so that reports and realtime monitoring in QueueMetrics appear correct.

Hiding sets of calls

Sometimes, a lot of outbound calls (e.g. outgoing trunks) will be picked up by Uniloader but are not really needed. In this case, if you can spot a pattern, you can tell Uniloader to "hide" those calls by logging them on a queue name that starts with an underscore.

In this way, information is not lost, but it will not be visible in QueueMetrics unless you manually create a queue with the correct name.

In order to enable this mode, you should use the parameter:

uniloader track --login adm --secret 123 \
          --outboundcalls=1 --hidden-channels '^PJSIP/'

This way, all calls where the channel starts with PJSIP/ will be logged on a queue that starts with an underscore, usually the default q-outbound that will then become _q-outbound.

As the parameter is a regular expression, you can use it to create complex filters, for example:

(?i)^sip/|^zap/

Will match (and hide) all channels starting with SIP/ or ZAP/, in a case-insensitive way.

Be aware of the fact that you usually think in terms of a set of extensions you want to hide, but Uniloader is monitoring the names of live channels. Those usually have names that start with the name of the extension followed by an unique identifier; for example a call made by PJSIP/301 could show up as PJSIP/301-00000014 - the exact format depends on the channel type being used and the Asterisk version. To make sure you are doing it right, you should start by going to the PBX and observe how your extensions appear when they are active and you issue the command core show channels.

You can use the Regexp tester to develop custom regular expressions without the need to relaunch Unitracker for each test. It lets you test the same regexp on a number of channels at once, so you can check that it matches only the ones you want matched.

Automatically tracking outbound queues in QueueMetrics

When you run automated tracking as described above, if you use the QueueMetrics agent page for your agents to dial out there is no need to include the outbound dial-plan.

You will have to create some specific physical queues in Asterisk to be used as "placeholders" for outbound campaigns; and then you must make QueueMetrics aware of them and set them as "outbound" queues.

From the Icon agent page, you will then be able to dial out by selecting the Dialout panel, choosing one of the outbound queues you are logged on to and entering a number to be dialed.

directami dialout

In order to turn this feature on, you will have to enable:

  • DirectAMI

  • Outbound

  • Tracker outbound

The following configuration can be a good starting point for a FreePBX system:

default.hotdesking=86400

platform.pbx=DIRECTAMI
platform.directami.agent=Agent/${num}
platform.directami.extension=SIP/${num}
platform.directami.transfer=${num}@from-internal
platform.directami.outbound.enabled=true
platform.directami.outbound.usetracker=true
platform.directami.outbound.trackerdialout=${num}@from-internal
platform.directami.localext=SIP/${num}
platform.directami.verbose=false
Please refer to the QueueMetrics User Manual for a complete description of how DirectAMI works and which options you can use.

Automatically tracking hotdesking events

If you use an external tool to login your agents to Asterisk, and these agents have a name set, you may want to enable tracking of hotdesking.

If hotdesking tracking is enabled, when an agent "joe" is logged on at SIP/71045 and produces an entry like:

1552380101|MANAGER|callcenter|SIP/71045|ADDMEMBER|

The following entries are added to "reverse" the log-in and create a new one with proper hotdesking:

1552380101|MANAGER|callcenter|SIP/71045|REMOVEMEMBER|
1552380101|MANAGER|callcenter|joe|HOTDESKING|SIP/71045|
1552380101|MANAGER|callcenter|joe|ADDMEMBER|

Debugging missed events

If you find that some calls are missing events or have multiple events and you are able to find a consistent pattern, you should run:

./uniloader track .... --debugfile debugdata.txt --noeventblacklisting 1

When running in debug mode, a large file is quickly generated; so it is appropriate to run it only for short periods and when the system is otherwise idle.

When you are done, you should send Loway:

  • The file that was just created

  • Your queue_log file that was produced (or at least its relevant lines)

  • An indication of which call is displaying wrong events