filter

Documentation

Overview

Package filter helps filtering an array of structs that were analyzed by the columns library.

If you have an array of a struct you have a `Column` instance for, you can simply filter it by using a filter string like this:

filter.FilterEntries(columnMap, events, []string{"pid:55"})

This will return an array only containing entries that have the pid column set to 55.

A filter string always starts with the column name, followed by a colon and then the actual filter rule.

If the filter rule starts with an exclamation mark ("!"), the filter will be negated and return only entries that don't match the rule. This indicator has always be the first character of the filter rule.

filter.FilterEntries(columnMap, events, "name:!Demo") // matches entries with column "name" not being "Demo"

A tilde ("~") at the start of a filter rule indicates a regular expression. The actual regular expression has to be written using the re2 syntax used by Go (see [https://github.com/google/re2/wiki/Syntax]).

Additional rule options for integers, floats and strings are `>`, `>=`, `<` and `<=`, e.g.:

filter.FilterEntries(columnMap, events, []string{"pid:>=55"})

Optimizing / Streaming

If you have to filter a stream of incoming events, you can use

myFilter := filter.GetFilterFromString(columnMap, filter)

to get a filter with a .Match(entry) function that you can use to match against entries.

Filter examples

"columnName:value" - matches, if the content of columnName equals exactly value
"columnName:!value" - matches, if the content of columnName does not equal exactly value
"columnName:>=value" - matches, if the content of columnName is greater or equal to the value
"columnName:~value" - matches, if the content of columnName matches the regular expression 'value'

Index

• func FilterEntries[T any](cols columns.ColumnMap[T], entries []*T, filters []string) ([]*T, error)
• type FilterSpec
  • func GetFilterFromString[T any](cols columns.ColumnMap[T], filter string) (*FilterSpec[T], error)
  • func (fs *FilterSpec[T]) Match(entry *T) bool
• type FilterSpecs
  • func GetFiltersFromStrings[T any](cols columns.ColumnMap[T], filters []string) (*FilterSpecs[T], error)
  • func (fs *FilterSpecs[T]) MatchAll(entry *T) bool
  • func (fs *FilterSpecs[T]) MatchAny(entry *T) bool

Examples

• FilterEntries
• GetFilterFromString

Functions

func FilterEntries

func FilterEntries[T any](cols columns.ColumnMap[T], entries []*T, filters []string) ([]*T, error)

FilterEntries will return the elements of entries that match all given filters.

Example

package main

import (
	"fmt"

	"github.com/inspektor-gadget/inspektor-gadget/pkg/columns"
	"github.com/inspektor-gadget/inspektor-gadget/pkg/columns/filter"
)

func main() {
	type Employee struct {
		Name       string `column:"name" columnTags:"sensitive"`
		Age        int    `column:"age" columnTags:"sensitive"`
		Department string `column:"department"`
	}

	Employees := []*Employee{
		{"Alice", 32, "Security"},
		{"Bob", 26, "Security"},
		{"Eve", 99, "Security also"},
	}

	employeeColumns := columns.MustCreateColumns[Employee]()

	// Get columnMap
	cmap := employeeColumns.GetColumnMap()

	// Filter entries, searching for people younger than 50 and an "e" in the name (case insensitive)
	result, err := filter.FilterEntries(cmap, Employees, []string{"age:<50", "name:~(?i)e"})
	if err != nil {
		panic(err)
	}

	for _, e := range result {
		fmt.Println(*e)
	}

}

Output:

{Alice 32 Security}

Types

type FilterSpec

type FilterSpec[T any] struct {
	// contains filtered or unexported fields
}

func GetFilterFromString

func GetFilterFromString[T any](cols columns.ColumnMap[T], filter string) (*FilterSpec[T], error)

GetFilterFromString prepares a filter that has a Match() function that can be called on entries of type *T

Example

package main

import (
	"fmt"

	"github.com/inspektor-gadget/inspektor-gadget/pkg/columns"
	"github.com/inspektor-gadget/inspektor-gadget/pkg/columns/filter"
)

func main() {
	type Employee struct {
		Name       string `column:"name" columnTags:"sensitive"`
		Age        int    `column:"age" columnTags:"sensitive"`
		Department string `column:"department"`
	}

	Employees := []*Employee{
		{"Alice", 32, "Security"},
		{"Bob", 26, "Security"},
		{"Eve", 99, "Security also"},
	}

	employeeColumns := columns.MustCreateColumns[Employee]()

	// Get columnMap
	cmap := employeeColumns.GetColumnMap()

	// Create a new filter that matches employees from the "Security" department
	employeeFilter, err := filter.GetFilterFromString(cmap, "department:Security")
	if err != nil {
		panic(err)
	}

	for _, e := range Employees {
		if employeeFilter.Match(e) {
			fmt.Println(*e)
		}
	}

}

Output:

{Alice 32 Security}
{Bob 26 Security}

func (*FilterSpec[T]) Match

func (fs *FilterSpec[T]) Match(entry *T) bool

Match matches a single entry against the FilterSpec and returns true if it matches

type FilterSpecs

type FilterSpecs[T any] []*FilterSpec[T]

func GetFiltersFromStrings

func GetFiltersFromStrings[T any](cols columns.ColumnMap[T], filters []string) (*FilterSpecs[T], error)

GetFiltersFromStrings prepares filters to FilterSpecs that can be used to match on several filters at once

func (*FilterSpecs[T]) MatchAll

func (fs *FilterSpecs[T]) MatchAll(entry *T) bool

MatchAll matches a single entry against the FilterSpecs and returns true if all filters match

func (*FilterSpecs[T]) MatchAny

func (fs *FilterSpecs[T]) MatchAny(entry *T) bool

MatchAny matches a single entry against the FilterSpecs and returns true if any filter matches