Documentation
¶
Overview ¶
Package metrics emits Prometheus-compatible metrics for one-shot nSelf CLI command invocations (backup.go: backup/verify results; license.go: license grace-period state; stripe.go: webhook processing outcomes) by writing node_exporter textfile-collector .prom files rather than serving a live /metrics endpoint.
Purpose: let short-lived CLI processes (a single `nself backup create` run, a license grace check, a webhook handler invocation) surface Prometheus metrics even though the process exits before any scraper could reach it — node_exporter picks up the written .prom files on its own schedule instead.
Inputs: a *Record struct per emitter (BackupRecord, VerifyRecord, LicenseRecord, StripeEventRecord, etc.) describing the single outcome to record, plus an optional TextfileDir override (defaults to DefaultTextfileDir).
Outputs: atomically-written `.prom` files under the textfile collector directory, one gauge/counter set per emitter, each file fully replaced (not appended) on every run.
Constraints: this package is for processes that exit — it has no live registry and cannot serve /metrics itself. A long-running process (a daemon, an embedded server) belongs in internal/observability instead, which keeps a live *prometheus.Registry and HTTP handler in memory. Resolved as a deliberate split, not overlapping responsibility, in CLI-R14 (2026-08-23): the two packages instrument disjoint process lifecycles. Current importers: internal/backup/create.go and internal/backup/verify.go (EmitBackup/EmitVerify); license.go and stripe.go's emitters are wired for the license-grace and Stripe-webhook features and are exercised by this package's own tests but have no production caller yet — left in place as forward wiring, out of scope for this ticket's dedup pass.
Package metrics — license.go emits Prometheus metrics for license grace period monitoring. Metrics are written as textfile collector .prom files for node_exporter to scrape.
Metrics:
- nself_license_grace_days_remaining (gauge)
- nself_license_offline_seconds (gauge)
Package metrics — stripe.go emits Prometheus metrics for Stripe webhook processing. These metrics enable alerting on webhook failures, latency, outbox depth, and signature attacks.
Metrics (spec G-31-11):
- nself_stripe_event_received_total{type,result} (counter)
- nself_stripe_event_duration_seconds{type} (histogram via gauge of last)
- nself_stripe_outbox_depth (gauge)
- nself_stripe_signature_failures_total (counter)
Index ¶
- Constants
- func EmitBackup(r BackupRecord) error
- func EmitLicense(r LicenseRecord) error
- func EmitStripeEvent(r StripeEventRecord) error
- func EmitStripeOutbox(r StripeOutboxRecord) error
- func EmitStripeSignatureFailure(r StripeSignatureRecord) error
- func EmitVerify(r VerifyRecord) error
- type BackupRecord
- type LicenseRecord
- type StripeEventRecord
- type StripeOutboxRecord
- type StripeSignatureRecord
- type VerifyRecord
Constants ¶
const DefaultTextfileDir = "/var/lib/node_exporter/textfile_collector"
DefaultTextfileDir is the node_exporter textfile collector directory.
Variables ¶
This section is empty.
Functions ¶
func EmitBackup ¶
func EmitBackup(r BackupRecord) error
EmitBackup writes a .prom file named `nself_backup_{type}.prom` atomically. The file is replaced each run, not appended, so gauges reflect the latest result only. Counters are cumulative and read-back before rewrite.
func EmitLicense ¶
func EmitLicense(r LicenseRecord) error
EmitLicense writes license grace metrics to nself_license.prom.
func EmitStripeEvent ¶
func EmitStripeEvent(r StripeEventRecord) error
EmitStripeEvent writes stripe event processing metrics.
func EmitStripeOutbox ¶
func EmitStripeOutbox(r StripeOutboxRecord) error
EmitStripeOutbox writes the current outbox depth gauge.
func EmitStripeSignatureFailure ¶
func EmitStripeSignatureFailure(r StripeSignatureRecord) error
EmitStripeSignatureFailure increments the signature failure counter.
func EmitVerify ¶
func EmitVerify(r VerifyRecord) error
EmitVerify writes the restore-test verify result to its own .prom file.
Types ¶
type BackupRecord ¶
type BackupRecord struct {
Env string // prod, staging, dev
Type string // full, wal, metadata, minio
Success bool // completion result
DurationSec float64 // total wall-clock seconds
Bytes int64 // archive size on disk
Encrypted bool // whether age encryption was applied
Timestamp time.Time // completion time
TextfileDir string // overrides DefaultTextfileDir when non-empty
}
BackupRecord is the signal set emitted on every nself backup create exit.
type LicenseRecord ¶
type LicenseRecord struct {
Host string // hostname label (e.g., "nclaw-prod")
Env string // prod, staging, dev
GraceDaysRemaining float64 // days until hard stop; negative if past
OfflineSeconds float64 // seconds since last successful validation
GraceState string // valid, grace_soft, grace_hard, expired
Tier string // license tier
TextfileDir string // overrides DefaultTextfileDir when non-empty
}
LicenseRecord captures the current license grace state for metric emission.
type StripeEventRecord ¶
type StripeEventRecord struct {
EventType string // e.g., "customer.subscription.created"
Result string // "ok" or "error"
DurationSec float64 // processing time in seconds
TextfileDir string // overrides DefaultTextfileDir when non-empty
}
StripeEventRecord captures a single Stripe webhook event for metric emission.
type StripeOutboxRecord ¶
type StripeOutboxRecord struct {
Depth int // number of events waiting in outbox
TextfileDir string // overrides DefaultTextfileDir when non-empty
}
StripeOutboxRecord captures the current outbox state.
type StripeSignatureRecord ¶
type StripeSignatureRecord struct {
TextfileDir string // overrides DefaultTextfileDir when non-empty
}
StripeSignatureRecord captures a signature verification failure.
Source Files