Help us shape the future of Go! Take the 2026 Go Developer Survey

metrics

package
v0.2.49 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MPL-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package metrics wires OpenTelemetry tracing and metrics for the chassis.

Configuration is via standard OTel environment variables:

  • OTEL_EXPORTER_OTLP_ENDPOINT (e.g. http://localhost:4318)
  • OTEL_EXPORTER_OTLP_PROTOCOL (http/protobuf | grpc)
  • OTEL_SERVICE_NAME (default: txco-chassis)
  • OTEL_RESOURCE_ATTRIBUTES (extra resource attributes)

If no OTLP endpoint is set the SDK still installs a working tracer/meter provider; spans and metrics are recorded in-process but not exported.

Index

Constants

View Source
const (
	AttrEventsSource        = "txco.events.source"
	AttrOpName              = "txco.op.name"
	AttrTenantSlug          = "txco.tenant.slug"
	AttrSecretName          = "txco.secret.name"
	AttrTelemetryDropReason = "txco.telemetry.drop_reason"
	AttrWebSearchOutcome    = "txco.websearch.outcome"
)

Attribute keys used across the chassis. These follow OTel semantic-convention style (lower-snake-case, dotted namespace) so they roll up cleanly in any OTLP backend.

Variables

This section is empty.

Functions

This section is empty.

Types

type Metrics

type Metrics struct {
	Tracer trace.Tracer
	Meter  metric.Meter

	EventsReceived       metric.Int64Counter
	EventsResponseTimeMs metric.Int64Histogram
	OpTotal              metric.Int64Counter
	OpDurationMs         metric.Int64Histogram

	// SecretMaterialized increments once per (tenant_slug, secret_name)
	// reference the processor's splice resolves for an op (cache hit
	// or miss — both count as a reference). Lets operators detect a
	// runaway op that materializes the same secret thousands of times
	// per second, AND see the per-tenant access pattern for audit/
	// quota purposes. NEVER record the cleartext or the cleartext
	// length here — only the names.
	SecretMaterialized metric.Int64Counter

	// TelemetryDropped counts tenant metric intents the request-end
	// telemetry processor dropped, tagged tenant slug + drop reason
	// (validation failure, no exporter config, export error, …). This
	// is the chassis-side diagnostic for "my metrics aren't arriving".
	// NEVER record metric names or values here — only counts + reason.
	TelemetryDropped metric.Int64Counter

	// WebSearchRequests counts txco://web/search calls, tagged tenant slug
	// + outcome (`ok` or the error code without its txco_web_ prefix).
	// NEVER record the query or a result here.
	WebSearchRequests metric.Int64Counter
	// contains filtered or unexported fields
}

Metrics holds the chassis tracer, meter, and pre-built instruments.

func New

func New(ctx context.Context, conf config.Config, logger *zap.Logger) *Metrics

New initialises OTel providers and returns a Metrics with pre-built instruments. Call Metrics.Shutdown(ctx) before process exit to flush.

func (*Metrics) RecordEvent

func (m *Metrics) RecordEvent(ctx context.Context, source string, durationMs int64)

RecordEvent increments the events.received counter and records the events.response_time histogram, both tagged with the event source (web, tcp, cron, ...). Call once per envelope processed.

func (*Metrics) RecordOp

func (m *Metrics) RecordOp(ctx context.Context, opName string, durationMs int64)

RecordOp increments the op.count counter and records the op.duration histogram, both tagged with the operation name.

func (*Metrics) RecordSecretMaterialize

func (m *Metrics) RecordSecretMaterialize(ctx context.Context, tenantSlug, secretName string)

RecordSecretMaterialize increments the secret.materialize counter tagged with tenant slug + secret name. Nil-safe: if m or m.SecretMaterialized is nil (the chassis was built without metrics, e.g. some unit tests), this is a no-op. NEVER pass the cleartext or any portion of it — only the NAME.

func (*Metrics) RecordTelemetryDrop added in v0.2.19

func (m *Metrics) RecordTelemetryDrop(ctx context.Context, tenantSlug, reason string, n int64)

RecordTelemetryDrop adds n to the telemetry.dropped counter tagged with tenant slug + drop reason. Nil-safe like RecordSecretMaterialize (no-op when the chassis was built without metrics). Reasons are a small fixed vocabulary (unpinned, disabled, invalid_*, over_limit, bad_endpoint, secret_error, export_error) — never metric names, values, or attribute content.

func (*Metrics) RecordWebSearch added in v0.2.49

func (m *Metrics) RecordWebSearch(ctx context.Context, tenantSlug, outcome string)

RecordWebSearch increments the websearch.requests counter tagged with tenant slug + outcome. Nil-safe like RecordSecretMaterialize. The outcome is a fixed vocabulary (ok, or an error code): never the query.

func (*Metrics) Shutdown

func (m *Metrics) Shutdown(ctx context.Context) error

Shutdown flushes any pending telemetry. Call from main.go on signal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL