https://github.com/hamba/cmd
Go cmd helper
https://github.com/hamba/cmd
cli cmd golang helper
Last synced: about 1 year ago
JSON representation
Go cmd helper
- Host: GitHub
- URL: https://github.com/hamba/cmd
- Owner: hamba
- License: mit
- Created: 2019-02-13T13:04:17.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-04-14T00:37:28.000Z (about 1 year ago)
- Last Synced: 2025-04-14T01:30:01.859Z (about 1 year ago)
- Topics: cli, cmd, golang, helper
- Language: Go
- Size: 426 KB
- Stars: 6
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://goreportcard.com/report/github.com/hamba/cmd)
[](https://github.com/hamba/cmd/actions)
[](https://coveralls.io/github/hamba/cmd?branch=master)
[](https://pkg.go.dev/github.com/hamba/cmd/v2)
[](https://github.com/hamba/cmd/releases)
[](https://raw.githubusercontent.com/hamba/cmd/master/LICENSE)
Go cmd helper.
This provides helpers on top of `github.com/urfave/cli`.
## Overview
Install with:
```shell
go get github.com/hamba/cmd/v2
```
## Example
```go
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...
return nil
}
```
## 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`, `victoriametrics`.
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"`
### Profiler
The profiler flags are used by `cmd.NewProfiler` to create a Pyroscope `*pyroscope.Profiler`.
#### FlagProfilingDSN: *--profiling.dsn, $PROFILING_DSN*
This flag configures the URL, authentication and optionally the Tenant ID for Pyroscope.
Example: `--profiling.dsn=https://user:pass@host/path?token=auth-token&tenantid=my-tenant-id`
#### FlagProfileUploadRate: *--profiling.upload-rate, $PROFILING_UPLOAD_RATE*
This flag configures the rate at which profiles are uploaded.
Example: `--profiling.upload-rate=10s`
#### FlagProfilingTags: *--profiling.tags, $PROFILING_TAGS*
This configures a list of tags appended to every profile. This flag can be specified multiple times.
Example: `--profiling.tags="app=my-app" --profiling.tags="zone=eu-west"`
#### FlagProfilingTypes: *--profiling.types, $PROFILING_TYPES*
This configures the profile types that are captured. By default all supported types are captured. This flag can be specified multiple times.
Example: `--profiling.types=cpu --profiling.types=inuse_object`
### 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 `zipkin`, `otlphttp` and `otlpgrpc`.
Example: `--tracing.exporter=otlphttp`
#### 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"`
#### FlagTracingEndpointInsecure: *--tracing.endpoint-insecure, $TRACING_ENDPOINT_INSECURE*
This flag sets the endpoint the exporter should send traces to.
Example: `--tracing.endpoint-insecure`
#### 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`
#### FlagTracingTags: *--tracing.tags, $TRACING_TAGS*
This flag sets a list of tags appended to every trace. This flag can be specified multiple times.
Example: `--tracing.tags="app=my-app" --tracing.tags="zone=eu-west"`
### 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:
```go
func yourAction(c *cli.Context) error {
obsvr, err := observe.NewFromCLI(c, "my-service", &observe.Options{
LogTimestamps: true,
StatsRuntime: true,
TracingAttrs: []attribute.KeyValue{
semconv.ServiceVersionKey.String("1.0.0"),
},
})
if err != nil {
return err
}
defer obsvr.Close()
// Run your application here...
return nil
}
```
It also exposes `NewFake` which allows you to pass fake loggers, tracers and statters in your tests easily.