trapcheck

README

Package go-trapcheck

HTTPTrap check management to separate checkmgr from cgm. Goes with go-trapmetrics for handling collection and submission of metrics from applications.

Configuration options

• Client - required, an instance of the API Client
• CheckConfig - optional, pointer to a valid API Client Check Bundle. If it is used at all, some or none of the settings may be used, offering the most flexible method for configuring a check bundle to be created. Pass nil for the defaults. Defaults will be used to backfill any partial configuration used. (e.g. set the Target and all other settings will use defaults.)
• SubmissionURL - optional, explicit submission URL to use when sending metrics (e.g. a circonus-agent on the local host). If the destination is using TLS then a SubmitTLSConfig must be provided.
• SubmitTLSConfig - optional, pointer to a valid tls.Config for the submission target (e.g. the broker or an explicit submission URL using TLS).
• Logger - optional, something satisfying the Logger interface defined in this module.
• BrokerSelectTags - optional, when creating a check and the check configuraiton does not contain an explict broker, one will be selected. These tags provide a way to define which broker(s) should be evaluated.
• BrokerMaxResponseTiime - optional, duration defining in what time the broker must respond to a connection in order to be considered valid for selection when creating a new check.
• CheckSearchTags - optional, the module will first search for an existing check satisfying certain conditions (active, check type, check target). This setting provides a method for narrowing the search down more explicitly for checks created via other mechanisms.
• TraceMetrics - optional, the path where metric traces should be written. Each metric submission (raw JSON) will be written to a file in this location. If set to -, metrics will be written using Logger.Infof(). Infof is used so that regular debug messages and tracing can be controlled independently. For debugging purposes only.

Basic pseudocode example

package main

import (
    "log"

    apiclient "github.com/circonus-labs/go-apiclient"
    trapcheck "github.com/circonus-labs/go-trapcheck"
)

func main() {
    logger := log.New(os.Stderr, "", log.LstdFlags)

    client, err := apiclient.New(&apiclient.Config{
        TokenKey: "", // required, Circonus API Token Key
        // any other API Client settings desired
    })
    if err != nil {
        logger.Fatal(err)
    }

    
    check, err := trapcheck.New(&trapcheck.Config{
        Client: client, // required, Client is a valid circonus go-apiclient instance
        // CheckConfig is a valid circonus apiclient.CheckBundle configuration
        // or nil for defaults
        // CheckConfig: &apiclient.CheckBundle{...},
        // SubmissionURL explicit submission url (e.g. submitting to an agent, 
        // if tls used a SubmitTLSConfig is required)
        // SubmissionURL: "",
        // SubmitTLSConfig is a *tls.Config to use when submitting to the broker
        // SubmitTLSConfig: &tls.Config{...},
        // Logger interface for logging
        Logger: &trapcheck.LogWrapper{
            Log:   logger,
            Debug: false,
        },
        // BrokerSelectTags defines tags to use when selecting a broker to use (when creating a check)
        // BrokerSelectTag: apiclient.TagType{"location:us_east"},
        // BrokerMaxResponseTime defines the timeout in which brokers must respond when selecting
        // BrokerMaxResponseTime: "500ms",
        // CheckSearchTags defines tags to use when searching for a check
        // CheckSearchTag: apiclient.TagType{"service_id:web21"},
        // TraceMetrics path to write traced metrics to (must be writable by the user running app)
        // TraceMetrics: "/tmp/metric_trace",
    })
    if err != nil {
        logger.Fatal(err)
    }
}

---

Unless otherwise noted, the source files are distributed under the BSD-style license found in the LICENSE file.

Documentation

Index

• type API
• type Config
• type LogWrapper
  • func (lw *LogWrapper) Debugf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Errorf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Infof(fmt string, v ...interface{})
  • func (lw *LogWrapper) Printf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Warnf(fmt string, v ...interface{})
• type Logger
• type TrapCheck
  • func New(cfg *Config) (*TrapCheck, error)
  • func NewFromCheckBundle(cfg *Config, bundle *apiclient.CheckBundle) (*TrapCheck, error)
  • func (tc *TrapCheck) GetBrokerTLSConfig() (*tls.Config, error)
  • func (tc *TrapCheck) GetCheckBundle() (apiclient.CheckBundle, error)
  • func (tc *TrapCheck) IsNewCheckBundle() bool
  • func (tc *TrapCheck) RefreshCheckBundle() (apiclient.CheckBundle, error)
  • func (tc *TrapCheck) SendMetrics(ctx context.Context, metrics bytes.Buffer) (*TrapResult, error)
  • func (tc *TrapCheck) TraceMetrics(trace string) (string, error)
  • func (tc *TrapCheck) UpdateCheckTags(_ context.Context, tags []string) (*apiclient.CheckBundle, error)
• type TrapResult

Types

type API

type API interface {
	// generic methods
	Get(requrl string) ([]byte, error)
	// broker methods
	FetchBroker(cid apiclient.CIDType) (*apiclient.Broker, error)
	FetchBrokers() (*[]apiclient.Broker, error)
	SearchBrokers(searchCriteria *apiclient.SearchQueryType, filterCriteria *apiclient.SearchFilterType) (*[]apiclient.Broker, error)
	// check bundle methods
	FetchCheckBundle(cid apiclient.CIDType) (*apiclient.CheckBundle, error)
	CreateCheckBundle(cfg *apiclient.CheckBundle) (*apiclient.CheckBundle, error)
	SearchCheckBundles(searchCriteria *apiclient.SearchQueryType, filterCriteria *apiclient.SearchFilterType) (*[]apiclient.CheckBundle, error)
	UpdateCheckBundle(cfg *apiclient.CheckBundle) (*apiclient.CheckBundle, error)
}

