Logging in software is usually a good thing. It’s often used to output useful information and/or statistics relevant to a current software task. However, everything comes with a cost, and logging is no exception. Excessive logging slows a system down. As well “information overload” can actually confuse a situation and complicate things.

Like any good software system Asterisk tries to maximize the good while minimizing the bad with regards to its logging facilities. It manages this by offering various kinds of logging sub-systems, and channels for log output. Additionally, these components are usually configurable in some way to allow for more or less data output, or complete disabling.

Debug logging, though, is at least one resource in Asterisk that can sometimes be burdensome. Often enabled by developers to track down a problem, debug output can slow a system down (potentially effecting timing), and quickly fill storage. While Asterisk allows for “levels” to help mitigate these problems, over time some of the levels themselves have grown to output an abundance of information. And more often than not a large portion of that information is superfluous to the current debugging task.

Debug Logging Categories

To help alleviate this problem, starting with Asterisk 16.15.0 and 18.1.0, you can enable/disable, and log debug information according to specified categories. Debug logging categories allow the user to limit, and filter debug output to data relevant to a particular context, or topic. For instance the following categories are now available in Asterisk for debug logging purposes:

dtls, dtls_packet, ice, rtcp, rtcp_packet, rtp, rtp_packet, stun, stun_packet

These debug categories can be enable/disable via new Asterisk CLI commands:

• core set debug category <category>[:<sublevel>] [category[:<sublevel] …]
• core set debug category off [<category> [<category>] …]

These commands permit multiple categories to be enabled/disabled at once. When enabling, an optional sub-level can also be specified. If given, then only those statements assigned a value at or below the associated sub-level are output. If no sub-level is assigned then all debug statements for a given category are output regardless of its level.

You may note that for some things Asterisk kind of already had a way to enable debug for a category (e.g. RTP packet level debug). While those commands to do such still exist in Asterisk, this new framework both consolidates those features, and makes it easier to add new categories.

Examples

I’m sure a few specific examples will be helpful. Let’s say you’re having a issue with RTP in Asterisk, and you feel like debug logging could help. Historically you could only do something like the following:

*CLI> core set debug 5

This of course can output RTP debug information, but it’ll also output a lot of irrelevant data. Instead with logging categories you can now do something like the following:

*CLI> core set debug category rtp

That should now only output debug information related to RTP. Still too much?

*CLI> core set debug category rtp:3

That’ll only output RTP debugging information on log statements marked for RTP debug level 3 and above. If you need to add in more context, say ICE debug then that can also be added:

*CLI> core set debug category ice

Or if you knew that from the start then:

*CLI> core set debug category rtp ice

Or level 3 or greater RTP debug, and all ICE debug:

*CLI> core set debug category rtp:3 ice

Want to turn ICE off now:

*CLI> core set debug category off ice

Or to turn off/disable all categories simply:

*CLI> core set debug category off

Final Thoughts

Asterisk continues to advance in many ways including it’s various logging facilities. Be sure to check out other recent logging improvements too.

For those wishing to add new, or more categories the API should make it simple to do so. As well, while logging categories are currently only available for debugging, the underlying framework that’s been built should make it easy enough to add it in for other sub-systems if the need arises.

Hopefully you now have a new tool to use to help you debug, and collect better and targeted information for your issue(s).