Start here
Core concepts
Projects, services, spans, traces, and the keys that connect them.
knotel uses OpenTelemetry's model of traces. If you've used Honeycomb, Jaeger or Datadog APM, most of this will be familiar.
Projects
A project groups the services you trace together, usually one per product or per environment. Each project has its own spans and its own ingest keys. Every member can see every project, and the Home page, Service map and Usage page cover all of them at once.
Services
A service is whatever sends spans under one service.name resource attribute: a website, a Worker, an API server. The browser script uses data-service (default: the page's hostname), and the Worker SDK uses its service option. Spans without a name are filed under unknown_service.
Spans and traces
A span is one timed operation: a page load, an HTTP request, a database query. It has a name, a kind, a start time, a duration, a status, attributes (key/value details such as http.route) and events (such as an exception with its stack trace).
A trace is every span that shares a trace id. Spans point to their parent, which gives the tree you see in the waterfall: the page load, the fetch it made, the Worker request that answered it, and the database calls inside that.
| Kind | Value | Used for |
|---|---|---|
| Internal | 1 | Work inside a service, custom spans, page load phases |
| Server | 2 | An incoming request handled by a service |
| Client | 3 | An outgoing call: fetch, HTTP client, database driver |
| Producer | 4 | Sending a message to a queue |
| Consumer | 5 | Processing queue messages |
Entry spans
Request counts, error rates and latency percentiles are computed over entry spans: server spans and trace roots (spans with no parent). Those are requests into a service. A request that makes ten database calls counts once, and its latency is the whole request's latency.
Errors
A span is an error when its status code is ERROR (2). The SDKs set it for HTTP responses of 500 and above, for thrown exceptions, and for uncaught errors and unhandled promise rejections in the browser. Exceptions are also attached as an exception event with the type, message and stack trace. At ingest, errors are fingerprinted by service, exception type and message (with ids and numbers folded) so the Errors page can group them.
Trace context propagation
Spans from different services join one trace through the W3C traceparent header (00-<trace id>-<span id>-01). The browser script adds it to requests to your own origin and to the hosts you list. The Worker SDK reads it from incoming requests and adds it to outgoing ones. The same links are how the service map knows which service calls which, even across projects.
Keys and tokens
| Credential | Looks like | Can do | Where |
|---|---|---|---|
| Ingest key | kn_… | Send spans to one project, from the domains and IPs it lists. Write-only, so it's safe in a public web page. | Project → Send data |
| Access token | knp_… | Read every project as you. Used by MCP clients. | Settings → Access tokens |
| Setup code | Any string | Claim a new instance once. | SETUP_TOKEN secret or Worker logs |
Keys and tokens are shown once and stored only as SHA-256 hashes. See Security.
Time ranges and percentiles
Dashboards look back 15 minutes, 1 hour, 6 hours, 24 hours, 7 days or 30 days from now. Durations are shown in milliseconds, and p50, p95 and p99 are nearest-rank percentiles. Times appear in your browser's time zone.