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