Skip to content

PATTERN Cited by 1 source

Five-category service knowledge schema

Intent

Capture per-service infrastructure knowledge in a fixed, typed, five-axis schema so that downstream AI-agent retrieval, composition, and cross-service reasoning can rely on every service memory having the same shape.

The five axes, in Grafana Assistant's canonical framing (Source: sources/2026-05-01-grafana-how-grafana-assistant-learns-your-infrastructure-before-you-even-ask):

  1. Identity and purpose — "What the service is, what it does, which namespace and cluster it belongs to, and what technology stack it uses."
  2. Key metrics — "The metric names and labels relevant to the service, including golden signals such as latency, error rate, traffic, and saturation. Not generic guesses, but the actual metric names from your Prometheus data sources."
  3. Deployment topology — "Kubernetes resources, replica counts, scaling configurations, and container details."
  4. Dependencies — "Upstream and downstream service connections, database and cache relationships, message queue interactions, and external integrations."
  5. Log structure — "Available log labels and their values, detected log formats (JSON, logfmt, or unstructured), common patterns, and extracted field names."

Why a fixed schema is load-bearing

Typed schema makes the memory corpus composable in ways freeform summaries can't be:

  • Predictable retrieval. "What metrics does X emit?" reliably pulls the Key-metrics chunk.
  • Cross-service reasoning. "What services depend on postgres-primary?" is a tractable query against every memory's Dependencies field — impossible if dependencies are buried in freeform prose.
  • Chunk-level semantic search. Each axis can be embedded as its own chunk, so queries about "latency metrics" match Key-metrics chunks directly without diluting against the full service summary.
  • Contract for agents producing the memory. The swarm's summarisation agents have a clear target: produce five well-defined fields, not "describe this service."
  • Quality gate. Missing or malformed fields are detectable and can trigger retry/validation.

Contrast with freeform summary

Meta's precompute engine (2026-04-06) produces per-module markdown files — freeform prose organised by convention, not typed schema. That shape is better-fitted to code modules where the salient knowledge varies per module (some modules have complex state invariants; others have tricky retry semantics; no fixed template covers all).

The Grafana infrastructure-memory shape is better-fitted where the salient knowledge is schematic — every service has identity, metrics, topology, dependencies, logs — so typing unlocks the composition properties listed above.

When to apply this pattern

  • Every entity in your domain has the same knowledge shape. Services, customers, accounts, products — anywhere there's a regular "what is this thing?" schema.
  • Cross-entity reasoning is a primary query pattern. "Which services depend on X?" across the corpus.
  • You need chunk-level retrieval precision. Freeform documents dilute similarity scores; typed chunks match more precisely.
  • Agents are producing the memory. Typed output makes validation tractable; a missing Key-metrics field is a detectable failure.

When to avoid

  • Entities have heterogeneous knowledge shape. Typed schema forces into-the-mould distortion; Meta's freeform markdown is the right call when every module is different.
  • The schema is provisional / still being discovered. Committing to five categories prematurely is worse than freeform prose you can refactor later.
  • Query patterns are genuinely open-ended. If users ask about anything, schematic memory adds little over a full document store.

Variations and extensions

The golden-signals subclass

Grafana's Key-metrics category explicitly references golden signals (latency, error rate, traffic, saturation) but with the load-bearing caveat "not generic guesses, but the actual metric names from your Prometheus data sources." The architectural bet is that the golden-signals taxonomy is universal, but the metric names emitting each signal are per-customer. The schema bridges this: each service's Key-metrics field records the taxonomy-to-name mapping for this specific service, this specific customer.

Per-axis chunking

The schema pairs naturally with per-axis chunk embedding: each of the five categories becomes its own vector-DB chunk, so "what does X depend on" retrieves just the Dependencies chunk. Total corpus size = 5 chunks × N service groups instead of 1 document × N.

Evolution risk

Adding a sixth category later is expensive (all memories need re-extraction). Grafana appears to have committed to five axes as a design bet; future extensions may require schema versioning.

Relationship to adjacent patterns

Pattern Relationship
patterns/precomputed-agent-context-files Parent. Both precompute agent context; this is the typed-output sibling to Meta's freeform-markdown sibling.
patterns/swarm-of-discovery-agents-for-context-prebuild Producer. The swarm's summarisation stage writes this schema.
patterns/weekly-refresh-cadence-for-agent-context Freshness discipline. The schema is re-populated weekly.

Failure modes

  1. Hallucinated metric names. Summarisation agents may produce metric names that don't actually exist in Prometheus. Mitigation: validate every claimed metric name against the actual Prometheus metric catalogue.
  2. Dependency omission. Traces only cover paths they're sampled on; Dependencies field underrepresents low-traffic dependencies.
  3. Log-structure confusion. Services with heterogeneous logs (some JSON, some unstructured, legacy format for migrated code) produce ambiguous Log-structure entries.
  4. Technology-stack drift. If a service migrates from Go to Rust mid-cycle, the Identity field's "technology stack" is temporarily wrong.
  5. Namespace-in-cluster conflation. Services with the same name in different namespaces need the schema to uniquely identify; Identity must include namespace+cluster, not just name.

Seen in

Last updated · 445 distilled / 1,275 read