query

package
v4.1.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2025 License: GPL-2.0 Imports: 21 Imported by: 1

README

goDB Query API

This package exposes methods to query the data stored in goDB.

Example

To access the data captured by goProbe (stored at the default location) from your own application, you can use the following to get started:

func main() {
     // set query output(s) redirection (default is os.Stdout). You can use multiple io.Writers here
     ctx := context.Background()
     outputs := os.Stderr

     args := query.NewArgs("sip,dip", "eth0",
        query.WithSortAscending(),
        query.WithCondition("dport eq 443"),
     )

     // prepare the statement (e.g. parse args and setup query parameters).
     // This example assumes that you are querying against goDB
     stmt, err := args.Prepare(output)
     if err != nil {
          fmt.Fprintf(os.Stderr, "couldn't prepare statement: %s\n", err)
          os.Exit(1)
     }

     // execute statement
     err = engine.NewQueryRunner().Run(ctx, stmt)
     if err != nil {
          fmt.Fprintf(os.Stderr, "query failed: %s\n", err)
          os.Exit(1)
     }
}

For a more complete overview, please consult the documentation.

Documentation

Overview

Package query supplies the API for running queries on a goDB database

Index

Constants

View Source 
const MaxResults = 9999999999999999

MaxResults stores the maximum number of rows a query will return. This limit is more or less theoretical, since a DB will unlikley feature such an amount of entries

Variables

View Source 
var (
	DefaultDBPath         = defaults.DBPath
	DefaultFormat         = types.FormatTXT
	DefaultMaxMemPct      = 60
	DefaultNumResults     = uint64(1000)
	DefaultResolveRows    = 25
	DefaultResolveTimeout = 1 * time.Second
	DefaultQueryTimeout   = defaults.QueryTimeout
	DefaultSortBy         = "bytes"
)

Defaults for query arguments

Functions

func ParseTimeArgument 

func ParseTimeArgument(timeString string) (int64, error)

ParseTimeArgument is the entry point for external calls and converts valid formats to a unix timtestamp

func ParseTimeRange 

func ParseTimeRange(firstStr, lastStr string) (first, last int64, err error)

ParseTimeRange will run ParseTimeArgument for a range and validate if the interval is non-zero

func ParseTimeRangeCollectErrors 

func ParseTimeRangeCollectErrors(firstStr, lastStr string) (first, last int64, details []*huma.ErrorDetail)

ParseTimeRangeCollectErrors will run ParseTimeArgument for a range and validate if the interval is non-zero. It will append errors encountered during interval validation to the huma.ErrorDetail slice and return them. The error condition will thus be len(details) > 0

func PermittedFormats 

func PermittedFormats() []string

PermittedFormats list which formats are supported

func PermittedSortBy 

func PermittedSortBy() []string

PermittedSortBy lists which sort by methods are supported

Types

type Args 

type Args struct {
	// required
	// Query: the query type
	Query string `` /* 129-byte string literal not displayed */
	// Ifaces: the interfaces to query
	Ifaces string `` /* 169-byte string literal not displayed */

	// QueryHosts: the hosts for which data is queried (comma-separated list)
	QueryHosts string `` /* 160-byte string literal not displayed */

	// Hostname: the hostname from which data is queried
	Hostname string `` /* 143-byte string literal not displayed */
	// HostID: the host id from which data is queried
	HostID uint `` /* 140-byte string literal not displayed */

	// data filtering
	// Condition: the condition to filter data by
	Condition string `` /* 152-byte string literal not displayed */

	// counter addition
	// In: only show incoming packets/bytes
	In bool `json:"in,omitempty" yaml:"in,omitempty" query:"in" required:"false" doc:"Only show incoming packets/bytes" example:"false"`
	// Out: only show outgoing packets/bytes
	Out bool `` /* 126-byte string literal not displayed */
	// Sum: show sum of incoming/outgoing packets/bytes
	Sum bool `` /* 136-byte string literal not displayed */

	// time selection
	// First: the first timestamp to query
	First string `` /* 147-byte string literal not displayed */
	// Last: the last timestamp to query
	Last string `json:"last,omitempty" yaml:"last,omitempty" query:"last" required:"false" doc:"The last timestamp to query" example:"-24h"`

	// formatting
	// Format: the output format
	Format string `` /* 134-byte string literal not displayed */
	// SortBy: column to sort by
	SortBy string `` /* 160-byte string literal not displayed */
	// NumResults: number of results to return/print
	NumResults uint64 `` /* 174-byte string literal not displayed */
	// SortAscending: sort ascending instead of the default descending
	SortAscending bool `` /* 162-byte string literal not displayed */

	// do-and-exit arguments
	// List: only list interfaces and return
	List bool `json:"list,omitempty" yaml:"list,omitempty" query:"list" required:"false" hidden:"true"`
	// Version: only print version and return
	Version bool `json:"version,omitempty" yaml:"version,omitempty" query:"version" required:"false" hidden:"true"`

	// resolution
	// Note: Nested structures are not supported for form data, see individual parameters in definition of DNSResolution
	// DNSResolution: guide reverse DNS resolution of sip,dip results
	DNSResolution DNSResolution `json:"dns_resolution,omitempty" yaml:"dns_resolution,omitempty" doc:"Configures DNS resolution of sip,dip results"`

	// file system
	// MaxMemPct: maximum percentage of available host memory to use for query processing
	MaxMemPct int `` /* 224-byte string literal not displayed */
	// LowMem: use less memory for query processing
	LowMem bool `` /* 141-byte string literal not displayed */
	// KeepAlive: keepalive message interval for query processor
	KeepAlive time.Duration `` /* 175-byte string literal not displayed */

	// Caller stores who produced these args (caller)
	Caller string `` /* 144-byte string literal not displayed */

	// Live can be used to request live flow data (in addition to DB results)
	Live bool `` /* 166-byte string literal not displayed */
	// contains filtered or unexported fields
}

Args bundles the command line/HTTP parameters required to prepare a query statement

func DefaultArgs 

func DefaultArgs() *Args

DefaultArgs creates a basic set of query arguments with only the defaults being set

func NewArgs 

func NewArgs(query, ifaces string, opts ...Option) *Args

NewArgs creates new query arguments with the defaults set

func (*Args) AddOutputs 

func (a *Args) AddOutputs(outputs ...io.Writer) *Args

AddOutputs allows more control over to which outputs the query results are written

func (*Args) CheckUnboundedQueries 

func (a *Args) CheckUnboundedQueries() error

CheckUnboundedQueries qualifies whether a query will load too much data. At the moment, this boils down to raw queries without a condition.

Callers can use this function to protect against long-running queries in order to preserve resources and bandwidth

func (*Args) LogValue 

func (a *Args) LogValue() slog.Value

LogValue creates an slog compatible value from an Args instance

func (*Args) Prepare 

func (a *Args) Prepare(writers ...io.Writer) (*Statement, error)

Prepare takes the query Arguments, validates them and creates an executable statement. Optionally, additional writers can be passed to route query results to different destinations.

func (*Args) SetDefaults 

func (args *Args) SetDefaults()

SetDefaults sets the default values for all uninitialized fields in the arguments

func (*Args) String 

func (a *Args) String() string

String formats aruguments in human-readable form

func (*Args) ToJSONString 

func (a *Args) ToJSONString() string

ToJSONString marshals the args and puts the result into a string

type DNSResolution 

type DNSResolution struct {

	// Enabled: enable reverse DNS lookups. Example: false
	Enabled bool `json:"enabled" yaml:"enabled" query:"dns_enabled" doc:"Enable reverse DNS lookups" example:"false"`
	// Timeout: timeout for reverse DNS lookups
	Timeout time.Duration `` /* 178-byte string literal not displayed */
	// MaxRows: maximum number of rows to resolve
	MaxRows int `` /* 154-byte string literal not displayed */
	// contains filtered or unexported fields
}

DNSResolution contains DNS query / resolution related config arguments / parameters

type DetailError 

type DetailError struct {
	huma.ErrorModel
}
return fmt.Sprintf(str, err.Field, err.Message, errStr)

'}

func NewDetailError 

func NewDetailError(code int, err error) *DetailError

NewDetailError creates a new generic DetailError of specific status and providing detailed information based on a generic error

func (*DetailError) Pretty 

func (d *DetailError) Pretty() string

Pretty implements the prettier interface for a huma.ErrorModel

type Option 

type Option func(*Args)

Option allows to modify an existing Args container

func WithCaller 

func WithCaller(c string) Option

WithCaller sets the name of the program/tool calling the query

func WithCondition 

func WithCondition(c string) Option

WithCondition sets the condition argument

func WithDirectionIn 

func WithDirectionIn() Option

