ddqb

import "github.com/jonwinton/ddqb"

Package ddqb provides a fluent API for building DataDog queries.

Package ddqb provides a fluent API for building DataDog queries.

Example

package main

import (
    "fmt"
    "log"

    "github.com/jonwinton/ddqb"
)

func main() {
    // Create a simple metric query
    query, err := ddqb.Metric().
        Metric("system.cpu.idle").
        Build()
    if err != nil {
        log.Fatalf("Failed to build query: %v", err)
    }
    fmt.Println(query)

    // Create a metric query with aggregation
    query, err = ddqb.Metric().
        Aggregator("avg").
        TimeWindow("5m").
        Metric("system.cpu.idle").
        Build()
    if err != nil {
        log.Fatalf("Failed to build query: %v", err)
    }
    fmt.Println(query)

    // Create a metric query with filtering
    query, err = ddqb.Metric().
        Metric("system.cpu.idle").
        Filter(ddqb.Filter("host").Equal("web-1")).
        Build()
    if err != nil {
        log.Fatalf("Failed to build query: %v", err)
    }
    fmt.Println(query)

    // Create a complex metric query
    query, err = ddqb.Metric().
        Aggregator("avg").
        TimeWindow("5m").
        Metric("system.cpu.idle").
        Filter(ddqb.Filter("host").Equal("web-1")).
        Filter(ddqb.Filter("env").Equal("prod")).
        GroupBy("host").
        ApplyFunction(ddqb.Function("fill").WithArg("0")).
        ApplyFunction(ddqb.Function("rollup").WithArgs("60", "sum")).
        Build()
    if err != nil {
        log.Fatalf("Failed to build query: %v", err)
    }
    fmt.Println(query)

}

#### Output

system.cpu.idle{*}
avg(5m):system.cpu.idle{*}
system.cpu.idle{host:web-1}
avg(5m):system.cpu.idle{host:web-1, env:prod} by {host}.fill(0).rollup(60, sum)

Index

• func Filter(key string) metric.FilterBuilder
• func FilterGroup() metric.FilterGroupBuilder
• func FromQuery(queryString string) (metric.QueryBuilder, error)
• func Function(name string) metric.FunctionBuilder
• func Metric() metric.QueryBuilder
• type Builder
• type Renderer

func Filter

func Filter(key string) metric.FilterBuilder

Filter creates a new filter builder with the given key. This is a convenience function for creating filter builders.

func FilterGroup

func FilterGroup() metric.FilterGroupBuilder

FilterGroup creates a new filter group builder. This is a convenience function for creating filter group builders.

func FromQuery

func FromQuery(queryString string) (metric.QueryBuilder, error)

FromQuery parses an existing DataDog query string and returns a QueryBuilder that can be modified using the fluent API.

Example:

builder, err := ddqb.FromQuery("avg(5m):system.cpu.idle{host:web-1} by {host}.fill(0)")
if err != nil {
    // handle error
}
modifiedQuery, err := builder.TimeWindow("10m").Filter(ddqb.Filter("env").Equal("prod")).Build()

func Function

func Function(name string) metric.FunctionBuilder

Function creates a new function builder with the given name. This is a convenience function for creating function builders.

func Metric

func Metric() metric.QueryBuilder

Metric creates a new metric query builder. This is the main entry point for building metric queries.

type Builder

Builder is the base interface for all query builders. It defines the methods that all builders must implement.

type Builder interface {
    // Build returns the built query as a string.
    Build() (string, error)
}

type Renderer

Renderer defines an interface for objects that can render themselves as DataDog query strings.

type Renderer interface {
    // String returns the object as a DataDog query string.
    String() string
}

metric

import "github.com/jonwinton/ddqb/metric"

Package metric provides builders for creating DataDog metric queries.

Index

• type FilterBuilder
• func NewFilterBuilder(key string) FilterBuilder
• type FilterExpression
• type FilterGroupBuilder
• func NewFilterGroupBuilder() FilterGroupBuilder
• type FilterOperation
• type FunctionBuilder
• func NewFunctionBuilder(name string) FunctionBuilder
• type GroupOperator
• type QueryBuilder
• func NewMetricQueryBuilder() QueryBuilder
• func ParseQuery(queryString string) (QueryBuilder, error)

type FilterBuilder

FilterBuilder provides a fluent interface for building filter conditions. FilterBuilder implements FilterExpression.

type FilterBuilder interface {
    FilterExpression

    // Equal creates an equality filter (key:value).
    Equal(value string) FilterBuilder

    // NotEqual creates a negated equality filter (key!:value).
    NotEqual(value string) FilterBuilder

    // Regex creates a regex filter (key:~value).
    Regex(pattern string) FilterBuilder

    // In creates an IN filter.
    In(values ...string) FilterBuilder

    // NotIn creates a NOT IN filter.
    NotIn(values ...string) FilterBuilder
}

func NewFilterBuilder

func NewFilterBuilder(key string) FilterBuilder

NewFilterBuilder creates a new filter builder with the given key.

type FilterExpression

FilterExpression is a common interface for both individual filters and filter groups. This allows QueryBuilder to accept either FilterBuilder or FilterGroupBuilder instances.

type FilterExpression interface {
    // Build returns the built filter expression as a string.
    Build() (string, error)
}

type FilterGroupBuilder

FilterGroupBuilder provides a fluent interface for building filter groups with boolean logic. FilterGroupBuilder implements FilterExpression.

type FilterGroupBuilder interface {
    FilterExpression

    // AND adds a filter or nested group with AND operator.
    AND(expr FilterExpression) FilterGroupBuilder

    // OR adds a filter or nested group with OR operator.
    OR(expr FilterExpression) FilterGroupBuilder

    // Not negates the entire group (wraps in NOT (...)).
    Not() FilterGroupBuilder
}

func NewFilterGroupBuilder

func NewFilterGroupBuilder() FilterGroupBuilder

NewFilterGroupBuilder creates a new filter group builder.

type FilterOperation

FilterOperation represents the type of filter operation.

type FilterOperation int

const (
    // Equal represents an equality filter (key:value).
    Equal FilterOperation = iota
    // NotEqual represents a negated equality filter (key!:value).
    NotEqual
    // Regex represents a regex filter (key:~value).
    Regex
    // In represents an IN filter.
    In
    // NotIn represents a NOT IN filter.
    NotIn
)

type FunctionBuilder

FunctionBuilder provides a fluent interface for building functions to apply to queries.

type FunctionBuilder interface {
    // WithArg adds an argument to the function.
    WithArg(arg string) FunctionBuilder

    // WithArgs adds multiple arguments to the function.
    WithArgs(args ...string) FunctionBuilder

    // Build returns the built function as a string.
    Build() (string, error)
}

func NewFunctionBuilder

func NewFunctionBuilder(name string) FunctionBuilder

NewFunctionBuilder creates a new function builder with the given name.

type GroupOperator

GroupOperator represents the boolean operator used in a filter group.

type GroupOperator int

const (
    // AndOperator represents an AND operation between filters.
    AndOperator GroupOperator = iota
    // OrOperator represents an OR operation between filters.
    OrOperator
)

type QueryBuilder

QueryBuilder provides a fluent interface for building metric queries.

type QueryBuilder interface {
    // Metric sets the metric name for the query.
    Metric(name string) QueryBuilder

    // Aggregator sets the aggregation method for the query (e.g., "avg", "sum").
    Aggregator(agg string) QueryBuilder

    // Filter adds a filter condition or filter group to the query.
    Filter(filter FilterExpression) QueryBuilder

    // GetFilters returns all filter expressions in the query.
    // This allows direct access to modify FilterGroupBuilder instances.
    GetFilters() []FilterExpression

    // FindGroup finds the first FilterGroupBuilder that matches the predicate function.
    // Returns nil if no matching group is found.
    FindGroup(predicate func(FilterGroupBuilder) bool) FilterGroupBuilder

    // AddToGroup adds a filter to the specified FilterGroupBuilder.
    // The filter is added using the group's existing operator (AND or OR).
    AddToGroup(group FilterGroupBuilder, filter FilterExpression) QueryBuilder

    // GroupBy sets grouping parameters for the query.
    GroupBy(groups ...string) QueryBuilder

    // ApplyFunction applies a function to the query.
    ApplyFunction(fn FunctionBuilder) QueryBuilder

    // TimeWindow sets the time window for the query (e.g., "1m", "5m").
    TimeWindow(window string) QueryBuilder

    // Build returns the built query as a string.
    Build() (string, error)
}

func NewMetricQueryBuilder

func NewMetricQueryBuilder() QueryBuilder

NewMetricQueryBuilder creates a new metric query builder.

func ParseQuery

func ParseQuery(queryString string) (QueryBuilder, error)

ParseQuery parses a DataDog query string and returns a QueryBuilder that can be modified using the fluent API.

advanced

import "github.com/jonwinton/ddqb/examples/advanced"

Package main demonstrates advanced usage of ddqb, including dynamic query building based on runtime conditions.

Index

basic

import "github.com/jonwinton/ddqb/examples/basic"

Package main demonstrates basic usage examples of ddqb for building DataDog metric queries.

Index

filters

import "github.com/jonwinton/ddqb/examples/filters"

Package main demonstrates various filter operations available in ddqb for DataDog metric queries.

Index

functions

import "github.com/jonwinton/ddqb/examples/functions"

Package main demonstrates how to apply functions to DataDog metric queries using ddqb.

Index

parse

import "github.com/jonwinton/ddqb/examples/parse"

Package main demonstrates parsing existing DataDog query strings and modifying them using ddqb.

Index

Generated by gomarkdoc