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
- type Config
- type Metrics
- func (m *Metrics) ExtensionMeter(name string) metric.Meter
- func (m *Metrics) Gather(ctx context.Context) ([]byte, error)
- func (m *Metrics) Handler() http.Handler
- func (m *Metrics) Meter() metric.Meter
- func (m *Metrics) RecordFailOpen(ctx context.Context, path string)
- func (m *Metrics) RecordGitCloneFirstByte(ctx context.Context, d time.Duration)
- func (m *Metrics) RecordGitConcurrency(ctx context.Context, op string, inflight int64)
- func (m *Metrics) RecordGitOp(ctx context.Context, op, outcome string, d time.Duration)
- func (m *Metrics) RecordHTTP(ctx context.Context, route, method string, status int, d time.Duration)
- func (m *Metrics) RecordJudgeTokens(ctx context.Context, prompt, completion int)
- func (m *Metrics) RecordMCPSweep(ctx context.Context, opened int, err error)
- func (m *Metrics) RecordModelInput(ctx context.Context, op, verdict string, inputTokens int)
- func (m *Metrics) RecordPublishSubmitted(ctx context.Context)
- func (m *Metrics) RecordQueueJob(ctx context.Context, queue, kind, outcome string, d time.Duration)
- func (m *Metrics) RecordQueueStats(ctx context.Context, queue string, depth int64, oldest time.Duration)
- func (m *Metrics) RecordScanStage(ctx context.Context, stage string, d time.Duration, findings int, err error)
- func (m *Metrics) RecordVerdict(ctx context.Context, verdict string)
- func (m *Metrics) RecordWebhookDelivery(ctx context.Context, outcome string)
- func (m *Metrics) Shutdown(ctx context.Context) error
Constants ¶
const ( VerdictClean = "clean" VerdictReview = "needs_review" VerdictBlocked = "blocked" )
Verdict values recorded by RecordVerdict. They match the version status vocabulary the pipeline already uses.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
RecordFailOpen counts one fail-open event on the named path.
func (*Metrics) RecordGitCloneFirstByte ¶
RecordGitCloneFirstByte records time-to-first-byte for a clone/fetch — the "p95 < 2 s first-byte" SLI.
func (*Metrics) RecordGitConcurrency ¶
RecordGitConcurrency publishes the in-flight count for a git op class.
func (*Metrics) RecordGitOp ¶
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 ¶
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 ¶
RecordMCPSweep counts one sweep run and the alerts it opened.
func (*Metrics) RecordModelInput ¶
RecordModelInput counts one model-input call by op and verdict, and the judge input tokens it spent.
func (*Metrics) RecordPublishSubmitted ¶
RecordPublishSubmitted counts a version entering the pipeline.
func (*Metrics) RecordQueueJob ¶
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 ¶
RecordVerdict counts one pipeline verdict. An unrecognized verdict is dropped rather than silently folded into another bucket.
func (*Metrics) RecordWebhookDelivery ¶
RecordWebhookDelivery counts one delivery attempt ("ok" | "error" | "throttled").