WithDirectionIn considers the incoming flows

func WithDirectionOut 

func WithDirectionOut() Option

WithDirectionOut considers the outgoing flows

func WithDirectionSum 

func WithDirectionSum() Option

WithDirectionSum adds both directions

func WithFirst 

func WithFirst(f string) Option

WithFirst sets the first timestamp to consider

func WithFormat 

func WithFormat(f string) Option

WithFormat sets the output format

func WithLast 

func WithLast(l string) Option

WithLast sets the last timestampt to consider

func WithList 

func WithList() Option

WithList sets the list parameter (only lists interfaces)

func WithLive 

func WithLive() Option

WithLive enables live data query

func WithMaxMemPct 

func WithMaxMemPct(m int) Option

WithMaxMemPct is an advanced parameter to restrict system memory usage to a fixed percentage of the available memory during query processing

func WithNumResults 

func WithNumResults(n uint64) Option

WithNumResults sets how many rows are returned

func WithQueryHosts 

func WithQueryHosts(c string) Option

WithQueryHosts sets the query hosts argument

func WithResolve 

func WithResolve() Option

WithResolve enables reverse lookups of IPs

func WithResolveRows 

func WithResolveRows(r int) Option

WithResolveRows sets the amount of rows for which lookups should be attempted

func WithResolveTimeout 

func WithResolveTimeout(t time.Duration) Option

WithResolveTimeout sets the timeout for reverse lookups (in seconds)

func WithSortAscending 

func WithSortAscending() Option

WithSortAscending sorts rows ascending

func WithSortBy 

func WithSortBy(s string) Option

WithSortBy sets by which parameter should be sorted

func WithVersion 

func WithVersion() Option

WithVersion sets the version parameter (print version and exit)

type Runner 

type Runner interface {

	// Run takes a query statement, executes the underlying query and returns the result(s)
	Run(ctx context.Context, args *Args) (*results.Result, error)
}

Runner specifies the functionality a query runner must provide

type Statement 

type Statement struct {
	// Ifaces holds the list of all interfaces that should be queried
	Ifaces []string `json:"ifaces"`

	LabelSelector types.LabelSelector `json:"label_selector,omitempty"`

	// needed for feedback to user
	QueryType string `json:"query_type"`

	Condition string `json:"condition,omitempty"`

	// which direction is added
	Direction types.Direction `json:"direction"`

	// time selection
	First int64 `json:"from"`
	Last  int64 `json:"to"`

	// formatting
	Format        string            `json:"format"`
	NumResults    uint64            `json:"limit"`
	SortBy        results.SortOrder `json:"sort_by"`
	SortAscending bool              `json:"sort_ascending,omitempty"`
	Output        io.Writer         `json:"-"`

	// parameters for external calls
	Caller string `json:"caller,omitempty"` // who called the query

	// resolution parameters (probably part of table printer)
	DNSResolution DNSResolution `json:"dns_resolution,omitempty"`

	// file system
	MaxMemPct int  `json:"max_mem_pct,omitempty"`
	LowMem    bool `json:"low_mem,omitempty"`

	// query keepalive
	KeepAliveDuration time.Duration `json:"keepalive,omitempty"`

	// request live flow data (in addition to DB)
	Live bool `json:"live,omitempty"`
	// contains filtered or unexported fields
}

Statement bundles all relevant options for running a query and displaying its result

func (*Statement) Pretty 

func (s *Statement) Pretty() string

func (*Statement) Print 

func (s *Statement) Print(ctx context.Context, result *results.Result, opts ...results.PrinterOption) error

Print prints a statement to the result

func (*Statement) String 

func (s *Statement) String() string

String prints the executable statement in human-readable form

type TimeFormat 

type TimeFormat struct {
	Name   string
	Format string
}

TimeFormat denotes a time format with an optional verbose name for display

func TimeFormatsCustom 

func TimeFormatsCustom() []TimeFormat

TimeFormatsCustom returns a list of all supported custom time formats

func TimeFormatsDefault 

func TimeFormatsDefault() []TimeFormat

TimeFormatsDefault returns a list of all supported default time formats

func TimeFormatsRelative 

func TimeFormatsRelative() []TimeFormat

TimeFormatsRelative returns a list of all supported relative time formats

Source Files

View all Source files

Directories

Path Synopsis
Package dns provides reverse lookup functionality for goQuery's results
 Package dns provides reverse lookup functionality for goQuery's results

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.