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
- type Metrics
- func (m *Metrics) RecordEvent(ctx context.Context, source string, durationMs int64)
- func (m *Metrics) RecordOp(ctx context.Context, opName string, durationMs int64)
- func (m *Metrics) RecordSecretMaterialize(ctx context.Context, tenantSlug, secretName string)
- func (m *Metrics) RecordTelemetryDrop(ctx context.Context, tenantSlug, reason string, n int64)
- func (m *Metrics) Shutdown(ctx context.Context) error
Constants ¶
const ( AttrEventsSource = "txco.events.source" AttrOpName = "txco.op.name" AttrTenantSlug = "txco.tenant.slug" AttrSecretName = "txco.secret.name" AttrTelemetryDropReason = "txco.telemetry.drop_reason" )
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
// contains filtered or unexported fields
}
Metrics holds the chassis tracer, meter, and pre-built instruments.
func New ¶
New initialises OTel providers and returns a Metrics with pre-built instruments. Call Metrics.Shutdown(ctx) before process exit to flush.
func (*Metrics) RecordEvent ¶
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 ¶
RecordOp increments the op.count counter and records the op.duration histogram, both tagged with the operation name.
func (*Metrics) RecordSecretMaterialize ¶
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
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.
Source Files