type Config

type Config struct {
	// Client is a valid circonus go-apiclient instance
	Client API
	// CheckConfig is a valid circonus go-apiclient.CheckBundle configuration
	// or nil for defaults
	CheckConfig *apiclient.CheckBundle
	// SubmitTLSConfig is a *tls.Config to use when submitting to the broker
	SubmitTLSConfig *tls.Config
	// Logger interface for logging
	Logger Logger
	// SubmissionURL explicit submission url (e.g. submitting to an agent, if tls used a SubmitTLSConfig is required)
	SubmissionURL string
	// SubmissionTimeout sets the timeout for submitting metrics to a broker
	SubmissionTimeout string
	// BrokerMaxResponseTime defines the timeout in which brokers must respond when selecting
	BrokerMaxResponseTime string
	// TraceMetrics path to write traced metrics to (must be writable by the user running app)
	TraceMetrics string
	// BrokerSelectTags defines a tag to use when selecting a broker to use (when creating a check)
	BrokerSelectTags apiclient.TagType
	// CheckSearchTags defines a tag to use when searching for a check
	CheckSearchTags apiclient.TagType
	// PublicCA indicates the broker is using a public cert (do not use custom TLS config)
	PublicCA bool
}

type LogWrapper

type LogWrapper struct {
	Log   *log.Logger
	Debug bool
}

LogWrapper is a wrapper around Go's log.Logger.

func (*LogWrapper) Debugf

func (lw *LogWrapper) Debugf(fmt string, v ...interface{})

func (*LogWrapper) Errorf

func (lw *LogWrapper) Errorf(fmt string, v ...interface{})

func (*LogWrapper) Infof

func (lw *LogWrapper) Infof(fmt string, v ...interface{})

func (*LogWrapper) Printf

func (lw *LogWrapper) Printf(fmt string, v ...interface{})

func (*LogWrapper) Warnf

func (lw *LogWrapper) Warnf(fmt string, v ...interface{})

type Logger

type Logger interface {
	Printf(fmt string, v ...interface{})
	Debugf(fmt string, v ...interface{})
	Infof(fmt string, v ...interface{})
	Warnf(fmt string, v ...interface{})
	Errorf(fmt string, v ...interface{})
}

Logger is a generic logging interface.

type TrapCheck

type TrapCheck struct {
	Log Logger
	// contains filtered or unexported fields
}

func New

func New(cfg *Config) (*TrapCheck, error)

New creates a new TrapCheck instance it will create a check if it is not able to find one based on the passed Check Config and Check Search Tag.

func NewFromCheckBundle

func NewFromCheckBundle(cfg *Config, bundle *apiclient.CheckBundle) (*TrapCheck, error)

NewFromCheckBundle creates a new TrapCheck instance using the supplied check bundle.

func (*TrapCheck) GetBrokerTLSConfig

func (tc *TrapCheck) GetBrokerTLSConfig() (*tls.Config, error)

GetBrokerTLSConfig returns the current tls config - can be used for pre-seeding multiple check creation without repeatedly calling the API for the same CA cert - returns tls config, error.

func (*TrapCheck) GetCheckBundle

func (tc *TrapCheck) GetCheckBundle() (apiclient.CheckBundle, error)

GetCheckBundle returns the trap check bundle currently in use - can be used for caching checks on disk and re-using the check quickly by passing the CID in via the check bundle config.

func (*TrapCheck) IsNewCheckBundle

func (tc *TrapCheck) IsNewCheckBundle() bool

IsNewCheckBundle returns true if the check bundle was created.

func (*TrapCheck) RefreshCheckBundle

func (tc *TrapCheck) RefreshCheckBundle() (apiclient.CheckBundle, error)

RefreshCheckBundle will pull down a fresh copy from the API.

func (*TrapCheck) SendMetrics

func (tc *TrapCheck) SendMetrics(ctx context.Context, metrics bytes.Buffer) (*TrapResult, error)

SendMetrics submits the metrics to the broker metrics must be valid JSON encoded data for the broker httptrap check returns trap results in a structure or an error.

func (*TrapCheck) TraceMetrics

func (tc *TrapCheck) TraceMetrics(trace string) (string, error)

TraceMetrics allows changing the tracing of metric submissions dynamically, pass "" to disable tracing going forward. returns current setting or error. on error, the current setting will not be changed. Note: if going from no Logger to trace="-" the Logger will need to be set.

func (*TrapCheck) UpdateCheckTags

func (tc *TrapCheck) UpdateCheckTags(_ context.Context, tags []string) (*apiclient.CheckBundle, error)

type TrapResult

type TrapResult struct {
	CheckUUID       string        `json:"check_uuid"`
	Error           string        `json:"error,omitempty"`
	SubmitUUID      string        `json:"submit_uuid"`
	Filtered        uint64        `json:"filtered,omitempty"`
	Stats           uint64        `json:"stats"`
	SubmitDuration  time.Duration `json:"submit_dur"`
	LastReqDuration time.Duration `json:"last_req_dur"`
	BytesSent       int           `json:"bytes_sent"`
	BytesSentGzip   int           `json:"bytes_sent_gz"`
}