Service catalog reference
The catalog is a list of services stored in stromboli’s database. Its import and export format is a YAML list whose entries have the shape of the stromboli.v1.Service message (proto/stromboli/v1/catalog.proto), with snake_case field names. Unknown fields are rejected.
- name: api # required
description: Public REST API
owners: ["@team-backend"]
repo: acme/api
path: services/api
runtime: fly.io
tier: 1
depends_on: [db-proxy]
logs:
source: loki
selector: '{service_name="api"}'
metrics:
source: fly
selectors: ['app="api"']
deploys:
source: github
repo: acme/api
workflow: deploy.yml
runbooks: [runbooks/api-5xx.md]
monitors: ["openstatus:1234"]
slos:
- name: availability
target: 99.9
fly:
app: acme-api
actions: fly-deploy
allow: [restart, cordon, uncordon]
Fields
| Field |
Type |
|
name |
string |
required. Unique; lowercase letters, digits, ., _, -, starting with a letter or digit, at most 63 characters |
description |
string |
shown in the brief |
owners |
list of strings |
free-form (@team-backend, an email…) |
repo |
string |
the service’s repository, informational |
path |
string |
path of the service in its repository, informational |
runtime |
string |
free-form. fly.io, fly or flyio (any case) marks a Fly.io service, as does a fly block |
tier |
integer |
criticality, 1 is the most critical. 0 = unset |
depends_on |
list of service names |
services this one calls (downstream). Builds the dependency graph |
logs |
LogsConfig |
where the service’s logs are |
metrics |
MetricsConfig |
where its metrics are |
deploys |
DeploysConfig |
where its deploys or commits are |
runbooks |
list of runbook paths |
e.g. runbooks/api-5xx.md; uploaded with catalog import --runbooks |
monitors |
list of strings |
alert sources mapped to this service. Today openstatus:<monitor id> |
slos |
list of {name, target} |
informational |
fly |
FlyConfig |
Fly.io app and machine actions |
logs
| Field |
|
source |
name of a log connector (loki, axiom, cloudwatch, gcp_logging, vercel) |
selector |
the connector’s query selecting the service’s logs. Syntax per kind: Connectors |
metrics
| Field |
|
source |
name of a metrics connector (prometheus, fly, gcp_monitoring) |
selectors |
PromQL label matchers, ANDed, e.g. ['app="api"']. Queries reference them as $selector. Required when source is set |
deploys
| Field |
|
source |
name of a github or vercel connector |
repo |
owner/name. Required for github |
workflow |
github: workflow file name: deploys are its completed runs |
environment |
github: deployment environment: deploys are its deployments. vercel: deployment target, production (default) or preview |
branch |
github: branch for the commit fallback (neither workflow nor environment). Default: the repository’s default branch. vercel: only deploys of this branch |
project |
vercel: project name or ID. Required for vercel |
fly
| Field |
|
app |
Fly app name. Default: the app="…" metrics selector, else the service name |
actions |
name of a fly_machines connector. With it (and STROMBOLI_ACTIONS_ENABLED=true), stromboli can run machine actions after approval |
allow |
machine actions stromboli may run: restart, clone, cordon, uncordon, stop, start. Default: restart, clone, cordon, uncordon |
Runbooks
Runbooks are Markdown files stored with the catalog. catalog import --runbooks <dir> uploads every *.md file under <dir> as runbooks/<relative path>; catalog export --runbooks <dir> writes them back. The agent reads them with read_runbook, and the brief lists the service’s runbooks.
Validation
Validation runs on import (--dry-run included), on UpsertService and with catalog validate. Errors block a write; warnings do not.
| Field |
Rule |
Level |
name |
invalid format |
error |
name |
duplicate |
error |
depends_on |
the service itself |
error |
depends_on |
unknown service (add external dependencies too) |
warning |
depends_on |
part of a dependency cycle |
warning |
logs |
no source or selector |
warning |
logs.source |
unknown connector |
warning |
logs.source |
connector is not a log connector |
error |
metrics.selectors |
empty while metrics.source is set |
error |
metrics.source |
unknown connector |
warning |
metrics.source |
connector is not a metrics connector |
error |
deploys.repo |
empty while deploys.source is a github connector |
error |
deploys.project |
empty while deploys.source is a vercel connector |
error |
deploys.source |
unknown connector |
warning |
deploys.source |
connector is not github or vercel |
error |
fly.allow |
unknown action |
error |
fly.actions |
unknown connector |
warning |
fly.actions |
connector is not fly_machines |
error |
runbooks |
runbook not found |
warning |
owners |
empty |
warning |
catalog validate --check-connectors also runs a test query for each service’s log and metrics selector.
Dependency graph
depends_on defines the graph used in briefs and by the get_service tool:
- downstream: the services this one depends on;
- upstream: the services that depend on this one;
- blast radius: every service that transitively depends on this one, which a failure here can reach.
Edit this page on GitHub ↗