Observability Basics

Monitoring versus observability

Monitoring watches for known, predefined conditions: is the error rate above a threshold, is the queue too deep. Observability is the broader property of being able to ask new questions about your system from the data it already emits, including questions you did not anticipate when you wrote the code.

The distinction matters because real incidents are rarely the ones you predicted. A well-monitored system tells you that something is wrong; an observable one gives you enough signal to work out why without shipping new code first. Aim for both — alert on the known, instrument for the unknown.

The three pillars

Three signal types cover most needs. Logs are discrete, timestamped events — rich detail about individual occurrences. Metrics are numeric aggregates over time — cheap to store and ideal for trends and alerts. Traces follow one request across services, showing where time went.

They complement each other. A metric tells you latency spiked at noon; a trace shows the spike lives in one downstream call; the logs for that call, found via a correlation identifier, explain the cause. No single pillar answers every question alone, which is why the three are most powerful when you can pivot smoothly between them. A practical setup lets you start from an alert on a metric, jump to traces for the affected window to see which hop slowed, and land on the logs that say exactly what went wrong — each step narrowing from aggregate to detail.

Match the signal to the question

Use the cheapest signal that answers your question. For "is the system healthy right now?" reach for metrics — they are compact and fast to aggregate. For "what exactly happened to this one request?" reach for logs and traces, which carry the detail. Trying to answer fleet-wide health questions from raw logs is slow and expensive; trying to debug a single request from coarse metrics is impossible.

A practical instrumentation order is metrics first for the signals you will alert on, then structured logs for detail, then tracing once you have multiple services. Build outward as your needs grow rather than instrumenting everything at once.

Instrument with restraint

More telemetry is not automatically better. High-cardinality labels, per-request metrics, and verbose logs can cost more than the system they observe and can bury the signal you need. Be deliberate: record what you would actually query during an incident, and sample or aggregate the rest.

Start from the questions you expect to ask, then add the minimum instrumentation to answer them. Our developer documentation describes the identifiers and response fields we expose so you can correlate your telemetry with ours. Review your dashboards periodically and retire signals nobody reads.