Introduction
What Unhandled records from your services in any language, which pages fill in on their own, and where to start reading.
Unhandled stores the traces, logs and metrics your services send over OpenTelemetry. It groups exceptions into issues and builds dashboards for requests, queries, jobs, emails and more from the same data. It works with any language or framework that exports OpenTelemetry. AdonisJS has a first-party agent that instruments the whole framework on install, Node.js frameworks have Unhandled SDKs, and every other runtime uses its standard OpenTelemetry SDK.
Create a service, install an SDK and see your first trace.
AdonisJS, Node.js, Express, Fastify, Hono, NestJS, Next.js, Python, Go, Ruby, PHP, Java and .NET.
Organizations, projects, services, environments and the DSN.
@unhandled/node, plus packages for Express, Fastify, Hono, NestJS and Next.js.
Everything @unhandled/agent-adonisjs records and how to tune it.
The wire contract for any other sender or Collector.
Front-end errors, network calls and page views.
Why data does not show up, in the order to check it.
What fills in on its own
A service that sends data with a valid DSN populates these pages. You create no dashboards and write no queries for them.
Each request, job or command as a tree of timed spans, joined across services.
Log records, linked to the trace and span that wrote them.
Every metric your services export, listed by name.
Exceptions grouped by type and in-app stack frames, with source lines and the affected user.
Calls, errors, average and P95 latency per method and route.
Database statements grouped by shape and ranked by total time.
Outgoing HTTP calls grouped by host.
Requests, errors and latency per signed-in user.
CPU, memory, V8 heap and event loop for each running instance.
Emails show mail sends from spans that carry email.system. Commands show CLI commands and scheduled tasks, and how long they ran. The AdonisJS agent creates both kinds of span for @adonisjs/mail and Ace. Other stacks fill both pages by following the semantic conventions.
What needs an instrumentation
These pages stay empty until matching spans arrive. Each one has a package or a convention to follow.
| Page | Source |
|---|---|
| Jobs | @adonisjs/queue or BullMQ |
| Cache | Bentocache |
| AI agents | The Vercel AI SDK or Mastra |
| MCP monitoring | The MCP server SDK |
| Analytics | Unhandled.track() in the Node.js SDK, or the browser SDK |
Beyond telemetry
HTTP checks on your URLs, published on a status page.
Latency and error-rate thresholds, delivered through notifications.
A marker on every chart for each release.
Charts you build yourself from any signal.
Link issues to GitHub and Linear, send alerts to Slack and Discord.
Let an AI assistant query your telemetry.
Built on OpenTelemetry
Unhandled receives standard OTLP over HTTP, as protobuf or JSON, on /v1/traces, /v1/logs and /v1/metrics. Nothing you instrument depends on an Unhandled API.
@unhandled/nodebuilds the OpenTelemetry Node SDK. The framework packages and the AdonisJS agent build on@unhandled/node.- Other languages use their OpenTelemetry SDK directly.
- The
destinationsoption of@unhandled/nodesends the same data to other OTLP endpoints at the same time. See Extra destinations. - Any SDK or Collector with an OTLP/HTTP exporter works. Point it at the origin of your DSN and send the
x-api-key,x-unhandled-service-idandx-unhandled-envheaders. Any OpenTelemetry SDK has the full contract.