Advanced Search Filters

As we allude to in several other places (notably, in 4.4 interface changes and in performance notes), there’s a whole world of searching that our app provides beyond what’s apparent in the interface.

What are we talking about?

This field, right here.

It’s a pretty awesome field and lets you do pretty much any sort of customized searching that you need.

Note that search filters use an implicit AND between them and that you have to parenthesize whenever you get mixed AND and ORs together. You can read more about these two situations down at the bottom, along with some notes on NOT and !=.

Important note, ​“legs” vs. ​“calls”

Be aware that most of the fields you use in here are actually ​“leg” fields, not ​“call” fields. There really are no fields that are ​“call” fields, except a very few that we create in the app.

This is a subtle but important thing: multiple legs make up a call and these searches will return any call with one or more legs having the values for the fields you are searching on.

For instance suppose you want to find where folks hung up on voicemail in less than 5 seconds. If you search duration<=5 device_type="unityvm", you will get any call where at least one leg was short-duration and where at some point they bounced through voicemail, but those two things may not have been in the same leg. Perhaps they got simply got an ​“Please hold” and placed on hold right away for that short duration, but then went to voicemail and left a reasonably long message.

But have no fear – there IS a way to do this!

Searching for a single leg that has two or more characteristics is exactly what leg_​types are for. They operate directly on legs, one at a time, and ​‘tag’ each leg with a type or ​“name” that you want. For instance, we could tag legs that match this: duration<=5 device_type="unityvm" with a leg_​type of ​“hung_​up_​on_​voicemail”. Then in the browse calls (or on general report) you can search for leg_type="hung_up_on_voicemail"

If you need this, then you’ll want to visit using leg types which covers this exact example and others like it.

On to the fun parts! What fields can I use?

Any field you want to.

But having said that, there are a few fields we find show up time and time again as useful for a lot of people. We go over many of those below in the use cases.

By the way, did you know that if you don’t know what a particular field is, does, or is for, you can poke at it in the field gallery at the bottom of the App’s Home page to find out!

Also, I’d recommend adding any fields you want to use to the selected fields using the field picker. It’s really hard to debug logic when you can’t see the values of the fields you are trying to filter on.

Use Case #1 – Quality

Add fields quality, MLQK, and jitter to your field list. Note you might want to take out some extra fields you don’t need if your screen is getting crowded. (MLQK, if you haven’t looked it up in the field gallery yet, is the MOS score of the last 8 seconds of the call – below perhaps 3 and the call was garbled in the last few seconds, above 4 and the call was decent, with 3 – 4 being that grey area).

To show only calls with low MLQK (but to get rid of all those Cisco says have an MLQK of zero, which isn’t really valid), simply add into search filters MLQK>0 MLQK<4.

If you think you have something interesting, you can always click the “» graph calls over time” link in the upper right and go straight to a report with those search filters already filled in.

Use Case #2 – OMG, the Boss is gonna yell at me!

Those dreaded words: ​“No circuit/​channel available”. Uh oh. We’ve run out of channels somewhere, calls aren’t being completed!

Well, luckily we make it easy to find those!

cause_description="No circuit/channel available"

Use Case #3 – What about all those other failed calls?

There are lots of reasons for a call to fail other than ​“No circuit/​channel available”. Of course, unassigned numbers or busy users aren’t really errors we care about, so we’ll get rid of those too. Note the parentheses.

NOT (cause_description="Unallocated (unassigned) number" OR cause_description="No circuit/channel available" OR cause_description="User Busy")

This could have been written as

NOT cause_description="Unallocated (unassigned) number" NOT cause_description="No circuit/channel available" NOT cause_description="User Busy"

The two are equivalent.

Use Case #4 – Those poor callers!

Quick scenario. I’m your customer. I call you, but get bounced from person to person until I finally end up in a voice mailbox. This is a nightmare for most callers. They don’t want to be bounced around like that, especially if the end result was just a voice mailbox anyway!

Here’s one search for that, assuming your voicemail number is 777.

transfers>4 duration_elapsed>100 terminatingCalledPartyNumber=777 on_hook_recipient=caller

Hopefully you don’t even have any that transfer that many times – try it with transfers>1 or so to get the feel of it.

Notes on use – implicit AND

First – note that by default all the search terms are combined with AND, but always remember each search term operates independently at the level of legs. This means a search filter like this:

dest_device_type="gateway" dest_device_type="unityvm"

Will return any call that had at least one leg be of dest_​device_​type gateway, and that also had a leg where dest_​device_​type was unityvm. Try thinking of it this way:

• Return all calls that match the following criteria:
  • One or more legs had a dest_​device_​type of ​“gateway”
  • AND one or more legs had a dest_​device_​type of ​“unityvm”

Clear enough?

Notes on use – parentheses

Splunk’s logic for combining AND and OR terms is rarely going to match your expectations. You can read about it in Splunk’s great documentation. The way around this is to use parentheses to group your terms together and make sure the logic is what you want.

A quick probably nonsensical example: suppose you’d like to search to return either where the dest_​device_​type was ​“gateway” and the call had great quality, or where the dest_​device_​type was voicemail but you don’t care about the quality. You’d think something like this should to it:

dest_device_type="gateway" AND MLQK>4 OR dest_device_type="unityvm"

Unfortunately, that’s not quite what it does. Instead, tell it specifically how to group them:

(dest_device_type="gateway" AND MLQK>4) OR dest_device_type="unityvm"

For readability, get used to using parentheses any time you mix up the ANDs and the ORs.

Notes on use – NOT and !=

This should be short: Use != for not equals, use NOT to do NOT.

OK, sorry, I lied a little bit there. The short answer is completely accurate, but doesn’t tell you how they differ.

The difference is easiest to see with an example, and it’s how Splunk works for this too so this knowledge is generally applicable.

Let’s take MLQK!=4.5 vs. NOT MLQK=4.5

MLQK!=4.5 will return calls where at least one leg had an MLQK field with a value, and where that value was not equal to 4.5. So a call that had no MLQK at all wouldn’t be returned at all.

NOT MLQK=4.5, on the other hand, will return any call – whether there was any leg with an MLQK set or not – where MLQK wasn’t 4.5. So it includes all the results from MLQK!=4.5, but also includes all the results where MLQK wasn’t set at all.

Think of it this way: MLQK!=4.5 looks for MLQK values that exist but that aren’t 4.5, so null or empty values don’t count because they’re not MLQK values at all, they’re just empty places. On the other hand, NOT MLQK=4.5 looks for any events where the MLQK isn’t 4.5 which includes zeros, nulls, 3.2, 7, … every single thing that isn’t 4.5.