cmd

README

Go cmd helper.

This provides helpers on top of github.com/urfave/cli.

Overview

Install with:

go get github.com/hamba/cmd/v2

Note: This project has renamed the default branch from master to main. You will need to update your local environment.

Example

func yourAction(c *cli.Context) error {
    log, err := cmd.NewLogger(c)
	if err != nil {
		// Handle error.
	}

	stats, err := cmd.NewStatter(c, log)
	if err != nil {
		// Handle error.
	}

    tracer, err := cmd.NewTracer(c, log,
        semconv.ServiceNameKey.String("my-service"),
        semconv.ServiceVersionKey.String("1.0.0"),
    )
    if err != nil {
        // Handle error.
        return
    }
    defer tracer.Shutdown(context.Background())

    // Run your application here...
}

Flags

Logger

The logger flags are used by cmd.NewLogger to create a hamba.Logger.

FlagLogFormat: --log.format, $LOG_FORMAT

This flag sets the log formatter to use. The available options are logfmt (default), json, console.

Example: --log.format=console

FlagLogLevel: --log.level, $LOG_LEVEL

This flag sets the log level to filer on. The available options are debug, info (default), warn, error, crit.

Example: --log.level=error

FlagLogCtx: --log.ctx, $LOG_CTX

This flag sets contextual key value pairs to set on all log messages. This flag can be specified multiple times.

Example: --log.ctx="app=my-app" --log.ctx="zone=eu-west"

Statter

