Skip to content

Tracing Event Filtering

$ sudo ./dist/tracee-ebpf --trace help
$ sudo ./dist/tracee-ebpf --trace xxx

Tracing output might become too hard to consume when tracing all the events from a system. Luckily, Tracee has a powerful mechanism to accurately trace just the information that is relevant to the user, the --trace flag.

With --trace command line flag you define expressions that tells tracee-ebpf what you are interested in based on event metadata filtering capabilities. Only events that match given criteria will be traced.


You can filter events by most of the visible fields from Tracee events.

Initial Example

All the examples bellow this item can be executed with the following tracee-ebpf prefix command:

$ sudo ./dist/tracee-ebpf \
    --output json \
    --trace comm=bash \
    --trace follow
    --output option:parse-arguments \
    <rest of filters>

This will allow you to test the filtering rules by executing a new process in any running shell and might serve as a good indicative if your filter works as expected.

Filters and Operators

  1. Event (Operators: =, != and "follow". Prefix/Suffix: *)

    1) --trace event=openat
    2) --trace event=execve,open
    3) --trace event=open*
    4) --trace event!=open*,dup*
    5) --trace follow


    The "follow" operator will make tracee to follow all newly created processes, that are being filtered for, childs.

  2. Event Arguments (Operators: =, !=. Prefix/Suffix: *)

    1) --trace event=openat --trace openat.pathname=/etc/shadow
    2) --trace event=openat --trace openat.pathname=/tmp*
    3) --trace event=openat --trace openat.pathname!=/tmp/1,/bin/ls


    Multiple values are ORed if used with = operator
    But ANDed if used with any other operator.

  3. Event Return Code (Operators: =, !=, <, >)

    1) --trace event=openat --trace openat.pathname=/etc/shadow --trace "openat.retval>0"
    2) --trace event=openat --trace openat.pathname=/etc/shadow --trace "openat.retval<0"


    Try cat /etc/shadow as a regular use and filter for retval<0.

  4. Event Sets (Operators: =, !=)

    1) --trace set=fs
    2) --trace set=lsm_hooks,network_events


    Selects a set of events to tracee according to pre-defined sets which can be listed by using --list command line argument.

  5. Container (Operators: =, != and "new". Boolean)

    1) --trace container # all container events
    2) --trace '!container' # events from the host only
    3) --trace container=new # containers created after tracee-ebf execution
    4) --trace container=3f93da58be3c --trace event=openat
    5) --trace container=new --trace event=openat --trace openat.pathname="/etc/shadow"


    The new flag allows to trace newly created containers only.

  6. Command (Operators: =, !=)

    1) --trace comm=cat,vim,ping
    2) --trace comm!=ping


    Do not use given command prefix for these examples as they're filtering by command name as well.

  7. PID (Operators: =, !=, <, > and "new")

    1) --trace pid=new # newly created events (after tracee-ebpf execution)
    2) --trace pid=510,1709 # # pids 510 and 1709
    3) --trace 'pid>0' --trace pid 'pid<1000'
    4) --trace pid=2578238 --trace event=openat --trace openat.pathname=/etc/shadow --trace follow
  8. Process Tree

    1) --trace tree=476165 # events descending from process 476165
    2) --trace tree!=5023 # events that do not descend from process 5023
  9. UID (Operators: =, !=, <, >)

    1) --trace uid=0
    2) --trace 'uid>0'
    3) --trace 'uid>0' --trace uid!=1000 # do not trace root and uid=1000
  10. Network Interface

    1) -trace comm=nc,ping -trace event=net_packet -trace net=docker0
    2) -trace event=dns_request,dns_response -trace net=docker0


    Do not forget to provide the interface to be traced with "net=name"

  11. UTS Namespace (hostnames) (Operators: =, !=)

    1) --trace uts!=ab356bc4dd554 
  12. PID Namespace (Operators: =, !=, <, >)

    1) --trace pidns!=4026531836
  13. MOUNT Namespace (Operators: =, !=, <, >)

    1) --trace mntns=4026531840