Skip to content

Service map

The service map shows what each workload calls and what calls it: from the Ingress to the front end, to the APIs behind it, to the databases, caches, queues and outside services at the end. Every line on it says how Seylo knows it, so you can tell an observed call from a guess.

It is on Observability → Service map. Pick the cluster, and a namespace or All namespaces you can see. A namespace’s own page links to it too.

The map is what incidents use to group related alerts and find where a failure started, and what Nightshift reads with its dependencies read. It needs no agent upgrade: it is built from reads the agent already serves.

Node From
A workload: Deployment, StatefulSet, DaemonSet, CronJob The cluster
A Service The cluster. Drawn as a hop between workloads, not as a box
An Ingress or HTTPRoute The cluster. Their arrows are drawn by default; Also draw → Routes turns them off
A database, cache, queue, Kafka topic, function or SaaS A connection string’s scheme, port or host name (postgres://, port 6379, a managed service’s host suffix); a trace; an architecture file
An external host A host your configuration names that is not a Service and has no known type
A component A service your architecture file declares that matches no workload, or a traced service Seylo could not place
A volume claim A PersistentVolumeClaim a workload’s pod template mounts, joined to it by a mounts edge. A StatefulSet’s volumeClaimTemplates give one node for every replica’s claim, named <template>-<statefulset>-*

Pods are never nodes: they come and go, and the workload is what you run.

A volume claim is named from the workload that mounts it; the claim itself is not read, so the map does not show its size, class or whether it is bound. A mounts edge says what the pod template declares, not traffic: it is not used when Seylo groups alerts into an incident or walks one to its root.

The map is drawn in lanes, columns read left to right the way a request flows. The same graph is always drawn the same way, so nothing moves while you follow a request. Hover over a lane’s header to see what it holds.

Lane What is in it
Entry Ingresses, HTTPRoutes, and a CronJob or Job that calls something: where work starts. Such a CronJob or Job is badged schedule
Stateless Deployments, in sub-columns by call depth inside the lane: web → api → pricing. A Deployment nothing calls, such as a queue consumer, starts the lane rather than sitting in Entry
Stateful StatefulSets, and databases, caches and queues that run in the cluster
Storage and outside Volume claims, hosts outside the cluster, SaaS, functions, managed databases, and a service in a namespace you cannot see

Below the lanes, a Background band holds DaemonSets, which run beside every request rather than in one (their edges are still drawn), and any CronJob, Job or workload with no known edge.

Which lane a node sits in, and how deep, is worked out from every edge you could draw, not only those drawn now, so ticking Also draw → Routes or NetworkPolicy never moves a box. NetworkPolicy edges never decide a lane: a policy allows traffic, it is not traffic. In All namespaces you can see, each namespace is a horizontal band with its own background row, and the lanes line up across bands; nodes outside any namespace, such as outside hosts and SaaS, get a last band of their own.

Hover over a node, or move to it with the keyboard, to light its whole request path: everything that calls it, what calls those, and everything it calls in turn. The rest of the map dims. Another caller of a service on that path is not lit, because it is not on this node’s path. Hidden edges and NetworkPolicy edges are not requests and are never lit.

  • Kind chips above the map show or hide each kind of node: Ingresses and routes, Deployments, StatefulSets, DaemonSets, CronJobs and Jobs, Databases, caches, queues, Volume claims, Outside hosts and SaaS, and Declared and traced services. Only the kinds on the map are listed.
  • Also draw → Hide unconnected leaves out the Background band’s nodes that have no edge at all. A DaemonSet with an edge stays.
  • A node’s tooltip says what it is and why it sits where it does.

One edge joins two nodes, however many sources report it. Each source is kept, and the edge shows the strongest:

Source What it means How sure
Traces A sample of whole traces showed one service calling the other: calls, error ratio and latency in the sample observed
Service mesh Istio or Linkerd request metrics: requests per second, error ratio, status codes, p95, over 5 minutes observed
Service selector, Ingress or HTTPRoute A Service’s selector matches the workload’s pods; a route sends to that Service. What the API server will do, not proof that traffic flows exact
ExternalName Service The Service points at an outside host exact
Architecture file, a person’s correction Someone wrote that one depends on the other declared
Environment variable, ConfigMap The workload’s configuration names the other’s address, such as DATABASE_URL or a ConfigMap key it reads configured
NetworkPolicy A policy allows the traffic. Allowing is not depending, so these are drawn only with Also draw → NetworkPolicy and never group alerts exact, as an allow

An edge can also join two clusters of your organisation, when one cluster’s upstream - an ExternalName, a selectorless Service’s address, a proxy’s configuration - is another cluster’s Ingress host or load balancer. Its source reads other cluster, and the map shows an Across clusters card. See across clusters.

The order, strongest first: observed, exact, declared, configured. A configured reference is not proof of a call; a declared edge is a person’s statement.

Conflicts are shown, not resolved. When your configuration or an architecture file says two services talk, both send traces, and the trace sample shows no call between them, the edge says so: ... but no call was seen in the trace sample. The same goes for a route to a Service that does not exist, and an edge someone hid that a source still reports.

To find addresses, Seylo reads environment variables and the ConfigMaps a workload uses, and keeps only the host, port, scheme and type. The user name, password, path, query string, database name and account ID are thrown away inside the read. It understands URLs, JDBC strings, Key=Value; connection strings, Redis connection strings and comma-separated broker lists. Secrets are never read: a value from a Secret is recorded by the Secret’s name, and the node’s panel lists Secrets used by name.

One exception, for putting a setting back. From the same reads, Seylo also keeps its own record of one-line ConfigMap settings, and of each flagd feature flag’s default variant, and of each change to them. Never a Secret, a file, or a value that looks like a credential. It is how Nightshift proves the value a setting had before a change, so it can put it back.

  • Configuration sees only what is written in environment variables and in ConfigMaps the workload uses. A host built at run time, read from a Secret, or fetched from a configuration server is invisible to it.
  • Traces see only workloads that send spans - APM coverage shows which do not - and only the sample: the 150 most recent traces and the 50 most recent with an error, over 15 minutes, at most 5,000 spans. Numbers are the sample’s, never a cluster-wide rate, and the panel says so.
  • A mesh sees only meshed workloads. No mesh means no mesh edges, and the map says so rather than showing an error.
  • NetworkPolicy says what is allowed, not what flows.
  • An architecture file is what a person wrote. Where both ends send spans, it is checked against the traces.
  • Not yet read: serverless functions and managed services from your cloud accounts (name them in an architecture file until then), Gateway API objects other than HTTPRoute, and the same host across two clusters.

Whatever the map could not see is listed under What the map could not see, rather than drawn as a missing edge.

Click a node to see:

  • Managed by - Argo CD, Flux or Helm, when one owns it;
  • Secrets used - by name only;
  • Declared in - the architecture file and line, if one names it;
  • Read from the cluster - when;
  • Health signals - what your exporters say about it: pools, connections, lag, backlogs, retries, breakers. See health signals;
  • Depends on and Depended on by - each edge with its sources, numbers and any conflict.

A releaser in the namespaces at both ends can correct what Seylo got wrong, with an optional Note saying why:

  • Hide this edge on an edge that is not real (Show again undoes it);
  • Add edge - Add a dependency on another node;
  • Set owner on a node, such as team-checkout.

Corrections are kept apart from what Seylo reads and applied every time the map is drawn, so a refresh never loses one. They are listed under Corrections with who made them and the note, and recorded in the audit log. Also draw → Hidden edges shows what was hidden.

Some things the cluster cannot show you: serverless functions, managed queues and databases, SaaS, and which hops are asynchronous. Describe them in an architecture file, in one of two formats. Files are read as data and never run.

  • Written in Seylo. Under Architecture files on the Service map, an admin presses Write a file, gives a Path, and writes or pastes the content. Check shows the errors; Save saves it only when there are none.
  • From Git. When your organisation connected a skills repository, Seylo also reads every catalog-info.yaml (or .yml) in it, anywhere in the tree, and every .seylo/architecture/*.yaml, read-only. Read the repository now reads it at once.

At most 50 files, 256 KiB each. Parsing is strict: an unknown key, a wrong kind, an edge to a node the file does not declare, or invalid YAML is an error with its line, and the file is refused. A file from Git that was good and is now refused keeps its last good version in use, and the page says which commit was refused. A value or key that looks like a credential refuses the whole file, and nothing of it is stored, not even its text.

Seylo reads your Backstage catalog as it is: Component as a service, Resource (database, cache, queue, topic, function, SaaS and similar) as a node, and API as the link between the components that consume and provide it. spec.dependsOn, spec.consumesApis, spec.owner and spec.system are used. A Component is matched to workloads by the backstage.io/kubernetes-id annotation (workloads labelled with the same backstage.io/kubernetes-id), or by backstage.io/kubernetes-label-selector, narrowed by backstage.io/kubernetes-namespace; with neither, by its name when exactly one workload has it. The github.com/project-slug annotation tells Seylo which repository holds the component’s code. Other kinds are accepted and skipped.

For what Backstage does not describe well:

apiVersion: seylo.io/v1
kind: Architecture
metadata:
name: kestrel-shop # optional; the default system of every node
owner: team-shop # optional; the default owner of every node
nodes:
- name: storefront
kind: service # service | function | queue | database | cache | saas | kafka-topic
workload: { namespace: shop, name: storefront }
repo: kestrel/storefront # optional; the GitHub repository its code lives in
- name: checkout
kind: service
workload: { namespace: shop, selector: { app: checkout } }
- name: orders
kind: kafka-topic
engine: kafka # optional, free text
- name: invoice-fn
kind: function
engine: azure-functions
owner: team-billing # optional; wins over metadata.owner
- name: orders-db
kind: database
engine: postgres
host: orders.postgres.example.com # optional; a host name only
edges:
- { from: storefront, to: checkout, protocol: sync }
- { from: checkout, to: orders-db, protocol: sync }
- { from: checkout, to: orders, protocol: async, note: publishes OrderPlaced }
- { from: orders, to: invoice-fn, protocol: async }
Key Rule
Top level apiVersion, kind, metadata (name, owner, system), nodes, edges. One document per file
A node name (letters, digits, . _ -, at most 120), kind, and optionally engine, host, owner, system, workload (namespace and a name or a selector), repo (owner/name on GitHub) and description
An edge from, to (nodes of the same file), protocol (sync or async), and an optional note of at most 300 characters
  • workload makes the workloads that run it that node on the map, with its owner and system.
  • host ties a declared node to configuration that names the same host: DATABASE_URL=postgres://...@orders.postgres.example.com/... and the node above become one edge with two sources.
  • protocol: async marks a hop the root-cause walk does not follow.
  • repo (or Backstage’s github.com/project-slug) is where an incident’s coding-agent fix is started.
  • The same name in two files is one node; the first file by path wins.

The editor starts from this example.

You see the nodes in the namespaces you may see, and what outside every namespace they connect to. An edge that leaves your namespaces ends at a service in a namespace you cannot see: you learn how sure the edge is and what kind of source reported it, never the other end’s name, namespace or numbers. A gap about a namespace you cannot see is not shown.

The map is built a few minutes after a cluster’s agent connects, then refreshed in rotation: each cluster at most every 5 minutes, a share of its namespaces each time, and traces and mesh metrics at most every 10 minutes. A kind the cluster does not serve, or the agent may not list, is skipped and said so. Something deleted from the cluster leaves the map once a full read no longer finds it.