Depending on your Linux distribution, you need to run different commands in order to install the required minimal dependencies.

Some older distributions do not ship Java 25 in their repositories. On those systems (marked Adoptium in the table below), you first need to add the Eclipse Adoptium repository, which provides the Temurin JDK packages, by following the instructions at https://adoptium.net/installation/linux. Then run the install command shown for your distribution.

Remember that the server must have internet access for license validation and API calls.

The default installer sets QM up with one gigabyte of heap memory, enough for all but the largest systems, but it can be reduced (see below) to fit on smaller servers.

Just run this one command as root:

And…​ that’s it!

The script performs the following steps:

Once the installation completes, open a browser and navigate to:

Log in with the default credentials: username demoadmin, password demo.

After verifying that QueueMetrics is running, install Uniloader on the PBX server to begin uploading call data (see section Configuring QueueMetrics).

If the server does not seem to be up after a couple of seconds, type:

To see what is happening.

QueueMetrics ships with an embedded demo license that lets you activate and try the product immediately. To install a full license key:

Set the QM_LICENSE_KEY parameter to the license key you received:

Restart the service for the change to take effect:

All configuration for QueueMetrics standalone is managed through a single file:

This file controls network settings, database connection, logging, Java memory allocation, and other runtime options. The file is well-commented and each parameter is explained inline.

The most commonly adjusted settings are:

After changing any parameter, restart the service:

To upgrade QueueMetrics, download the new version archive and repeat the installation procedure described above. Make a backup before upgrading (see Backing up).

The install script preserves your existing configuration file at /etc/default/queuemetrics. The database schema is updated automatically on the first run of the new version.

To create a complete backup of your QueueMetrics installation:

Store both files in a safe location. These two items are sufficient to restore your QueueMetrics installation on a new server.

A more detailed explanation is available at Backing up QueueMetrics.

The queuemetrics-cli tool is a convenience command-line utility installed to /usr/bin during setup. It provides quick access to common service management tasks, so you don’t have to remember them and will ask for sudo privileges when needed.

Usage:

Available commands:

Examples:

Suppose you are updating a system that was originally installed from the RPM package (via yum), and that this system:

Moving to the standalone version requires following the procedure below. The advantage of the standalone version is that it does not depend on a specific package manager and works on any modern Linux distribution.

When running QueueMetrics under Docker, the easiest way is to use the Install new license key page.

If you prefer, the license key can be passed in from the outside as an environment variable, using the -e flag of docker run, when starting the container:

The license key only needs to be specified once: it is written to the instance’s persistent data, so it does not need to be passed again on later restarts.

For the full list of environment variables that can be passed to a QueueMetrics Docker instance, see Configuring license, memory, time zones and more.

In order to do an upgrade, you must have started the original instance using a data volume or a shared folder.

If you did, you first download the new QueueMetrics image, then you stop (and remove) the current version and then run the image again using the same data folder:

At this point, it will just work.

Please note that system logs, the compilation cache and everything else that is not in your persistent data folder will be deleted.

The historical RPM-based installation of QueueMetrics is no longer supported. This is because many PBX distributions are no longer based on RHEL and its derivatives, and moving to a single standalone install script lets us support a much wider range of operating systems with the same procedure.

On the PBX system, edit the file /etc/sysconfig/uniloader; you need to set the following values in order to tell Uniloader to work with the local QueueMetrics database:

If you’re running a PBX server cluster you also have to modify the TOKEN value, giving to each of them a different partition name (usually P001, P002, P003, etc). This is fundamental to avoid any possible concurrent writing issue.

Now restart Uniloader:

If Uniloader is on a different machine than QueueMetrics (and MySQL) you will need to create a new database user able to connect remotely.

Log in where MySQL is as root:

One you’re in create a new remote user and give it all grants on the queuemetrics database:

and then set the correct database in the URI parameter of Uniloader.

If you have a single PBX server and have not modified the TOKEN value in the Uniloader configuration add (or, if exists, modify), in the configuration properties, the following values:

QueueMetrics is now already able to retrieve information from the PBX.
Instead, if you have a server cluster add or modify these values as follows:

Now, to enable QueueMetrics to place calls and log the agents on and off the queues you need to include the QueueMetrics dialplan in Asterisk. If you installed QueueMetrics with yum, you can find it in /usr/local/queuemetrics/qm-current/WEB-INF/mysql-utils/extensions-examples/extensions_queuemetrics_18.conf.

Copy the file under /etc/asterisk/ then add the following line at the end of your extensions.conf, or extensions_custom.conf if your PBX has this file:

