The data stored in the MCS database from tests being run can be used in various ways. The mechanism for referencing the data is what we call a dollar ($) variable. It allows the user to extract test results for use in things like emails and a web page.
The tutorial will detail the available variables by type and, when applicable, how to use them.
Name | Units | Data Type | Description | Variable |
IP | varchar(128 bit) | The IP address of the client | '%IP%' | |
Time | varchar(256 bit) | The date/time as a GMT String | '%TIME%' | |
Time Int | bigint(20) | The date/time as a number (eg: 20180725140500 for 14:05 on 25-Jul-2018) | %TIMEINT% | |
Time ms | ms | bigint(20) | The time in milliseconds from 1970 (eg: 1668193538367 for Fri Nov 11 2022 19:05:38 UTC 00:00). | %TIMEMS% |
Date/Time | varchar(256 bit) | The date/time that adheres to the SQL DATETIME standard. | '%DATETIME%' | |
Session ID | varchar(256 bit) | The session ID is a custom identifier used to help identify results | '%SID%' | |
DNS Name | varchar(256 bit) | Client's DNS Name | '%DNSNAME%' | |
Test To | varchar(32 bit) | Server test-to address as seen by the client | '%TESTTO%' | |
Country Code | varchar(3 bit) | Country code | '%CC%' | |
ISP | varchar(128 bit) | Client’s ISP name | '%ISP%' | |
Detail Link | varchar(256 bit) | The URL for the detail report | '%DETAILLINK%' | |
Test ID | int | The ID number for a particular group of tests (not unique) | %TESTID% | |
Record ID | int | Record ID # for an individual test (not unique) | %RECORDID% | |
Connection Type | varchar(16 bit) | The type of connection the test was run on (WiFi/Ethernet) | '%CONTYPE%' | |
Proxy State | varchar(1) | If a proxy was detected or not | '%VIAPROXY%' | |
Account ID | int | The ID of the account that ran the test, this will be 0 for public users. | '%ACCID%' | |
Wifi Signal | varchar(8) | The wifi signal strength, if applicable | '%WIFISIG%' | |
Wifi Quality | varchar(1) | The quality of a wifi connection, if applicable | '%WIFIQ%' |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[speed] INSERT INTO global (recordid, testid, timeint, time, datetime, sid, ip, isp, dns, testto, cc, detaillink, contype, proxy) VALUES (%RECORDID%, %TESTID%, %TIMEINT%, %TIME%, '%DATETIME%', '%SID%', '%IP%', '%ISP%', '%DNSNAME%', '%TESTTO%', '%CC%', '%DETAILLINK%', '%CONTYPE%', '%VIAPROXY%');
Name | Units | Data Type | Description | Variable |
Download Speed | bps | Integer (64 bit) | Download speed in bits per second | %ACT.DSPEED% |
Upload Speed | bps | Integer (64 bit) | Upload speed in bits per second | %ACT.USPEED% |
Download Bandwidth | Kbps | Integer (32 bit) | Download Bandwidth in bits per second | %ACT.DPCTKBPS% |
Upload Bandwidth | Kbps | Integer (32 bit) | Upload Bandwidth in bits per second | %ACT.UPCTKBPS% |
Download Percentile | % | Integer (8 bit) | %ACT.DPCTILE% | |
Upload Percentile | % | Integer (8 bit) | %ACT.UPCTILE% | |
QOS | % | Integer (8 bit) | Download Quality/Consistency of Service | %ACT.QOS% |
Upload QOS | % | Integer (8 bit) | Upload Quality/Consistency of Service | %ACT.UQOS% |
Min RTT | ms | Integer (8 bit) | The minimum round trip time | %ACT.RTT% |
Max RTT | % | Integer (8 bit) | The maximum round trip time | %ACT.RTTMAX% |
Average RTT | % | Integer (8 bit) | The average round trip time | %ACT.RTTAVG% |
Max Pause | ms | Integer (8 bit) | The max delay for the connection test | %ACT.MAXPAUSE% |
Up Max Pause | Ms | Integer (8 bit) | Upload Max Pause | %ACT.UMAXPAUSE% |
Max Route Speed | bps | Integer (64 bit) | The maximum achievable speed for the route based on the minimm round trp time | %ACT.MAXROUTESPEED% |
Up Max Route Speed | bps | Integer (64 bit) | The maximum achievable speed for the route based on the minimm round trp time | %ACT.UMAXROUTESPEED% |
Effective Speed | bps | Integer (64 bit) | The maximum effective speed | %ACT.MAXLINESPEED% |
Up Effective Speed | Ms | Integer (64 bit) | Upload Maximum Effective Speed | %ACT.UMAXLINESPEED% |
Max TCP Connections | Float | The maximum amount of TCP connections given the result of the test | %ACT.CONCURRENTTCP% | |
MUp ax TCP Connections | Decimal (32 bit) | Max TCP Connections | %ACT.UCONCURRENTTCP% | |
TCP forced Idle | % | Float | TCP Forced Idle | %ACT.TCPFORCEDIDLE% |
Up TCP Forced Idle | % | Float | Upload TCP Forced Idle | %ACT.UTCPFORCEDIDLE% |
TCP MTU | Integer (8 bit) | Maximum Transmission Unit | %ACT.TCPMTU% | |
Packets not in order | Integer (16 bit) | The number of packets that didn't arrive in order | %ACT.TCPRXPOOO% | |
Bytes not in order | Integer (16 bit) | The number of bytes that didn't arrive in order | %ACT.TCPRXBOOO% | |
Packets not in window | Integer (16 bit) | Packets that arrived outside of the window | %ACT.TCPRXPOW% | |
Bytes not in window | Integer (16 bit) | Bytest that arrived outside of the window | %ACT.TCPRXBOW% | |
Duplicated packets | Integer (16 bit) | Packets that were duplicated | %ACT.TCPRXDOP% | |
Duplicated bytes | Integer (16 bit) | Bytes that were duplicated | %ACT.TCPRXDOB% | |
Part duplicated packets | Integer (16 bit) | Packets that were partially duplicated | %ACT.TCPRXPDP% | |
Part duplicated bytes | Integer (16 bit) | Bytes that were partially duplicated | %ACT.TCPRXPDB% | |
CRC Packet Errors | Integer (16 bit) | CRC Packet Errors | %ACT.TCPRXCRCERR% | |
Bad Packet Offset | Integer (16 bit) | Bad packet offsets | %ACT.TCPRXBOFF% | |
Packets too short | Integer (16 bit) | Packets too short | %ACT.TCPRXTS% | |
Window probes received | Integer (16 bit) | Window probes received | %ACT.TCPRXPROBE% | |
Zero window updates sent | Integer (16 bit) | Zero window updates sent | %ACT.TCPRXWINZEROUP% | |
Bytes lost | Integer (16 bit) | Bytes lost | %ACT.TCPBYTESLOST% | |
Retransmit Timeouts | Integer (16 bit) | Retransmit Timeouts | %ACT.TCPTXRTXTMO% | |
Fast Retransmits | Integer (16 bit) | Fast Retransmits | %ACT.TCPTXRTXFAST% | |
Packets Retransmitted | Integer (16 bit) | Packets Retransmitted | %ACT.TCPTXPRETX% | |
Bytes Retransmitted | Integer (16 bit) | Bytes Retransmitted | %ACT.TCPTXBRETX% | |
Send Window Closed | Integer (16 bit) | Send Window Closed | %ACT.TCPTXSNDWINCLOSE% | |
Pure Window Update | Integer (16 bit) | Pure Window Update | %ACT.TCPTXRCVWINUPD% | |
Ack Too Much | Integer (16 bit) | Acknowledgements for unset packets | %ACT.TCPTXRCVACKTOOMUCH% | |
Duplicate Acknowledgements | Integer (16 bit) | Duplicate Acknowledgements | %ACT.TCPTXRCVDUPACK% | |
Send Probe | Integer (16 bit) | Window Probes Sent | %ACT.TCPTXSNDPROBE% | |
Persist Timeouts | Integer (16 bit) | Persist Timeouts | %ACT.TCPTXPERSISTTIMEO% | |
XL Frames | Integer (32 bit) | XL Frames | %ACT.ETHRXFTL% | |
NA Frames | Integer (32 bit) | NA Frames | %ACT.ETHRXNOAL% | |
Short Frames | Integer (32 bit) | Short Frames | %ACT.ETHRXSF% | |
CRC Errors | Integer (32 bit) | CRC Errors | %ACT.ETHRXCRCERR% | |
Overruns | Integer (32 bit) | Overruns | %ACT.ETHRXOVR% | |
Cut Frames | Integer (32 bit) | Cut Frames | %ACT.ETHRXTRUNC% | |
Download Test Type | Text | Download Test Type | %ACT.DTESTTYPE% | |
Upload Test Type | Text | Upload Test Type | %ACT.UTESTTYPE% | |
Network Downtime | Sec | Integer (32 bit) | Network Downtime | %ACT.NETDOWNSEC% |
Network Uptime | Sec | Integer (32 bit) | Network Uptime | %ACT.NETUPSEC% |
PC Network Downtime | % | Decimal (32 bit) | PC Network Downtime | %ACT.NETDOWNPC% |
HTTP 3xx | Sec | Integer (32 bit) | HTTP 3xx | %ACT.HTTP3XXSEC% |
HTTP 4xx | Sec | Integer (32 bit) | HTTP 4xx | %ACT.HTTP4XXSEC% |
HTTP 5xx | Sec | Integer (32 bit) | HTTP 5xx | %ACT.HTTP5XXSEC% |
HTTP ?xx | Sec | Integer (32 bit) | HTTP ?xx | %ACT.HTTPQXXSEC% |
Firmware Version | Text | Firmware Version | %ACT.VERSION% | |
CPU Up Time | Sec | Integer (64 bit) | CPU Up Time | %ACT.RUNTIME% |
FreeQ | Integer (32 bit) | FreeQ | %ACT.FREEQ% | |
Interface | Text | Ethernet Interface Type (100FD, 100HD etc) | %ACT.INTERFACE% |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[act] INSERT INTO quality (recordid, testid, dspeed, uspeed, qos, rtt, rttmax, rttavg, maxpause, maxroutespeed, maxlinespeed, concurrenttcp, tcpmtu, tcpforcedidle, pooo, booo, pow, bow, dop, dob, pdp, pdb, crcerr, boff, ts, probe, winzeroup, byteslost, rtxtmo, rtxfast, pretx, bretx, sendclose, rcvwinup, acktoomuch, duppack, sndprobe, presisttmo, interface, uqos, umaxpause, umaxlinespeed, uconcurrenttcp, utcpforcedidle, ftl, noal, sf, ethrxcrcerr, ovr, trunc, dtesttype, utesttype, netdown, netup, downpc, http3, http4, http5, httpq, version, runtime, freeq) VALUES (%RECORDID%, %TESTID%, %ACT.DSPEED%, %ACT.USPEED%, %ACT.QOS%, %ACT.RTT%, %ACT.RTTMAX%, %ACT.RTTAVG%, %ACT.MAXPAUSE%, %ACT.MAXROUTESPEED%, %ACT.MAXLINESPEED%, %ACT.CONCURRENTTCP%, %ACT.TCPMTU%, %ACT.TCPFORCEDIDLE%, %ACT.TCPRXPOOO%, %ACT.TCPRXBOOO%, %ACT.TCPRXPOW%, %ACT.TCPRXBOW%, %ACT.TCPRXDOP%, %ACT.TCPRXDOB%, %ACT.TCPRXPDP%, %ACT.TCPRXPDB%, %ACT.TCPRXCRCERR%, %ACT.TCPRXBOFF%, %ACT.TCPRXTS%, %ACT.TCPRXPROBE%, %ACT.TCPRXWINZEROUP%, %ACT.TCPBYTESLOST%, %ACT.TCPTXRTXTMO%, %ACT.TCPTXRTXFAST%, %ACT.TCPTXPRETX%, %ACT.TCPTXBRETX%, %ACT.TCPTXSNDWINCLOSE%, %ACT.TCPTXRCVWINUPD%, %ACT.TCPTXRCVACKTOOMUCH%, %ACT.TCPTXRCVDUPACK%, %ACT.TCPTXSNDPROBE%, %ACT.TCPTXPERSISTTIMEO%, '%ACT.INTERFACE%', %ACT.UQOS%, %ACT.UMAXPAUSE%, %ACT.UMAXLINESPEED%, %ACT.UCONCURRENTTCP%, %ACT.UTCPFORCEDIDLE%, %ACT.ETHRXFTL%, %ACT.ETHRXNOAL%, %ACT.ETHRXSF%, %ACT.ETHRXCRCERR%, %ACT.ETHRXOVR%, %ACT.ETHRXTRUNC%, '%ACT.DTESTTYPE%', '%ACT.UTESTTYPE%', %ACT.NETDOWNSEC%, %ACT.NETUPSEC%, %ACT.NETDOWNPC%, %ACT.HTTP3XXSEC%, %ACT.HTTP4XXSEC%, %ACT.HTTP5XXSEC%, %ACT.HTTPQXXSEC%, '%ACT.VERSION%', %ACT.RUNTIME%, %ACT.FREEQ%);
Below is the CREATE TABLE statement for MySQL.
CREATE TABLE accessct (recordid bigint, testid bigint, dspeed bigint, uspeed bigint, qos int, rtt int, rttmax int, rttavg int, maxpause int, maxroutespeed bigint, maxlinespeed bigint, concurrenttcp float, tcpmtu int, tcpforcedidle float, pooo int, booo int, pow int, bow int, dop int, dob int, pdp int, pdb int, crcerr int, boff int, ts int, probe int, winzeroup int, byteslost int, rtxtmo int, rtxfast int, pretx int, bretx int, sendclose int, rcvwinup int, acktoomuch int, duppack int, sndprobe int, presisttmo int, interface varchar(128), uqos int, umaxpause int, umaxlinespeed bigint, uconcurrenttcp float, utcpforcedidle float, ftl int, noal int, sf int, ethrxcrcerr int, ovr int, trunc int, dtesttype varchar(6), utesttype varchar(6), netdown int, netup int, downpc int, http3 int, http4 int, http5 int, httpq int, version varchar(128), runtime int, freeq int, PRIMARY KEY (recordid));
Name | Units | Data Type | Description | Variable |
Up Jitter | ms | Float | Jitter result for the upstream | %VOIP.JITTER% |
Up Loss | % | Float | Packet loss for the upstream | %VOIP.LOSS% |
Down Jitter | ms | Float | Jitter for the downstream | %VOIP.DJITTER% |
Down Loss | % | Float | Packet loss for the downstream | %VOIP.DLOSS% |
Discards | % | Float | Prcentage of packets discarded by protocol | %VOIP.DISCARDS% |
Order | % | Float | Ordering percentage (metric showing how well ordered the packets were) | %VOIP.ORDER% |
RTT Minimum | ms | Int (8 bit) | Minimum RTT (Round trip time) | %VOIP.RTTMIN% |
RTT Average | ms | Int (8 bit) | Average RTT (Round trip time) | %VOIP.RTTAVG% |
RTT Maximum | ms | Int (8 bit) | Maximum RTT (Round trip time) | %VOIP.RTTMAX% |
RTT Consistency | % | Float | RTT (Round trip time) consistency | %VOIP.RTTCONSISTENCY% |
SIP Register | ms | Int (8 bit) | Time taken to perform SIP REGISTER | %VOIP.REGISTER% |
SIP Invite | ms | Int (8 bit) | Time taken to perform SIP INVITE | %VOIP.INVITE% |
SIP Bye | ms | Int (8 bit) | Time taken to perform SIP BYE | %VOIP.BYE% |
SIP ALG | String | Varchar (8 bit) | SIP Application Layer Gateway detected | %VOIP.SIPALGFW% |
Up Distribution Loss | % | Float | Upstream distribution loss | %VOIP.UPDISTLOSS% |
Down Distribution Loss | % | Float | Upstream distribution loss | %VOIP.DOWNDISTLOSS% |
Up Max Jitter | ms | Float | Maximum recorded jitter during the upstream | %VOIP.MAXJITTER% |
Down Max Jitter | ms | Float | Maximum recorded jitter during the downstream | %VOIP.DMAXJITTER% |
Up MOS | - | Float | MOS score for the upstream | %VOIP.MOS% |
Down MOS | - | Float | MOS score for the downstream | %VOIP.DMOS% |
Lines | - | Int | Number of lines simulated for the test | %VOIP.LINES% |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[voip] INSERT INTO myvoip (recordid, testid, jitter, loss, djitter, dloss, discards, pktorder, rttmin, rttavg, rttmax, rttcon, reg, inv, bye, sipalg, updist, downdist, maxjit, dmaxjit, mos, dmos, simlines) VALUES (%RECORDID%, %TESTID%, %VOIP.JITTER%, %VOIP.LOSS%, %VOIP.DJITTER%, %VOIP.DLOSS%, %VOIP.DISCARDS%, %VOIP.ORDER%, %VOIP.RTTMIN%, %VOIP.RTTAVG%, %VOIP.RTTMAX%, %VOIP.RTTCONSISTENCY%, %VOIP.REGISTER%, %VOIP.INVITE%, %VOIP.BYE%, '%VOIP.SIPALGFW%', %VOIP.UPDISTLOSS%, %VOIP.DOWNDISTLOSS%, %VOIP.MAXJITTER%, %VOIP.DMAXJITTER%, %VOIP.MOS%, %VOIP.DMOS%, %VOIP.LINES%);
Below is the CREATE TABLE statement for MySQL.
CREATE TABLE myvoip (recordid int, testid int, jitter float, loss float, djitter float, dloss float, discards float, pktorder float, rttmin int, rttavg int, rttmax int, rttcon float, reg int, inv int, bye int, sipalg varchar(8), updist float, downdist float, maxjit float, dmaxjit float, mos float, dmos float, simlines int);
Name | Units | Data Type | Description | Variable |
Max Route Response (client to server) |
ms | SMALLINT | Maximum response time for the route | %ROUTE.MAXMS% |
Max Route Response (server to client) |
ms | SMALLINT | Maximum response time for the route | %ROUTE.MAXMS% |
Target Packet Loss (client to server) |
% | TINYINT | Packet loss to target | %ROUTE.ENDLOSS% |
Target Packet Loss (server to client) |
% | TINYINT | Packet loss to target | %ROUTE.ENDLOSS% |
Target Average Response (client to server) |
ms | SMALLINT | Average response time to target | %ROUTE.ENDMS% |
Target Average Response (server to client) |
ms | SMALLINT | Average response time to target | %ROUTE.ENDMS% |
Target IP (client to server) |
Varchar(128) | The target IP address | %ROUTE.IPTO% | |
Target IP (server to client) |
Varchar(128) | The target IP address | %ROUTE.IPTO% | |
Hops to target (client to server) |
SMALLINT | Total number of hops in route | %ROUTE.HOPS% | |
Hops to target (server to client) |
SMALLINT | Total number of hops in route | %ROUTE.HOPS% | |
Source IP (client to server) |
Varchar(128) | The IP address the route originated from | %ROUTE.IPFROM% | |
Source IP (server to client) |
Varchar(128) | The IP address the route originated from | %ROUTE.IPFROM% | |
Route target name | Varchar(128) | The name of the trace route target | %ROUTE.ENTEREDNAME% | |
DNS Response | ms | SMALLINT | The DNS response time for the target | %ROUTE.DNSTIME% |
Max Route Loss | % | TINYINT | Maximum loss recorded for all hops over the route | %ROUTE.MAXLOSS% |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[route] INSERT INTO myroute (recordid, testid, traceto, totalhops, targetms, maxms, targetloss, maxloss, dnstime, targetip, tracefrom) VALUES (%RECORDID%, %TESTID%, '%ROUTE.ENTEREDNAME%', %ROUTE.HOPS%, %ROUTE.ENDMS%, %ROUTE.MAXMS%, %ROUTE.ENDLOSS%, %ROUTE.MAXLOSS%, %ROUTE.DNSTIME%, '%ROUTE.IPTO%', '%ROUTE.IPFROM%');
Below is the CREATE TABLE statement for MySQL.
CREATE TABLE myroute (recordid int, testid int, traceto varchar(128), totalhops tinyint, targetms smallint, maxms smallint, targetloss smallint, maxloss smallint, dnstime smallint, targetip varchar(128), tracefrom varchar(128));
When running a bi-directional route test MCS will export one record for each direction. So, in the SQL table there will be a row for client-to-server and a row for server-to-client.
Name | Units | Data Type | Description | Variable |
Downstream Capacity | bits | BIGINT | The download capacity result | %CAPACITY.DCAPACITY% |
Upstream Capacity | bits | BIGINT | The upload capacity result | %CAPACITY.UCAPACITY% |
Downstream Packets | bits | INT | The packet rate achieved for the download result | %CAPACITY.DPACKETS% |
Upstream Packets | bits | INT | The packet rate achieved for the upload result | %CAPACITY.UCPACKETS% |
Downstream Limit | bits | BIGINT | The upper limit that was configured for the test | %CAPACITY.DMAXBANDWIDTH% |
Upstream Limit | bits | BIGINT | The upper limit that was configured for the test | %CAPACITY.UMAXBANDWIDTH% |
Packet Size | Bytes | INT | The packet size used for the test | %CAPACITY.PACKETSIZE% |
Consistency of Service | % | TINYINT | The consistency of service percentage | %CAPACITY.QOS% |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[capacity] INSERT INTO capacity (recordid, testid, dcap, ucap, dlimit, ulimit, dpkt, upkt, pktsize, cos) VALUES (%RECORDID%, %TESTID%, %CAPACITY.DCAPACITY%, %CAPACITY.UCAPACITY%, %CAPACITY.DMAXBANDWIDTH%, %CAPACITY.UMAXBANDWIDTH%, %CAPACITY.DPACKETS%, %CAPACITY.UPACKETS%, %CAPACITY.PACKETSIZE%, %CAPACITY.QOS%);
Below is the CREATE TABLE statement for MySQL.
CREATE TABLE capacity (recordid int, testid int, dcap bigint, ucap bigint, dlimit bigint, ulimit bigint, dpkt int, upkt int, pktsize int, cos tinyint);
Name | Units | Data Type | Description | Variable |
Firewall Record Id | - | - | A delimitted string of the record IDs for each port/port group. | See Global (above) |
Ports tested | - | - | An array of the port/port groups that were tested. | %FIREWALL.PORTS% |
Port protocol | - | - | An array of the protocol for the tested ports (UDP, TCP) | %FIREWALL.PROTOCOL% |
Average response | ms | Float | The average response time for testing the port availability | %FIREWALL.AVGRESPONSE% |
Minimum response | ms | SMALLINT | The minimum response time for testing the port availability | %FIREWALL.MINRESPONSE% |
Maximum response | ms | SMALLINT | The maximum response time for testing the port availability | %FIREWALL.MAXRESPONSE% |
Open ports | - | INT | A count of how many ports were open. | %FIREWALL.POPEN% |
Blocked ports | - | INT | A count of how many ports were blocked. | %FIREWALL.PBLOCK% |
Total open ports | - | INT | A count of how many ports were open for the entire test. | %FIREWALL.TPOPEN% |
Total blocked ports | - | INT | A count of how many ports were blocked for the entire test. | %FIREWALL.TPBLOCK% |
SQL Example
To use the SQL variables above create an SQL profile as shown below.
The SQL statment shown below must match the SQL table. The column types are shown above.
[firewall] INSERT INTO myfirewall (recordid, testid, avgres, minres, maxres, port, protocol, popen, pblock, tpopen, tpblock) VALUES (%RECORDID%, %TESTID%, %FIREWALL.AVGRESPONSE%, %FIREWALL.MINRESPONSE%, %FIREWALL.MAXRESPONSE%, '%FIREWALL.PORTS%', '%FIREWALL.PROTOCOL%', %FIREWALL.POPEN%, %FIREWALL.PBLOCK%, %FIREWALL.TPOPEN%, %FIREWALL.TPBLOCK%);
Below is the CREATE TABLE statement for MySQL.
CREATE TABLE myfirewall (recordid int, testid int, avgres float, minres smallint, maxres smallint, port varchar(16), protocol varchar(8), popen int, pblock int, tpopen int, tpblock int);