Core Concepts
A handful of ideas show up everywhere in Midil. This page defines them once so the rest of the docs can just use the words.
Your services report what happens through an SDK. The Python SDK is available today, with more languages on the way. The SDK talks to the Midil API on your behalf, so you only ever interact with the dashboard and the SDK directly, never with the API itself.
Events and traces
An event is one thing that happened at one point in your system: a message was produced, or a consumer picked one up and processed it. A trace ties every event from a single logical transaction together (for example, everything that happened because one order was placed), so you can follow it end to end in Event Explorer and the Trace Graph.
Statuses
Every event settles into one of five statuses:
- Success: handled without issue.
- Retrying: failed once, but a retry is expected to happen automatically.
- Failed: failed and won't be retried automatically.
- Dead-lettered: failed enough times (or hit a non-retryable error) that it landed in the dead-letter queue for you to investigate.
- Duplicate: the same logical event was delivered more than once and was caught before it could run twice.
Consumers and control
A consumer is any service that processes events. Consumer health shows up as Healthy, Degraded, or Down in the dashboard. Beyond just watching, you can reach in and change what a consumer is doing right now. Pause it, throttle it to slow it down, or drain it before taking it offline for maintenance, all from Consumers, without deploying anything.
Idempotency
Some event types are protected by an idempotency key, a value that identifies "this exact logical step," independent of how many times the underlying message gets delivered. When Observatory sees the same key twice, the second delivery is recorded as a Duplicate instead of being processed again. This is what makes retries and future replays safe: reprocessing an event you've already handled won't double-charge a customer or double-send an email. See the Idempotency Center to check which event types are covered.
The dead-letter queue (DLQ)
When an event fails in a way that won't resolve itself on retry, it's moved to the dead-letter queue instead of being retried forever. The DLQ Center groups these by failure class so you can see the shape of a problem. "400 events failing with the same timeout" is a lot easier to act on than 400 individual alerts.
What's next
- Using the Dashboard: a tour of every screen, using exactly the vocabulary defined above.
- Python SDK: instrument a service so it starts reporting events.