Then open the Asterisk CLI and reload the dialplan:

QueueMetrics runs as the queuemetrics user (group queuemetrics), while call recordings on the PBX are usually owned by the PBX’s own user and group; QueueMetrics cannot read them by default, and click-and-listen will fail.

The simplest fix is to add the queuemetrics user to the PBX’s group, so that it inherits read access to the recordings without changing any file permission.

The example below is for Asterisk, but the same reasoning applies to any PBX, including FreeSWITCH: identify the user/group the PBX process runs as, and the group that owns the recordings directory, then add queuemetrics to that group.

To find the right group, run the following diagnostic commands and compare their output:

If all three outputs agree on the same group, that is the group to use. If they disagree, trust the value in asterisk.conf, as that is what actually determines the group the process will run as on the next restart.

Once you know the group, add queuemetrics to it:

Group membership changes only apply to new processes, so restart QueueMetrics for the change to take effect:

QueueMetrics has some test tools to check if all is running the right way and for troubleshooting.
The System Diagnostic Tools page offers a number of tools that check database and AMI connections and more (see Troubleshooting).

To check that everything works you can open your browser and point it to http://hostname:8080/queuemetrics, the first time you run it you might get an error, it will disappear in a few seconds and QueueMetrics will guide you through the database configuration; probably you’ll just need to confirm without making any change.
After that you will be able to log in with the default username demoadmin and password demo.
Obviously, at the moment, no data is shown.

To understand QueueMetrics' memory needs, you must consider that the memory requirements are roughly proportional to the width of the analysis and to the number of required events to track. You may think of it as the number of calls plus the number of agent events, i.e. agents logging on and off and setting pauses on and off.

Calls can be restricted by the queue filter, but all agent events in the required time window are tracked. This gives you an idea of the memory usage.

Though the actual memory requirements depend considerably on the actual content of your analysis and the exact brand and version of Java virtual machine that you are running, you should expect to be possible to track about 80,000 calls and 40,000 agent events with a standard 64 megabyte Java VM and Tomcat running.

You can of course start your servlet container with more memory in order to allow more room for larger analyses. See Further Configuration.

Consider also that Java will never return this memory to the system free memory pool, even when it stops using it. The only way to have this memory returned to the system memory pool is to stop the Java VM and restart it. Therefore, it’s a good idea to perform a scheduled restart of the servlet container, to avoid possible memory leaks and to reclaim now-unused memory to the main pool.

As a last note, the memory footprint of a Java VM may be quite larger than the memory you give it as Java heap space, as it will need RAM space for the VM itself and all its required libraries. Overheads of 100-200 megabytes are not unheard of, depending on the Java Virtual Machine in use.

A more in-depth discussion of QueueMetrics memory usage and live monitoring can be found on the "Advanced Configuration Manual", chapter "Tuning QueueMetrics memory settings".

A real-life example for a large call-center with about 400 agents logged on and running on a dedicated server may be like:

But the actual optimal configuration on a large system should be determined by running the system for a while under the required workload and monitoring the actual resource consumption.

Each user accessing QM should have his own user and password. The administrator can easily setup multiple accounts from the administrative interface. All user activity is tagged to the user performing it, so it’s a good idea to give an account to each person accessing the system. Accounts can be created, blocked and revoked in a matter of minutes.

Each feature that QM offers is enabled by a special key, as if there was a padlock protecting it from unauthorized access. The administrator gives each user a key ring that specifies which locks the user can open, and therefore what the user can do. A list of keys used in QM is available in Appendix A: Security keys.

To ease the burden of administering multiple users, keys can be grouped into classes. Each class offers the additional advantage of giving the key ring a label, so that it’s easier to see whether a user is an Administrator, a User or an Agent by looking at the label and not at the very keys s/he holds.

Individual keys can be granted or revoked individually to handle special cases, in addition to the ones anyway present in the user’s class. For more information, see Editing QueueMetrics settings.

A list of default users provided with the standard QM installation and their default passwords can be found in Default users.

Just to be on the safe side, QueueMetrics keeps an 'Audit Log' of all activities that may have security implications; see The Audit log for more details.

Often this is a firewall problem. First of all, check if QueueMetrics is running:

If it returns something then QueueMetrics is running; if so, do try temporarily stopping the firewall:

Now retry pointing your browser to http://hostname:8080/queuemetrics.

If it works now, you should setup your firewall in order to accept incoming connections to port 8080.

See Configuring system preferences.