The statter flags are used by cmd.NewStatter to create a new `hamba.Statter.

FlagStatsDSN: --stats.dsn, $STATS_DSN

This flag sets the DSN describing the stats reporter to use. The available options are statsd, prometheus, l2met.

The DSN can in some situations specify the host and configuration values as shown in the below examples:

Statsd:

--stats.dsn="statsd://host:port?flushBytes=1432&flushInterval=10s"

The host and port are required. Optionally flushBytes and flushInterval can be set, controlling how often the stats will be sent to the Statsd server.

Prometheus:

--stats.dsn="prometheus://host:port"

or

--stats.dsn="prom://host:port"

The host and port are optional. If set they will start a prometheus http server on the specified host and port.

Victoria Metrics:

--stats.dsn="victoriametrics://host:port"

or

--stats.dsn="vm://host:port"

The host and port are optional. If set they will start a victoria metrics http server on the specified host and port.

l2met:

--stats.dsn="l2met://"

This report has no exposed options.

FlagStatsInterval: --stats.interval, $STATS_INTERVAL

This flag sets the interval at which the aggregated stats will be reported to the reporter.

Example: --stats-interval=10s

FlagStatsPrefix: --stats.prefix, $STATS_PREFIX

This flag sets the prefix attached to all stats keys.

Example: --stats.prefix=my-app.server

FlagStatsTags: --stats.tags, $STATS_TAGS

This flag sets tag key value pairs to set on all stats. This flag can be specified multiple times.

Example: --stats.tags="app=my-app" --stats.tags="zone=eu-west"

Tracer

The tracing flags are used by cmd.NewTracer to create a new open telemetry trace.TraceProvider.

FlagTracingExporter: --tracing.exporter, $TRACING_EXPORTER

This flag sets the exporter to send spans to. The available options are jaeger and zipkin.

Example: --tracing.exporter=jaeger

FlagTracingEndpoint: --tracing.endpoint, $TRACING_ENDPOINT

This flag sets the endpoint the exporter should send traces to.

Example: --tracing.endpoint="agent-host:port" or --tracing.endpoint="http://host:port/api/v2"

FlagTracingRatio: --tracing.ratio, $TRACING_RATIO

This flag sets the sample ratio of spans that will be reported to the exporter. This should be between 0 and 1.

Example: --tracing.ratio=0.2

Observer

The observe package exposes an Observer type which is essentially a helper that combines a logger, tracer and statter. It is useful if you use all three for your services and want to avoid carrying around many arguments.

Here is an example of how one might use it:

func runServer(c *cli.Context) error {
    ctx, cancel := context.WithCancel(c.Context)
    defer cancel()

    obsvr, err := cmd.New(c, svcName, version)
    if err != nil {
        return err
    }
    defer obsvr.Close()

    // Initialize components by passing the obsvr variable.
    return nil
}

func New(c *cli.Context, svc, version string) (*observe.Observer, error) {
	log, logCancel, err := NewLogger(c, svc)
	if err != nil {
		return nil, err
	}

	stats, statsCancel, err := NewStatter(c, log, svc)
	if err != nil {
		logCancel()
		return nil, err
	}

	tracer, traceCancel, err := NewTracer(c, log, svc, version)
	if err != nil {
		logCancel()
		statsCancel()
		return nil, err
	}

	return observe.New(log, stats, tracer, traceCancel, statsCancel, logCancel), nil
}

It also exposes NewFake which allows you to pass fake loggers, tracers and statters in your tests easily.

Documentation

Overview

Package cmd implements cmd helpers.

This provides helpers on top of `github.com/urfave/cli`.

Example usage:

var c *cli.Context // Get this from your action

log, err := cmd.NewLogger(c)
if err != nil {
	// Handle error.
}

stats, err := cmd.NewStatter(c, log)
if err != nil {
	// Handle error.
}

Index

• Constants
• Variables
• func NewLogger(c *cli.Context) (*logger.Logger, error)
• func NewStatter(c *cli.Context, log *logger.Logger, opts ...statter.Option) (*statter.Statter, error)
• func NewTracer(c *cli.Context, log *logger.Logger, resAttributes ...attribute.KeyValue) (*trace.TracerProvider, error)
• func Split(slice []string, sep string) ([][2]string, error)
• type Flags
  • func (f Flags) Merge(flags ...Flags) Flags

Examples

• NewLogger
• NewStatter
• NewTracer
• Split

Constants

const (
	FlagLogFormat = "log.format"
	FlagLogLevel  = "log.level"
	FlagLogCtx    = "log.ctx"
)

Log flag constants declared for CLI use.

const (
	FlagStatsDSN      = "stats.dsn"
	FlagStatsInterval = "stats.interval"
	FlagStatsPrefix   = "stats.prefix"
	FlagStatsTags     = "stats.tags"
)

Stats flag constants declared for CLI use.

const (
	FlagTracingExporter         = "tracing.exporter"
	FlagTracingEndpoint         = "tracing.endpoint"
	FlagTracingEndpointInsecure = "tracing.endpoint-insecure"
	FlagTracingTags             = "tracing.tags"
	FlagTracingRatio            = "tracing.ratio"
)

Tracing flag constants declared for CLI use.

Variables

var LogFlags = Flags{
	&cli.StringFlag{
		Name:    FlagLogFormat,
		Usage:   "Specify the format of logs. Supported formats: 'logfmt', 'json', 'console'",
		EnvVars: []string{"LOG_FORMAT"},
	},
	&cli.StringFlag{
		Name:    FlagLogLevel,
		Value:   "info",
		Usage:   "Specify the log level. e.g. 'debug', 'info', 'error'.",
		EnvVars: []string{"LOG_LEVEL"},
	},
	&cli.StringSliceFlag{
		Name:    FlagLogCtx,
		Usage:   "A list of context field appended to every log. Format: key=value.",
		EnvVars: []string{"LOG_CTX"},
	},
}

LogFlags are flags that configure logging.

var MonitoringFlags = Flags{}.Merge(LogFlags, StatsFlags, TracingFlags)

MonitoringFlags are flags that configure logging, stats and tracing.

var StatsFlags = Flags{
	&cli.StringFlag{
		Name:    FlagStatsDSN,
		Usage:   "The DSN of a stats backend.",
		EnvVars: []string{"STATS_DSN"},
	},
	&cli.DurationFlag{
		Name:    FlagStatsInterval,
		Usage:   "The frequency at which the stats are reported.",
		Value:   time.Second,
		EnvVars: []string{"STATS_INTERVAL"},
	},
	&cli.StringFlag{
		Name:    FlagStatsPrefix,
		Usage:   "The prefix of the measurements names.",
		EnvVars: []string{"STATS_PREFIX"},
	},
	&cli.StringSliceFlag{
		Name:    FlagStatsTags,
		Usage:   "A list of tags appended to every measurement. Format: key=value.",
		EnvVars: []string{"STATS_TAGS"},
	},
}

StatsFlags are flags that configure stats.

var TracingFlags = Flags{
	&cli.StringFlag{
		Name:    FlagTracingExporter,
		Usage:   "The tracing backend. Supported: 'zipkin', 'otlphttp', 'otlpgrpc.",
		EnvVars: []string{"TRACING_EXPORTER"},
	},
	&cli.StringFlag{
		Name:    FlagTracingEndpoint,
		Usage:   "The tracing backend endpoint.",
		EnvVars: []string{"TRACING_ENDPOINT"},
	},
	&cli.BoolFlag{
		Name:    FlagTracingEndpointInsecure,
		Usage:   "Determines if the endpoint is insecure.",
		EnvVars: []string{"TRACING_ENDPOINT_INSECURE"},
	},
	&cli.StringSliceFlag{
		Name:    FlagTracingTags,
		Usage:   "A list of tags appended to every trace. Format: key=value.",
		EnvVars: []string{"TRACING_TAGS"},
	},
	&cli.Float64Flag{
		Name:    FlagTracingRatio,
		Usage:   "The ratio between 0 and 1 of sample traces to take.",
		Value:   0.5,
		EnvVars: []string{"TRACING_RATIO"},
	},
}

TracingFlags are flags that configure tracing.

Functions

func NewLogger

func NewLogger(c *cli.Context) (*logger.Logger, error)

NewLogger returns a logger configured from the cli.

Example

var c *cli.Context // Get this from your action

log, err := cmd.NewLogger(c)
if err != nil {
	// Handle error.
	return
}

_ = log

func NewStatter

func NewStatter(c *cli.Context, log *logger.Logger, opts ...statter.Option) (*statter.Statter, error)

NewStatter returns a statter configured from the cli.

Example

var c *cli.Context // Get this from your action

log, err := cmd.NewLogger(c)
if err != nil {
	// Handle error.
	return
}

stats, err := cmd.NewStatter(c, log)
if err != nil {
	// Handle error.
	return
}
defer stats.Close()

_ = stats

func NewTracer

func NewTracer(c *cli.Context, log *logger.Logger, resAttributes ...attribute.KeyValue) (*trace.TracerProvider, error)

NewTracer returns a tracer configures from the cli.

Example

var c *cli.Context // Get this from your action

log, err := cmd.NewLogger(c)
if err != nil {
	// Handle error.
	return
}

tracer, err := cmd.NewTracer(c, log,
	semconv.ServiceNameKey.String("my-service"),
	semconv.ServiceVersionKey.String("1.0.0"),
)
if err != nil {
	// Handle error.
	return
}
defer tracer.Shutdown(context.Background())

_ = tracer

func Split

func Split(slice []string, sep string) ([][2]string, error)

Split splits a slice of strings into an slice of arrays using the given separator.

Example

input := []string{"a=b", "foo=bar"} // Usually from a cli.StringSlice

tags, err := cmd.Split(input, "=")
if err != nil {
	// Handle error
}

fmt.Println(tags)

Output:

[[a b] [foo bar]]

Types

type Flags

type Flags []cli.Flag

Flags represents a set of CLI flags.

func (Flags) Merge

func (f Flags) Merge(flags ...Flags) Flags

Merge joins one or more Flags together, making a new set.