observability

Traces

Live

Distributed tracing viewer for OpenTelemetry spans, service maps, and request waterfalls.

event.type === "trace" modules/traces

Overview

What Traces does

Traces accepts OpenTelemetry-style spans and stores request waterfalls by project, service, trace id, and span id. It is built for the debugging path after logs say something happened but not why.

The module keeps the ingest path plain JSON first, backed by stock PostgreSQL partitions and rollup tables. SDKs and existing OTLP exporters can feed the same span shape while the portal renders service maps, slow spans, and trace detail pages.

Wire payload

Same shape, three syntaxes

The wire protocol is plain HTTP, plain JSON, HMAC-SHA256. The TypeScript tab uses the SDK; the cURL tab is the raw HTTP equivalent; the Python tab shows the preview SDK shape.

import { createCuittyClient } from "@cuitty/sdk";
import { tracesPlugin } from "@cuitty/sdk/plugins/traces";

const cuitty = createCuittyClient({
  portalUrl: "https://app.cuitty.com",
  projectId: process.env.CUITTY_PROJECT_ID!,
  apiKey: process.env.CUITTY_API_KEY!,
});
cuitty.use(tracesPlugin());
cuitty.start();

await cuitty.emit({
  type: "trace",
  timestamp: new Date().toISOString(),
  data: {
    traceId: "trace_01",
    spanId: "span_01",
    serviceName: "portal",
    name: "GET /api/projects",
    durationMs: 42,
  },
});

Storage

Database schema

Excerpt from modules/traces/schema.sql. One libSQL file per module — back it up with cp.

CREATE TABLE cuitty_traces.spans (
  id BIGSERIAL PRIMARY KEY,
  project_id TEXT NOT NULL,
  trace_id TEXT NOT NULL,
  span_id TEXT NOT NULL,
  parent_span_id TEXT,
  service_name TEXT NOT NULL,
  name TEXT NOT NULL,
  start_time BIGINT NOT NULL,
  end_time BIGINT NOT NULL,
  attributes JSONB
);

Related modules

observability

Traces

What Traces does

Wire payload

Database schema

Related modules

Errors

Audit

Configs