What is a service catalog?

A service catalog is a central inventory of every service an organization runs, with ownership, dependencies, and operational metadata for each one. It helps engineers find who owns a service, how to page them, and how it is deployed during incidents.

What is a service criticality tier?

A criticality tier ranks how important a service is to the business, usually from Tier 1 (an outage causes direct revenue or safety impact) down to Tier 4 (best-effort). The tier drives SLA targets, on-call expectations, and review rigor.

Can I use this entry in Backstage?

Yes. The generated Markdown captures the same fields Backstage and similar developer portals expect, so you can paste it into a wiki page or use it as a checklist while filling in a catalog-info.yaml file.

Why list dependencies explicitly?

Documented dependencies let responders trace failures upstream and downstream during an incident, and they make blast-radius analysis possible. Listing each dependency on its own line keeps the entry parseable and easy to scan.

What belongs in the runbook link field?

It should point to the operational runbook for the service — the document that explains how to restart it, common alerts, and recovery steps. Pairing the runbook with the on-call contact gives a responder everything needed to act fast.

What is the Internal Service Catalog Entry Builder?

Builds a complete internal service catalog entry with service name, owner team, criticality tier, SLA and latency targets, API endpoint summary, dependencies, deployment info, runbook link, and on-call contact — ready to paste into Backstage, a wiki, or a YAML record. It runs free in your browser on Gera Tools, with nothing uploaded.

Internal Service Catalog Entry Builder

Name: Internal Service Catalog Entry Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Get one useful tool a week

Like this tool? Enter your email and we'll send you one genuinely useful Gera tool a week — plus a link to come back to this one. No spam, one-click unsubscribe any time.

A catalog entry without the blank-page problem

A good service catalog is only useful when every service has a complete, consistent entry. This builder turns a short form into a clean, structured Markdown record covering ownership, reliability targets, API surface, dependencies, deployment, and on-call — the fields responders actually need at 3am during an incident.

How it works

You fill in the service identity (name, owner team, criticality tier, language, repository) and a one-line description. The tool derives a stable catalog ID by lowercasing the name and replacing spaces with hyphens. You then add reliability targets (availability SLA and latency SLO), list API endpoints and dependencies one per line, and provide deployment notes, a runbook URL, and an on-call contact. The builder assembles all of this into ordered Markdown sections so the same shape is reused for every service, which is what makes a catalog searchable and trustworthy.

What a complete entry enables

During an incident: a responder who has never touched the service can find the owner in one lookup, get the on-call number, pull up the runbook, and know which upstream dependencies to check — without paging three people to ask.

Blast-radius analysis: explicit dependency lists let you trace the downstream impact of a failing service immediately. “Payments-API is down — which services depend on it?” is answerable in seconds if every service lists its dependencies.

Capacity planning: the tier and SLA information drives infrastructure investment decisions. A Tier 1 service needs redundancy, multi-region failover, and rigorous SLO tracking; a Tier 4 service may run on shared resources.

Onboarding: new engineers can read the catalog to understand what every service does and who owns it before their first on-call rotation.

Criticality tier definitions

Most organizations use a four-tier model, though naming varies:

Tier	Impact of outage	On-call expectation
Tier 1	Direct revenue loss or safety impact	Immediate page, 24/7
Tier 2	Significant degradation, workaround exists	Page during business hours
Tier 3	Internal tooling; users adapt	Next-business-day
Tier 4	Best-effort; low usage	Weekly sweep

The tier drives SLA targets — you cannot reasonably commit to 99.99% for a Tier 3 service without the same investment you would make in a Tier 1 service.

Example entry structure

## payments-api

**Owner:** Platform Team
**Tier:** 1
**Description:** Handles all Stripe charge and refund requests.

### Reliability
- Availability SLA: 99.95%
- P95 latency SLO: 200ms

### API
- POST /charges — create a charge
- POST /refunds — issue a refund

### Dependencies
- postgres-payments
- stripe-gateway
- redis-session

### Deployment
- Railway: payments-api-production
- Runbook: https://wiki.internal/runbooks/payments-api

### On-call
- PagerDuty: payments-oncall
- Slack: #payments-oncall

Tips

Keep endpoint lines in METHOD /path — purpose form so the catalog reads like lightweight API docs.
Put one dependency per line so blast-radius tooling can parse them programmatically.
Match the criticality tier to your on-call policy: a Tier 1 service needs a paging contact, not just a Slack channel.
Reuse the same catalog ID as your repo and deploy names so a responder can jump between them without guessing.