The StatS subsystem allows us to calculate statistics based on CGrateS events.

Each StatS object contains one or more “metrics” which are things like Average call duration, Total call duration, Average call cost or totals and average of other fields.

The first thing we’ll need to do is enable stats in our JSON config file:

"stats": {
	"enabled": true,
	"string_indexed_fields": ["*req.Account","*req.RunID","*req.Destination"],
},

With that done we’re ready to create our first StatS entry, this one is pretty much a burger-with-the-lot, so let’s take a look:

{
    "method": "APIerSv1.SetStatQueueProfile",
    "params": [
        {
            "ID" : "StatQueueProfile_VoiceStats",
            "QueueLength": 10000000,
            "TTL": -1,
            "MinItems": 0,
            "FilterIDs": [],
            "Metrics": [
                {"FilterIDs": [],"MetricID": "*tcd"},
                {"FilterIDs": [],"MetricID": "*tcc"},
                {"FilterIDs": [],"MetricID": "*asr"},
                {"FilterIDs": [],"MetricID": "*acd"},
                {"FilterIDs": [],"MetricID": "*ddc"}
            ],
            "Stored": True,
        }
    ]
}

So what have we just done?

Well we’ve created a StatQueueProfile named StatQueueProfile_VoiceStats, in which we’ll store a maximum of 10000000 datapoints (this is important because to calculate an average we need to know all the previous datapoints), for a maximum of forever (Because TTL is -1, if we wanted to store for 1 hour we’d set TTL to 1h.

We’re not matching any FilterIDs, but based on what we covered on the post in FilterS, you can imagine using this to match calls from a given Account / customer, or to a specific group of destinations, or maybe from a given supplier, etc, etc.

What we do have that’s interesting is we have defined a series of metrics.

The docs page of CGrateS explains all the available metrics and what they mean (we’ve also mapped them in the CGrateS UI), but the ones I’ve included above are Total Call Duration (*tcd), Total Call Cost (*tcc), Answer Seizure Ratio (*asr), Average Call Duration (*acd) and Distinct Destination Count (*ddc).

So what happens if we now generate a bunch of calls? Well, for starters as we’ve got no FilterS defined here, every call will match this StatQueueProfile, and so we’ll collect data for each.

The example code I’ve provided in the repo for this post generates a bunch of calls, and we can check the values for all our Metrics with GetQueueStringMetrics for our :

{'method': 'StatSv1.GetQueueStringMetrics', 'params': [{'Tenant': '', 'ID': 'StatQueueProfile_TalkTime', 'APIOpts': {}}], 'id': 11}
{'error': None,
 'id': 11,
 'result': {'*acd': '8m4.4s',
            '*asr': '100%',
            '*ddc': '50',
            '*tcc': '5396',
            '*tcd': '6h43m40s'}}

We can now see the values of each metric.

If we’ve got a TTL set, old values that have existed in the QueueProfile longer than the TTL are removed, but we can also manually clear the values by using the ResetStatQueue endpoint:

{"method":"StatSv1.ResetStatQueue","params":[{"Tenant":"cgrates.org","ID":"StatQueueProfile_TalkTime"}],"id":4}

Which resets all the values back to zero / null.

One thing to keep in mind is you can’t modify a StatQueue object via the API without resetting the values.

string_indexed_fields in the config file

Sidebar on this – By specifying the string_indexed_fields means that CGrateS will not evaluate every field against Filter rules, but instead only those defined here. This means if you’ve got an event with say 20 fields (AnswerTime, Account, Subject, Destination, RunID, SetupTime, Extra Fields, etc, etc) each of these gets evaluated against a filter, which is pretty processor intensive if your FilterS only ever look at Account and Destination, so by specifying which fields are indexed here to only the fields you use in your filters, you can boost your performance. On the flip side, you can leave this blank to evaluate all fields, but you’ll take a performance hit by doing so.