knotelResources
Sign in
Browse resources

Start here

Getting started

Deploy knotel to your Cloudflare account, claim it, and send your first trace.

knotel is one Cloudflare Worker that stores spans in an Iceberg table on R2, with a D1 database and a KV namespace alongside it, all in your own account. This guide takes you from nothing to your first trace in about ten minutes.

What you need

  • A Cloudflare account. The Workers Free plan is enough to try it; the Workers Paid plan ($5/month) raises the limits and is what the cost estimate assumes.
  • For a command-line deploy: git and Bun (Node with npx works too).

Deploy

From a clone of the repository, one command builds the app and deploys it. The D1 database and KV namespace are created on the first deploy, and database migrations run inside the Worker on its first request, so there is no separate setup step.

git clone https://github.com/kien-ngo/knotel.git
cd knotel
bun install
bunx wrangler login
bun run deploy
More than one Cloudflare account?
Wrangler asks which account to use, or fails in CI. Set CLOUDFLARE_ACCOUNT_ID for the deploy, for example CLOUDFLARE_ACCOUNT_ID=… bun run deploy, or put account_id in a deploy target.

The deploy prints your Worker's URL, such as https://knotel.your-subdomain.workers.dev. To use your own domain, see Configuration.

Optional: the span store, for history past a week
Out of the box spans live in D1 for HOT_WINDOW_DAYS (7) and are then deleted; each project can keep less or more from Settings. To keep them for good, Cloudflare Pipelines can write every span to an Iceberg table on R2 as well. It needs the Workers Paid plan and takes a handful of wrangler commands, once — see Configuration.

Claim your instance

A new instance has no accounts. The first person to enter the setup code becomes its owner.

  1. Open the Worker URL and choose Set up this instance.
  2. Enter the setup code. If you set a SETUP_TOKEN secret, that's the code. Otherwise a one-time code is printed in the Worker's logs (Cloudflare dashboard → Workers & Pages → knotel → Logs).
  3. Enter your name, email and a password of at least 8 characters.

To choose the code yourself, set the secret before your first visit:

bunx wrangler secret put SETUP_TOKEN
There is no public sign-up
After the claim, the sign-up endpoint refuses new accounts. Members add teammates from Settings.

Send your first trace

  1. Create a project. Home offers a form when there are none; later ones come from Settings.
  2. Open the project's Send data page and create an ingest key, listing the domains and IP addresses it should accept data from: your site's domain for the script tag, your server's public IP for a backend. It's shown once, so copy it.
  3. Add the script tag or Worker SDK from that page (the snippets fill in your key), or send a test span straight away:
Test span with curl
START=$(($(date +%s) * 1000000000))
curl -X POST https://YOUR-INSTANCE/v1/traces \
  -H "content-type: application/json" \
  -H "x-knotel-key: kn_YOUR_KEY" \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"curl-test"}}]},
  "scopeSpans":[{"spans":[{"traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174",
  "name":"GET /hello","kind":2,"startTimeUnixNano":"'$START'","endTimeUnixNano":"'$((START + 120000000))'"}]}]}]}'

A 200 with {} means the span was stored. Open the project's Traces page and it's there. A 403 means the key doesn't allow the machine you ran curl on: the response names the IP it saw, so add it to the key.

Run it locally

bun run dev starts the app at http://localhost:3001 with a local D1 database, and prints the setup code in the terminal. To fill it with realistic traces (browser → API → MongoDB, Redis, Postgres and a third-party API, with some errors and a latency tail), create a key that accepts 127.0.0.1 and run:

bun run dev
bun scripts/send-test-spans.ts --url http://localhost:3001 --key kn_YOUR_KEY --traces 300 --hours 6

Next steps