QueueMetrics has some tools that help you to solve most of the possible issues.
You can find them clicking on System Diagnostic Tools or pointing your browser to http://hostname:8080/queuemetrics/dbtest/.

You can have a full description in chapter Using the DbTest Diagnostic Tools.

QueueMetrics needs to establish direct HTTP outbound connections:

If such connections are unavailable, then QM will not even start up (the Java process will start, but the GUI won’t become available).

As in some corporate environment, direct outbound connections are not possible, so you need to use an intermediate proxy.

The JVM has a standard way to set up HTTP proxies, by setting the JVM properties:

In the example above, you tell QM to use a proxy located at address 10.10.1.1 on port 8888 that handles both HTTP and HTTPS traffic.

Or, to set up a SOCKS proxy:

You will need both HTTP and HTTPS proxy access, as license validation happens over HTTPS.

To check whether connectivity is working correctly, you can use a script called checkLicenseConnectivity.sh that can be found under WEB-INF/README/.

For example, to check connectivity with no proxy, you would simply run:

While to attempt using a SOCKS proxy, you could for example try:

Sometimes, the database will refuse to use an existing index. This may happen if the index file is broken (e.g. full disk, unclean shutdown, crashed tables) - though sometimes this happens for no apparent reason.

You will notice that operations take a lot more to complete - a report that took a second or two starts taking a few minutes to run - and that all the load in on MySQL/MariaDB and/or disk access.

The easiest way to solve the issue, if you are not a MySQL/MariaDB expert, is to:

E.g.

Make sure that you have enough disk space for the backup to complete successfully, and run this off-hours, as a very large database might take hours to backup and rebuild.

QueueMetrics is licensed based on:

You need an agent for each separate agent entity you want to keep track of - so if you have two shifts of 20 persons each, you need 40 agents total, no matter how many of them are logged in at once. If your agents change over time and you want to keep track of both present and past ones each using a different code for each, you will have to factor that in as well. So, for most call centers, you will need something that matches the number of paychecks you write every month for call-center agents.

QueueMetrics natively tracks only calls on queues, so any entity that is not answering a queue (or taking part in an outbound campaigns) is not counted. If you use automated outbound tracking, all phones will be tracked and so every one of them will be counted as one agent.

You will need a cluster license if you want to track multiple PBXs at once - whether this happens because you want to view multiple PBXs from the same GUI (e.g. different branches, or different countries) or because you have a high-availability system where calls may be processed in multiple locations. Vanilla QM licenses let you track only one PBX, but it’s possible to have more when ordering the license. See Monitoring clusters with QueueMetrics for further information on clusters.

Each license has a specified expiry date, that is set at creation and cannot be altered. After a license is expired, the system displays an error message and becomes unavailable. Before this happens, it displays a message to remind you when the license is almost expired.

If you need to install multiple QM systems, you will need to order a separate key for each system. For the common case where you have a stand-by system for high availability, you may order it together with its master key and it has a special price.

Log on to QueueMetrics as "demoadmin" and click on the License page, if you have the correct grants you should see a label called "Install new license key"; click on it.

Copy the activation code you received by e-mail into the license box and press "Install". The system will restart in a few seconds (you may see a blank page - if you do, just try and reload). Log off an on again. On the License page you should see the new key.

As an alternative, you can set the license in the configuration file. The former method (GUI) is easier if you manage the system yourself; the latter is better if you manage a fleet of QueueMetrics servers. To install a license through the configuration file:

QueueMetrics will notify users on the Home Page when the license is about to expire; this helps preventing downtime in case a license actually expires without renewal.

To set up a cluster, you should define the following configuration variables in configuration properties:

cluster.servers=aleph|trix

This statement tells QM that the current cluster has two members, that are called "aleph" and "trix". We suggest using a short name for each server, as it will appear in many different screenshots. One option would be using the capital letters, like ""A", "B", "C" etc for different members of the cluster.

For each server (in our case "aleph", but we’ll have to repeat it for all members of the cluster), we will define the following properties:

cluster.aleph.manager=tcp:user:pass@10.10.3.5

This tells QueueMetrics that the manager interface for aleph can be found at 10.10.3.5, logging in as "user" with password "pass". The manager interface is needed to run Live monitoring and can be used to run commands to Asterisk (like logging agents on and off, starting chanspy sessions, etc).

cluster.aleph.queuelog=sql:P001

This tells QM that the queue_log file (or its contents) can be downloaded from partition P001 of the QM database. You must use MySQL storage in order for clustering to work at all.

