Skip to main content

Observe your app

Beginner ⏱ 10 min observability · debugging · metrics

You will build: the everyday observation loop — watch any topic live, tail the engine log, and read per-agent throughput.

events tail · logs -f · metrics agent

Prerequisites​

  • Any deployed app.

1 · Tail any topic — the superpower​

pulse events tail --topic oncall.reason.out

Every stage boundary is a durable topic, so every seam of your app is observable — not just the ends. Debugging usually starts here: tail the topic just before where things look wrong.

2 · Follow the engine log​

pulse logs -f

Deploys, stage lifecycle, connector activity, errors with causes.

3 · Read a stage's vitals​

pulse metrics agent reason

Per-agent throughput, lag and error counts — is the stage keeping up with its input topic?

4 · Stream events into anything else​

curl -N -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9090/api/pulse/events/stream"

The SSE endpoint pushes events as they land — the same feed your dashboards, scripts or a browser tab can consume. Getting $TOKEN is covered in Call your app from anywhere.

What just happened​

Observability here isn't an add-on — the architecture is the instrumentation. Because everything flows through named topics, "what is my app doing right now" is always answerable with a tail, and "how fast" with a metrics call. For the full picture (Prometheus metrics, tracing, audit streams) see the observability pages on streamflowmesh.io.

Troubleshooting​

tail shows nothing at all

Verify the topic name: it's <app>.<stage>.out exactly as named in pulse.yaml. pulse logs -f tells you if events are flowing but failing inside a stage.

Next​