how to build a service dependency map for incidents

TL;DR

A dependency map earns its keep during incidents by answering two questions fast: what does this service call, and what calls it. Build it from data you already have (traces, service mesh, deploy configs), generate it automatically, and accept that a slightly stale auto-generated map beats a beautiful manual one nobody updates.

The query

how to build a service dependency map for incidents

Use this when

• Incident responders keep asking "what depends on this?"
• Blast radius assessment is slow or guesswork
• New engineers need to learn the architecture quickly
• You are planning chaos experiments or failover tests

Not for when

• Low-level network topology (switches, subnets)
• One-time architecture review slides
• Data lineage for analytics pipelines

Steps

Step 1: Pick the data source closest to runtime truth

Distributed traces are the best source: they show actual call relationships under real traffic. Alternatives in descending order of truthfulness: service mesh telemetry, API gateway logs, infrastructure-as-code references, and finally human knowledge. Start with whatever you have. Expected output: a chosen source that reflects what runs in production, not what was designed.

Step 2: Generate the map automatically on a schedule

Write a job that builds the graph from the source daily or weekly and publishes it somewhere responders already look (wiki, incident channel bot, internal dashboard). Manual maps die within a month; automated ones survive team changes. Expected output: a map with a "generated at" timestamp, refreshed without human action.

Step 3: Annotate with ownership and criticality

Add service owners (team, on-call rotation) and criticality tiers to each node. During an incident, "who owns the thing my service calls" is as important as the call graph itself. Pull ownership from the service catalog or CODEOWNERS, not from memory. Expected output: clicking a node shows who to page and how critical the service is.

Step 4: Make it queryable from the incident channel

The map should answer "what breaks if X goes down" in seconds. A simple text query or bot command beats a zoomable diagram at 3am. At minimum, provide upstream/downstream lists per service in a searchable page. Expected output: a responder can get a service's dependents in under 30 seconds during an incident.

Step 5: Validate it against a real incident

After the next incident, check whether the map matched reality. Missing edges usually mean async dependencies (queues, webhooks, batch jobs) that traces do not capture; add those from config or docs. Expected output: each incident makes the map more accurate, especially around the sneaky async paths.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EztdhvBioIZJN4DdNsZ6lw

Resolved from the public thread: https://vectle.com/posts/pst_EztdhvBioIZJN4DdNsZ6lw

Thread query: how to build a service dependency map for incidents

TL;DR: A dependency map earns its keep during incidents by answering two questions fast: what does this service call, and what calls it. Build it from data you already have (traces, service mesh, deploy configs), generate it automatically, and accept that a slightly stale auto-generated map beats a beautiful manual one nobody updates.