cluster.aleph.monitored_calls=/share/aleph/calls/

This tells QM where to look for recorded calls on each PBX server. This is used by QueueMetrics in order to click-and-listen to recorded calls. A NFS or SMB share is usually a good starting point. As an alternative, you can enter the URL of an XML-RPC server that will return information about the recorded call (for more information on this topic, see Enabling XML-RPC call listening and streaming).

cluster.aleph.callfilesdir=/share/aleph/callfiles/

If you do not want to connect to your PBX servers using the manager interface, you still need a way to send it commands (e.g. to start a chanspy session). In order to do this, you should give QM a directory to write callfiles to. If you use the manager interface, leave this entry blank. (We strongly suggest doing so and using the manager interface instead).

cluster.aleph.audioRpcServer=http://myserver/xmlRpcServer

If you use an XML-RPC "broker" in order to used live calls listening using a third-party software like Orecx, you should enter its URL here. This must be activated at once for all servers by not leaving blank in the property default.audioRpcServer. In all other cases, just leave this property blank. (for more information on this topic, see Enabling XML-RPC call listening and streaming).

cluster.aleph.agentSecurityKey=AAA

When using the agent’s page in cluster mode, you must make sure that each agent "points" to the correct server, as this server will be used for both pulling agent’s data and sending logon/logoff commands. This is obtained on the agent’s page through a pull-down menu where the agent must select the correct server he’s logged on to. In order to avoid mistakes, it is possible to protect a server by adding a security key, so that only agents having that security key will see that server. If an agent has only one possible server, that server will be automatically selected. In practice, this means that you could create two agent classes, we call them AGENT_A and AGENT_B. They have the same keys, but in class AGENT_A there is the key SERVER_A, and in the other SERVER_B. We protect each server entry with SERVER_A for the first and SERVER_B for the other. Then we assign users to classes AGENT_A (for agents working on the first server) and AGENT_B (for agents working on the second server). If you want agents to manually switch servers, or your cluster is made up of only one machine, leave this blank.

On each box that is a member of the cluster, you should set up the following items:

First thing, you should make sure that you have a clustered license for QueueMetrics and that your license is big enough in terms of agents to support all agents that are present in the call-center. Older licenses are valid for one PBX server only and QueueMetrics will complain they are not correct.

To report on all members of a cluster, you should set the property:

default.queue_log_file=cluster:*

This means that all boxes defined as members of this cluster will be used as a data source.

To report on a subset of the members of the cluster, you will use a syntax like:

default.queue_log_file=cluster:A|B|C

This way you will be reporting on boxes A, B and C.

If you want to report only on a single box, the syntax:

default.queue_log_file=cluster:C

Will be appropriate.

You can then change this property on-the-fly by going to the report page and editing as needed under the report’s settings.

If you have agents using QueueMetrics’s Agent’s pages, you should set them up so that each agents points to its correct server.

The agent’s page on QueueMetrics acts as a kind of portal for an agent; she can use it to log on, log off, go to pause, enter pause codes, launch external apps linked to a call (e.g. CRM apps) and enter call codes (see The real-time agent page).

As the number of agents can be very high if compared to the number of supervisors who run reports or monitor the call center, QM uses a "minimal impact" policy: the page must be refreshed manually by each agent in order to avoid hammering the server with repeated page hits and the analysis run is a stripped-down, low-fat version of the full analysis QueueMetrics is able to perform. When coming to clusters, this means that to avoid useless load, calls for an agent will be searched only on the server the agent is working on and not on the entire cluster.

Also, we have the problem of defining where an agent is supposed to work: as QM can issue commands to the PBX on behalf of an agent, it needs to know to which PBX server those commands must go. This is obtained by using the Server selection that will appear on the agent’s page if QueueMetrics is running in clustered mode. If more than one server is selectable, the combo box will let the agent switch server as she best sees fit (if only one server is selectable, QueueMetrics will use that server immediately and will make the combo locked).

As a QM installer, you can control which servers are selectable to which agents by setting the properties cluster.---.agentSecurityKey correctly for each PBX server in the cluster.

When working on a clustered environment, an agent is allowed to access only one server at a time. The server selection is usually done through the Agent Logon Panel, where you choose the queues to log on to, the server to use and the agent extension.

the first time an agent logs into the Icon Agent’s Page though, a special panel will appear that will ask the agent for the preferred server. This can be changed later on from the Agent Logon Panel.

There are some rules that QueueMetrics enforces, that must be understood:

To sum it up, an agent will be able to choose a server only if three conditions are met: