A service catalog that stays current because it is built from telemetry

What is a service catalog?

A service catalog is a central inventory of the services that make up a software system, together with the information people need to operate them: who owns a service, what it depends on, which services depend on it, how reliable it is supposed to be, where its code and runbooks live and how healthy it is right now. In platform engineering it is often the backbone of an internal developer portal.

The challenge with most catalogs is freshness. When the catalog is maintained by hand in a wiki or spreadsheet, it starts drifting the day it is published. New services appear without an entry, ownership changes after a reorganisation and dependency diagrams no longer match reality. During an incident, an outdated catalog is worse than none, because it sends people in the wrong direction.

Why a service catalog matters

As systems grow to dozens or hundreds of services, the question "who owns this?" becomes one of the most expensive in engineering. It slows down incident response, delays security fixes and makes it hard to assign reliability work. A current catalog answers it in seconds.

It also makes reliability manageable. When every service has a defined tier and SLO, teams can agree on what "good enough" means, prioritise work based on error budgets and see which critical services lack basic safeguards such as runbooks or alerting. For engineering leaders, the catalog becomes the map for platform investments and migrations.

What belongs in a service catalog

A useful catalog entry combines static metadata with live operational data:

• Ownership: owning team, on-call schedule, chat channel and escalation contact.
• Classification: tier or criticality, lifecycle stage, language and runtime.
• Dependencies: upstream callers, downstream services, databases, queues and third-party APIs.
• Reliability: SLOs, error budget remaining, recent incidents and golden signals.
• Change: current version, recent deployments and links to the repository.
• Documentation: runbooks, architecture notes and API specifications.

How Obseria builds the service catalog

Obseria starts from what it can observe. Services are discovered from OpenTelemetry resource attributes such as service.name and service.namespace, from the Obseria Agent and from Kubernetes metadata. Obseria TopoGraph derives dependencies from traces and network data, so the catalog shows which services actually call each other, how much traffic flows and where errors occur. Services that are not registered yet still show up, which makes gaps visible.

Teams add the information telemetry cannot provide. A small YAML file in the repository, or an API call from your provisioning pipeline, sets owner, tier, runbooks and links:

service: checkout
owner: team-payments
tier: 1
oncall: payments-primary
runbook: docs/runbooks/checkout.md
slo:
  availability: 99.9
  latency_p95_ms: 400

That metadata drives the rest of the platform. Incident management routes pages to the owning team's on-call schedule. Status pages build components from catalog services. SLOs defined on a service get error budgets and burn-rate alerts automatically. Scorecards show which services meet your standards, for example whether a tier 1 service has an SLO, a runbook and full trace coverage.

Because ownership and dependencies are known, the catalog also answers impact questions before a change: which teams need to be informed when a shared database is migrated, or which tier 1 services would be affected if a particular queue slowed down. Security and compliance teams use the same inventory to see which services process personal data and who is responsible for them.

Service catalog best practices

1. Automate discovery. Never rely on people to register services; let telemetry find them and ask for metadata.
2. Keep metadata next to the code. YAML in the repository is reviewed and versioned like everything else.
3. Make ownership mandatory. A service without an owner should be visible and flagged.
4. Start SLOs with critical services. Define tier 1 SLOs first, then expand.
5. Use scorecards to guide, not punish. Track progress on standards and celebrate improvement.