Service catalog: unified tags, definitions in repos, scorecards

TL;DR

Use it in incident response instead of the wiki. A catalog full of dead services is a catalog nobody trusts. - Definition review in code review: the service definition file changes with the service. New endpoint, new dependency: update the file in the same PR. - Dependency map: the service map derives from trace data, which means it reflects reality, not the architecture diagram from 2023.

When to use

You are seeing this: The Service Catalog is only as good as the tags feeding it. Use this skill when you run into "Service catalog: unified tags, definitions in repos, scorecards".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Service catalog that stays accurate

The Service Catalog is only as good as the tags feeding it. Unified tagging (service, env, version on everything) is the prerequisite; everything below assumes it is done.

Build it

1. Tag every service with unified tagging: agent config for infra, env vars for tracers, resource specs for serverless. No tag, no catalog entry worth trusting.
2. Service definitions in the repo: a small definition file per service (name, team, contacts, links to runbooks and dashboards) committed next to the code. The catalog reads it; the repo owns it.
3. Scorecards: define the standards (has runbook, has SLO, has on-call, logs parsed, traces sampled) and score every service. Publish the scores. Nothing motivates like a red scorecard in the team channel.
4. Ownership tags: team: on every service so the catalog answers "who owns this" without a wiki hunt.

Keep it accurate

• Stale service cleanup: services with no telemetry in 30 days get flagged, then removed. A catalog full of dead services is a catalog nobody trusts.
• Definition review in code review: the service definition file changes with the service. New endpoint, new dependency: update the file in the same PR.
• Dependency map: the service map derives from trace data, which means it reflects reality, not the architecture diagram from 2023. Use it in incident response instead of the wiki.

Verify

Every production service appears with correct team, runbook link, and SLO status. The scorecard has no reds older than a quarter. An incident responder can find the owner and runbook from the catalog alone.

The unified service tagging docs define the three standard tags (service, env, version) that power the Service Catalog, Service Map, and correlation across telemetry. Verified against live docs 2026-09-26.