First event in five minutes

1. 01

   Install the agent

   One package, no build step. The agent buffers events in memory and flushes on a two-second interval, so an ingest outage costs you telemetry, never requests.

   bash

   npm install @tracepoint/node
   # or: pip install tracepoint · go get go.tracepoint.dev/agent

2. 02

   Set the key and the service name

   Write keys are per-environment and scoped to ingest only — a leaked write key cannot read your data or change a routing rule. Rotate from Settings → Keys without a redeploy; both keys stay valid for an hour.

   bash

   TRACEPOINT_KEY=wk_live_3f9a2c...
   TRACEPOINT_SERVICE=checkout-api
   TRACEPOINT_ENV=production

3. 03

   Add the middleware

   Mount it before your routes so the timer starts at the edge of your app. The route pattern is read from the router, which is what keeps /v2/checkout/:cartId one series instead of one per cart.

   ts

   import express from "express";
   import { tracepoint } from "@tracepoint/node";
   
   const app = express();
   
   app.use(tracepoint({
     service: process.env.TRACEPOINT_SERVICE,
     env: process.env.TRACEPOINT_ENV,
     // Health checks are excluded by default and never bill.
     ignore: ["/healthz", "/readyz", "/metrics"],
   }));
   
   app.post("/v2/checkout/:cartId", handleCheckout);

4. 04

   Confirm ingest

   Events appear in the console within about five seconds. If nothing arrives, the verify command tells you which of the three usual causes it is — wrong key, blocked egress, or a service name that does not match the one in the workspace.

   bash

   npx @tracepoint/cli verify
   
   ✓ key valid (workspace: northwind, env: production)
   ✓ egress to ingest.tracepoint.dev:443 ok
   ✓ 214 events received in the last 60s

# tracepoint.yml — checked into the repo, applied on push
rules:
  - name: checkout p99
    service: checkout-api
    signal: latency.p99
    route: "POST /v2/checkout/:cartId"
    condition: "> 800ms for 3m"
    severity: sev2
    notify: codeowners        # resolves via CODEOWNERS
    escalate_after: 10m

  - name: checkout 5xx
    service: checkout-api
    signal: errors.rate_5xx
    condition: "> 1% for 2m"
    severity: sev2
    notify: codeowners

  - name: novel log patterns
    service: "*"
    signal: logs.novel_pattern
    condition: "> 25/hr"
    severity: sev3
    notify: "@northwind/platform"

• Rules live in your repository and apply on push, so an alerting change goes through review like any other change.
• `notify: codeowners` resolves the owning team from the CODEOWNERS entry covering the route's handler, then pages that team's current on-call.
• Escalation is time-based per severity: unacknowledged sev1 escalates in 5 minutes, sev2 in 10, sev3 never pages outside working hours.
• Every destination — Slack, PagerDuty, Opsgenie, webhook — receives the same payload shape, documented under `POST /v1/incidents` below.

• POST/v1/events

  Ingest a batch of request, log, or check events.

  Up to 1,000 events per batch, gzip encouraged. Returns 202 with an accepted count; malformed events are reported individually rather than failing the batch.

• GET/v1/services

  List services in the workspace with current health, rpm, p99, and error rate.

• GET/v1/services/:service/routes

  Per-route percentiles and error rates over a time window.

  Window defaults to 1h. `resolution=1m` is available for the last 24 hours, `5m` for the rest of retention.

• GET/v1/incidents

  List incidents, filterable by service, severity, and state.

• PATCH/v1/incidents/:id

  Acknowledge, reassign, or resolve an incident.

  The same call the Slack action buttons make. Acknowledgement is idempotent.

• POST/v1/deploys

  Record a deploy so it appears as a marker on every chart.

  Send `service`, `sha`, and optionally `diff_url`. The GitHub Actions integration calls this for you.

• GET/v1/metrics

  Read back computed series in Prometheus exposition format.

  Available on every plan including Starter. Scoped to the API key's workspace.

Base URL is https://api.tracepoint.dev. Ingest terminates separately at ingest.tracepoint.dev in all four regions; the SDK picks the nearest and fails over on its own.

Colour tokens

• --backgroundPage ground
• --cardPanel and card surface
• --mutedRecessed rows, table headers
• --borderHairlines and panel edges
• --primarySignal cyan — actions, healthy series
• --accentAlert violet — eventing and routing surfaces
• --successHealthy state only
• --destructiveIncidents. Never decoration.

Every pair clears WCAG AA in both themes. Values are declared once in forge-theme.css and consumed everywhere as variables — there are no hex codes in any component.

Type scale

• DisplayKnow what brokeChivo 600 · 3.5rem / 1.03 · -0.03em
• HeadingAlert rules and routingChivo 600 · 2rem / 1.12 · -0.028em
• BodyPercentiles are computed per route, over rolling one-minute windows.Manrope 400 · 1.0625rem / 1.65
• Marker/ SIGNALSJetBrains Mono 500 · 0.7rem · 0.16em, uppercase
• Codep99 1,412ms · 3.10% · 4.2k rpmJetBrains Mono 400 · 0.85rem / 1.6 · tabular

Components

• Radii are 6px. Nothing on this site is a pill — a console has corners, and the marketing site should not promise a shape the product does not have.
• Numbers are always tabular and always monospace, including in body copy. A latency figure that reflows as it updates reads as decoration rather than as data.
• Red is reserved for incidents. A destructive-coloured button on a page about alerting would be the single most confusing thing we could do.
• Every panel is a 1px border and a flat surface. Elevation is used once, on the hero composition, and nowhere else.