Filtering

A list of all the keyword filters that hunter.trace or hunter.Q accept:

  • arg - you probably don’t care about this - it may have a value for return/exception events

  • builtin (bool) - True if function is a builtin function

  • calls (int) - a call counter, you can use it to limit output by using a lt operator

  • depth (int) - call depth, starts from 0, increases for call events and decreases for returns

  • filename (str)

  • fullsource (str) - sourcecode for the executed lines (may be multiple lines in some situations)

  • function (str) - function name

  • globals (dict) - global variables

  • instruction (int or str, depending on Python version) - current executed bytecode, see Silenced exception runtime analysis for example usage

  • kind (str) - one of ‘call’, ‘exception’, ‘line’ or ‘return’

  • lineno (int)

  • locals (dict) - local variables

  • module (str) - dotted module

  • source (str) - sourcecode for the executed line

  • stdlib (bool) - True if module is from stdlib

  • threadid (int)

  • threadname (str) - whatever threading.Thread.name returns

You can append operators to the above filters. Note that some of of the filters won’t work well with the bool or int types.

  • contains - works best with str, for example module_contains='foobar' translates to 'foobar' in event.module

  • has - alias for contains

  • endswith - works best with str, for example module_endswith='foobar' translates to event.module.endswith('foobar'). You can also pass in a iterable, example module_endswith=('foo', 'bar') is acceptable

  • ew - alias for endswith

  • gt - works best with int, for example lineno_gt=100 translates to event.lineno > 100

  • gte - works best with int, for example lineno_gte=100 translates to event.lineno >= 100

  • in - a membership test, for example module_in=('foo', 'bar') translates to event.module in ('foo', 'bar'). You can use any iterable, for example module_in='foo bar' translates to event.module in 'foo bar', and that would probably have the same result as the first example

  • lt - works best with int, for example calls_lt=100 translates to event.calls < 100

  • lte - works best with int, for example depth_lte=100 translates to event.depth <= 100

  • regex - works best with str, for example module_regex=r'(test|test.*)\b' translates to re.match(r'(test|test.*)\b', event.module)

  • rx - alias for regex

  • startswith - works best with str, for example module_startswith='foobar' translates to event.module.startswith('foobar'). You can also pass in a iterable, example module_startswith=('foo', 'bar') is acceptable

  • sw - alias for startswith

Notes:

  • you can also use double underscore (if you’re too used to Django query lookups), eg: module__has='foobar' is acceptable

  • there’s nothing smart going on for the dots in module names so sometimes you might need to account for said dots:

    • module_sw='foo' will match "foo.bar" and "foobar" - if you want to avoid matchin the later you could do either of:

      • Q(module='foo')|Q(module_sw='foo.')

      • Q(module_rx=r'foo($|\.)') - but this might cost you in speed

      • Q(filename_sw='/path/to/foo/') - probably the fastest

      • Q(filename_has='/foo/') - avoids putting in the full path but might match unwanted paths