What is a service catalog?
What a service catalog is
A service catalog is the central record of the software services running in your organization: what each service is, who owns it, what it depends on, and whether it is production ready. It is the reference engineers reach for when they need to know who to page, what breaks if a service goes down, or whether a service is safe to depend on.
Developer portals like Backstage, Cortex, Compass, and Roadie are built around this idea. The catalog is meant to be the single place where the shape of your production estate is written down.
The problem: declared, not observed
Almost every service catalog is populated by declaration. An engineer writes an entry, usually a YAML file, describing the service, its owner, and its dependencies. That entry is accurate the day it is written.
Then production moves on. A team reorganizes. A dependency shifts. A new service ships. Nobody goes back to update the YAML, so the catalog drifts from reality. In practice this happens within about two weeks, and it compounds from there. The catalog becomes a record of what your system looked like at some point in the past, not what it is doing now.
This is why on-call engineers so often learn the real dependency graph during an incident. The catalog said one thing; production was doing another.
Observed vs declared
The difference is architectural. A declared catalog depends on humans to stay accurate. An observed catalog is derived from live production, so it reflects what is actually running.
| Declared catalog | Observed catalog | |
|---|---|---|
| Source of truth | YAML and forms written by hand | Repositories, traces, deploys, and incidents |
| Freshness | Correct when written, stale within weeks | Reconciled continuously on every change |
| Dependencies | Declared, no confidence model | Traced from the observed call graph, with provenance |
| Maintenance | Ongoing engineer time | Near zero |
Why this matters more now
For years a stale catalog was a productivity tax. An engineer hit a wrong entry, lost twenty minutes, corrected course, and moved on.
That calculus changed when the reader of the catalog stopped being only human. Coding, deployment, and incident-response agents now read the catalog and act on what it says. A stale entry a person would have double-checked becomes an action taken in production. The catalog nobody maintains has quietly become the system context every agent that touches production depends on.
What a self-maintaining catalog looks like
A self-maintaining service catalog is built from observation rather than declaration. It reads your repositories, distributed traces, deploy events, and incident history, and it keeps the catalog current without anyone editing it. Ownership is traced from deploy history and contributor activity. Dependencies come from the observed call graph. Readiness is scored from real SLOs, alerts, and incident data. Blast radius is calculated from live topology.
Crucially, every fact carries where it came from. Each entry is labeled runtime, synthesized, or intent, each with a confidence score, so humans and agents know exactly what to trust. Where there is no evidence, the catalog says so rather than filling in a gap.
To see this applied to your own stack, explore the self-maintaining service catalog.
Frequently asked questions
- What is the difference between a service catalog and a CMDB?
- A CMDB is a broad inventory of configuration items across IT, often populated by periodic discovery scans. A service catalog is narrower and engineering-facing: it centers on software services, their owners, their dependencies, and their production readiness. Both share the same weakness when populated by hand: they describe what someone recorded, not what production is doing now.
- Why do service catalogs go stale?
- Because they are declared, not observed. Someone writes an entry once, in YAML or a form, and it is correct until the next team reorg, dependency change, or new service. Nobody updates it, so it drifts from reality within weeks. On-call teams often discover the real topology during an incident, when the catalog turns out to be wrong.
- What is the best Backstage alternative?
- Backstage, Cortex, Compass, and Roadie all share the declaration model: humans keep the catalog accurate by maintaining YAML. The alternative is a catalog derived from observation, built from repositories, traces, deploys, and incidents, with no YAML to write and no plugins to maintain. See how the NOFire service catalog works.
- How does a self-maintaining service catalog stay current?
- It reads live production signals continuously and reconciles the catalog on every change. Ownership is traced from deploy history and contributor activity, dependencies from observed call graphs, and readiness from real SLOs, alerts, and incident data. Every fact carries where it came from, labeled runtime, synthesized, or intent, with a confidence score.