metrics

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package metrics is the telemetry seam: one instrument set, two ways out of the process.

  • OTLP/HTTP export (opt-in, AGENTRY_OTEL_ENDPOINT). On SaaS this points at the ADOT sidecar, which writes the metrics to CloudWatch as EMF under the `Agentry` namespace — which is where the alarms read them.
  • A Prometheus exposition endpoint at /metrics, always on (a self-hosted operator gets the same numbers without running a collector).

Instrument names are the CloudWatch metric names the hosted deployment's dashboards and alarms reference, verbatim — QueueAgeSeconds, ScanStageErrors, ScanStageRuns and the rest. They are deliberately NOT renamed to OTel dotted convention on the way out: an alarm that reads a metric nobody emits is worse than an unidiomatic name, and the same names appear in the Prometheus output so the two views agree.

A nil *Metrics is usable: every method is a no-op. Call sites therefore never need a nil check, and code paths that run without telemetry (tests, `agentry validate`) stay unchanged.

Index

Constants

View Source
const (
	VerdictClean   = "clean"
	VerdictReview  = "needs_review"
	VerdictBlocked = "blocked"
)

Verdict values recorded by RecordVerdict. They match the version status vocabulary the pipeline already uses.

View Source
const (
	FailOpenAuditStreamDrop = "audit_stream_drop"
	FailOpenOSVNotChecked   = "osv_not_checked"
	FailOpenOSVError        = "osv_error"
	// FailOpenVersionNotChecked counts declared MCP server versions S7 did
	// not check against their package registry: the check is
	// off, or the registry gave no answer, and the version publishes.
	FailOpenVersionNotChecked = "version_not_checked"
	// FailOpenHistoryNotScanned counts git-tag publishes whose history S2
	// could not (fully) scan for secrets.
	FailOpenHistoryNotScanned = "history_not_scanned"
	// FailOpenDirectoryErasure counts account erasures whose directory
	// half did not happen: the retries ran out, or the retry could not be
	// queued. The registry's erasure stands; the sign-in
	// account is left for the operator to delete.
	FailOpenDirectoryErasure = "directory_erasure"
)

FailOpen paths, the attribute values RecordFailOpen accepts. Each is a place the code chooses to continue rather than stop when a control is unavailable, so its count is the honest measure of how often that control did not run.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// OTLPEndpoint is the collector base URL (AGENTRY_OTEL_ENDPOINT), e.g.
	// http://localhost:4318. Empty disables OTLP export entirely — no
	// background exporter, no connection attempts.
	OTLPEndpoint string
	// ServiceName and ServiceVersion label the resource.
	ServiceName    string
	ServiceVersion string
	// Role is the agentryd role (api|git|worker|all); it becomes a resource
	// attribute so per-service dashboards can split by it.
	Role string
	// Env is dev|staging|prod.
	Env string
	// ExportInterval is how often the OTLP reader flushes. Zero uses 30s,
	// which matches the ADOT collector's batch timeout.
	ExportInterval time.Duration
}

Config selects the exporters.

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics owns the meter provider and the instrument set.

func New

func New(ctx context.Context, cfg Config) (*Metrics, error)

New builds the meter provider and instruments. It returns an error only for a malformed OTLP endpoint; every other failure mode degrades to the scrape-only reader rather than refusing to start, because losing telemetry must never take the registry down with it.

func (*Metrics) ExtensionMeter

func (m *Metrics) ExtensionMeter(name string) metric.Meter

ExtensionMeter is the meter an extension named name creates its own instruments on. It is the same provider as the core's, so what the extension records is scraped from /metrics with the core's resource labels and leaves through OTLP when that is configured; only the instrumentation scope differs. In the scrape the core's series win: Gather renders the core's scope first and drops a later family any of whose sample names is already taken, and a series label never overrides a resource label. The OTLP export keeps each scope's instruments apart and is protected only by the naming rule pkg/extension's Deps.Meter states. Returns a no-op meter on a nil receiver, never nil.

func (*Metrics) Gather

func (m *Metrics) Gather(ctx context.Context) ([]byte, error)

Gather collects the current values from the manual reader and renders them in the Prometheus text exposition format.

