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

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

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) (*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"
	FlagTracingRatio    = "tracing.ratio"
)

Tracing flag constants declared for CLI use.

const FlagPort = "port"

FlagPort contains the flag name for a server port.

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 ServerFlags = Flags{
	&cli.StringFlag{
		Name:    FlagPort,
		Value:   "80",
		Usage:   "Port for HTTP server to listen on",
		EnvVars: []string{"PORT"},
	},
}

ServerFlags are flags that configure a server. Deprecated: There is no standardisation around this. It is preferred to make your own flag.

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: 'jaeger', 'zipkin'.",
		EnvVars: []string{"TRACING_EXPORTER"},
	},
	&cli.StringFlag{
		Name:    FlagTracingEndpoint,
		Usage:   "The tracing backend endpoint.",
		EnvVars: []string{"TRACING_ENDPOINT"},
	},
	&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) (*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.