Appendix II: FAQs

Service uniloader-freeswitch is generating no data

To test that the system is working, you can either send a call to a mod_callcenter queue, or you can change the status of an agent from the FusionPBX GUI. When either of these things happen, Freeswitch will generate events that will trigger the writing on your aggregate queue_log file.

If this does not happen, it might mean that:

  • Uniloader cannot connect to Freeswitch - you can easily exclude this by checking access - see Checking ESL access

  • Freeswitch is generating no events

  • Freeswitch is generating events with a format that is not supported

To verify which is which of the last two options, we can connect with and do the same interaction Uniloader does (note: we assume the default address, port and auth token - change as needed):

nc -v 127.0.0.1 8021

When you have a reply, you type:

auth ClueCon

And then:

events json custom callcenter::info

At this points, events are printed. If you log an agent on or off and you receive nothing, then events are not being generated.

To close the connection, press Ctrl + D.

If the command nc is not available, the package 'netcat' that contains it is available with apt-get install netcat on Debian or yum install netcat on CentOS.

My tenant is receiving no data

  • Verify queue log generation: Confirm that a queue_log file is being created at /opt/uniloader/qlogs/qlog-synth.txt

  • Validate tenant configuration: Open the generated queue_log file and verify that your tenant name/ID appears in the logs.

  • Confirm receiving instance status: Ensure the receiving instance is active and functioning properly.

  • Test server connectivity: Run the following command to verify data connectivity from your server:

uniloader testupload  --uri "https://qmlive/instance"  --login webqloader --pass ThEpAsSw0rD

Agents cannot log on or off

First, log on to the QueueMetrics Live instance, then click on Home Page → Settings Bar → Diagnostics → AMI Commands.

You should see a list of actions performed recently (or pending), and their own state.

  • A state of wait means that the action was not yet picked up by Uniloader; a few seconds are OK, but if it stays there for longer, it may mean that service uniloader-splitter is not running, or there is a network issue, or maybe you did not set actions: True in the Ansible script.

  • A state of ok means that the action was performed successfully, i.e. the PBX handled it without raising errors.

  • A state of ko means that the action was not performed: that is, the PBX was unreachable, access credentials were wrong or agent/queue ids were incorrect. Check PBX access using Uniloader.

The time shown in "Sent" is how long the command waited/has been waiting in the queue, while "Proc" is how long it took for the PBX to process it.

How do I take an event trace?

If you need to debug or clarify an unknown issue, Loway support may request an activity trace. This process is straightforward and does not interfere with current operations of service uniloader-freeswitch, so it can run in parallel with your current configuration. However, traces should be captured when there is minimal or no traffic on the system to ensure the resulting data is easy to analyze, as they are extremely verbose.

Capturing an event trace

  • Access your FusionPBX server via the command line

  • Start the trace collection

    • Run the appropriate command from the command line

    • The system will begin printing events as they occur in real-time

An example session could be like:

# uniloader-ctl trace

Now running event trace files:
 - /opt/fusion-splitter-data/traces/evt_251118-1408_trace.txt
 - /opt/fusion-splitter-data/traces/evt_251118-1408_qlog.txt

Press Ctrl+C to terminate.

2025/11/18 14:08:54 Uniloader 25.09.3 (0-20251118.1037) up - GR: 2 - Mem: Alloc 508k (Free 0k) Sys 6743k
....
^C

  • Execute your test call while the trace is running

  • Stop the trace by pressing Ctrl+C when your test is complete

Submitting your trace files

After stopping the collection, two files will be generated in /opt/fusion-splitter-data/traces:

  • evt_(date)_qlog.txt

  • evt_(date)_trace.txt

Send both files to Loway support along with detailed information about the test call, including:

  • Exact time of the call

  • Calling number

  • Queue selected

  • Agent who answered

  • Any other relevant characteristics that will help identify your specific call in the trace

This information is essential for support to quickly locate and analyze your call within the trace data.

You may run multiple traces, and each one will be named differently, in case you need to run multiple separate tests.

For more detail, see qm-fsw-ctl trace.

Can I originate a call via the Freeswitch API and have it tracked?

If you use the Freeswitch API to originate calls, you must "earmark" the call in a specific way so that uniloader-freeswitch can pick it up correctly. If you don’t, the agent code might be tracked improperly - this happens because when dialing through the API, the first call that appears rings the agent, but what you want to track is the second "call leg" that goes from the agent to the callee.

The secret is adding a new variable to the call, namely qm_queue=xxx where xxx is a unique code for your outbound campaign. You can have as many codes as you want: this way you can log calls as appearing to specific sets of calls instead of being simple "outbound".

So for example to originate a call from user 999 in tenant tenant1.my.srv to number 0012345678 and have it logged as camp1, you could use the following code:

api originate
  {qm_queue=camp1,
   origination_caller_id_number=1973,
   origination_caller_id_name=QM-camp1,
   enable_early_media=true}user/999@tenant1.my.srv 0012345678 XML tenant1.my.srv

A more complex example where you set the DID and different IDs for the agent leg vs the callee leg, could be:

api originate
  {qm_queue=camp1,
   domain_uuid=c42639a1-7536-4d60-8df4-7a6735420c2c,
   domain_name=tenant1.my.srv,
   origination_caller_id_name='Campaign1',
   origination_uuid=c53a59a0-35e9-4d2e-827c-3af089a8e24a,
   outbound_caller_id_name=User_1025,
   outbound_caller_id_number=41771234123,
   origination_caller_id_number=41771234123,
   instant_ringback=true,
   presence_id=1025@tenant1.my.srv,
   call_direction=outbound,
   sip_auto_answer=}user/1025@tenant1.my.srv &transfer('0012345678 XML tenant1.my.srv')"

To view this call, you first have to create a new queue in QueueMetrics. Go to Homepage → Configuration → Queues → "Create new", then set the following fields:

  • Queue alias: "Campaign 1"

  • Queues: camp1 (the same value you set in )

  • Call flow: Outbound

And then run a report for queue "Campaign 1", or select it on a wallboard, in order to start seeing calls.