The rendering is done here rather than by go.opentelemetry.io/otel/exporters/ prometheus for two reasons. First, that exporter would pull the whole prometheus/client_golang tree in for one HTTP handler. Second — and this is the one that matters operationally — it rewrites instrument names on the way out (unit suffixes, `_total` on counters), so `QueueAgeSeconds` in a CloudWatch alarm and the same series scraped from a self-hosted box would no longer share a name. One vocabulary across both backends is worth ~120 lines of encoder.

func (*Metrics) Handler

func (m *Metrics) Handler() http.Handler

Handler serves the Prometheus exposition of the current instrument values. It is mounted OUTSIDE /api/v1 and unauthenticated (see docs/ops/ deployment.md): bind agentryd to a private interface, or keep /metrics off the public listener at the proxy, if the numbers are sensitive.

func (*Metrics) Meter

func (m *Metrics) Meter() metric.Meter

Meter exposes the provider's meter for callers that need an instrument this package does not wrap. Returns a no-op meter on a nil receiver.

func (*Metrics) RecordFailOpen

func (m *Metrics) RecordFailOpen(ctx context.Context, path string)

RecordFailOpen counts one fail-open event on the named path.

func (*Metrics) RecordGitCloneFirstByte

func (m *Metrics) RecordGitCloneFirstByte(ctx context.Context, d time.Duration)

RecordGitCloneFirstByte records time-to-first-byte for a clone/fetch — the "p95 < 2 s first-byte" SLI.

func (*Metrics) RecordGitConcurrency

func (m *Metrics) RecordGitConcurrency(ctx context.Context, op string, inflight int64)

RecordGitConcurrency publishes the in-flight count for a git op class.

func (*Metrics) RecordGitOp

func (m *Metrics) RecordGitOp(ctx context.Context, op, outcome string, d time.Duration)

RecordGitOp records a completed git smart-HTTP operation.

func (*Metrics) RecordHTTP

func (m *Metrics) RecordHTTP(ctx context.Context, route, method string, status int, d time.Duration)

RecordHTTP records one served request. route is a low-cardinality route class (the matched pattern), never the raw path: a per-path metric would let any caller mint unbounded time series by varying a path segment.

func (*Metrics) RecordJudgeTokens

func (m *Metrics) RecordJudgeTokens(ctx context.Context, prompt, completion int)

RecordJudgeTokens counts one adjudication's token use by kind. It records counts, not a price: the price per token is the operator's to apply to these counts, and a count is what every provider reports.

func (*Metrics) RecordMCPSweep

func (m *Metrics) RecordMCPSweep(ctx context.Context, opened int, err error)

RecordMCPSweep counts one sweep run and the alerts it opened.

func (*Metrics) RecordModelInput

func (m *Metrics) RecordModelInput(ctx context.Context, op, verdict string, inputTokens int)

RecordModelInput counts one model-input call by op and verdict, and the judge input tokens it spent.

func (*Metrics) RecordPublishSubmitted

func (m *Metrics) RecordPublishSubmitted(ctx context.Context)

RecordPublishSubmitted counts a version entering the pipeline.

func (*Metrics) RecordQueueJob

func (m *Metrics) RecordQueueJob(ctx context.Context, queue, kind, outcome string, d time.Duration)

RecordQueueJob records one job's terminal outcome ("ok" | "error").

func (*Metrics) RecordQueueStats

func (m *Metrics) RecordQueueStats(ctx context.Context, queue string, depth int64, oldest time.Duration)

RecordQueueStats publishes the depth and oldest-job age of one queue.

func (*Metrics) RecordScanStage

func (m *Metrics) RecordScanStage(ctx context.Context, stage string, d time.Duration, findings int, err error)

RecordScanStage records one stage execution: always a run, plus an error when it failed and the number of findings it produced.

func (*Metrics) RecordVerdict

func (m *Metrics) RecordVerdict(ctx context.Context, verdict string)

RecordVerdict counts one pipeline verdict. An unrecognized verdict is dropped rather than silently folded into another bucket.

func (*Metrics) RecordWebhookDelivery

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

RecordWebhookDelivery counts one delivery attempt ("ok" | "error" | "throttled").

func (*Metrics) Shutdown

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

Shutdown flushes and stops the exporters. Safe on a nil receiver.

Jump to

Keyboard shortcuts

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