Documentation
¶
Overview ¶
Package telemetry is vault's tracing and metrics plumbing: the instrumentation scope on every vault span, a way to mark a span failed that never copies error text, and label vectors over a go-utils metrics sink.
Nothing here ever takes a secret value, a secret, flag or config key, a tenant or a user. Span attributes are counts, booleans and fixed enums, and metric labels are fixed enums. Error text stays off spans because store and rotator errors quote keys and, from a careless rotator, values.
Index ¶
- Constants
- Variables
- func Detach(ctx context.Context) context.Context
- func ErrorType(err error) string
- func Fail(span trace.Span, err error)
- func FailAs(span trace.Span, class string, err error)
- func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- type Counter
- type Histogram
Constants ¶
const ( // MetricSecretOperations counts secret service calls. // Labels: op (get, get_version, set, delete), result (ok, not_found, error). MetricSecretOperations = "vault_secret_operations_attempted_total" // MetricCryptoOperations counts AES-GCM encrypt and decrypt calls the // secret service makes. Labels: op (encrypt, decrypt), result (ok, error). MetricCryptoOperations = "vault_crypto_operations_attempted_total" // MetricFlagEvaluations counts flag evaluations. // Labels: source (cache, store), result (ok, not_found, error). MetricFlagEvaluations = "vault_flags_evaluated_total" // MetricRotations counts rotation attempts. // Labels: trigger (scheduled, manual), result (ok, error). MetricRotations = "vault_rotations_attempted_total" // MetricRotationDuration times rotation attempts, the rotator included. // Labels: trigger (scheduled, manual), result (ok, error). MetricRotationDuration = "vault_rotation_duration_seconds" // MetricConfigPolls counts the polls config sources make to spot // changes. Labels: source (confy, database), result (changed, // unchanged, error). MetricConfigPolls = "vault_config_sources_polled_total" )
The metric names vault records. A Forge app scrapes each one with its namespace prefix, so vault_rotations_attempted_total appears as forge_vault_rotations_attempted_total.
const ( ResultOK = "ok" ResultNotFound = "not_found" ResultError = "error" )
Label values shared by more than one metric.
const ScopeName = "github.com/xraph/vault"
ScopeName is the instrumentation scope on every span vault starts.
Variables ¶
var RotationDurationBuckets = []float64{0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10, 30, 60, 300}
RotationDurationBuckets are the bounds of MetricRotationDuration, in seconds. A rotator can call out to another system, and a rotation has to finish inside the five minute claim lease, so the top bucket is 300s.
Functions ¶
func Detach ¶
Detach returns ctx without its span, keeping its values and its cancellation. A long-lived loop calls it once on the ctx it was handed: that ctx can carry forge's "start <ext>" span or a request's server span, and grove starts a db.client span under any valid span context, even an ended one. Without Detach every idle tick's query would land in that old trace.
func ErrorType ¶
ErrorType names err without quoting it: a vault sentinel's name when err wraps one, otherwise the Go type of the innermost error in the chain.
func Fail ¶
Fail marks span as failed. The status description and the exception event's exception.type are both ErrorType(err), never err.Error().
func FailAs ¶
FailAs is Fail with the status description set to class, a short name for the step that failed, such as "decrypt failed". An empty class means ErrorType(err). The exception event still carries ErrorType(err).
func Start ¶
func Start(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
Start starts an internal span on the global tracer provider, which forge.New installs. It looks the tracer up on every call, so a provider installed after vault was built still gets the spans.
func StartRoot ¶
func StartRoot(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartRoot starts a span that begins its own trace, whatever span ctx carries. Background work uses it: a poll loop's ctx can carry the span of the call that started the loop, and every later tick would otherwise hang off that long-finished trace.
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
Counter is a counter declared with label keys. Children are created on first use and cached, so a hot path takes no registry lock. A nil *Counter records nothing, which is what a nil sink gives you.
func NewCounter ¶
NewCounter declares a counter on m. It returns nil when m is nil.
type Histogram ¶
type Histogram struct {
// contains filtered or unexported fields
}
Histogram is a histogram declared with label keys. A nil *Histogram records nothing.
Source Files