> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service map

> A live topology of service-to-service calls derived automatically from trace spans.

The **service map** shows service-to-service calls and call health through request rate, error rate,
and latency (the **RED** metrics). MoleSignal builds the map automatically from existing traces, so
normal tracing requires no extra instrumentation.

<Info>
  Service map and [APM](/en-US/apm) use the same trace input but different projections. Service map
  pairs cross-service parent and child spans to build topology. APM builds bounded service,
  transaction, dependency, error, and version aggregates.
</Info>

## How the map is built

As trace spans arrive, MoleSignal pairs each span with the parent span. Spans from **different
services** form a call edge — *parent service → child service* — and the edge takes
the child (callee) span's duration and error status. Same-service parent/child spans are internal and
aren't drawn as edges.

Edges are accumulated into **one-minute buckets** per service pair and flushed to storage in the
background, so the map reflects recent traffic within roughly half a minute.

### In-memory vs storage mode

By default (`intake` mode) pairing happens **in-memory** on the node that accepts the spans — low
latency. In a multi-node deployment, spans for one call that land on different nodes can't be paired
in memory, so the map may undercount those edges. The map never invents an edge.

To get a complete map across nodes, switch **Settings → General → Service map data source** to
**storage** mode. A single node then periodically rebuilds the graph from **stored traces** — seeing
every span regardless of the intake node — at the cost of a 1–2 minute delay. The setting is
stored in the database and takes effect at runtime; no restart needed.

## Required trace data

The map needs traces with:

* a **`service.name`** resource attribute on every span (OTLP exporters set this attribute), and
* **parent/child span relationships** that cross service boundaries — i.e. a client span in one
  service whose child server span runs in another.

Standard OpenTelemetry instrumentation produces both. Point the tracer at any
[trace intake endpoint](/en-US/intake), and MoleSignal populates the map automatically.

## Topology

The topology endpoint aggregates a time window into nodes (services) and edges (calls):

```http theme={null}
GET /api/v1/web/topology?from=2026-06-14T00:00:00Z&to=2026-06-14T01:00:00Z
Authorization: Bearer <jwt>
```

```json theme={null}
{
  "nodes": [
    { "id": "checkout", "name": "checkout", "rps": 42.0, "error_rate": 0.01, "p95_ms": 120.0, "span_count": 151200 }
  ],
  "edges": [
    { "source": "checkout", "target": "payments", "rps": 41.0, "err_rate": 0.02, "p95_ms": 95.0 }
  ]
}
```

| Field                     | Meaning                                            |
| ------------------------- | -------------------------------------------------- |
| `rps`                     | Requests per second over the window.               |
| `error_rate` / `err_rate` | Fraction of requests with an `ERROR` status (0–1). |
| `p95_ms`                  | 95th-percentile latency, in milliseconds.          |
| `span_count`              | Total spans seen for the node in the window.       |

## Raw service graph

For the underlying minute-by-minute edge snapshots — useful for charting a single dependency over
time — query the service graph directly:

```http theme={null}
GET /api/v1/traces/service_graph?from=1717200000000000&to=1717286400000000&service=checkout
Authorization: Bearer <jwt>
```

`from` and `to` are microseconds since the Unix epoch. The optional `service` filter returns edges
where the selected service appears on either side of the call. Each row carries `request_count`, `error_count`, and
`p50_us` / `p95_us` / `p99_us` for one service pair in one minute.

## In the UI

* The **Services** page lists every service with request rate, error rate, and p95, ordered by traffic.
* Open a service to see upstream callers and downstream dependencies.
* The **topology** view draws the live graph — edge thickness follows traffic, and color follows the
  error rate.

From any service or edge, pivot straight into the underlying traces and logs through
[cross-signal correlation](/en-US/correlation).

<CardGroup cols={2}>
  <Card title="Topology & service-graph API" icon="diagram-project" href="/en-US/api/web/topology">
    Query the topology and raw service-graph endpoints over HTTP.
  </Card>

  <Card title="Application performance monitoring" icon="gauge-high" href="/en-US/apm">
    Analyze service RED metrics, transactions, dependencies, errors, and deployments.
  </Card>
</CardGroup>