Observability
Observability is being able to answer questions about a running system without shipping new code to ask them. The standard three signals — metrics, logs, traces — are organised around requests, and a request is the wrong unit here: the thing that succeeds or fails is a conversation, a decision or a call, and it spans many requests and several days.
The three signals, and where they stop being enough#
| Signal | Answers | Blind to |
|---|---|---|
| Metrics | How much, how often, how fast, in aggregate | Which particular thing went wrong |
| Logs | What happened in one component at one moment | Whether the work as a whole completed |
| Traces | How one request travelled through the parts | Anything that spans more than one request |
All three are healthy while a mailbox authenticates, returns nothing, and quietly stops bringing in mail. No error is raised, no latency changes, no trace looks unusual. The failure is that a business is not hearing from its customers, and none of the three signals is shaped to notice it.
That is why “connected” is not health here. A mailbox that answers correctly and brings back nothing is a quiet mailbox — a health signal in its own right rather than an error, and one that only makes sense against the expectation that mail usually arrives.
A wrong number is worse than an error#
The failures that survive longest in a product like this are the ones that produce a confident, incorrect answer. Two documented examples make the point better than a principle would.
- A conversation list read 400 threads and then counted, filtered, searched and paged over that slice in Python. On a workspace with 430 conversations whose 25 closed ones were the oldest, the Closed tab read 0, the total read 400, and page five came back empty. Nothing errored.
- A prospecting summary derived every headline number from the newest 500 rows. On a 540-contact workspace it reported 500 organisations where there were really 530, and 0 already contacted where there were really 40. Every number was plausible.
Neither would appear on an error-rate chart, and both are precisely the sort of thing a person notices before a dashboard does. Which is an argument for putting the signal where the person already is.
Does Connect use observability, and where does it surface?#
Yes, and mostly in the product rather than in an operator-only console — because the person who can act on an operational problem in a workspace is usually somebody in that workspace.
- Needs You
- Decisions, approvals and operational problems, ranked rather than chronological. Voice line health escalates into it, rendered for both audiences by the same code, and each entry drains by itself as its cause clears
- The Decision Log
- What was decided, by what, under which rule, and what happened — refusals included
- Mailbox health verdicts
- Per mailbox, distinct from whether it is connected
- Readiness on the Phone screen
- What the configured provider actually carries, stated plainly rather than by offering a control that cannot work
/api/health- The one health endpoint. There is no
/healthz,/healthor/readyz - Query cost in statements
- Counted rather than timed, so a regression is visible on a small database
A queue that drains itself is doing something a dashboard does not: it distinguishes a problem that has been fixed from one nobody has looked at, without anybody having to acknowledge an alert.
Designing signals for work that spans days#
- Instrument the unit somebody cares about. A conversation answered, a call completed, a follow-up honoured — not a handler returning 200.
- Count refusals as events. A held reply and a suppressed recipient are outcomes, and a system that only records what it did looks idle when it is correctly declining.
- Make absence visible. Nothing arriving is a state, and it needs a representation, otherwise it is indistinguishable from nothing being wrong.
- Prefer counts that cannot drift over durations that depend on the machine. A statement count is the same on a laptop and in production; a millisecond threshold is not.
- Route the signal to whoever can act. An operational problem inside one workspace belongs on that workspace's screen.
Questions#
Is there a metrics dashboard I can open?
Not as a separate monitoring product. The operational signals are placed in the screens where they can be acted on — Needs You for problems and decisions, the Decision Log for what has already been decided, mailbox health on the mailbox, readiness on the Phone screen. Plan and Usage covers consumption against your allowances.
How do I know Connect is running at all?
/api/health is the health endpoint, and it is the only one — there is no /healthz, /health or /readyz to try. Inside the product, the more useful question is usually whether work is flowing, which Needs You and the conversation list answer better than a liveness check does.
Why does an item disappear from Needs You without my doing anything?
Because entries drain as their cause clears. A line-health item raised while a provider was unreachable goes when the line is healthy again. That is the intended behaviour: the queue is a picture of what is currently true, not a log of everything that has ever been true — the Decision Log is that.