Skip to content

The only tool you need to know what is happening and how to fix it.

feat: restructure skills into installable agent-skills format (#190) (#195)

Jovan Stojiljkovic7adc23654e4c
diff --git a/cli/.claude/skills/traceway-cli.md b/cli/.claude/skills/traceway-cli.md
index 7814ef99..3224e83a 100644
--- a/cli/.claude/skills/traceway-cli.md
+++ b/cli/.claude/skills/traceway-cli.md
@@ -193,6 +193,8 @@ traceway metrics query --name <metric.name>
`--name` is required; omitting it exits with code 2 and `usage_error`.
+**Percentile caveat:** the CLI accepts `p50`/`p95`/`p99` but the server has no quantile aggregation for metric points — it silently computes `avg` for them. Do not present percentile results from `metrics query` to a user; latency percentiles come from `traceway endpoints list` (computed from raw request durations).
+
**There is no `metrics list` / `metrics discover` subcommand.** The CLI cannot enumerate available metric names — the user has to provide one, or you have to guess from OpenTelemetry semantic conventions. Names observed live: `system.cpu.utilization`, `system.network.io`, `system.network.errors`, `system.network.dropped`. If the user is checking system telemetry, those four are the likeliest starting points; if they're checking app-level metrics, ask.
A bogus metric name returns exit 0 with `series: {}` (clean empty, not an error). Use that to probe whether a name exists.
diff --git a/frontend/src/lib/components/setup/ai-setup-steps.svelte b/frontend/src/lib/components/setup/ai-setup-steps.svelte
new file mode 100644
index 00000000..a5bb1596
--- /dev/null
+++ b/frontend/src/lib/components/setup/ai-setup-steps.svelte
@@ -0,0 +1,52 @@
+<script lang="ts">
+ import bash from 'svelte-highlight/languages/bash';
+ import { SKILL_INSTALL_COMMAND, getSetupPromptParts } from '$lib/utils/ai-setup';
+ import { projectsState } from '$lib/state/projects.svelte';
+ import CopyableCodeBlock from './copyable-code-block.svelte';
+ import CopyablePrompt from './copyable-prompt.svelte';
+
+ let { backendUrl, token }: { backendUrl: string; token: string } = $props();
+
+ const sourceMapToken = $derived(projectsState.currentProject?.sourceMapToken ?? null);
+ const promptParts = $derived(getSetupPromptParts(backendUrl, token, sourceMapToken));
+</script>
+
+<div class="rounded-md border bg-card">
+ <div class="border-b px-4 py-3">
+ <div class="flex items-center gap-3">
+ <div
+ class="flex h-6 w-6 items-center justify-center rounded-full bg-primary text-sm font-medium text-primary-foreground"
+ >
+ 1
+ </div>
+ <h3 class="font-semibold">Install the Traceway Skill</h3>
+ </div>
+ <p class="mt-1 ml-9 text-sm text-muted-foreground">
+ Add the Traceway setup skill to your coding agent. Works with Claude Code, Cursor, and any
+ agent that supports agent skills.
+ </p>
+ </div>
+ <div class="p-4">
+ <CopyableCodeBlock code={SKILL_INSTALL_COMMAND} language={bash} />
+ </div>
+</div>
+
+<div class="rounded-md border bg-card">
+ <div class="border-b px-4 py-3">
+ <div class="flex items-center gap-3">
+ <div
+ class="flex h-6 w-6 items-center justify-center rounded-full bg-primary text-sm font-medium text-primary-foreground"
+ >
+ 2
+ </div>
+ <h3 class="font-semibold">Run the Setup Prompt</h3>
+ </div>
+ <p class="mt-1 ml-9 text-sm text-muted-foreground">
+ Paste this prompt into your agent. Your instance URL and project token are already filled
+ in{sourceMapToken ? ', along with your source map upload token' : ''}.
+ </p>
+ </div>
+ <div class="p-4">
+ <CopyablePrompt parts={promptParts} />
+ </div>
+</div>
diff --git a/frontend/src/lib/components/setup/copyable-code-block.svelte b/frontend/src/lib/components/setup/copyable-code-block.svelte
new file mode 100644
index 00000000..4cb8d83b
--- /dev/null
+++ b/frontend/src/lib/components/setup/copyable-code-block.svelte
@@ -0,0 +1,108 @@
+<script lang="ts">
+ import { Button } from '$lib/components/ui/button';
+ import { Copy, Check } from 'lucide-svelte';
+ import Highlight from 'svelte-highlight';
+ import type { LanguageFn } from 'highlight.js';
+ import { themeState } from '$lib/state/theme.svelte';
+ import 'svelte-highlight/styles/github-dark.css';
+
+ let {
+ code,
+ language,
+ wrap = false
+ }: { code: string; language: { name: string; register: LanguageFn }; wrap?: boolean } = $props();
+
+ let copied = $state(false);
+
+ async function copy() {
+ await navigator.clipboard.writeText(code);
+ copied = true;
+ setTimeout(() => (copied = false), 2000);
+ }
+</script>
+
+<div class="relative">
+ <div class="absolute top-2 right-2 z-10">
+ <Button variant="outline" size="sm" onclick={copy}>
+ {#if copied}
+ <Check class="mr-2 h-4 w-4 text-green-500" />
+ Copied!
+ {:else}
+ <Copy class="mr-2 h-4 w-4" />
+ Copy
+ {/if}
+ </Button>
+ </div>
+ <div
+ class="overflow-x-auto rounded-lg text-sm {wrap ? 'wrap-code' : ''} {themeState.isDark
+ ? 'dark-code'
+ : 'light-code'}"
+ >
+ <Highlight {language} {code} />
+ </div>
+</div>
+
+<style>
+ :global(.wrap-code pre code) {
+ white-space: pre-wrap;
+ word-break: break-word;
+ }
+
+ :global(.light-code .hljs-name) {
+ color: #4ba3f7;
+ }
+ :global(.light-code .hljs) {
+ background: #f6f8fa;
+ color: #24292e;
+ }
+ :global(.light-code .hljs-keyword),
+ :global(.light-code .hljs-selector-tag) {
+ color: #d73a49;
+ }
+ :global(.light-code .hljs-string),
+ :global(.light-code .hljs-attr) {
+ color: #032f62;
+ }
+ :global(.light-code .hljs-function),
+ :global(.light-code .hljs-title) {
+ color: #6f42c1;
+ }
+ :global(.light-code .hljs-comment) {
+ color: #6a737d;
+ }
+ :global(.light-code .hljs-built_in) {
+ color: #005cc5;
+ }
+ :global(.light-code .hljs-meta) {
+ color: #d73a49;
+ }
+ :global(.light-code .hljs-variable) {
+ color: #24292e;
+ }
+
+ :global(.dark-code .hljs) {
+ background: #0d1117;
+ color: #c9d1d9;
+ }
+ :global(.dark-code .hljs-keyword),
+ :global(.dark-code .hljs-selector-tag) {
+ color: #ff7b72;
+ }
+ :global(.dark-code .hljs-string),
+ :global(.dark-code .hljs-attr) {
+ color: #a5d6ff;
+ }
+ :global(.dark-code .hljs-function),
+ :global(.dark-code .hljs-title) {
+ color: #d2a8ff;
+ }
+ :global(.dark-code .hljs-comment) {
+ color: #8b949e;
+ }
+ :global(.dark-code .hljs-built_in) {
+ color: #79c0ff;
+ }
+ :global(.dark-code .hljs-meta) {
+ color: #ff7b72;
+ }
+</style>
diff --git a/frontend/src/lib/components/setup/copyable-inline.svelte b/frontend/src/lib/components/setup/copyable-inline.svelte
new file mode 100644
index 00000000..1ce79592
--- /dev/null
+++ b/frontend/src/lib/components/setup/copyable-inline.svelte
@@ -0,0 +1,25 @@
+<script lang="ts">
+ import { Button } from '$lib/components/ui/button';
+ import { Copy, Check } from 'lucide-svelte';
+
+ let { value }: { value: string } = $props();
+
+ let copied = $state(false);
+
+ async function copy() {
+ await navigator.clipboard.writeText(value);
+ copied = true;
+ setTimeout(() => (copied = false), 2000);
+ }
+</script>
+
+<div class="flex items-center gap-2">
+ <code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-sm break-all">{value}</code>
+ <Button variant="outline" size="sm" onclick={copy}>
+ {#if copied}
+ <Check class="h-4 w-4 text-green-500" />
+ {:else}
+ <Copy class="h-4 w-4" />
+ {/if}
+ </Button>
+</div>
diff --git a/frontend/src/lib/components/setup/copyable-prompt.svelte b/frontend/src/lib/components/setup/copyable-prompt.svelte
new file mode 100644
index 00000000..b5470c71
--- /dev/null
+++ b/frontend/src/lib/components/setup/copyable-prompt.svelte
@@ -0,0 +1,42 @@
+<script lang="ts">
+ import { Button } from '$lib/components/ui/button';
+ import { Copy, Check } from 'lucide-svelte';
+ import type { PromptPart } from '$lib/utils/ai-setup';
+
+ let { parts }: { parts: PromptPart[] } = $props();
+
+ const text = $derived(parts.map((p) => p.text).join(''));
+
+ let copied = $state(false);
+
+ async function copy() {
+ await navigator.clipboard.writeText(text);
+ copied = true;
+ setTimeout(() => (copied = false), 2000);
+ }
+</script>
+
+<div class="relative">
+ <div class="absolute top-2 right-2 z-10">
+ <Button variant="outline" size="sm" onclick={copy}>
+ {#if copied}
+ <Check class="mr-2 h-4 w-4 text-green-500" />
+ Copied!
+ {:else}
+ <Copy class="mr-2 h-4 w-4" />
+ Copy
+ {/if}
+ </Button>
+ </div>
+ <code
+ class="block rounded-lg bg-muted py-3 pr-24 pl-4 font-mono text-sm break-words whitespace-pre-wrap text-foreground"
+ >
+ {#each parts as part, i (i)}
+ {#if part.bold}
+ <span class="break-all text-muted-foreground">{part.text}</span>
+ {:else}
+ {part.text}
+ {/if}
+ {/each}
+ </code>
+</div>
diff --git a/frontend/src/lib/components/setup/otel-exporter-config.svelte b/frontend/src/lib/components/setup/otel-exporter-config.svelte
new file mode 100644
index 00000000..1c1d8906
--- /dev/null
+++ b/frontend/src/lib/components/setup/otel-exporter-config.svelte
@@ -0,0 +1,33 @@
+<script lang="ts">
+ import yaml from 'svelte-highlight/languages/yaml';
+ import CopyableInline from './copyable-inline.svelte';
+ import CopyableCodeBlock from './copyable-code-block.svelte';
+
+ let {
+ endpoint,
+ authHeader,
+ collectorConfig
+ }: { endpoint: string; authHeader: string; collectorConfig: string } = $props();
+</script>
+
+<div class="space-y-6">
+ <div>
+ <p class="mb-1 text-sm font-medium">OTLP Endpoint</p>
+ <p class="mb-2 text-xs text-muted-foreground">
+ Your SDK or Collector will append <code
+ class="rounded bg-muted px-1 py-0.5 font-mono text-xs">/v1/traces</code
+ >
+ and
+ <code class="rounded bg-muted px-1 py-0.5 font-mono text-xs">/v1/metrics</code> automatically.
+ </p>
+ <CopyableInline value={endpoint} />
+ </div>
+ <div>
+ <p class="mb-2 text-sm font-medium">Authorization Header</p>
+ <CopyableInline value={authHeader} />
+ </div>
+ <div>
+ <p class="mb-2 text-sm font-medium">Example: OTel Collector (optional)</p>
+ <CopyableCodeBlock code={collectorConfig} language={yaml} />
+ </div>
+</div>
diff --git a/frontend/src/lib/components/setup/otel-setup-steps.svelte b/frontend/src/lib/components/setup/otel-setup-steps.svelte
new file mode 100644
index 00000000..b6cab16b
--- /dev/null
+++ b/frontend/src/lib/components/setup/otel-setup-steps.svelte
@@ -0,0 +1,126 @@
+<script lang="ts">
+ import * as Tabs from '$lib/components/ui/tabs';
+ import bash from 'svelte-highlight/languages/bash';
+ import go from 'svelte-highlight/languages/go';
+ import javascript from 'svelte-highlight/languages/javascript';
+ import typescript from 'svelte-highlight/languages/typescript';
+ import python from 'svelte-highlight/languages/python';
+ import gradle from 'svelte-highlight/languages/gradle';
+ import csharp from 'svelte-highlight/languages/csharp';
+ import ruby from 'svelte-highlight/languages/ruby';
+ import yaml from 'svelte-highlight/languages/yaml';
+ import {
+ OTEL_TARGETS,
+ getOtelSteps,
+ type OtelStepLanguage,
+ type OtelTargetId
+ } from '$lib/utils/otel-setup';
+ import {
+ getOtelTarget,
+ setOtelTarget,
+ getOtelFramework,
+ setOtelFramework
+ } from '$lib/utils/setup-storage';
+ import CopyableCodeBlock from './copyable-code-block.svelte';
+ import SourceMapUploadCard from './source-map-upload-card.svelte';
+
+ let { backendUrl, token }: { backendUrl: string; token: string } = $props();
+
+ let target = $state(getOtelTarget());
+ let framework = $state(getOtelFramework());
+
+ const highlightLanguages = {
+ bash,
+ go,
+ javascript,
+ typescript,
+ python,
+ gradle,
+ csharp,
+ ruby,
+ yaml
+ };
+
+ const targetDef = $derived(OTEL_TARGETS.find((t) => t.id === target) ?? OTEL_TARGETS[0]);
+ const activeFramework = $derived(
+ targetDef.frameworks.find((f) => f.id === framework)?.id ?? targetDef.frameworks[0]?.id ?? ''
+ );
+ const steps = $derived(getOtelSteps(targetDef.id, activeFramework, backendUrl, token));
+
+ function handleTargetChange(value: string) {
+ const next = OTEL_TARGETS.find((t) => t.id === value);
+ if (next) {
+ target = next.id;
+ setOtelTarget(next.id);
+ }
+ }
+
+ function handleFrameworkChange(value: string) {
+ if (targetDef.frameworks.some((f) => f.id === value)) {
+ framework = value;
+ setOtelFramework(value);
+ }
+ }
+
+ function languageFor(id: OtelStepLanguage | undefined) {
+ return highlightLanguages[id ?? 'bash'];
+ }
+</script>
+
+<div class="space-y-2">
+ <p class="text-sm font-medium">Language</p>
+ <Tabs.Root value={target} onValueChange={handleTargetChange}>
+ <Tabs.List class="h-auto flex-wrap justify-start">
+ {#each OTEL_TARGETS as t (t.id)}
+ <Tabs.Trigger value={t.id}>{t.label}</Tabs.Trigger>
+ {/each}
+ </Tabs.List>
+ </Tabs.Root>
+ {#if targetDef.frameworks.length > 1}
+ <p class="pt-1 text-sm font-medium">Framework</p>
+ <Tabs.Root value={activeFramework} onValueChange={handleFrameworkChange}>
+ <Tabs.List class="h-auto flex-wrap justify-start">
+ {#each targetDef.frameworks as f (f.id)}
+ <Tabs.Trigger value={f.id}>{f.label}</Tabs.Trigger>
+ {/each}
+ </Tabs.List>
+ </Tabs.Root>
+ {/if}
+</div>
+
+{#each steps as step, i (targetDef.id + activeFramework + step.title)}
+ <div class="rounded-md border bg-card">
+ <div class="border-b px-4 py-3">
+ <div class="flex items-center gap-3">
+ <div
+ class="flex h-6 w-6 items-center justify-center rounded-full bg-primary text-sm font-medium text-primary-foreground"
+ >
+ {i + 1}
+ </div>
+ <h3 class="font-semibold">{step.title}</h3>
+ </div>
+ {#if step.description}
+ <p class="mt-1 ml-9 text-sm text-muted-foreground">{step.description}</p>
+ {/if}
+ </div>
+ {#if step.code}
+ <div class="p-4">
+ <CopyableCodeBlock code={step.code} language={languageFor(step.codeLanguage)} />
+ {#if step.link}
+ <p class="pt-2 text-xs text-muted-foreground">
+ <a
+ href={step.link.href}
+ target="_blank"
+ rel="noopener noreferrer"
+ class="underline hover:text-foreground">{step.link.label}</a
+ >
+ </p>
+ {/if}
+ </div>
+ {/if}
+ </div>
+{/each}
+
+{#if target === 'nodejs'}
+ <SourceMapUploadCard />
+{/if}
diff --git a/frontend/src/lib/components/setup/setup-mode-tabs.svelte b/frontend/src/lib/components/setup/setup-mode-tabs.svelte
new file mode 100644
index 00000000..363919c2
--- /dev/null
+++ b/frontend/src/lib/components/setup/setup-mode-tabs.svelte
@@ -0,0 +1,24 @@
+<script lang="ts">
+ import * as Tabs from '$lib/components/ui/tabs';
+ import { setSetupMode, type SetupMode } from '$lib/utils/setup-storage';
+
+ let { mode, onModeChange }: { mode: SetupMode; onModeChange: (mode: SetupMode) => void } =
+ $props();
+
+ const tabTriggerClass =
+ '-mb-px rounded-none border-b-2 border-transparent bg-transparent px-0 pb-2.5 pt-0 text-sm font-medium text-muted-foreground shadow-none data-[state=active]:border-primary data-[state=active]:bg-transparent data-[state=active]:text-foreground data-[state=active]:shadow-none';
+
+ function handleChange(value: string) {
+ if (value === 'ai' || value === 'manual') {
+ setSetupMode(value);
+ onModeChange(value);
+ }
+ }
+</script>
+
+<Tabs.Root value={mode} onValueChange={handleChange}>
+ <Tabs.List class="h-auto w-full justify-start gap-4 rounded-none border-b bg-transparent p-0">
+ <Tabs.Trigger value="ai" class={tabTriggerClass}>AI</Tabs.Trigger>
+ <Tabs.Trigger value="manual" class={tabTriggerClass}>Manual</Tabs.Trigger>
+ </Tabs.List>
+</Tabs.Root>
diff --git a/frontend/src/lib/components/setup/source-map-upload-card.svelte b/frontend/src/lib/components/setup/source-map-upload-card.svelte
new file mode 100644
index 00000000..a6f7b416
--- /dev/null
+++ b/frontend/src/lib/components/setup/source-map-upload-card.svelte
@@ -0,0 +1,38 @@
+<script lang="ts">
+ import {
+ Card,
+ CardContent,
+ CardDescription,
+ CardHeader,
+ CardTitle
+ } from '$lib/components/ui/card';
+ import { KeyRound } from 'lucide-svelte';
+ import { projectsState } from '$lib/state/projects.svelte';
+ import { authState } from '$lib/state/auth.svelte';
+ import SourceMapSetup from '$lib/components/source-map-setup.svelte';
+
+ let projectWithToken = $derived(projectsState.currentProject);
+
+ const isReadonly = $derived(
+ authState.getRoleForOrganization(projectsState.currentProject?.organizationId ?? 0) ===
+ 'readonly'
+ );
+</script>
+
+{#if projectWithToken && !isReadonly}
+ <Card>
+ <CardHeader>
+ <CardTitle class="flex items-center gap-2">
+ <KeyRound class="h-5 w-5" />
+ Source Map Upload
+ </CardTitle>
+ <CardDescription>
+ Upload source maps to see original file names and line numbers in stack traces from
+ minified code.
+ </CardDescription>
+ </CardHeader>
+ <CardContent>
+ <SourceMapSetup />
+ </CardContent>
+ </Card>
+{/if}
diff --git a/frontend/src/lib/utils/ai-setup.ts b/frontend/src/lib/utils/ai-setup.ts
new file mode 100644
index 00000000..c21700d7
--- /dev/null
+++ b/frontend/src/lib/utils/ai-setup.ts
@@ -0,0 +1,36 @@
+export const SKILL_INSTALL_COMMAND = 'npx skills add tracewayapp/traceway';
+
+export type PromptPart = {
+ text: string;
+ bold: boolean;
+};
+
+export function getSetupPromptParts(
+ backendUrl: string,
+ token: string,
+ sourceMapToken: string | null = null
+): PromptPart[] {
+ const parts: PromptPart[] = [
+ { text: '/traceway-setup with token ', bold: false },
+ { text: token, bold: true },
+ { text: ' and url ', bold: false },
+ { text: backendUrl, bold: true }
+ ];
+ if (sourceMapToken) {
+ parts.push(
+ { text: ' and source map upload token ', bold: false },
+ { text: sourceMapToken, bold: true }
+ );
+ }
+ return parts;
+}
+
+export function getSetupPrompt(
+ backendUrl: string,
+ token: string,
+ sourceMapToken: string | null = null
+): string {
+ return getSetupPromptParts(backendUrl, token, sourceMapToken)
+ .map((p) => p.text)
+ .join('');
+}
diff --git a/frontend/src/lib/utils/otel-sdks.ts b/frontend/src/lib/utils/otel-sdks.ts
new file mode 100644
index 00000000..827fb3db
--- /dev/null
+++ b/frontend/src/lib/utils/otel-sdks.ts
@@ -0,0 +1,42 @@
+export type OtelSdkId = 'nodejs' | 'go' | 'python' | 'java' | 'dotnet' | 'php';
+
+export type OtelSdk = {
+ id: OtelSdkId;
+ label: string;
+ installCommand: string;
+};
+
+export const OTEL_SDKS: OtelSdk[] = [
+ {
+ id: 'nodejs',
+ label: 'Node.js',
+ installCommand:
+ 'npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http'
+ },
+ {
+ id: 'go',
+ label: 'Go',
+ installCommand: 'go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp'
+ },
+ {
+ id: 'python',
+ label: 'Python',
+ installCommand: 'pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http'
+ },
+ {
+ id: 'java',
+ label: 'Java',
+ installCommand: "implementation 'io.opentelemetry:opentelemetry-exporter-otlp'"
+ },
+ {
+ id: 'dotnet',
+ label: '.NET',
+ installCommand: 'dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol'
+ },
+ {
+ id: 'php',
+ label: 'PHP',
+ installCommand:
+ 'composer require open-telemetry/sdk open-telemetry/exporter-otlp php-http/guzzle7-adapter'
+ }
+];
diff --git a/frontend/src/lib/utils/otel-setup.ts b/frontend/src/lib/utils/otel-setup.ts
new file mode 100644
index 00000000..9180102b
--- /dev/null
+++ b/frontend/src/lib/utils/otel-setup.ts
@@ -0,0 +1,566 @@
+export type OtelTargetId =
+ | 'collector'
+ | 'nodejs'
+ | 'go'
+ | 'python'
+ | 'java'
+ | 'dotnet'
+ | 'php'
+ | 'ruby'
+ | 'other';
+
+export type OtelFramework = {
+ id: string;
+ label: string;
+};
+
+export type OtelTarget = {
+ id: OtelTargetId;
+ label: string;
+ frameworks: OtelFramework[];
+};
+
+export type OtelStepLanguage =
+ | 'bash'
+ | 'go'
+ | 'javascript'
+ | 'typescript'
+ | 'python'
+ | 'gradle'
+ | 'csharp'
+ | 'ruby'
+ | 'yaml';
+
+export type OtelStep = {
+ title: string;
+ description?: string;
+ code?: string;
+ codeLanguage?: OtelStepLanguage;
+ link?: { label: string; href: string };
+};
+
+export const OTEL_TARGETS: OtelTarget[] = [
+ { id: 'collector', label: 'Collector', frameworks: [] },
+ {
+ id: 'nodejs',
+ label: 'Node.js',
+ frameworks: [
+ { id: 'express', label: 'Express' },
+ { id: 'nestjs', label: 'NestJS' },
+ { id: 'fastify', label: 'Fastify' },
+ { id: 'nextjs', label: 'Next.js' },
+ { id: 'koa', label: 'Koa' },
+ { id: 'other', label: 'Other' }
+ ]
+ },
+ {
+ id: 'go',
+ label: 'Go',
+ frameworks: [
+ { id: 'gin', label: 'Gin' },
+ { id: 'echo', label: 'Echo' },
+ { id: 'chi', label: 'Chi' },
+ { id: 'fiber', label: 'Fiber' },
+ { id: 'mux', label: 'gorilla/mux' },
+ { id: 'nethttp', label: 'net/http' }
+ ]
+ },
+ {
+ id: 'python',
+ label: 'Python',
+ frameworks: [
+ { id: 'django', label: 'Django' },
+ { id: 'flask', label: 'Flask' },
+ { id: 'fastapi', label: 'FastAPI' },
+ { id: 'other', label: 'Other' }
+ ]
+ },
+ {
+ id: 'java',
+ label: 'Java',
+ frameworks: [
+ { id: 'agent', label: 'Any framework' },
+ { id: 'spring', label: 'Spring Boot' }
+ ]
+ },
+ { id: 'dotnet', label: '.NET', frameworks: [] },
+ {
+ id: 'php',
+ label: 'PHP',
+ frameworks: [
+ { id: 'symfony', label: 'Symfony' },
+ { id: 'laravel', label: 'Laravel' },
+ { id: 'slim', label: 'Slim' },
+ { id: 'other', label: 'Other' }
+ ]
+ },
+ {
+ id: 'ruby',
+ label: 'Ruby',
+ frameworks: [
+ { id: 'rails', label: 'Rails' },
+ { id: 'other', label: 'Other' }
+ ]
+ },
+ { id: 'other', label: 'Other', frameworks: [] }
+];
+
+function envBlock(backendUrl: string, token: string, extra: string[] = []): string {
+ return [
+ 'OTEL_SERVICE_NAME=my-service',
+ `OTEL_EXPORTER_OTLP_ENDPOINT=${backendUrl}/api/otel`,
+ `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${token}`,
+ ...extra
+ ].join('\n');
+}
+
+function envStep(backendUrl: string, token: string, extra: string[] = [], note = ''): OtelStep {
+ return {
+ title: 'Configure the Exporter',
+ description: `Set these environment variables in your shell, .env file, or deployment config. The SDK appends /v1/traces and /v1/metrics to the endpoint automatically.${note ? ' ' + note : ''}`,
+ code: envBlock(backendUrl, token, extra),
+ codeLanguage: 'bash'
+ };
+}
+
+function collectorConfig(backendUrl: string, token: string): string {
+ return `exporters:
+ otlphttp:
+ endpoint: "${backendUrl}/api/otel"
+ headers:
+ Authorization: "Bearer ${token}"
+
+service:
+ pipelines:
+ traces:
+ exporters: [otlphttp]
+ metrics:
+ exporters: [otlphttp]`;
+}
+
+const GO_BOOTSTRAP = `import (
+ "context"
+ "log"
+
+ "go.opentelemetry.io/otel"
+ "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+ "go.opentelemetry.io/otel/propagation"
+ sdktrace "go.opentelemetry.io/otel/sdk/trace"
+)
+
+func initTracer(ctx context.Context) *sdktrace.TracerProvider {
+ exp, err := otlptracehttp.New(ctx)
+ if err != nil {
+ log.Fatal(err)
+ }
+ tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp))
+ otel.SetTracerProvider(tp)
+ otel.SetTextMapPropagator(propagation.TraceContext{})
+ return tp
+}`;
+
+const GO_FRAMEWORKS: Record<string, { lib: string; snippet: string; note?: string }> = {
+ gin: {
+ lib: 'go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin',
+ snippet: `import "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
+
+r := gin.Default()
+r.Use(otelgin.Middleware("my-service"))`
+ },
+ echo: {
+ lib: 'go.opentelemetry.io/contrib/instrumentation/github.com/labstack/echo/otelecho',
+ snippet: `import "go.opentelemetry.io/contrib/instrumentation/github.com/labstack/echo/otelecho"
+
+e := echo.New()
+e.Use(otelecho.Middleware("my-service"))`
+ },
+ chi: {
+ lib: 'github.com/riandyrn/otelchi',
+ snippet: `import "github.com/riandyrn/otelchi"
+
+r := chi.NewRouter()
+r.Use(otelchi.Middleware("my-service", otelchi.WithChiRoutes(r)))`,
+ note: 'WithChiRoutes lets the middleware resolve the route pattern so endpoints group correctly.'
+ },
+ fiber: {
+ lib: 'github.com/gofiber/contrib/v3/otel',
+ snippet: `import fiberotel "github.com/gofiber/contrib/v3/otel"
+
+app := fiber.New()
+app.Use(fiberotel.Middleware())`,
+ note: 'For Fiber v2 use github.com/gofiber/contrib/otelfiber/v2 and otelfiber.Middleware() instead.'
+ },
+ mux: {
+ lib: 'go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux',
+ snippet: `import "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux"
+
+r := mux.NewRouter()
+r.Use(otelmux.Middleware("my-service"))`
+ },
+ nethttp: {
+ lib: 'go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp',
+ snippet: `import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+
+mux := http.NewServeMux()
+mux.Handle("GET /users/{id}", otelhttp.NewHandler(http.HandlerFunc(getUser), "GET /users/{id}"))
+http.ListenAndServe(":8080", mux)`,
+ note: 'Wrap each route individually with Go 1.22+ method patterns so the route is set on spans and endpoints group by pattern instead of raw URL.'
+ }
+};
+
+const NODE_ZERO_CODE_INSTALL = 'npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node';
+
+function nodeZeroCodeSteps(
+ backendUrl: string,
+ token: string,
+ entrypoint: string,
+ installNote: string,
+ runNote: string
+): OtelStep[] {
+ return [
+ {
+ title: 'Install the SDK',
+ description: installNote,
+ code: NODE_ZERO_CODE_INSTALL,
+ codeLanguage: 'bash'
+ },
+ envStep(backendUrl, token),
+ {
+ title: 'Run with Instrumentation',
+ description: runNote,
+ code: `node --require @opentelemetry/auto-instrumentations-node/register ${entrypoint}`,
+ codeLanguage: 'bash'
+ }
+ ];
+}
+
+export function getOtelSteps(
+ target: OtelTargetId,
+ framework: string,
+ backendUrl: string,
+ token: string
+): OtelStep[] {
+ switch (target) {
+ case 'collector':
+ return [
+ {
+ title: 'Add the Traceway Exporter',
+ description:
+ 'Merge this into your OpenTelemetry Collector configuration. Any pipeline that lists the otlphttp exporter will be forwarded to Traceway.',
+ code: collectorConfig(backendUrl, token),
+ codeLanguage: 'yaml'
+ },
+ {
+ title: 'Restart the Collector',
+ description:
+ 'Restart the Collector to apply the configuration. Traces and metrics flowing through its pipelines will appear in Traceway.'
+ }
+ ];
+
+ case 'nodejs': {
+ if (framework === 'fastify') {
+ return [
+ {
+ title: 'Install the SDK',
+ description:
+ 'Fastify is instrumented by the @fastify/otel package maintained by the Fastify team.',
+ code: 'npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @fastify/otel',
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Create instrumentation.js',
+ description: 'Add this file at the project root.',
+ code: `const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+const { FastifyOtelInstrumentation } = require('@fastify/otel');
+
+new NodeSDK({
+ instrumentations: [
+ getNodeAutoInstrumentations(),
+ new FastifyOtelInstrumentation({ registerOnInitialization: true }),
+ ],
+}).start();`,
+ codeLanguage: 'javascript'
+ },
+ envStep(backendUrl, token),
+ {
+ title: 'Run with Instrumentation',
+ code: 'node --require ./instrumentation.js app.js',
+ codeLanguage: 'bash'
+ }
+ ];
+ }
+ if (framework === 'nextjs') {
+ return [
+ {
+ title: 'Install the SDK',
+ code: 'npm install @vercel/otel',
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Create instrumentation.ts',
+ description:
+ 'Add this file at the project root (next to package.json). Next.js calls register() automatically on startup.',
+ code: `import { registerOTel } from '@vercel/otel'
+
+export function register() {
+ registerOTel({ serviceName: 'my-service' })
+}`,
+ codeLanguage: 'typescript'
+ },
+ envStep(
+ backendUrl,
+ token,
+ [],
+ 'Start your app normally with next start; no extra flags are needed.'
+ )
+ ];
+ }
+ if (framework === 'nestjs') {
+ return nodeZeroCodeSteps(
+ backendUrl,
+ token,
+ 'dist/main.js',
+ 'Auto-instrumentation captures NestJS routes, status codes, and errors through the default Express adapter with no code changes. If you use the Fastify adapter, follow the Fastify setup instead.',
+ 'Routes group by pattern automatically.'
+ );
+ }
+ if (framework === 'koa') {
+ return nodeZeroCodeSteps(
+ backendUrl,
+ token,
+ 'app.js',
+ 'Auto-instrumentation captures Koa requests, status codes, and errors with no code changes.',
+ 'Route patterns are captured when routing with @koa/router.'
+ );
+ }
+ return nodeZeroCodeSteps(
+ backendUrl,
+ token,
+ 'app.js',
+ 'Auto-instrumentation captures routes, status codes, and errors with no code changes.',
+ 'For ESM apps, add --experimental-loader=@opentelemetry/instrumentation/hook.mjs and use --import instead of --require.'
+ );
+ }
+
+ case 'go': {
+ const fw = GO_FRAMEWORKS[framework] ?? GO_FRAMEWORKS.gin;
+ return [
+ {
+ title: 'Install the SDK',
+ code: `go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp ${fw.lib}`,
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Initialize the SDK',
+ description:
+ 'Call initTracer at startup and defer tp.Shutdown(ctx) before exit. The exporter reads the environment variables from the next step.',
+ code: GO_BOOTSTRAP,
+ codeLanguage: 'go'
+ },
+ {
+ title: 'Add the Middleware',
+ description: fw.note,
+ code: fw.snippet,
+ codeLanguage: 'go'
+ },
+ envStep(backendUrl, token)
+ ];
+ }
+
+ case 'python': {
+ const runByFramework: Record<string, { cmd: string; note?: string }> = {
+ django: {
+ cmd: 'opentelemetry-instrument python manage.py runserver --noreload',
+ note: 'The --noreload flag is required with runserver; the autoreloader breaks instrumentation. It is not needed under gunicorn or other production servers.'
+ },
+ flask: { cmd: 'opentelemetry-instrument flask run' },
+ fastapi: {
+ cmd: 'opentelemetry-instrument uvicorn main:app',
+ note: 'Avoid --reload and --workers with zero-code instrumentation; for multi-worker production use gunicorn with uvicorn workers.'
+ },
+ other: { cmd: 'opentelemetry-instrument python app.py' }
+ };
+ const run = runByFramework[framework] ?? runByFramework.other;
+ return [
+ {
+ title: 'Install the SDK',
+ description:
+ 'opentelemetry-bootstrap detects your installed packages and adds the matching instrumentation.',
+ code: 'pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http\nopentelemetry-bootstrap -a install',
+ codeLanguage: 'bash'
+ },
+ envStep(
+ backendUrl,
+ token,
+ ['OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf'],
+ 'The protocol variable is required; the Python SDK defaults to gRPC.'
+ ),
+ {
+ title: 'Run with Instrumentation',
+ description: run.note,
+ code: run.cmd,
+ codeLanguage: 'bash'
+ }
+ ];
+ }
+
+ case 'java': {
+ if (framework === 'spring') {
+ return [
+ {
+ title: 'Add the Starter',
+ description: 'Add the OpenTelemetry Spring Boot starter to your Gradle build (a Maven dependency works the same way).',
+ code: `implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.28.1"))
+implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter")`,
+ codeLanguage: 'gradle'
+ },
+ envStep(
+ backendUrl,
+ token,
+ [],
+ 'Start your app normally; the starter reads these variables and reports routes, status codes, and exceptions.'
+ )
+ ];
+ }
+ return [
+ {
+ title: 'Download the Java Agent',
+ description:
+ 'The agent instruments Spring, JAX-RS, and most Java frameworks with zero code changes.',
+ code: 'curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar',
+ codeLanguage: 'bash'
+ },
+ envStep(backendUrl, token),
+ {
+ title: 'Run with the Agent',
+ code: 'java -javaagent:./opentelemetry-javaagent.jar -jar myapp.jar',
+ codeLanguage: 'bash'
+ }
+ ];
+ }
+
+ case 'dotnet':
+ return [
+ {
+ title: 'Install the Packages',
+ code: `dotnet add package OpenTelemetry.Extensions.Hosting
+dotnet add package OpenTelemetry.Instrumentation.AspNetCore
+dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol`,
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Add to Program.cs',
+ description:
+ 'Keep AddOtlpExporter() empty so the exporter is driven entirely by the environment variables in the next step.',
+ code: `builder.Services.AddOpenTelemetry()
+ .WithTracing(t => t
+ .AddAspNetCoreInstrumentation()
+ .AddOtlpExporter());`,
+ codeLanguage: 'csharp'
+ },
+ envStep(
+ backendUrl,
+ token,
+ ['OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf'],
+ 'The protocol variable is required; the .NET exporter defaults to gRPC.'
+ )
+ ];
+
+ case 'php': {
+ const autoPackages: Record<string, string> = {
+ symfony: ' open-telemetry/opentelemetry-auto-symfony',
+ laravel: ' open-telemetry/opentelemetry-auto-laravel',
+ slim: ' open-telemetry/opentelemetry-auto-slim',
+ other: ''
+ };
+ const autoPackage = autoPackages[framework] ?? '';
+ return [
+ {
+ title: 'Install the SDK',
+ description:
+ 'Auto-instrumentation needs the opentelemetry PECL extension; enable it with extension=opentelemetry in php.ini.' +
+ (framework === 'other'
+ ? ' Find auto-instrumentation packages for your framework in the OpenTelemetry registry.'
+ : ''),
+ code: `pecl install opentelemetry
+composer require open-telemetry/sdk open-telemetry/exporter-otlp php-http/guzzle7-adapter${autoPackage}`,
+ codeLanguage: 'bash',
+ link:
+ framework === 'other'
+ ? {
+ label: 'Browse PHP instrumentation packages',
+ href: 'https://opentelemetry.io/ecosystem/registry/?language=php&component=instrumentation'
+ }
+ : undefined
+ },
+ envStep(
+ backendUrl,
+ token,
+ ['OTEL_PHP_AUTOLOAD_ENABLED=true'],
+ 'These must be real process environment variables; the extension does not read framework .env files. Use env[...] in php-fpm pool config or SetEnv in Apache.'
+ )
+ ];
+ }
+
+ case 'ruby': {
+ if (framework === 'rails') {
+ return [
+ {
+ title: 'Install the Gems',
+ code: 'bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-rails',
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Create the Initializer',
+ description: 'Add config/initializers/opentelemetry.rb.',
+ code: `require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'opentelemetry/instrumentation/rails'
+
+OpenTelemetry::SDK.configure do |c|
+ c.use 'OpenTelemetry::Instrumentation::Rails'
+end`,
+ codeLanguage: 'ruby'
+ },
+ envStep(backendUrl, token)
+ ];
+ }
+ return [
+ {
+ title: 'Install the Gems',
+ code: 'bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all',
+ codeLanguage: 'bash'
+ },
+ {
+ title: 'Configure the SDK',
+ description: 'Run this once at startup, before your app starts handling requests.',
+ code: `require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'opentelemetry/instrumentation/all'
+
+OpenTelemetry::SDK.configure do |c|
+ c.use_all
+end`,
+ codeLanguage: 'ruby'
+ },
+ envStep(backendUrl, token)
+ ];
+ }
+
+ default:
+ return [
+ {
+ title: 'Configure any OpenTelemetry SDK',
+ description:
+ 'Any language with an OTLP/HTTP exporter works. Set these environment variables; the protocol variable matters for SDKs that default to gRPC. Make sure http.route is set on root server spans so endpoints group by route pattern, and use SpanKind CONSUMER for background jobs.',
+ code: envBlock(backendUrl, token, ['OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf']),
+ codeLanguage: 'bash',
+ link: {
+ label: 'View all supported languages',
+ href: 'https://opentelemetry.io/docs/languages/'
+ }
+ }
+ ];
+ }
+}
diff --git a/frontend/src/lib/utils/setup-storage.ts b/frontend/src/lib/utils/setup-storage.ts
new file mode 100644
index 00000000..de8d5ab4
--- /dev/null
+++ b/frontend/src/lib/utils/setup-storage.ts
@@ -0,0 +1,68 @@
+import { browser } from '$app/environment';
+import { OTEL_TARGETS, type OtelTargetId } from './otel-setup';
+
+export type SetupMode = 'ai' | 'manual';
+
+const MODE_KEY = 'traceway_setup_mode';
+const OTEL_TARGET_KEY = 'traceway_otel_language';
+const OTEL_FRAMEWORK_KEY = 'traceway_otel_framework';
+
+export function getSetupMode(): SetupMode {
+ if (!browser) return 'ai';
+
+ try {
+ const stored = localStorage.getItem(MODE_KEY);
+ if (stored === 'ai' || stored === 'manual') {
+ return stored;
+ }
+ } catch {}
+
+ return 'ai';
+}
+
+export function setSetupMode(mode: SetupMode): void {
+ if (!browser) return;
+
+ try {
+ localStorage.setItem(MODE_KEY, mode);
+ } catch {}
+}
+
+export function getOtelTarget(): OtelTargetId {
+ if (!browser) return OTEL_TARGETS[0].id;
+
+ try {
+ const stored = localStorage.getItem(OTEL_TARGET_KEY);
+ if (stored && OTEL_TARGETS.some((t) => t.id === stored)) {
+ return stored as OtelTargetId;
+ }
+ } catch {}
+
+ return OTEL_TARGETS[0].id;
+}
+
+export function setOtelTarget(id: OtelTargetId): void {
+ if (!browser) return;
+
+ try {
+ localStorage.setItem(OTEL_TARGET_KEY, id);
+ } catch {}
+}
+
+export function getOtelFramework(): string | null {
+ if (!browser) return null;
+
+ try {
+ return localStorage.getItem(OTEL_FRAMEWORK_KEY);
+ } catch {}
+
+ return null;
+}
+
+export function setOtelFramework(id: string): void {
+ if (!browser) return;
+
+ try {
+ localStorage.setItem(OTEL_FRAMEWORK_KEY, id);
+ } catch {}
+}
diff --git a/frontend/src/routes/+page.svelte b/frontend/src/routes/+page.svelte
index 39047a0d..c995b5d4 100644
--- a/frontend/src/routes/+page.svelte
+++ b/frontend/src/routes/+page.svelte
@@ -42,7 +42,6 @@
import php from 'svelte-highlight/languages/php';
import python from 'svelte-highlight/languages/python';
import { themeState } from '$lib/state/theme.svelte';
- import yaml from 'svelte-highlight/languages/yaml';
import 'svelte-highlight/styles/github-dark.css';
import {
getFrameworkCode,
@@ -54,6 +53,12 @@
} from '$lib/utils/framework-code';
import { toast } from 'svelte-sonner';
import { goto } from '$app/navigation';
+ import { OTEL_SDKS } from '$lib/utils/otel-sdks';
+ import { getSetupMode } from '$lib/utils/setup-storage';
+ import SetupModeTabs from '$lib/components/setup/setup-mode-tabs.svelte';
+ import AiSetupSteps from '$lib/components/setup/ai-setup-steps.svelte';
+ import OtelSetupSteps from '$lib/components/setup/otel-setup-steps.svelte';
+ import OtelExporterConfig from '$lib/components/setup/otel-exporter-config.svelte';
const timezone = $derived(getTimezone());
@@ -115,6 +120,7 @@
const impactfulEndpoints = $derived(data?.worstEndpoints?.filter((e) => e.impact >= 0.25) ?? []);
let projectWithToken = $derived(projectsState.currentProject);
+ let setupMode = $state(getSetupMode());
let copiedInstall = $state(false);
let copiedCode = $state(false);
let copiedTesting = $state(false);
@@ -176,6 +182,7 @@
let copiedCfDeploy = $state(false);
const isOtel = $derived(projectWithToken ? isOtelFramework(projectWithToken.framework) : false);
+ const isOtelGeneric = $derived(projectWithToken?.framework === 'opentelemetry');
const otelBaseEndpoint = $derived(
projectWithToken ? `${projectWithToken.backendUrl}/api/otel` : ''
);
@@ -197,21 +204,7 @@ service:
: ''
);
- const otelSdks = [
- {
- lang: 'Node.js',
- cmd: 'npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http'
- },
- { lang: 'Python', cmd: 'pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http' },
- { lang: 'Go', cmd: 'go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp' },
- { lang: 'Java', cmd: "implementation 'io.opentelemetry:opentelemetry-exporter-otlp'" },
- { lang: '.NET', cmd: 'dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol' }
- ];
-
let copiedSdkLang = $state<string | null>(null);
- let copiedOtelEndpoint = $state(false);
- let copiedOtelAuth = $state(false);
- let copiedOtelCollector = $state(false);
async function copyCfEndpoint() {
await navigator.clipboard.writeText(cfOtelEndpoint);
@@ -243,24 +236,6 @@ service:
setTimeout(() => (copiedSdkLang = null), 2000);
}
- async function copyOtelEndpoint() {
- await navigator.clipboard.writeText(otelBaseEndpoint);
- copiedOtelEndpoint = true;
- setTimeout(() => (copiedOtelEndpoint = false), 2000);
- }
-
- async function copyOtelAuth() {
- await navigator.clipboard.writeText(otelAuthHeader);
- copiedOtelAuth = true;
- setTimeout(() => (copiedOtelAuth = false), 2000);
- }
-
- async function copyOtelCollector() {
- await navigator.clipboard.writeText(otelCollectorConfig);
- copiedOtelCollector = true;
- setTimeout(() => (copiedOtelCollector = false), 2000);
- }
-
async function copyInstall() {
await navigator.clipboard.writeText(installCommand);
copiedInstall = true;
@@ -395,7 +370,10 @@ service:
</div>
{#if projectWithToken}
- {#if isCloudflare}
+ <SetupModeTabs mode={setupMode} onModeChange={(m) => (setupMode = m)} />
+ {#if setupMode === 'ai'}
+ <AiSetupSteps backendUrl={projectWithToken.backendUrl} token={projectWithToken.token} />
+ {:else if isCloudflare}
<!-- Cloudflare Step 1: Create a Destination -->
<div class="rounded-md border bg-card">
<div class="border-b px-4 py-3">
@@ -515,6 +493,11 @@ service:
</div>
</div>
</div>
+ {:else if isOtelGeneric}
+ <OtelSetupSteps
+ backendUrl={projectWithToken.backendUrl}
+ token={projectWithToken.token}
+ />
{:else if isOtel}
<!-- OTel Step 1: Install an OTel SDK -->
<div class="rounded-md border bg-card">
@@ -533,18 +516,18 @@ service:
</p>
</div>
<div class="space-y-2 p-4">
- {#each otelSdks as sdk}
+ {#each OTEL_SDKS as sdk (sdk.id)}
<div class="flex items-center gap-2">
- <span class="w-16 shrink-0 text-sm font-medium">{sdk.lang}</span>
+ <span class="w-16 shrink-0 text-sm font-medium">{sdk.label}</span>
<code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-xs break-all"
- >{sdk.cmd}</code
+ >{sdk.installCommand}</code
>
<Button
variant="outline"
size="sm"
- onclick={() => copySdkInstall(sdk.lang, sdk.cmd)}
+ onclick={() => copySdkInstall(sdk.label, sdk.installCommand)}
>
- {#if copiedSdkLang === sdk.lang}
+ {#if copiedSdkLang === sdk.label}
<Check class="h-4 w-4 text-green-500" />
{:else}
<Copy class="h-4 w-4" />
@@ -578,67 +561,12 @@ service:
Point your OTLP/HTTP exporter at Traceway using the endpoint and token below.
</p>
</div>
- <div class="space-y-4 p-4">
- <div>
- <p class="mb-2 text-sm font-medium">OTLP Endpoint</p>
- <p class="mb-2 text-xs text-muted-foreground">
- Your SDK or Collector will append <code
- class="rounded bg-muted px-1 py-0.5 font-mono text-xs">/v1/traces</code
- >
- and
- <code class="rounded bg-muted px-1 py-0.5 font-mono text-xs">/v1/metrics</code> automatically.
- </p>
- <div class="flex items-center gap-2">
- <code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-sm break-all"
- >{otelBaseEndpoint}</code
- >
- <Button variant="outline" size="sm" onclick={copyOtelEndpoint}>
- {#if copiedOtelEndpoint}
- <Check class="h-4 w-4 text-green-500" />
- {:else}
- <Copy class="h-4 w-4" />
- {/if}
- </Button>
- </div>
- </div>
- <div>
- <p class="mb-2 text-sm font-medium">Authorization Header</p>
- <div class="flex items-center gap-2">
- <code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-sm break-all"
- >{otelAuthHeader}</code
- >
- <Button variant="outline" size="sm" onclick={copyOtelAuth}>
- {#if copiedOtelAuth}
- <Check class="h-4 w-4 text-green-500" />
- {:else}
- <Copy class="h-4 w-4" />
- {/if}
- </Button>
- </div>
- </div>
- <div>
- <p class="mb-2 text-sm font-medium">Example: OTel Collector (optional)</p>
- <div class="relative">
- <div class="absolute top-2 right-2 z-10">
- <Button variant="outline" size="sm" onclick={copyOtelCollector}>
- {#if copiedOtelCollector}
- <Check class="mr-2 h-4 w-4 text-green-500" />
- Copied!
- {:else}
- <Copy class="mr-2 h-4 w-4" />
- Copy
- {/if}
- </Button>
- </div>
- <div
- class="overflow-x-auto rounded-lg text-sm {themeState.isDark
- ? 'dark-code'
- : 'light-code'}"
- >
- <Highlight language={yaml} code={otelCollectorConfig} />
- </div>
- </div>
- </div>
+ <div class="p-4">
+ <OtelExporterConfig
+ endpoint={otelBaseEndpoint}
+ authHeader={otelAuthHeader}
+ collectorConfig={otelCollectorConfig}
+ />
</div>
</div>
@@ -812,7 +740,7 @@ service:
<Unplug class="h-6 w-6 text-destructive" />
</div>
<p class="mb-4 text-sm text-muted-foreground">
- {#if isOtel || isCloudflare}
+ {#if setupMode === 'ai' || isOtel || isCloudflare}
Once you've completed the steps above and sent some traffic through your
application, click below to verify.
{:else}
diff --git a/frontend/src/routes/connection/+page.svelte b/frontend/src/routes/connection/+page.svelte
index 0ec23358..8b867fc9 100644
--- a/frontend/src/routes/connection/+page.svelte
+++ b/frontend/src/routes/connection/+page.svelte
@@ -7,7 +7,7 @@
CardTitle
} from '$lib/components/ui/card';
import { Button } from '$lib/components/ui/button';
- import { Copy, Check, KeyRound } from 'lucide-svelte';
+ import { Copy, Check } from 'lucide-svelte';
import {
projectsState,
type ProjectWithToken,
@@ -15,16 +15,13 @@
isOtelFramework,
isCloudflareFramework
} from '$lib/state/projects.svelte';
- import { authState } from '$lib/state/auth.svelte';
import FrameworkIcon from '$lib/components/framework-icon.svelte';
- import SourceMapSetup from '$lib/components/source-map-setup.svelte';
import Highlight from 'svelte-highlight';
import go from 'svelte-highlight/languages/go';
import javascript from 'svelte-highlight/languages/javascript';
import bash from 'svelte-highlight/languages/bash';
import php from 'svelte-highlight/languages/php';
import python from 'svelte-highlight/languages/python';
- import yaml from 'svelte-highlight/languages/yaml';
import { themeState } from '$lib/state/theme.svelte';
import 'svelte-highlight/styles/github-dark.css';
import {
@@ -32,19 +29,24 @@
getInstallCommand,
getFrameworkLabel
} from '$lib/utils/framework-code';
+ import { getSetupMode } from '$lib/utils/setup-storage';
+ import SetupModeTabs from '$lib/components/setup/setup-mode-tabs.svelte';
+ import AiSetupSteps from '$lib/components/setup/ai-setup-steps.svelte';
+ import OtelSetupSteps from '$lib/components/setup/otel-setup-steps.svelte';
+ import OtelExporterConfig from '$lib/components/setup/otel-exporter-config.svelte';
+ import SourceMapUploadCard from '$lib/components/setup/source-map-upload-card.svelte';
let projectWithToken = $derived(projectsState.currentProject);
+ let setupMode = $state(getSetupMode());
let copiedCode = $state(false);
let copiedInstall = $state(false);
- let copiedOtelEndpoint = $state(false);
- let copiedOtelAuth = $state(false);
- let copiedOtelCollector = $state(false);
let copiedCfEndpoint = $state(false);
let copiedCfAuth = $state(false);
let copiedCfWrangler = $state(false);
let copiedCfDeploy = $state(false);
const isOtel = $derived(projectWithToken ? isOtelFramework(projectWithToken.framework) : false);
+ const isOtelGeneric = $derived(projectWithToken?.framework === 'opentelemetry');
const isCloudflare = $derived(
projectWithToken ? isCloudflareFramework(projectWithToken.framework) : false
);
@@ -113,10 +115,7 @@ service:
});
const isJs = $derived(projectWithToken ? isJsFramework(projectWithToken.framework) : false);
- const isReadonly = $derived(
- authState.getRoleForOrganization(projectsState.currentProject?.organizationId ?? 0) ===
- 'readonly'
- );
+
async function copyCode() {
await navigator.clipboard.writeText(sdkCode);
copiedCode = true;
@@ -152,24 +151,6 @@ service:
copiedCfDeploy = true;
setTimeout(() => (copiedCfDeploy = false), 2000);
}
-
- async function copyOtelEndpoint() {
- await navigator.clipboard.writeText(otelEndpoint);
- copiedOtelEndpoint = true;
- setTimeout(() => (copiedOtelEndpoint = false), 2000);
- }
-
- async function copyOtelAuth() {
- await navigator.clipboard.writeText(otelAuthHeader);
- copiedOtelAuth = true;
- setTimeout(() => (copiedOtelAuth = false), 2000);
- }
-
- async function copyOtelCollector() {
- await navigator.clipboard.writeText(otelCollectorConfig);
- copiedOtelCollector = true;
- setTimeout(() => (copiedOtelCollector = false), 2000);
- }
</script>
<div class="space-y-4">
@@ -179,7 +160,12 @@ service:
</div>
{#if projectWithToken}
- {#if isOtel}
+ <SetupModeTabs mode={setupMode} onModeChange={(m) => (setupMode = m)} />
+ {#if setupMode === 'ai'}
+ <AiSetupSteps backendUrl={projectWithToken.backendUrl} token={projectWithToken.token} />
+ {:else if isOtelGeneric}
+ <OtelSetupSteps backendUrl={projectWithToken.backendUrl} token={projectWithToken.token} />
+ {:else if isOtel}
<Card>
<CardHeader>
<CardTitle class="flex items-center gap-2">
@@ -191,65 +177,11 @@ service:
</CardDescription>
</CardHeader>
<CardContent>
- <div class="space-y-6">
- <div>
- <p class="mb-1 text-sm font-medium">OTLP Endpoint</p>
- <p class="mb-2 text-xs text-muted-foreground">
- Your SDK or Collector will append <code class="text-xs">/v1/traces</code> and
- <code class="text-xs">/v1/metrics</code> automatically.
- </p>
- <div class="flex items-center gap-2">
- <code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-sm break-all"
- >{otelEndpoint}</code
- >
- <Button variant="outline" size="sm" onclick={copyOtelEndpoint}>
- {#if copiedOtelEndpoint}
- <Check class="h-4 w-4 text-green-500" />
- {:else}
- <Copy class="h-4 w-4" />
- {/if}
- </Button>
- </div>
- </div>
- <div>
- <p class="mb-2 text-sm font-medium">Authorization Header</p>
- <div class="flex items-center gap-2">
- <code class="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-sm break-all"
- >{otelAuthHeader}</code
- >
- <Button variant="outline" size="sm" onclick={copyOtelAuth}>
- {#if copiedOtelAuth}
- <Check class="h-4 w-4 text-green-500" />
- {:else}
- <Copy class="h-4 w-4" />
- {/if}
- </Button>
- </div>
- </div>
- <div>
- <p class="mb-2 text-sm font-medium">Example: OTel Collector (optional)</p>
- <div class="relative">
- <div class="absolute top-2 right-2 z-10">
- <Button variant="outline" size="sm" onclick={copyOtelCollector}>
- {#if copiedOtelCollector}
- <Check class="mr-2 h-4 w-4 text-green-500" />
- Copied!
- {:else}
- <Copy class="mr-2 h-4 w-4" />
- Copy
- {/if}
- </Button>
- </div>
- <div
- class="overflow-x-auto rounded-lg text-sm {themeState.isDark
- ? 'dark-code'
- : 'light-code'}"
- >
- <Highlight language={yaml} code={otelCollectorConfig} />
- </div>
- </div>
- </div>
- </div>
+ <OtelExporterConfig
+ endpoint={otelEndpoint}
+ authHeader={otelAuthHeader}
+ collectorConfig={otelCollectorConfig}
+ />
</CardContent>
</Card>
{:else if isCloudflare}
@@ -410,23 +342,9 @@ service:
</div>
</CardContent>
</Card>
- {/if}
- {#if (isJs || isOtel) && !isReadonly}
- <Card>
- <CardHeader>
- <CardTitle class="flex items-center gap-2">
- <KeyRound class="h-5 w-5" />
- Source Map Upload
- </CardTitle>
- <CardDescription>
- Upload source maps to see original file names and line numbers in stack traces from
- minified code.{#if isOtel}{' '}Only applies to JavaScript applications.{/if}
- </CardDescription>
- </CardHeader>
- <CardContent>
- <SourceMapSetup />
- </CardContent>
- </Card>
+ {#if isJs}
+ <SourceMapUploadCard />
+ {/if}
{/if}
{:else}
<Card>
diff --git a/skills/add-traceway-to-hono-project.md b/skills/add-traceway-to-hono-project.md
deleted file mode 100644
index daf5a953..00000000
--- a/skills/add-traceway-to-hono-project.md
+++ /dev/null
@@ -1,277 +0,0 @@
-# Add Traceway to a Hono Project
-
-Add OpenTelemetry tracing to an existing Hono (Node.js) project so it reports endpoints, spans, and errors to a Traceway instance.
-
-## Prerequisites
-
-- Hono app running on Node.js via `@hono/node-server`
-- A Traceway instance URL and project token (get these from your Traceway dashboard → Connection page)
-
-## Step 1: Install Dependencies
-
-```bash
-npm install @hono/otel \
- @opentelemetry/sdk-node \
- @opentelemetry/auto-instrumentations-node \
- @opentelemetry/exporter-trace-otlp-http \
- @opentelemetry/exporter-metrics-otlp-http \
- @opentelemetry/api
-```
-
-`hono` and `@hono/node-server` should already be in the project.
-
-## Step 2: Create the Instrumentation File
-
-Create `instrumentation.js` (or `.ts`) at the project root — next to `package.json`, NOT inside `src/`:
-
-```javascript
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-
-const tracewayUrl = process.env.TRACEWAY_URL || "https://your-traceway-instance.com";
-const tracewayToken = process.env.TRACEWAY_TOKEN || "your-project-token";
-
-const sdk = new NodeSDK({
- traceExporter: new OTLPTraceExporter({
- url: `${tracewayUrl}/api/otel/v1/traces`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
-
- metricReader: new PeriodicExportingMetricReader({
- exporter: new OTLPMetricExporter({
- url: `${tracewayUrl}/api/otel/v1/metrics`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
- exportIntervalMillis: 30_000,
- }),
-
- // IMPORTANT: Disable instrumentation-http.
- // @hono/node-server imports Node's `http` via ESM. On Node 22+, OTel's
- // import-in-the-middle hook cannot intercept ESM imports of built-in modules,
- // so instrumentation-http never patches the server. @hono/otel handles HTTP
- // spans at the middleware level instead.
- instrumentations: [
- getNodeAutoInstrumentations({
- "@opentelemetry/instrumentation-http": { enabled: false },
- }),
- ],
-});
-
-sdk.start();
-```
-
-### Key decisions in this file
-
-- **No `serviceName` / `serviceVersion` in SDK config.** Set these via `OTEL_SERVICE_NAME` env var or pass them to `otel()` in step 3.
-- **`instrumentation-http` is disabled.** `@hono/otel` replaces it. Without this, you get either duplicate spans or zero spans (depending on Node version).
-- **Other auto-instrumentations stay enabled.** CJS npm packages (`pg`, `mysql2`, `mongodb`, `ioredis`) are automatically traced. Only ESM-imported Node.js built-in modules have the patching issue.
-
-## Step 3: Add the OTel Middleware
-
-In your main server file, add two lines — import `otel` and register it as middleware **before** your routes:
-
-```javascript
-import { otel } from "@hono/otel";
-
-// Add BEFORE route definitions
-app.use(otel());
-```
-
-Full example:
-
-```javascript
-import { serve } from "@hono/node-server";
-import { Hono } from "hono";
-import { otel } from "@hono/otel";
-
-const app = new Hono();
-
-app.use(otel()); // ← this is the only change to your app code
-
-// ... existing routes unchanged ...
-app.get("/api/users", (c) => c.json({ users: [] }));
-app.get("/api/users/:id", (c) => c.json({ id: c.req.param("id") }));
-
-serve({ fetch: app.fetch, port: 3000 });
-```
-
-### What `otel()` does automatically
-
-- Creates a root SERVER span for every request
-- Sets `http.route` to the matched route pattern (e.g., `/api/users/:id`) so Traceway groups endpoints correctly
-- Sets `http.request.method`, `http.response.status_code`, `url.full`
-- Records thrown exceptions as span events with `exception.type`, `exception.message`, `exception.stacktrace` — these appear as Issues in Traceway
-- Sets span status to ERROR on exceptions
-
-### Optional: pass config to `otel()`
-
-```javascript
-app.use(otel({
- serviceName: "my-app",
- serviceVersion: "1.0.0",
- captureRequestHeaders: ["user-agent", "x-request-id"],
- captureResponseHeaders: ["x-trace-id"],
-}));
-```
-
-## Step 4: Update the Start Script
-
-The instrumentation file must load **before** the app code. Update `package.json`:
-
-```json
-{
- "scripts": {
- "start": "node --import ./instrumentation.js server.js"
- }
-}
-```
-
-If using CommonJS:
-
-```json
-{
- "scripts": {
- "start": "node --require ./instrumentation.js server.js"
- }
-}
-```
-
-Or set via environment variable:
-
-```bash
-export NODE_OPTIONS="--import ./instrumentation.js"
-```
-
-## Step 5: Set Environment Variables
-
-```bash
-TRACEWAY_URL=https://your-traceway-instance.com
-TRACEWAY_TOKEN=your-project-token
-```
-
-## What Gets Traced Automatically
-
-After completing steps 1-5, the following produces traces with zero additional code:
-
-| What | How | Span type in Traceway |
-|------|-----|----------------------|
-| Every incoming HTTP request | `@hono/otel` middleware | **Endpoint** (root SERVER span) |
-| Route grouping (`/users/1` + `/users/2` → `/users/:id`) | `@hono/otel` sets `http.route` | Endpoint attribute |
-| Thrown errors | `@hono/otel` calls `span.recordException()` | **Issue** |
-| Outgoing `fetch()` calls | `instrumentation-undici` (auto) | **Span** (child) |
-| PostgreSQL queries (`pg`) | `instrumentation-pg` (auto) | **Span** (child) |
-| MySQL queries (`mysql2`) | `instrumentation-mysql2` (auto) | **Span** (child) |
-| MongoDB queries | `instrumentation-mongodb` (auto) | **Span** (child) |
-| Redis operations (`ioredis`) | `instrumentation-ioredis` (auto) | **Span** (child) |
-| DNS lookups | `instrumentation-dns` (auto) | **Span** (child) |
-
-## Adding Manual Spans (Optional)
-
-For operations without auto-instrumentation (SQLite, custom business logic, external APIs via non-fetch clients):
-
-```javascript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-app");
-
-// Wrap any operation in a span
-function dbSpan(name, query, fn) {
- return tracer.startActiveSpan(name, (span) => {
- span.setAttribute("db.system", "sqlite");
- span.setAttribute("db.statement", query);
- try {
- const result = fn();
- span.end();
- return result;
- } catch (error) {
- span.recordException(error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
- span.end();
- throw error;
- }
- });
-}
-
-// Use in a route handler — automatically becomes a child of the @hono/otel root span
-app.get("/api/users", (c) => {
- const users = dbSpan("db.query", "SELECT * FROM users", () =>
- db.prepare("SELECT * FROM users").all()
- );
- return c.json(users);
-});
-```
-
-## Instrumenting Background Tasks (Optional)
-
-Hono has no built-in scheduler. If your app runs cron jobs or queue consumers (via `node-cron`, `bullmq`, etc.), wrap them with `SpanKind.CONSUMER` so they appear as **Tasks** in Traceway:
-
-```javascript
-import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-app");
-
-// In your cron/queue handler
-async function processQueueJob(job) {
- await tracer.startActiveSpan(
- "process-email-queue",
- { kind: SpanKind.CONSUMER },
- async (span) => {
- try {
- span.setAttribute("job.id", job.id);
- await sendEmail(job.data);
- span.setStatus({ code: SpanStatusCode.OK });
- } catch (error) {
- span.recordException(error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
- throw error;
- } finally {
- span.end();
- }
- }
- );
-}
-```
-
-Without `SpanKind.CONSUMER`, background work would be dropped or misclassified as an Endpoint.
-
-## Recording Caught Exceptions (Optional)
-
-`@hono/otel` auto-records thrown errors. For errors you catch and handle:
-
-```javascript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-app.get("/api/checkout", async (c) => {
- const span = trace.getActiveSpan();
- try {
- await processPayment();
- } catch (error) {
- if (span) {
- span.recordException(error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
- }
- return c.json({ error: "Payment failed" }, 500);
- }
- return c.json({ status: "ok" });
-});
-```
-
-## Verification
-
-After starting your app, hit a few endpoints and check Traceway:
-
-1. **Endpoints page** — routes should appear grouped by pattern (e.g., `GET /api/users/:id`), not by literal URL
-2. **Issues page** — any thrown errors should appear with stack traces
-3. **Endpoint detail → Spans tab** — database queries, outgoing fetch calls, and manual spans should appear as children of the HTTP request
-
-## Checklist
-
-- [ ] `@hono/otel` and OTel packages installed
-- [ ] `instrumentation.js` created at project root with `instrumentation-http` disabled
-- [ ] `app.use(otel())` added before route definitions
-- [ ] Start script uses `--import ./instrumentation.js` (ESM) or `--require` (CJS)
-- [ ] `TRACEWAY_URL` and `TRACEWAY_TOKEN` env vars set
-- [ ] Verified endpoints appear in Traceway dashboard
diff --git a/skills/add-traceway-to-nestjs-project.md b/skills/add-traceway-to-nestjs-project.md
deleted file mode 100644
index ec07ee8e..00000000
--- a/skills/add-traceway-to-nestjs-project.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# Add Traceway to a NestJS Project
-
-Add OpenTelemetry tracing to an existing NestJS project so it reports endpoints, spans, and errors to a Traceway instance.
-
-## Prerequisites
-
-- NestJS application (Express or Fastify adapter)
-- A Traceway instance URL and project token (get these from your Traceway dashboard → Connection page)
-
-## Step 1: Install Dependencies
-
-```bash
-npm install @opentelemetry/sdk-node \
- @opentelemetry/auto-instrumentations-node \
- @opentelemetry/exporter-trace-otlp-http \
- @opentelemetry/exporter-metrics-otlp-http \
- @opentelemetry/api
-```
-
-If the project uses Prisma, also install its OTel instrumentation:
-
-```bash
-npm install @prisma/instrumentation
-```
-
-## Step 2: Create the Instrumentation File
-
-Create `instrumentation.ts` at the project root — next to `package.json`, NOT inside `src/`:
-
-```typescript
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
-import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { Resource } from "@opentelemetry/resources";
-
-const tracewayUrl = process.env.TRACEWAY_URL || "https://your-traceway-instance.com";
-const tracewayToken = process.env.TRACEWAY_TOKEN || "your-project-token";
-
-const sdk = new NodeSDK({
- resource: new Resource({
- "service.name": "my-nestjs-app",
- "service.version": "1.0.0",
- }),
-
- traceExporter: new OTLPTraceExporter({
- url: `${tracewayUrl}/api/otel/v1/traces`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
-
- metricReader: new PeriodicExportingMetricReader({
- exporter: new OTLPMetricExporter({
- url: `${tracewayUrl}/api/otel/v1/metrics`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
- exportIntervalMillis: 30_000,
- }),
-
- instrumentations: [getNodeAutoInstrumentations()],
-});
-
-sdk.start();
-```
-
-If using Prisma, add `import { PrismaInstrumentation } from "@prisma/instrumentation"` and include `new PrismaInstrumentation()` in the `instrumentations` array.
-
-### Why NestJS is simpler than Hono/Next.js
-
-- **No `instrumentation-http` disable needed.** NestJS uses Express (CJS) internally, so OTel patches it successfully.
-- **No route helper needed.** `@opentelemetry/instrumentation-express` automatically sets `http.route` — endpoint grouping works out of the box.
-- **No error handler needed.** Express instrumentation records exceptions automatically.
-
-## Step 3: Update Start Scripts
-
-The instrumentation file must load **before** NestJS boots. Update `package.json`:
-
-```json
-{
- "scripts": {
- "start": "node --require ./instrumentation.js dist/main.js",
- "start:dev": "node --require ts-node/register --require ./instrumentation.ts src/main.ts"
- }
-}
-```
-
-Requires `ts-node` as a dev dependency for development mode:
-
-```bash
-npm install -D ts-node
-```
-
-If using the NestJS CLI (`nest start`), set via environment variable instead:
-
-```bash
-export NODE_OPTIONS="--require ./instrumentation.js"
-npm run start
-```
-
-## Step 4: Set Environment Variables
-
-```bash
-TRACEWAY_URL=https://your-traceway-instance.com
-TRACEWAY_TOKEN=your-project-token
-```
-
-## Step 5: Instrument Background Tasks (Optional)
-
-NestJS doesn't have built-in scheduled tasks that auto-instrument. If your app uses `@nestjs/schedule` (cron jobs) or `@nestjs/bull` (queues), wrap them in manual spans with `SpanKind.CONSUMER` so they appear as **Tasks** in Traceway:
-
-```typescript
-import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-nestjs-app");
-
-@Injectable()
-export class TasksService {
- @Cron("0 * * * *")
- async hourlyCleanup() {
- await tracer.startActiveSpan(
- "hourly-cleanup",
- { kind: SpanKind.CONSUMER },
- async (span) => {
- try {
- await this.cleanupExpiredSessions();
- span.setStatus({ code: SpanStatusCode.OK });
- } catch (error) {
- span.recordException(error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
- throw error;
- } finally {
- span.end();
- }
- }
- );
- }
-}
-```
-
-The `SpanKind.CONSUMER` is what tells Traceway to classify this as a **Task** instead of an Endpoint.
-
-## What Gets Traced Automatically
-
-After completing steps 1-4, the following produces traces with zero additional code:
-
-| What | How | Span type in Traceway |
-|------|-----|----------------------|
-| Every incoming HTTP request | `instrumentation-http` + `instrumentation-express` | **Endpoint** (root SERVER span) |
-| Route grouping (`/users/1` + `/users/2` → `/users/:id`) | `instrumentation-express` sets `http.route` | Endpoint attribute |
-| Status codes (200, 404, 500) | `instrumentation-http` sets `http.response.status_code` | Endpoint attribute |
-| Thrown errors | Express error handling records exceptions | **Issue** |
-| NestJS handler spans | `instrumentation-nestjs-core` | **Span** (child) |
-| Prisma queries | `@prisma/instrumentation` (if installed) | **Span** (child) |
-| Outgoing `fetch()` calls | `instrumentation-undici` (auto) | **Span** (child) |
-| Outgoing HTTP (`axios`) | `instrumentation-http` (auto) | **Span** (child) |
-| PostgreSQL queries (`pg`) | `instrumentation-pg` (auto) | **Span** (child) |
-| MySQL queries (`mysql2`) | `instrumentation-mysql2` (auto) | **Span** (child) |
-| MongoDB queries | `instrumentation-mongodb` (auto) | **Span** (child) |
-| Redis operations (`ioredis`) | `instrumentation-ioredis` (auto) | **Span** (child) |
-| Cron jobs / queue consumers | Manual with `SpanKind.CONSUMER` (step 5) | **Task** |
-
-## Verification
-
-After starting your app, hit a few endpoints and check Traceway:
-
-1. **Endpoints page** — routes should appear grouped by pattern (e.g., `GET /api/users/:id`), not by literal URL
-2. **Issues page** — any thrown errors should appear with stack traces
-3. **Endpoint detail → Spans tab** — database queries, outgoing fetch calls, and NestJS handler spans should appear as children
-
-## Checklist
-
-- [ ] OTel packages installed (+ `@prisma/instrumentation` if using Prisma)
-- [ ] `instrumentation.ts` created at project root
-- [ ] Start scripts updated to use `--require ./instrumentation.ts` (dev) or `--require ./instrumentation.js` (prod)
-- [ ] `TRACEWAY_URL` and `TRACEWAY_TOKEN` env vars set
-- [ ] Cron jobs / queue consumers wrapped with `SpanKind.CONSUMER` spans (if applicable)
-- [ ] Verified endpoints appear in Traceway dashboard
diff --git a/skills/add-traceway-to-nextjs-project.md b/skills/add-traceway-to-nextjs-project.md
deleted file mode 100644
index fb681bb4..00000000
--- a/skills/add-traceway-to-nextjs-project.md
+++ /dev/null
@@ -1,331 +0,0 @@
-# Add Traceway to a Next.js Project
-
-Add OpenTelemetry tracing to an existing Next.js (App Router) project so it reports endpoints, spans, and errors to a Traceway instance.
-
-## Prerequisites
-
-- Next.js 13.4+ with App Router
-- A Traceway instance URL and project token (get these from your Traceway dashboard → Connection page)
-
-## Step 1: Install Dependencies
-
-```bash
-npm install @opentelemetry/sdk-node \
- @opentelemetry/auto-instrumentations-node \
- @opentelemetry/exporter-trace-otlp-http \
- @opentelemetry/exporter-metrics-otlp-http \
- @opentelemetry/api
-```
-
-If the project uses Prisma, also install its OTel instrumentation for automatic query tracing:
-
-```bash
-npm install @prisma/instrumentation
-```
-
-## Step 2: Create the Instrumentation File
-
-Create `instrumentation.ts` at the project root — next to `next.config.js`, NOT inside `src/` or `app/`. Next.js loads this file automatically during server startup. No `--require` or `--import` flag needed.
-
-```typescript
-export async function register() {
- if (process.env.NEXT_RUNTIME === "nodejs") {
- const { NodeSDK } = await import("@opentelemetry/sdk-node");
- const { OTLPTraceExporter } = await import(
- "@opentelemetry/exporter-trace-otlp-http"
- );
- const { OTLPMetricExporter } = await import(
- "@opentelemetry/exporter-metrics-otlp-http"
- );
- const { PeriodicExportingMetricReader } = await import(
- "@opentelemetry/sdk-metrics"
- );
- const { getNodeAutoInstrumentations } = await import(
- "@opentelemetry/auto-instrumentations-node"
- );
- const { Resource } = await import("@opentelemetry/resources");
- const { PrismaInstrumentation } = await import(
- "@prisma/instrumentation"
- );
-
- const tracewayUrl = process.env.TRACEWAY_URL || "https://your-traceway-instance.com";
- const tracewayToken = process.env.TRACEWAY_TOKEN || "your-project-token";
-
- const sdk = new NodeSDK({
- resource: new Resource({
- "service.name": "my-nextjs-app",
- "service.version": "1.0.0",
- }),
-
- traceExporter: new OTLPTraceExporter({
- url: `${tracewayUrl}/api/otel/v1/traces`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
-
- metricReader: new PeriodicExportingMetricReader({
- exporter: new OTLPMetricExporter({
- url: `${tracewayUrl}/api/otel/v1/metrics`,
- headers: { Authorization: `Bearer ${tracewayToken}` },
- }),
- exportIntervalMillis: 30_000,
- }),
-
- instrumentations: [
- getNodeAutoInstrumentations(),
- new PrismaInstrumentation(),
- ],
- });
-
- sdk.start();
- }
-}
-```
-
-### Key decisions in this file
-
-- **`process.env.NEXT_RUNTIME === "nodejs"` guard is required.** Next.js runs `instrumentation.ts` in both Node.js and Edge runtimes. The OTel Node SDK only works in Node.js.
-- **All imports are dynamic `import()`.** This prevents OTel packages from being bundled into the Edge runtime.
-- **`PrismaInstrumentation` is included.** If the project doesn't use Prisma, remove the import and the `new PrismaInstrumentation()` line.
-- **`getNodeAutoInstrumentations()` is kept with defaults.** Unlike Hono, `instrumentation-http` is NOT disabled — it may capture some spans depending on the Node.js version.
-
-## Step 3: Create the Route Helper
-
-Next.js (App Router) does not use Express or Fastify, so OTel auto-instrumentation cannot set `http.route` automatically. Without it, Traceway creates a separate endpoint for every unique URL path instead of grouping them.
-
-Create `lib/with-route.ts`:
-
-```typescript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-type RouteHandler = (
- req: Request,
- context: { params: Promise<Record<string, string>> }
-) => Response | Promise<Response>;
-
-export function withRoute(route: string, handler: RouteHandler): RouteHandler {
- return async (req, context) => {
- const span = trace.getActiveSpan();
- if (span) {
- span.setAttribute("http.route", route);
- }
- try {
- return await handler(req, context);
- } catch (error) {
- if (span) {
- span.recordException(error as Error);
- span.setStatus({
- code: SpanStatusCode.ERROR,
- message: (error as Error).message,
- });
- }
- throw error;
- }
- };
-}
-```
-
-### What `withRoute` does
-
-- Sets `http.route` to the parameterized route pattern so Traceway groups endpoints correctly (e.g., `/api/users/[id]` instead of `/api/users/1`, `/api/users/2`)
-- Catches thrown exceptions, records them as span events (appear as Issues in Traceway), then re-throws
-
-## Step 4: Wrap Every API Route Handler
-
-Wrap each exported handler with `withRoute`, passing the route pattern that matches the file path:
-
-```typescript
-// app/api/users/route.ts
-import { withRoute } from "@/lib/with-route";
-import { prisma } from "@/lib/db";
-
-export const GET = withRoute("/api/users", async () => {
- const users = await prisma.user.findMany();
- return Response.json(users);
-});
-
-export const POST = withRoute("/api/users", async (req) => {
- const body = await req.json();
- const user = await prisma.user.create({ data: body });
- return Response.json(user, { status: 201 });
-});
-```
-
-```typescript
-// app/api/users/[id]/route.ts
-import { withRoute } from "@/lib/with-route";
-import { prisma } from "@/lib/db";
-
-export const GET = withRoute("/api/users/[id]", async (req, { params }) => {
- const { id } = await params;
- const user = await prisma.user.findUnique({ where: { id: parseInt(id) } });
- if (!user) {
- return Response.json({ error: "User not found" }, { status: 404 });
- }
- return Response.json(user);
-});
-```
-
-### Route pattern convention
-
-The `route` string passed to `withRoute` should match the file-system path with Next.js bracket notation:
-
-| File path | Route string |
-|---|---|
-| `app/api/users/route.ts` | `"/api/users"` |
-| `app/api/users/[id]/route.ts` | `"/api/users/[id]"` |
-| `app/api/posts/[slug]/comments/route.ts` | `"/api/posts/[slug]/comments"` |
-
-## Step 5: Enable Instrumentation Hook (Next.js 13.4–14.x only)
-
-For Next.js versions before 15, add to `next.config.js`:
-
-```javascript
-/** @type {import('next').NextConfig} */
-const nextConfig = {
- experimental: {
- instrumentationHook: true,
- },
-};
-
-module.exports = nextConfig;
-```
-
-Not needed for Next.js 15+.
-
-## Step 6: Set Environment Variables
-
-```bash
-TRACEWAY_URL=https://your-traceway-instance.com
-TRACEWAY_TOKEN=your-project-token
-```
-
-## What Gets Traced Automatically
-
-After completing steps 1-6, the following produces traces with zero additional code:
-
-| What | How | Span type in Traceway |
-|------|-----|----------------------|
-| Every incoming HTTP request | `withRoute` sets `http.route` | **Endpoint** (root SERVER span) |
-| Route grouping (`/users/1` + `/users/2` → `/users/[id]`) | `withRoute` sets `http.route` | Endpoint attribute |
-| Thrown errors | `withRoute` calls `span.recordException()` | **Issue** |
-| Prisma queries | `@prisma/instrumentation` (auto) | **Span** (child) |
-| Outgoing `fetch()` calls | `instrumentation-undici` (auto) | **Span** (child) |
-| PostgreSQL queries (`pg`) | `instrumentation-pg` (auto) | **Span** (child) |
-| MySQL queries (`mysql2`) | `instrumentation-mysql2` (auto) | **Span** (child) |
-| MongoDB queries | `instrumentation-mongodb` (auto) | **Span** (child) |
-| Redis operations (`ioredis`) | `instrumentation-ioredis` (auto) | **Span** (child) |
-
-## Instrumenting Background Tasks (Optional)
-
-Next.js has no built-in scheduler. If your app runs cron jobs or queue consumers (via `node-cron`, `bullmq`, or triggered by an external scheduler like Vercel Cron), wrap them with `SpanKind.CONSUMER` so they appear as **Tasks** in Traceway:
-
-```typescript
-import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-nextjs-app");
-
-// e.g., in an API route triggered by a cron scheduler
-export const POST = withRoute("/api/cron/cleanup", async () => {
- return tracer.startActiveSpan(
- "cleanup-expired-sessions",
- { kind: SpanKind.CONSUMER },
- async (span) => {
- try {
- await prisma.session.deleteMany({
- where: { expiresAt: { lt: new Date() } },
- });
- span.setStatus({ code: SpanStatusCode.OK });
- span.end();
- return Response.json({ status: "ok" });
- } catch (error) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
- span.end();
- throw error;
- }
- }
- );
-});
-```
-
-Without `SpanKind.CONSUMER`, background work would be classified as an Endpoint or dropped.
-
-## Adding Manual Spans (Optional)
-
-For operations without auto-instrumentation (SQLite, Server Components, custom business logic):
-
-```typescript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-nextjs-app");
-
-// In an API route handler
-export const GET = withRoute("/api/report", async () => {
- return tracer.startActiveSpan("generate-report", async (span) => {
- try {
- span.setAttribute("report.type", "monthly");
- const data = await generateReport();
- span.end();
- return Response.json(data);
- } catch (error) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
- span.end();
- throw error;
- }
- });
-});
-
-// In a Server Component
-export default async function DashboardPage() {
- return tracer.startActiveSpan("DashboardPage.render", async (span) => {
- try {
- const stats = await fetchStats();
- span.setAttribute("stats.count", stats.length);
- return <Dashboard stats={stats} />;
- } finally {
- span.end();
- }
- });
-}
-```
-
-## Recording Caught Exceptions (Optional)
-
-`withRoute` auto-records thrown errors. For errors you catch and handle:
-
-```typescript
-import { trace, SpanStatusCode } from "@opentelemetry/api";
-
-export const POST = withRoute("/api/checkout", async (req) => {
- const span = trace.getActiveSpan();
- try {
- await processPayment(await req.json());
- } catch (error) {
- if (span) {
- span.recordException(error as Error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
- }
- return Response.json({ error: "Payment failed" }, { status: 500 });
- }
- return Response.json({ status: "ok" });
-});
-```
-
-## Verification
-
-After starting your app, hit a few endpoints and check Traceway:
-
-1. **Endpoints page** — routes should appear grouped by pattern (e.g., `GET /api/users/[id]`), not by literal URL
-2. **Issues page** — any thrown errors should appear with stack traces
-3. **Endpoint detail → Spans tab** — Prisma queries, outgoing fetch calls, and manual spans should appear as children of the HTTP request
-
-## Checklist
-
-- [ ] OTel packages installed (+ `@prisma/instrumentation` if using Prisma)
-- [ ] `instrumentation.ts` created at project root with `register()` function and runtime guard
-- [ ] `lib/with-route.ts` created
-- [ ] Every API route handler wrapped with `withRoute("/api/path/[param]", handler)`
-- [ ] `experimental.instrumentationHook: true` added (Next.js 13.4-14.x only)
-- [ ] `TRACEWAY_URL` and `TRACEWAY_TOKEN` env vars set
-- [ ] Verified endpoints appear in Traceway dashboard
diff --git a/skills/add-traceway.md b/skills/add-traceway.md
deleted file mode 100644
index ab1870fa..00000000
--- a/skills/add-traceway.md
+++ /dev/null
@@ -1,131 +0,0 @@
-# Add Traceway to a Project
-
-Add OpenTelemetry tracing to an existing project so it reports to a Traceway instance.
-
-## What Traceway Needs
-
-For the integration to work correctly, the instrumentation MUST capture:
-
-1. **Endpoints grouped by route pattern** — `GET /api/users/1` and `GET /api/users/2` must appear as a single `GET /api/users/:id` endpoint, NOT as separate entries. This requires `http.route` to be set on the root span. Without it, the Traceway dashboard explodes with thousands of unique URL entries.
-
-2. **Status codes** — `http.response.status_code` must be set on spans so Traceway can track error rates, 4xx/5xx breakdowns, and Apdex scores.
-
-3. **Exceptions with stack traces** — Thrown errors must be recorded as span events with `exception.type`, `exception.message`, and `exception.stacktrace` attributes. These appear as **Issues** in Traceway.
-
-4. **Scheduled/long-running tasks** — Background jobs (cron, queues, consumers) must create root spans with `SpanKind.CONSUMER`. This is how Traceway distinguishes Tasks from Endpoints. Without the correct span kind, background work either gets misclassified as an Endpoint or dropped entirely.
-
-### How Traceway classifies spans
-
-| OTel Span | Condition | Traceway Concept |
-|---|---|---|
-| Root span | `SpanKind = SERVER` or `INTERNAL` with HTTP attributes | **Endpoint** |
-| Root span | `SpanKind = CONSUMER` | **Task** |
-| Non-root span | Has a parent span ID | **Span** |
-| Exception event | Event named `"exception"` on any span | **Issue** |
-
-## Step 1: Identify the Framework
-
-Detect the framework by reading `package.json` (Node.js), `go.mod` (Go), `composer.json` (PHP), or asking the user.
-
-## Step 2: Follow the Framework-Specific Guide
-
-### Hono (Node.js)
-Follow `skills/add-traceway-to-hono-project.md`. Uses `@hono/otel` middleware — do NOT use `@opentelemetry/instrumentation-http` (it doesn't work with Hono's ESM imports on Node 22+).
-- Endpoints: `@hono/otel` sets `http.route` automatically
-- Status codes: `@hono/otel` sets them automatically
-- Exceptions: `@hono/otel` records thrown errors automatically
-- Tasks: No built-in scheduler — use `SpanKind.CONSUMER` manually for background work
-
-### NestJS (Node.js)
-Follow `skills/add-traceway-to-nestjs-project.md`. Simplest integration — Express auto-instrumentation handles everything.
-- Endpoints: `instrumentation-express` sets `http.route` automatically
-- Status codes: `instrumentation-http` sets them automatically
-- Exceptions: Express error handling records them automatically
-- Tasks: Wrap `@nestjs/schedule` cron jobs and `@nestjs/bull` queue consumers with `SpanKind.CONSUMER` spans
-
-### Next.js (Node.js)
-Follow `skills/add-traceway-to-nextjs-project.md`. Requires `withRoute()` wrapper for API routes and `@prisma/instrumentation` for database tracing.
-- Endpoints: `withRoute()` helper must be added manually to every API route handler
-- Status codes: Set by the HTTP instrumentation
-- Exceptions: `withRoute()` catches and records thrown errors
-- Tasks: No built-in scheduler — use `SpanKind.CONSUMER` manually for background work
-
-### Express (Node.js)
-- Install: `@opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http @opentelemetry/api`
-- Create `instrumentation.js` at project root with `NodeSDK` + `getNodeAutoInstrumentations()`
-- No app code changes needed — auto-instrumentation captures routes, status codes, errors
-- Start with `node --import ./instrumentation.js server.js`
-- Tasks: Use `SpanKind.CONSUMER` manually for background work
-- Full docs: `docs/pages/client/node-sdk/index.mdx`
-
-### Gin / Chi / Fiber / FastHTTP / stdlib (Go)
-- Install the framework-specific middleware: `go get go.tracewayapp.com/tracewaygin` (or `tracewaychi`, `tracewayfiber`, `tracewayfasthttp`, `tracewayhttp`)
-- Add middleware: `r.Use(tracewaygin.New("token@http://traceway:8082/api/report"))`
-- Reports via Traceway's native protocol (`/api/report`), not OTel
-- Endpoints, status codes, exceptions, and tasks are all handled by the Go SDK automatically
-- Full docs: `docs/pages/client/gin-middleware/index.mdx` (or the corresponding framework directory)
-
-### Symfony (PHP)
-- Install: `composer require traceway/opentelemetry-symfony open-telemetry/exporter-otlp php-http/guzzle7-adapter`
-- Configure via `.env` with `OTEL_*` variables
-- Add `\OpenTelemetry\SDK\SdkAutoloader::autoload()` to `public/index.php`
-- Endpoints and status codes: handled by Symfony OTel auto-instrumentation
-- Tasks: Symfony Messenger consumers are auto-instrumented as Tasks
-- Full docs: `docs/pages/client/symfony/index.mdx`
-
-### React / Vue / Svelte / jQuery (Frontend)
-- Install the framework-specific Traceway SDK: `npm install @tracewayapp/react` (or `@tracewayapp/vue`, `@tracewayapp/svelte`, `@tracewayapp/jquery`)
-- These are client-side SDKs that report to `/api/report`, not OTel
-- Full docs: `docs/pages/client/react/index.mdx` (or the corresponding framework directory)
-
-### Cloudflare Workers
-- Uses Cloudflare's built-in OTLP export, not the Node SDK
-- Scheduled handlers (`scheduled` event) create root spans automatically
-- Full docs: `docs/pages/client/cloudflare/index.mdx`
-
-### Any Other Language (Generic OTel)
-- Use any OpenTelemetry SDK for the language
-- Export via OTLP/HTTP to `https://<traceway-instance>/api/otel/v1/traces` and `/v1/metrics`
-- Set `Authorization: Bearer <project-token>` header
-- Ensure `http.route` is set on root SERVER spans (not just `url.path`)
-- Use `SpanKind.CONSUMER` for background/scheduled work
-- Full docs: `docs/pages/client/otel/index.mdx`
-
-## Instrumenting Background Tasks (All Frameworks)
-
-For any framework, background work (cron jobs, queue consumers, scheduled tasks) must create a root span with `SpanKind.CONSUMER` to appear as a **Task** in Traceway:
-
-```typescript
-import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
-
-const tracer = trace.getTracer("my-app");
-
-async function runScheduledJob() {
- await tracer.startActiveSpan(
- "cleanup-expired-sessions",
- { kind: SpanKind.CONSUMER },
- async (span) => {
- try {
- await doWork();
- span.setStatus({ code: SpanStatusCode.OK });
- } catch (error) {
- span.recordException(error);
- span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
- throw error;
- } finally {
- span.end();
- }
- }
- );
-}
-```
-
-Without `SpanKind.CONSUMER`, the span would either be classified as an Endpoint (wrong) or dropped.
-
-## Common Across All Node.js Frameworks
-
-- **Traceway URL**: `https://<instance>/api/otel/v1/traces` and `/v1/metrics`
-- **Auth header**: `Authorization: Bearer <project-token>`
-- **Environment variables**: `TRACEWAY_URL` and `TRACEWAY_TOKEN` (or standard `OTEL_*` vars)
-- **Auto-instrumented child spans** (CJS packages only): `pg`, `mysql2`, `mongodb`, `ioredis`, `redis`, Prisma (with `@prisma/instrumentation`), outgoing `fetch()` via `instrumentation-undici`
-- **Not auto-instrumented**: SQLite (`better-sqlite3`), custom business logic — use `tracer.startActiveSpan()` manually
diff --git a/skills/traceway-setup/SKILL.md b/skills/traceway-setup/SKILL.md
new file mode 100644
index 00000000..8ca2bedf
--- /dev/null
+++ b/skills/traceway-setup/SKILL.md
@@ -0,0 +1,298 @@
+---
+name: traceway-setup
+description: Connect a project to a Traceway instance so it reports endpoints, spans, errors, background tasks, AI traces, and metrics. Backends use OpenTelemetry over OTLP/HTTP, frontends and mobile apps use the Traceway SDKs, and host metrics use the Traceway OTel Agent. Use when the user wants to add Traceway (or OpenTelemetry tracing that exports to Traceway) to a backend, frontend, full-stack, or mobile project. Accepts a project token and instance URL, e.g. "/traceway-setup with token abc123".
+---
+
+# Set Up Traceway in a Project
+
+Connect an existing project to a Traceway instance so it reports endpoints, spans, errors, background tasks, AI traces, and metrics.
+
+## Step 0: Gather Connection Info
+
+| Value | Example | Where to find it |
+|---|---|---|
+| **Instance URL** | `https://traceway.example.com` | The URL of the Traceway dashboard |
+| **Project token** | `abc123...` | Traceway dashboard → Connection page |
+| **Source map upload token** (optional, frontend only) | `def456...` | Traceway dashboard → Connection page → Source Maps |
+
+Instance URL and project token may be provided in the invocation (e.g. `/traceway-setup with token abc123 and url https://traceway.example.com`). If either is missing:
+
+1. Check for existing `TRACEWAY_URL` / `TRACEWAY_TOKEN` environment variables or `.env` entries in the project.
+2. Still missing: ask the user whether they already have a Traceway account.
+ - **Yes**: ask them to open their Traceway dashboard, go to the project's **Connection** page, and paste the instance URL and project token here. If no project exists yet for this app, have them create one first, picking the framework that matches this codebase.
+ - **No**: send them to the register page to create an account: https://cloud.tracewayapp.com/register (or `https://<their-instance>/register` if they are self-hosting). After registering and creating a project, the Connection page shows the token; ask them to paste the URL and token here.
+
+Do not proceed without real values. Never invent placeholder values in committed code; wire everything through environment variables.
+
+## Integration Paths
+
+Pick the path by project type. This is not negotiable per framework; it is how Traceway is designed to receive data:
+
+| Project type | Path |
+|---|---|
+| **Backend** (any language) | OpenTelemetry, exporting OTLP/HTTP to `<instance>/api/otel/v1/*`. Always, including Go. The native Traceway Go SDK is used only when the user explicitly asks for it. |
+| **Frontend** (browser SPA) | Traceway `@tracewayapp/<framework>` SDK + bundler plugin + source map upload (see "Frontend and Mobile" below). |
+| **Full-stack JS** (Next.js, SvelteKit, Remix) | BOTH: server side via OpenTelemetry AND browser side via the frontend SDK. |
+| **Mobile** (Flutter, React Native, Android) | The Traceway platform SDK only. Never OTel. |
+
+Two hard rules apply to every backend integration:
+
+1. **Endpoints MUST arrive parametrized.** `http.route` must be set to the route pattern (`/api/users/:id`), never the concrete URL. Traceway uses the value as-is; when it is missing it falls back to `url.path`, and the Endpoints page explodes into one row per unique URL.
+2. **Background work MUST use `SpanKind.CONSUMER`.** A root span with the default `INTERNAL` kind and no HTTP attributes is silently dropped.
+
+### How Traceway classifies spans
+
+| OTel Span | Condition | Traceway Concept |
+|---|---|---|
+| Root span (or span whose parent lives in another service) | `SpanKind = SERVER` or `INTERNAL` with HTTP attributes | **Endpoint** |
+| Any span | `SpanKind = CONSUMER` | **Task** |
+| Root span | `SpanKind = INTERNAL` with a `console.command` attribute | **Task** (CLI command) |
+| Any span | Has any `gen_ai.*` attribute | **AI Trace** |
+| Non-root span | Has a parent span ID, matched none of the above | **Span** (child) |
+| Exception event | Event named `"exception"` on any span above | **Issue** |
+| Root span | Matched none of the above | **Dropped silently** (including its exception events) |
+
+For the exact classification rules, endpoint naming, metric conversion, and all the quirks, read `data-model.md` in this skill directory. It is the authoritative reference.
+
+## Step 1: Analyze the Architecture
+
+Before changing anything, build a picture of what needs instrumenting:
+
+1. **Frameworks and languages**: detect them by reading `package.json` (Node.js), `go.mod` (Go), `composer.json` (PHP), `requirements.txt`/`pyproject.toml` (Python), `pubspec.yaml` (Flutter), `build.gradle` (Android), or asking the user.
+2. **Services and entry points**: in a monorepo, list each deployable service and its entry point. Each service that should report to Traceway needs its own integration, and usually its own project token (ask the user before reusing one token across services).
+3. **Background work**: find cron jobs, queue consumers, schedulers, CLI commands, and long-running workers. These must be instrumented as Tasks (Step 3).
+4. **AI/LLM usage**: check dependencies for `openai`, `@anthropic-ai/sdk`, `anthropic`, `langchain` / `@langchain/*`, `ai` (Vercel AI SDK), `litellm`, `google-generativeai`, `cohere`, `openrouter`. If any are present, Step 4 applies.
+5. **Deployment signals**: note Dockerfiles, `docker-compose.yml`, Kubernetes manifests, Helm charts, deploy/provisioning scripts, `fly.toml`, `vercel.json`, Procfiles. You will use these in Step 5 to set up server metrics.
+
+## Step 2: Backend OTel Setup
+
+The same shape in every language:
+
+1. Install the language's OpenTelemetry SDK plus the auto-instrumentation for the web framework and database clients.
+2. Point the OTLP/HTTP exporter at Traceway with the project token as a Bearer header.
+3. Set `service.name` (becomes the Server Name in Traceway) and `service.version` (enables release comparison) on the resource.
+4. Verify endpoint grouping (the hard rule above) before anything else.
+
+### Exporter configuration
+
+Where the SDK supports the standard env vars, prefer them; they work identically across languages:
+
+```bash
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=https://<instance>/api/otel
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <project-token>"
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+```
+
+SDKs append `/v1/traces`, `/v1/metrics`, `/v1/logs` to the endpoint automatically. When configuring in code instead, the full URLs are `https://<instance>/api/otel/v1/traces` (and `/v1/metrics`, `/v1/logs`) with header `Authorization: Bearer <project-token>`.
+
+Constraints: OTLP/HTTP only (protobuf or JSON), OTLP/gRPC is NOT supported; gzip is fine; max request body 10 MB.
+
+### Node.js example
+
+Create `instrumentation.js` at the project root and load it before the app (`node --import ./instrumentation.js server.js`):
+
+```javascript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+
+const url = process.env.TRACEWAY_URL;
+const headers = { Authorization: `Bearer ${process.env.TRACEWAY_TOKEN}` };
+
+const sdk = new NodeSDK({
+ traceExporter: new OTLPTraceExporter({ url: `${url}/api/otel/v1/traces`, headers }),
+ metricReader: new PeriodicExportingMetricReader({
+ exporter: new OTLPMetricExporter({ url: `${url}/api/otel/v1/metrics`, headers }),
+ exportIntervalMillis: 30_000,
+ }),
+ instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+Auto-instrumentation covers Express routes (sets `http.route`), status codes, errors, and CJS database clients (`pg`, `mysql2`, `mongodb`, `ioredis`). SQLite and custom business logic need manual `tracer.startActiveSpan()` child spans.
+
+### Per-language notes
+
+- **Go**: use the contrib middleware for the framework: `otelgin`, `otelchi` (with `otelchi.WithChiRoutes(r)`), `otelfiber`; they set `http.route` from the route pattern. For stdlib `net/http`, current `otelhttp` derives `http.route` from Go 1.23+ `ServeMux` method+pattern routes (`GET /api/users/{id}`); for other routers set `http.route` manually on the active span. Exporter: `otlptracehttp.WithEndpointURL(...)` + `WithHeaders`.
+- **Python**: `opentelemetry-distro` + `opentelemetry-bootstrap -a install`, run under `opentelemetry-instrument` with the env vars above. Django/Flask/FastAPI instrumentations set `http.route`.
+- **PHP**: Symfony and Laravel via their OTel packages and `OTEL_*` env vars. Symfony caveat: the stock auto-instrumentation sets `http.route` to the route NAME, which Traceway ignores; use the Traceway Symfony integration (`composer require traceway/opentelemetry-symfony`). See `data-model.md`.
+- **Java / .NET / anything else**: the standard OTel agent or SDK with the env vars above works as-is.
+- Full per-framework docs: https://docs.tracewayapp.com/client/otel
+
+### Verify endpoint grouping (do this first)
+
+Hit a parametrized route a few times with different IDs and check the Traceway Endpoints page: you must see ONE row (`GET /api/users/:id`), not one row per ID. If you see raw IDs, the instrumentation is not setting `http.route`; fix that before continuing. Last resort, set it manually in a middleware that knows the matched route pattern:
+
+```javascript
+import { trace } from "@opentelemetry/api";
+
+trace.getActiveSpan()?.setAttribute("http.route", matchedRoutePattern);
+```
+
+### Errors
+
+Thrown errors must be recorded as exception events to appear as Issues. Auto-instrumentation handles uncaught errors; for caught-and-handled ones:
+
+```javascript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const span = trace.getActiveSpan();
+span?.recordException(error);
+span?.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+```
+
+(Go: `span.RecordError(err, trace.WithStackTrace(true))`; the stack trace option is what produces the `exception.stacktrace` attribute.)
+
+### If the user explicitly asks for the Traceway Go SDK
+
+Only on explicit request, instead of OTel: `go get go.tracewayapp.com/tracewaygin` (or `tracewaychi`, `tracewayfiber`, `tracewayfasthttp`, `tracewayhttp`), add the middleware with connection string `<project-token>@https://<instance>/api/report`. Trade-off: the Go SDK natively emits the built-in system metric names (`cpu.used_pcnt`, `mem.used`, `go.*`) that populate the dashboard's built-in charts; on the OTel path those charts stay empty and host metrics come from the Traceway OTel Agent (Step 5).
+
+## Step 3: Background Tasks (Boundaries and Labeling)
+
+If Step 1 found background work, instrument it as Tasks. The rules:
+
+- **Boundary: one Task = one execution of a unit of background work.** A whole cron job run is one task. One queue message or job is one task. One CLI command invocation is one task. Per-item work inside a run (each email in a batch, each row in an import) is a child span of the task span, never a separate `CONSUMER` span.
+- **Do not double-wrap.** If a library's auto-instrumentation already emits `CONSUMER` spans (Kafka, RabbitMQ, Symfony Messenger consumers), wrapping them again creates duplicate Task entries.
+- **Labeling: the span name IS the task name and the grouping key.** Use a stable identifier like `cleanup-expired-sessions` or `process-email-queue`. Never embed job IDs, timestamps, or user IDs in the name; each unique name becomes a separate task group. Dynamic context (job ID, batch size) belongs in span attributes, where it shows on the task detail page without affecting grouping.
+- **The kind must be `CONSUMER`.** A root span with the default `SpanKind.INTERNAL` is dropped silently; this is the most common reason "my cron job doesn't show up". CLI commands may alternatively be root `INTERNAL` spans with a `console.command` attribute (Laravel/Symfony console instrumentation does this).
+
+```typescript
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-app");
+
+async function runScheduledJob() {
+ await tracer.startActiveSpan(
+ "cleanup-expired-sessions",
+ { kind: SpanKind.CONSUMER },
+ async (span) => {
+ try {
+ await doWork();
+ span.setStatus({ code: SpanStatusCode.OK });
+ } catch (error) {
+ span.recordException(error);
+ span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+ );
+}
+```
+
+(Go: `tracer.Start(ctx, "cleanup-expired-sessions", trace.WithSpanKind(trace.SpanKindConsumer))`.)
+
+## Step 4: AI Traces
+
+If Step 1 found AI/LLM dependencies, instrument the model calls. Any span carrying at least one `gen_ai.*` attribute is promoted to an **AI Trace**; since calls usually happen inside a request or task, the span is naturally a child and stays linked to its Endpoint/Task by trace ID.
+
+Boundaries: **one span per model call** (one provider API request = one AI Trace row). A multi-step agent run is multiple spans sharing a stable `trace.name` (same labeling discipline as task names: no IDs or timestamps). For streaming, end the span when the stream finishes. Set `user.id` to break down usage and cost per user.
+
+Attributes Traceway reads (all optional, set what is available):
+
+| Attribute | Meaning |
+|---|---|
+| `gen_ai.request.model` / `gen_ai.response.model` | Requested / serving model |
+| `gen_ai.system` or `gen_ai.provider.name` | Provider (`openai`, `anthropic`, ...) |
+| `gen_ai.operation.name` | Operation (`chat`, `embeddings`, ...) |
+| `gen_ai.usage.input_tokens` / `.output_tokens` / `.total_tokens` | Token counts |
+| `gen_ai.usage.input_tokens.cached` / `gen_ai.usage.output_tokens.reasoning` | Cached / reasoning tokens |
+| `gen_ai.usage.input_cost` / `.output_cost` / `.total_cost` | Cost, when you compute pricing |
+| `trace.name` | Agent/workflow grouping name |
+| `user.id` | End-user attribution |
+| `gen_ai.response.finish_reason` | Why generation stopped |
+| `gen_ai.prompt` / `gen_ai.completion` | Conversation content, shown on the trace detail page (skip if content must not leave the app) |
+
+```typescript
+return tracer.startActiveSpan("chat-completion", async (span) => {
+ const response = await openai.chat.completions.create({ model: "gpt-4o", messages });
+ span.setAttributes({
+ "gen_ai.system": "openai",
+ "gen_ai.request.model": "gpt-4o",
+ "gen_ai.usage.input_tokens": response.usage.prompt_tokens,
+ "gen_ai.usage.output_tokens": response.usage.completion_tokens,
+ "trace.name": "support-agent",
+ });
+ span.end();
+ return response;
+});
+```
+
+Zero-code path for OpenRouter users: in OpenRouter Settings → Observability, add an OpenTelemetry Collector destination pointing at `https://<instance>/api/otel/v1/traces` with header `{"Authorization": "Bearer <project-token>"}`. Docs: https://docs.tracewayapp.com/client/openrouter
+
+## Frontend and Mobile
+
+Frontend and mobile projects do NOT use OTel; they use the Traceway SDKs reporting to `/api/report` with connection string `<project-token>@https://<instance>/api/report`.
+
+**Browser** (React / Vue / Svelte / jQuery / plain JS), three pieces, all expected:
+
+1. **SDK**: `npm install @tracewayapp/react` (or `vue`, `svelte`, `jquery`, `frontend` for plain JS) and initialize with the connection string (React: wrap the app in `<TracewayProvider connectionString="...">`). Captures errors, web vitals, and session replay.
+2. **Bundler plugin**: `npm install -D @tracewayapp/bundler-plugin`, then add `tracewayDebugIds()` from `@tracewayapp/bundler-plugin/vite` (or `/rollup`, or `TracewayDebugIdsWebpackPlugin` from `/webpack`) to the bundler config, with source maps enabled (`build.sourcemap: true` / `devtool: "source-map"`).
+3. **Source map upload**: `npm install -D @tracewayapp/sourcemap-upload`, then run `traceway-sourcemaps --url <instance> --token <source-map-upload-token> --directory ./dist` as a postbuild or CI step (env vars: `TRACEWAY_URL`, `TRACEWAY_SOURCEMAP_TOKEN`). The upload token comes from Step 0 and is a CI secret, never committed.
+
+Full docs: https://docs.tracewayapp.com/client/react (or `vue`, `svelte`, `jquery`, `js-sdk`).
+
+**Full-stack JS** (Next.js, SvelteKit, Remix): both sides. Server side follows Step 2 (verify `http.route` grouping; set it manually in a server hook where the auto-instrumentation does not know the router). Browser side follows the three pieces above.
+
+**Mobile**, always the platform SDK, never OTel:
+
+- **Flutter**: `flutter pub add traceway`, then `Traceway.run(connectionString: '<token>@https://<instance>/api/report', child: MyApp())`. Docs: https://docs.tracewayapp.com/client/flutter
+- **React Native**: `npm install @tracewayapp/react-native`, wrap the app in `TracewayProvider`. Docs: https://docs.tracewayapp.com/client/react-native
+- **Android**: `implementation("com.tracewayapp:traceway:<version>")`, call `Traceway.init(...)` at startup. Docs: https://docs.tracewayapp.com/client/android
+
+## Step 5: Deployment and Server Metrics
+
+After the code-side integration is in place, ask the user two questions (pre-fill your best guess from the deployment signals found in Step 1 and let them confirm):
+
+1. **How is this project deployed?** Docker on a VM / directly on a VM or bare metal / Kubernetes / serverless or PaaS.
+2. **Do you want server (host) metrics tracked in Traceway?** CPU, memory, disk, filesystem, network of the machine running the app.
+
+| Deployment | Wants host metrics | What to do |
+|---|---|---|
+| Docker on a VM, or directly on a VM/host | Yes | Install the **Traceway OTel Agent** on the host (below). For Docker deploys this is the default; the agent goes on the host, not in a container. |
+| Kubernetes | Any | Agent not applicable (host service, no Docker image or K8s manifests by design). In-process app metrics still flow via the OTLP metrics exporter from Step 2. |
+| Serverless / PaaS | Any | No host to install on; skip. |
+| Anything | No | Skip. |
+
+The agent is a tiny pre-configured OTel Collector that scrapes host metrics every 60s and ships them with the project token. Install on the host (Linux systemd / macOS launchd; PowerShell installer exists for Windows):
+
+```bash
+curl -fsSL https://install.tracewayapp.com/install.sh | \
+ TRACEWAY_TOKEN=<project-token> \
+ TRACEWAY_ENDPOINT=https://<instance>/api/otel \
+ TRACEWAY_SERVICE_NAME=<host-label, e.g. api-prod-eu-1> \
+ bash
+```
+
+- `TRACEWAY_ENDPOINT` ends in `/api/otel` and is required for self-hosted instances; omit only for Traceway Cloud.
+- Optional: `TRACEWAY_LOG_PATHS` (comma-separated globs to tail as logs), `TRACEWAY_PROCESS_NAMES` (per-process metrics).
+- Re-running the installer upgrades in place, so the command is safe to keep in provisioning scripts.
+- If the repo has host provisioning or deploy scripts (cloud-init, Ansible, Terraform `user_data`, `deploy.sh`), add the command there with the token referenced from a secret. Otherwise hand the operator the filled-in one-liner; do not modify the repo.
+
+Metrics arrive within ~60s under their hostmetrics names (`system.cpu.utilization`, `system.memory.usage`, ...), tagged with `service.name` and `host.name`. They are chartable via custom widgets; they do NOT populate the built-in CPU/memory charts (those read the Go SDK's exact names). Agent repo: https://github.com/tracewayapp/traceway-otel-agent
+
+## Step 6: Verify
+
+1. Start the app and hit a few endpoints (or trigger an error on purpose).
+2. Check the Traceway dashboard:
+ - **Endpoints page**: routes appear grouped by pattern (e.g. `GET /api/users/:id`), not by literal URL, and status codes are non-zero.
+ - **Issues page**: thrown errors appear with stack traces. For frontend projects, stack traces are symbolicated to original files and lines.
+ - **Endpoint detail → Spans tab**: database queries and outgoing calls appear as children.
+ - **Tasks page**: after triggering each background job once, it appears under one stable name.
+ - **AI Traces page** (if Step 4 applied): model calls appear with token counts and cost.
+ - **Metrics** (if the agent was installed): host metrics arrive within about 60 seconds.
+3. If the `traceway` CLI is installed and authenticated, verify from the terminal instead:
+ ```bash
+ traceway endpoints list --since 15m
+ traceway exceptions list --since 15m
+ traceway metrics query --name system.cpu.utilization --since 15m
+ ```
diff --git a/skills/traceway-setup/data-model.md b/skills/traceway-setup/data-model.md
new file mode 100644
index 00000000..c895ad1e
--- /dev/null
+++ b/skills/traceway-setup/data-model.md
@@ -0,0 +1,233 @@
+# How Traceway Interprets OpenTelemetry Data
+
+This is the framework-agnostic reference for connecting any OpenTelemetry project to Traceway. It explains what Traceway shows in the dashboard, how it classifies incoming OTel spans, and the quirks the instrumentation MUST respect for the data to display correctly. Read this before following any framework-specific guide.
+
+## Sending Data
+
+| What | Value |
+|---|---|
+| Traces | `POST https://<instance>/api/otel/v1/traces` |
+| Metrics | `POST https://<instance>/api/otel/v1/metrics` |
+| Logs | `POST https://<instance>/api/otel/v1/logs` |
+| Auth | `Authorization: Bearer <project-token>` header on every request |
+| Encoding | OTLP/HTTP — both `application/x-protobuf` and `application/json` are accepted. OTLP/gRPC is NOT supported. |
+| Compression | `Content-Encoding: gzip` is supported (exporters default to no compression; enabling `compression: gzip` is fine). Max request body: 10 MB. |
+
+## What the Dashboard Shows
+
+Traceway turns OTel spans into five distinct concepts, each with its own dashboard page:
+
+| Concept | Dashboard page | Built from |
+|---|---|---|
+| **Endpoint** | Endpoints (P50/P95/P99, error rates, Apdex) | Root spans that look like HTTP requests |
+| **Task** | Tasks (background jobs, cron, consumers) | `CONSUMER`-kind spans |
+| **Span** | Endpoint/Task detail → Spans tab (waterfall) | Child spans (DB queries, outgoing calls, custom work) |
+| **Issue** | Issues (grouped errors with stack traces) | `exception` events on spans |
+| **AI Trace** | AI Traces (tokens, cost, model) | Spans with `gen_ai.*` attributes |
+
+## Span Classification Rules (exact)
+
+For every incoming span, Traceway applies these rules in order:
+
+1. **Endpoint** — `SpanKind` is `SERVER` or `INTERNAL`, the span has at least one HTTP attribute (`http.request.method`, `http.method`, `http.route`, or `url.path`), AND it is either a root span (no parent) or its parent span is not present in the same export batch (cross-process tracing, e.g. behind a proxy that injects `traceparent`).
+2. **Task** — `SpanKind` is `CONSUMER`. This applies to ANY consumer span, root or not.
+3. **Task** — a root `INTERNAL` span with a `console.command` attribute (CLI command instrumentation, e.g. Laravel/Symfony console).
+4. **AI Trace** — the span has any attribute starting with `gen_ai.`.
+5. **Child span** — anything else with a parent: stored as a generic span, attached to the nearest promoted ancestor (Endpoint/Task/AI Trace) by walking up the parent chain.
+6. **Dropped** — anything else that is a root span. A root span that matches none of the rules above is silently discarded, along with any exception events on it.
+
+The consequences of rule 6 are the most common integration bug: a custom root span created with `tracer.startActiveSpan("my-job")` and default `SpanKind.INTERNAL` produces NOTHING in Traceway. Background work must use `SpanKind.CONSUMER` (see Tasks below).
+
+## Endpoints: Name and Route Parameters
+
+This is where most integrations go wrong. The endpoint name displayed and grouped in the dashboard is built as:
+
+```
+<method> <route>
+```
+
+e.g. `GET /api/users/:id`. The pieces come from span attributes, with these exact rules:
+
+- **Method**: `http.request.method` (current semconv), falling back to `http.method` (old semconv).
+- **Route**: `http.route`, falling back to `url.path`. A `http.route` value that does not start with `/` is ignored entirely (treated as absent).
+- If the method is present but no route can be resolved, the span name is used as the route. If neither is present, the raw span name becomes the endpoint name.
+
+### The cardinality quirk — `http.route` is mandatory
+
+`http.route` must contain the **route pattern with parameter placeholders**, never the concrete URL:
+
+```
+correct: http.route = /api/users/:id -> one endpoint: "GET /api/users/:id"
+correct: http.route = /api/users/{id} -> one endpoint: "GET /api/users/{id}"
+wrong: http.route missing, url.path only -> thousands of endpoints: "GET /api/users/1", "GET /api/users/2", ...
+```
+
+The placeholder style (`:id`, `{id}`, `<id>`) does not matter — Traceway uses the route string as-is. What matters is that the string is **identical for every request hitting that route**. If `http.route` is missing, Traceway falls back to `url.path`, which contains real IDs, and the Endpoints page explodes into one row per unique URL. Express, Hono (via `@hono/otel`), and Django instrumentations set `http.route` to the path template automatically — but verify it in the dashboard after setup; it's the #1 thing to check.
+
+Symfony caveat: the stock `open-telemetry/opentelemetry-auto-symfony` package sets `http.route` to the Symfony route *name* (e.g. `app_user_show`), not a path template. Traceway deliberately ignores `http.route` values that don't start with `/` and falls back to `url.path` — so endpoint grouping for raw Symfony auto-instrumentation degrades to literal paths. Use the Traceway Symfony integration (see the Symfony guide) instead.
+
+### Other endpoint attributes Traceway reads
+
+| Attribute (current semconv) | Legacy fallback also read | Used for |
+|---|---|---|
+| `http.response.status_code` | `http.status_code` | Status, error rate, 4xx/5xx breakdown |
+| `http.response.body.size` | `http.response_content_length` | Response size |
+| `client.address` | `net.peer.ip` | Client IP |
+
+Quirks:
+
+- **404 responses are renamed to `UNMATCHED`.** Any endpoint span with status 404 is grouped under a single `UNMATCHED` endpoint regardless of its route — bot scans and typo'd URLs don't pollute the endpoint list. Don't be surprised when a legitimate 404-returning route doesn't appear under its own name.
+- **Missing status code becomes `0`.** Without `http.response.status_code`, error tracking and Apdex for that endpoint are meaningless. Make sure the instrumentation sets it.
+- **Streaming endpoints** (long-lived responses that would otherwise look like terrible P99s) are detected when: status is `101` (WebSocket upgrade), the captured response header `http.response.header.content-type` contains `text/event-stream` (SSE), or the vendor attribute `traceway.is_stream` (boolean) is `true`. OTel clients don't capture response headers by default — for SSE endpoints either enable capture of `content-type` or set `traceway.is_stream` manually. Streaming endpoints keep their request count and error rate, but latency percentiles and Apdex are zeroed (connection lifetime is not request latency).
+- **Health-check endpoints are filtered at ingestion** according to the project's health-check configuration, so `GET /health`-style routes don't pollute the endpoint list or stats.
+- **Apdex thresholds are fixed**: satisfied at duration up to 750 ms, tolerating up to 1.5 s, bad above that or on any 5xx response.
+
+## Tasks: Scheduled Jobs, Cron, Queue Consumers
+
+Background work appears on the **Tasks** page only when the span has `SpanKind.CONSUMER`:
+
+```typescript
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-app");
+
+async function runScheduledJob() {
+ await tracer.startActiveSpan(
+ "cleanup-expired-sessions", // becomes the Task name, must be stable
+ { kind: SpanKind.CONSUMER }, // without this the span is DROPPED
+ async (span) => {
+ try {
+ await doWork();
+ span.setStatus({ code: SpanStatusCode.OK });
+ } catch (error) {
+ span.recordException(error); // becomes an Issue, linked to this Task
+ span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+ throw error;
+ } finally {
+ span.end();
+ }
+ }
+ );
+}
+```
+
+Quirks:
+
+- **The span name IS the task name, and Traceway groups tasks by name.** Use a stable identifier like `cleanup-expired-sessions` or `process-email-queue`. Never put job IDs, timestamps, or user IDs in the span name — each unique name becomes a separate task group.
+- **Every `CONSUMER` span becomes a Task, even non-root ones.** If a queue library's auto-instrumentation already emits `CONSUMER` spans (e.g. Kafka/RabbitMQ consumers, Symfony Messenger), do NOT wrap them in another `CONSUMER` span — you'd get duplicate Task entries.
+- A root `INTERNAL` span with `SpanKind.INTERNAL` (the default!) is **dropped silently** — this is the most common reason "my cron job doesn't show up". The kind must be `CONSUMER`.
+- Per-job context (job ID, batch size) belongs in span **attributes**, where it shows on the task detail page without affecting grouping.
+
+## Database Queries and Child Spans
+
+Work inside an endpoint or task — DB queries, cache hits, outgoing HTTP calls, custom business logic — should be **child spans** of the entity's root span. They render in the waterfall on the Endpoint/Task detail page.
+
+How Traceway handles them:
+
+- **The span name is replaced by the SQL text when present**: if the span has `db.query.text` (current semconv) or `db.statement` (old semconv), that value is displayed instead of the span name. So a `pg.query` span carrying `db.statement = "SELECT * FROM users WHERE id = $1"` shows the query itself in the waterfall — this is what makes auto-instrumented DB clients (`pg`, `mysql2`, `mongodb`, `ioredis`, Prisma via `@prisma/instrumentation`) useful out of the box.
+- **Child spans attach to the nearest promoted ancestor.** The parent chain is walked until an Endpoint/Task/AI Trace is found. This means DB spans must be created **inside the active context** of the request/task span (`startActiveSpan`, or the framework middleware's context). A DB span created outside any active context becomes a root `INTERNAL` span — and is dropped.
+- Spans whose parent lives in another process/batch and never resolves to a promoted entity are kept but linked by the raw OTel trace ID instead.
+- For databases without auto-instrumentation (e.g. SQLite), create a manual child span and set `db.system` + `db.statement` attributes so it renders like the auto-instrumented ones.
+
+## Issues: Exceptions
+
+Errors become **Issues** when recorded as a span **event named `exception`** (`span.recordException(error)` does exactly this) with the standard attributes:
+
+- `exception.type` — error class, e.g. `TypeError`
+- `exception.message` — error message
+- `exception.stacktrace` — full stack trace text
+
+Quirks:
+
+- **Exceptions on dropped spans are dropped too.** An exception recorded on an unpromoted root span (see classification rule 6) never reaches the Issues page. Record exceptions on spans that live inside an Endpoint/Task, or fix the span kind.
+- Traceway also understands Honeycomb-style structured stack traces (`exception.structured_stacktrace.urls` / `.functions` / `.lines` / `.columns` array attributes) — used by some browser/edge SDKs.
+- **Grouping is automatic.** Before hashing (SHA-256, truncated to 16 hex chars), Traceway normalizes the stack trace: error messages are stripped (only the error type is kept, including on `Caused by:` lines), JS function-name lines collapse to `<fn>`, absolute paths reduce to `filename:line`, dependency version suffixes (`@v1.2.3`) are removed, and runtime values are replaced with placeholders — hex addresses → `<hex>`, UUIDs → `<uuid>`, numbers of 5+ digits → `<id>`, emails → `<email>`, IPs → `<ip>`, goroutine IDs → `goroutine <n>`. JVM frames additionally lose their line numbers (`(Foo.java:123)` → `(Foo.java)`) and `... N more` becomes `... more`. The same logical error therefore groups into one Issue even when runtime values differ — don't try to pre-group errors client-side.
+- **JS projects get source-map symbolication.** Triggered when the `telemetry.sdk.language` resource attribute is a JS value (`nodejs`, `webjs`, `javascript`, `typescript` — OTel SDKs set this automatically), or when the instrumentation scope name is npm-scoped (`@scope/pkg`) or `next.js`. Minified frames are resolved server-side **before** grouping, so uploading source maps improves grouping too.
+- **Source maps are matched by filename (and debug ID when embedded), not by version.** Upload via `POST /api/sourcemaps/upload` (multipart `files` field, `.map`/`.js`/`.cjs`/`.mjs`, max 50 MB per file) using a token from `POST /api/projects/source-map-token`. A frame referencing `app.min.js` resolves against the uploaded `app.min.js.map` by name — keep bundle filenames unique per release (content hashes do this) or rely on debug IDs.
+
+## Metrics
+
+OTLP metrics sent to `/api/otel/v1/metrics` are stored under their **original names** — there is no renaming or namespacing. Every incoming metric is auto-registered (name, unit, type) in the metric registry, becomes discoverable in the dashboard's metric explorer, and can be charted in custom widgets or queried via `traceway metrics query --name <name>`.
+
+Conversion rules per OTLP metric type:
+
+| OTLP type | Stored as | Registered type |
+|---|---|---|
+| Gauge | `<name>`, value as-is | `gauge` |
+| Sum (monotonic) | `<name>`, value as-is | `counter` |
+| Sum (non-monotonic) | `<name>`, value as-is | `gauge` |
+| Histogram | TWO series: `<name>.avg` (sum/count per export) and `<name>.count` | `gauge` + `counter` |
+| ExponentialHistogram, Summary | **silently dropped** | — |
+
+Quirks:
+
+- **Histograms lose their buckets.** Only the average and count survive — you cannot compute true percentiles from an OTLP histogram in Traceway.
+- **No percentile aggregations on metrics at all.** Metric queries support `avg`, `sum`, `count`, `min`, and `max` only; anything else silently falls back to `avg`. Latency percentiles (P50/P95/P99) exist for Endpoints and Tasks because those are computed from raw span durations — if you need percentiles on a measurement, model it as a span, not a metric.
+- **Tags come from data-point attributes only.** Resource attributes are NOT copied onto metric points, with two exceptions: `service.name` becomes the `server_name` tag, and the process-scraper allowlist (`process.pid`, `process.executable.name`, `process.command_line`, `process.owner`) is lifted so hostmetrics per-process series stay distinguishable. Any per-series dimension must be a data-point attribute, and keep its cardinality low.
+
+### Built-in metric names
+
+The dashboard's built-in system charts (Metrics page, default widget suggestions) read these **exact hardcoded names** — they are emitted natively by the Traceway Go SDK:
+
+| Name | Meaning | Unit |
+|---|---|---|
+| `cpu.used_pcnt` | CPU usage | percent (0–100) |
+| `mem.used` | Memory used | MB |
+| `mem.total` | Memory total | MB |
+| `go.go_routines` | Goroutine count | count |
+| `go.heap_objects` | Heap objects | count |
+| `go.num_gc` | Total GC cycles | count |
+| `go.gc_pause` | Last GC pause | nanoseconds |
+
+An OTel project's metrics (e.g. hostmetrics' `system.cpu.utilization`) do NOT populate those built-in charts — they appear as custom metrics under their own names, chartable via custom widgets. To fill the built-in CPU/memory charts from an OTel pipeline, the metrics must be emitted under the exact names and units above.
+
+## Logs
+
+OTLP logs sent to `/api/otel/v1/logs` appear on the **Logs** page. From each LogRecord, Traceway reads: timestamp (falling back to observed timestamp), severity number and text, body, trace ID and span ID, and three separate attribute maps — resource, scope, and log-record attributes — each independently filterable.
+
+What the Logs page (and `traceway logs query`) can filter by: minimum severity, service name (from the `service.name` resource attribute), trace ID, free-text body search, and attribute key/value filters scoped to resource, scope, or log attributes.
+
+Quirks:
+
+- **Emit logs inside the active span context.** The trace ID on a log record is what links it to the Endpoint/Task that produced it — OTel log bridges do this automatically when a span is active.
+- **Body search over ranges longer than 24 hours requires at least one additional filter** (service, severity, trace, or attribute) — unbounded full-text scans are rejected.
+- A JS `exception.stacktrace` attribute on a log record is source-map symbolicated, same as span exceptions.
+- Logs are retained for 30 days (database TTL); other telemetry has no fixed expiry on ClickHouse deployments.
+
+## Resource Attributes
+
+Set these once on the OTel `Resource` — they tag everything the service exports:
+
+| Resource attribute | Shown in Traceway as | Notes |
+|---|---|---|
+| `service.name` | Server Name | Set via `OTEL_SERVICE_NAME` or SDK config. Distinguishes instances/services within a project. |
+| `service.version` | App Version | Enables release-over-release comparison. On Cloudflare Workers, derived from `cloudflare.script_version.id` automatically. |
+| `telemetry.sdk.language` | — | Drives JS symbolication; set automatically by every OTel SDK. |
+
+## Vendor Extension Attributes
+
+Traceway recognizes these non-standard span attributes:
+
+| Attribute | Type | Purpose |
+|---|---|---|
+| `traceway.is_stream` | boolean | Mark an endpoint span as streaming (SSE/long-poll) so its duration is excluded from latency percentiles. |
+| `traceway.distributed_trace_id` | string (UUID) | Override the distributed trace ID used to link entities across services. Rarely needed — the OTel trace ID is used by default. |
+
+## Verification Checklist
+
+After wiring up any project, confirm in the dashboard (or via `traceway` CLI):
+
+1. **Endpoints page** — routes are grouped by pattern (`GET /api/users/:id`), NOT one row per concrete URL. If you see raw IDs, `http.route` is not being set.
+2. **Endpoints page** — status codes are non-zero.
+3. **Tasks page** — each scheduled job appears under one stable name after triggering it. (Dashboard only — the CLI has no `tasks` command.)
+4. **Issues page** — a deliberately thrown error shows up with a readable stack trace.
+5. **Endpoint detail → Spans tab** — DB queries appear as children showing the SQL text.
+
+With the `traceway` CLI (`--since` takes relative ranges like `1h`, `24h`, `7d`):
+
+```bash
+traceway endpoints list --since 1h
+traceway exceptions list --since 1h
+traceway logs query --since 1h --min-severity 17
+traceway metrics query --name <metric-name> --since 1h
+```
diff --git a/skills/traceway/SKILL.md b/skills/traceway/SKILL.md
new file mode 100644
index 00000000..c28937ab
--- /dev/null
+++ b/skills/traceway/SKILL.md
@@ -0,0 +1,223 @@
+---
+name: traceway
+description: Operate a Traceway observability instance through the traceway CLI: log in, query exceptions, logs, endpoints, and metrics, and debug production issues down to root cause. Use when the user invokes /traceway with a subcommand, e.g. "/traceway login", "/traceway debug issue <hash|url|title>", "/traceway what's broken in prod", or whenever they want to investigate errors, crashes, slowness, or logs from an app monitored by Traceway.
+---
+
+# Traceway
+
+Drive a Traceway instance from the terminal with the `traceway` CLI. The first word of the argument decides the flow:
+
+| Invocation | Flow |
+|---|---|
+| `/traceway login` | **Login**: install the CLI if missing, authenticate, select a project |
+| `/traceway debug <issue ref or bug description>` | **Debug**: resolve the issue and investigate to root cause |
+| `/traceway <anything else>` | **Query**: answer the observability question with CLI reads |
+| `/traceway` (no argument) | Ask what they want: log in, debug an issue, or run a query |
+
+> The CLI is under active development. If a flag documented here does not appear in `traceway <command> --help`, trust the binary.
+
+## Ground Rules (All Flows)
+
+- **Reads are safe**: any `list` / `show` / `query` subcommand may run freely; they never mutate server state.
+- **Writes require explicit user instruction**: `exceptions archive` / `unarchive` are the only mutating data commands; only run them when the user asks by name, with `--yes` in non-interactive contexts. "Look at this error" means read it, not archive it.
+- **Output**: piped output defaults to JSON (table on a TTY). Prefer JSON + `jq`, and `--fields a,b,c` to trim responses. Keep `--page-size` at 10 to 20 for triage.
+- **Time windows**: always bound queries, default `--since 1h` for "now" questions, `--since 24h` otherwise. `--since` accepts `s`, `m`, `h`, lowercase `Nd` (no `1w`, no `7d2h`). Absolute windows via `--from` / `--to` (RFC3339).
+- **Exit codes**: 0 ok, 1 generic/API, 2 usage, 3 connection, 4 auth, 5 not found, 6 rate limited, 7 server 5xx. Errors emit `{"error":"<stable_id>","message":"...","hint":"...","exit_code":N}` on stderr; branch on the `error` field.
+- On exit code 4 (auth), do not run `traceway login` yourself; switch to the Login flow and let the user enter credentials.
+
+## Resolving Dashboard URLs
+
+Users paste dashboard URLs (`https://<instance>/<route>`) as references in any flow. Resolve by route family:
+
+| URL path | Identifies | How to fetch it |
+|---|---|---|
+| `/issues/<hash>` and `/issues/<hash>/events` | Exception group (hash = 16 hex chars) | `traceway exceptions show <hash>` |
+| `/issues/<hash>/<occurrenceId>` (UUID) | One occurrence within the group | `traceway exceptions show <hash> --output json \| jq '.occurrences[] \| select(.id=="<occurrenceId>")'`; occurrences are paginated, walk `--page` if not in the first page |
+| `/endpoints/<endpoint>` | Endpoint group; the segment is the URL-encoded endpoint name (`GET%20%2Fapi%2Fusers%2F%3Aid` is `GET /api/users/:id`) | Decode it, then `traceway endpoints list --search "<decoded name>"` (there is no `endpoints show`) |
+| `/endpoints/<endpoint>/<endpointId>` | One request (transaction) of that endpoint | No CLI for single transactions; fetch the group as above, correlate with `traceway logs query --trace-id <id>` if a trace ID is known from context |
+| `/tasks/<task>` and `/tasks/<task>/<taskId>` | Background task group / single run | No CLI; point the user at the dashboard Tasks page |
+| `/sessions/<sessionId>` | Session replay | No CLI; dashboard only. Occurrences reference sessions via their `sessionId` field |
+| `/ai-traces/<traceName>` and `/ai-traces/<traceName>/<traceId>` | AI trace group / single trace | No CLI; dashboard only |
+| `/logs` | Logs page (its filters are not stored in the URL) | `traceway logs query` with flags taken from the user's description |
+| `/issues`, `/endpoints`, `/metrics`, `/` | List and dashboard pages | The matching `list` / `query` command |
+
+**Time window**: most dashboard URLs carry `?preset=<p>` or `?from=<iso>&to=<iso>` (sticky across pages); honor them instead of the default window.
+
+- `preset` values `5m 30m 60m 3h 6h 12h 24h 3d 7d` map directly to `--since`; the CLI has no month unit, so map `1M` to `--since 30d` and `3M` to `--since 90d`.
+- `from`/`to` are ISO timestamps; pass via `--from`/`--to`, appending `Z` (or the correct offset) when missing, since the CLI requires RFC3339.
+- No time params means the page was on its default; pick `--since` per the ground rules.
+
+## Flow: Login
+
+### 1. Check for an existing install
+
+```bash
+traceway version
+```
+
+If it prints a version, skip to authentication.
+
+### 2. Install if missing
+
+Prebuilt binaries are on the [tracewayapp/traceway releases page](https://github.com/tracewayapp/traceway/releases) under `cli/vX.Y.Z` tags (the latest release may be a Backend release, so filter for CLI tags):
+
+```bash
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m); [ "$ARCH" = "aarch64" ] && ARCH=arm64
+URL=$(curl -s "https://api.github.com/repos/tracewayapp/traceway/releases?per_page=20" \
+ | grep -o "https://[^\"]*traceway_[^\"]*_${OS}_${ARCH}\.tar\.gz" | head -1)
+TMP=$(mktemp -d)
+curl -sL "$URL" | tar -xz -C "$TMP"
+install -m 755 "$TMP/traceway" ~/.local/bin/traceway && rm -rf "$TMP"
+```
+
+Make sure `~/.local/bin` is on `PATH` (or install to `/usr/local/bin`). Fallback, build from source (requires Go):
+
+```bash
+git clone https://github.com/tracewayapp/traceway && cd traceway/cli
+go build -o bin/traceway ./cmd/traceway && install -m 755 bin/traceway ~/.local/bin/traceway
+```
+
+Verify with `traceway version`.
+
+### 3. Authenticate
+
+Login prompts for the password interactively, so ask the user to run it themselves (in Claude Code, suggest typing `! traceway login --url https://<instance>` so the output lands in the session):
+
+```bash
+traceway login --url https://<traceway-instance>
+```
+
+Non-interactive alternative when the password is in a secret store (never echo a password into the command line or shell history):
+
+```bash
+printf '%s' "$TRACEWAY_PASSWORD" | traceway login --url https://<instance> --username [email protected] --password-stdin
+```
+
+Multiple instances or accounts coexist via profiles: `traceway login --url ... --profile work`, then `traceway profiles list` / `traceway profiles use work`.
+
+### 4. Select a project and smoke-check
+
+```bash
+traceway projects list
+traceway projects use <project-id>
+traceway exceptions list --since 24h
+```
+
+The selected project is used implicitly by all subsequent commands.
+
+## Flow: Debug
+
+`/traceway debug issue X` or `/traceway debug <free-form bug description>`.
+
+### 1. Resolve the issue reference
+
+`X` can be several things; resolve it to an exception hash (16 hex chars):
+
+| Reference looks like | How to resolve |
+|---|---|
+| Dashboard URL | See "Resolving Dashboard URLs" above; for `/issues/...` URLs the path segment right after `/issues/` is the hash, and `?preset`/`?from`/`?to` give the time window |
+| Bare 16-char hex string | Already the hash |
+| Anything else (title, error message, type, file name) | Search: `traceway exceptions list --since 7d --search "<text>"`; widen to `--since 30d` (and `--include-archived`) if empty |
+| No issue reference, just a bug description | Skip to triage below |
+
+When a search returns multiple groups, show a shortlist (hash, count, lastSeen, first stack line) and ask the user which one before drilling in.
+
+```bash
+traceway exceptions list --since 7d --search "checkout" --output json \
+ | jq '.data[]? | {hash: .exceptionHash, count, lastSeen, top: (.stackTrace | split("\n")[0])}'
+```
+
+### 2. Drill into the issue
+
+```bash
+traceway exceptions show <hash>
+```
+
+This is the high-value call: full stack trace, occurrence list with `recordedAt`, `attributes` (user IDs, app versions, request context), and optional `distributedTraceId` / `sessionId` per occurrence. `firstSeen` correlates with deploys: a group that first appeared right after a release points at that release's diff. A bogus hash exits 5 with `not_found`; fall back to search.
+
+### 3. Triage and correlate (also the entry point for free-form bug descriptions)
+
+From the description extract symptom, affected endpoint/feature, and time window, then read several signals before forming a hypothesis:
+
+```bash
+traceway exceptions list --since 24h --order-by lastSeen # what is erroring (firstSeen for regressions, count for volume)
+traceway logs query --since 24h --min-severity 17 # errors and worse
+traceway logs query --since 24h --search "payment declined" # search log bodies
+traceway logs query --since 24h --service checkout-api --min-severity 13
+traceway endpoints list --since 24h --search "checkout" # latency p50/p95/p99 and error counts, --order-by impact|count|p95|lastSeen
+```
+
+Severity is an OTel number, not a name: 1 TRACE, 5 DEBUG, 9 INFO, 13 WARN, 17 ERROR, 21 FATAL. The flag is `--min-severity 17`, never `--severity error`.
+
+**Correlate by trace**: when an occurrence or log line carries a trace ID, pull the whole request timeline; this is usually the fastest route to a root cause:
+
+```bash
+traceway exceptions show $HASH --output json | jq -r '.occurrences[0].distributedTraceId' \
+ | xargs -I{} traceway logs query --trace-id {} --output json
+```
+
+**Check metrics for systemic causes** (spikes lining up with `firstSeen` suggest saturation rather than a code bug):
+
+```bash
+traceway metrics query --name system.cpu.utilization --aggregation max --since 24h
+traceway metrics query --name <name> --aggregation avg|sum|count|min|max [--tag key=value] [--group-by <tag>]
+```
+
+The CLI also accepts `p50|p95|p99`, but the server has no quantile aggregation for metric points and silently computes `avg` for them — never present those as percentiles. Latency percentiles come from `traceway endpoints list`, computed from raw request durations. There is no `metrics list`; a bogus name returns an empty `series: {}` cleanly, so probing names is safe. Host metrics from the Traceway OTel Agent live under `system.*` names, and OTLP histogram metrics are stored as two series, `<name>.avg` and `<name>.count`.
+
+### 4. Correlate with the code
+
+1. Open the files and lines named in the stack trace and read the failing path.
+2. If the issue started at a known time, check what shipped then: `git log --since "<firstSeen>" --until "<firstSeen + 1h>"` or the deploy history.
+3. Form a hypothesis that explains ALL observations (error message, affected endpoint, timing, volume), not just the first stack frame.
+4. Propose or implement the fix per the user's instruction.
+
+### 5. Report and clean up
+
+Summarize: symptom, evidence (exception hashes, log excerpts, metric anomalies), root cause, fix. Include `traceway exceptions show <hash>` references so the user can verify. After a fix is deployed and verified, archive only when the user asks:
+
+```bash
+traceway exceptions archive <hash> --yes
+```
+
+## Flow: Query
+
+For free-form requests ("what's broken in prod?", "is /api/checkout slow?", "show errors for service X"), use the read commands directly.
+
+### Command reference
+
+| Command | Purpose |
+|---|---|
+| `traceway projects {list,use}` | List or select the active project |
+| `traceway exceptions list` | Grouped exceptions; `--search`, `--search-type text\|regex`, `--order-by lastSeen\|firstSeen\|count`, `--include-archived` |
+| `traceway exceptions show <hash>` | One group: full stack trace + occurrences |
+| `traceway exceptions archive/unarchive <hash>...` | Mutating; explicit user request + `--yes` only |
+| `traceway logs query` | Logs; `--search` (`--search-type body\|attribute`), `--service`, `--min-severity <n>`, `--trace-id` |
+| `traceway endpoints list` | Per-endpoint p50/p95/p99 and counts; `--search`, `--order-by impact\|count\|p95\|lastSeen` |
+| `traceway metrics query --name <metric>` | Time series; `--aggregation`, `--tag`, `--group-by`, `--interval-minutes` |
+| `traceway profiles {list,use}`, `login`, `logout`, `version` | Profile and session management |
+
+Not implemented yet (do not fabricate flags; point the user at the web UI): `traces show`, `sessions list/show`, `ai-traces list/show`, `endpoints show`, `metrics list/discover`. Tasks have no CLI command either; the dashboard's Tasks page covers them.
+
+### Recipes
+
+```bash
+# What's broken right now
+traceway exceptions list --since 1h --order-by lastSeen --page-size 10 --output json \
+ | jq '.data[]? | {hash: .exceptionHash, count, lastSeen}'
+
+# Did anything NEW break since a deploy at 13:00 UTC
+traceway exceptions list --from 2026-06-11T13:00:00Z --to "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+ --order-by firstSeen --output json \
+ | jq '.data[]? | select(.firstSeen >= "2026-06-11T13:00:00Z") | {hash: .exceptionHash, firstSeen, count}'
+
+# Worst endpoint by latency
+traceway endpoints list --since 1h --order-by p95 --page-size 1 --output json | jq '.data[0]'
+
+# Errors for one service (exceptions --search is free text, not a service filter; use logs)
+traceway logs query --service checkout-api --min-severity 17 --since 1h --output json \
+ | jq '.data[]? | {timestamp, body, traceId}'
+```
+
+Empty results (`data: null`) are not errors: widen the window, re-check the active project (`traceway projects list`), and if the app was never connected to Traceway, set it up first (the `traceway-setup` skill).
diff --git a/testing/otel-collector-grafana-honeycomb/.gitignore b/testing/otel-collector-grafana-honeycomb/.gitignore
new file mode 100644
index 00000000..6303ccf1
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/.gitignore
@@ -0,0 +1,3 @@
+bin/
+build/
+.env
diff --git a/testing/otel-collector-grafana-honeycomb/config.yaml b/testing/otel-collector-grafana-honeycomb/config.yaml
new file mode 100644
index 00000000..319567b1
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/config.yaml
@@ -0,0 +1,42 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:5317
+ http:
+ endpoint: 0.0.0.0:5318
+ cors:
+ allowed_origins:
+ - "*"
+ allowed_headers:
+ - "*"
+
+processors:
+ source_map_symbolicator:
+ source_map_store: file_store
+ local_source_maps:
+ path: ./sourcemaps
+ batch:
+ timeout: 2s
+
+exporters:
+ otlphttp/grafana:
+ endpoint: https://otlp-gateway-prod-us-east-3.grafana.net/otlp
+ headers:
+ Authorization: "Basic ${env:GRAFANA_OTLP_BASIC}"
+ debug:
+ verbosity: detailed
+
+service:
+ telemetry:
+ metrics:
+ level: none
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [source_map_symbolicator, batch]
+ exporters: [otlphttp/grafana, debug]
+ logs:
+ receivers: [otlp]
+ processors: [source_map_symbolicator, batch]
+ exporters: [otlphttp/grafana, debug]
diff --git a/testing/otel-collector-grafana-honeycomb/manifest.yaml b/testing/otel-collector-grafana-honeycomb/manifest.yaml
new file mode 100644
index 00000000..276d9e3e
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/manifest.yaml
@@ -0,0 +1,16 @@
+dist:
+ name: otelcol-honeycomb-symbolicator
+ description: OTel Collector with the Honeycomb source map symbolicator
+ output_path: ./build
+ cgo_enabled: true
+
+receivers:
+ - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.143.0
+
+processors:
+ - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.143.0
+ - gomod: github.com/honeycombio/opentelemetry-collector-symbolicator/sourcemapprocessor v1.0.3
+
+exporters:
+ - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.143.0
+ - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.143.0
diff --git a/testing/otel-collector-grafana-honeycomb/run.sh b/testing/otel-collector-grafana-honeycomb/run.sh
new file mode 100755
index 00000000..f5d0cee4
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/run.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+source .env
+
+export GRAFANA_OTLP_BASIC="$(printf '%s:%s' "$GRAFANA_OTLP_INSTANCE_ID" "$GRAFANA_CLOUD_TOKEN" | base64)"
+
+if [ ! -x build/otelcol-honeycomb-symbolicator ]; then
+ echo "build/otelcol-honeycomb-symbolicator not found, run ./bin/builder --config manifest.yaml first" >&2
+ exit 1
+fi
+
+exec ./build/otelcol-honeycomb-symbolicator --config config.yaml
diff --git a/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs b/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs
new file mode 100644
index 00000000..0449178c
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs
@@ -0,0 +1,3 @@
+import{trace as e,SpanKind as t,SpanStatusCode as r}from"@opentelemetry/api";import{NodeTracerProvider as o,BatchSpanProcessor as s}from"@opentelemetry/sdk-trace-node";import{OTLPTraceExporter as n}from"@opentelemetry/exporter-trace-otlp-http";import{defaultResource as a,resourceFromAttributes as c}from"@opentelemetry/resources";const i=new Map([["ord_1042",2]]);function p(e){const t=function(e,t){const r=i.get(e)??0;if(t>r)throw new RangeError(`cannot reserve ${t} units for order ${e}, only ${r} in stock`);return i.set(e,r-t),{orderId:e,units:t}}(e.orderId,e.units);return{orderId:e.orderId,reservation:t}}const d=process.env.TW_TOKEN||"5638c2de607f45169bcf98aa8774fe5c",l=process.env.TW_OTLP_URL||"http://localhost:8082/api/otel/v1/traces",u=process.argv[2]||"event";(async function(){const i=new o({resource:a().merge(c({"service.name":"symbolication-node-app"})),spanProcessors:[new s(new n({url:l,headers:{Authorization:`Bearer ${d}`}}))]});i.register();const m=e.getTracer("symbolication-node-app"),f=m.startSpan("POST /orders/fulfill",{kind:t.SERVER,attributes:{"http.request.method":"POST","http.route":"/orders/fulfill","url.path":"/orders/fulfill"}});try{const e=p({orderId:"ord_1042",units:3});f.setAttribute("http.response.status_code",200),f.setStatus({code:r.OK}),console.log("order fulfilled:",e)}catch(e){if(f.setAttribute("http.response.status_code",500),f.setStatus({code:r.ERROR,message:e.message}),"span"===u){m.startSpan("exception",{attributes:{"exception.type":e.name,"exception.message":e.message,"exception.stacktrace":e.stack}}).end()}else f.recordException(e);console.error(`reported ${e.name} via mode=${u}: ${e.message}`)}f.end(),await i.shutdown(),console.log(`flushed to ${l}`)})().catch(e=>{console.error("fatal:",e),process.exit(1)});
+
+//# sourceMappingURL=app.mjs.map
diff --git a/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs.map b/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs.map
new file mode 100644
index 00000000..4d784be8
--- /dev/null
+++ b/testing/otel-collector-grafana-honeycomb/sourcemaps/app.mjs.map
@@ -0,0 +1 @@
+{"version":3,"file":"app.mjs","sources":["../src/inventory.js","../src/order.js","../src/index.js"],"sourcesContent":["const stockLevels = new Map([[\"ord_1042\", 2]]);\n\nexport function reserveStock(orderId, units) {\n const available = stockLevels.get(orderId) ?? 0;\n if (units > available) {\n throw new RangeError(\n `cannot reserve ${units} units for order ${orderId}, only ${available} in stock`,\n );\n }\n stockLevels.set(orderId, available - units);\n return { orderId, units };\n}\n","import { reserveStock } from \"./inventory.js\";\n\nexport function fulfillOrder(order) {\n const reservation = reserveStock(order.orderId, order.units);\n return { orderId: order.orderId, reservation };\n}\n","import { trace, SpanKind, SpanStatusCode } from \"@opentelemetry/api\";\nimport {\n NodeTracerProvider,\n BatchSpanProcessor,\n} from \"@opentelemetry/sdk-trace-node\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-http\";\nimport {\n defaultResource,\n resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { fulfillOrder } from \"./order.js\";\n\nconst token = process.env.TW_TOKEN || \"5638c2de607f45169bcf98aa8774fe5c\";\nconst url =\n process.env.TW_OTLP_URL || \"http://localhost:8082/api/otel/v1/traces\";\nconst mode = process.argv[2] || \"event\";\n\nasync function main() {\n const provider = new NodeTracerProvider({\n resource: defaultResource().merge(\n resourceFromAttributes({ \"service.name\": \"symbolication-node-app\" }),\n ),\n spanProcessors: [\n new BatchSpanProcessor(\n new OTLPTraceExporter({\n url,\n headers: { Authorization: `Bearer ${token}` },\n }),\n ),\n ],\n });\n provider.register();\n\n const tracer = trace.getTracer(\"symbolication-node-app\");\n\n const span = tracer.startSpan(\"POST /orders/fulfill\", {\n kind: SpanKind.SERVER,\n attributes: {\n \"http.request.method\": \"POST\",\n \"http.route\": \"/orders/fulfill\",\n \"url.path\": \"/orders/fulfill\",\n },\n });\n try {\n const result = fulfillOrder({ orderId: \"ord_1042\", units: 3 });\n span.setAttribute(\"http.response.status_code\", 200);\n span.setStatus({ code: SpanStatusCode.OK });\n console.log(\"order fulfilled:\", result);\n } catch (err) {\n span.setAttribute(\"http.response.status_code\", 500);\n span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });\n if (mode === \"span\") {\n const exceptionSpan = tracer.startSpan(\"exception\", {\n attributes: {\n \"exception.type\": err.name,\n \"exception.message\": err.message,\n \"exception.stacktrace\": err.stack,\n },\n });\n exceptionSpan.end();\n } else {\n span.recordException(err);\n }\n console.error(`reported ${err.name} via mode=${mode}: ${err.message}`);\n }\n span.end();\n\n await provider.shutdown();\n console.log(`flushed to ${url}`);\n}\n\nmain().catch((err) => {\n console.error(\"fatal:\", err);\n process.exit(1);\n});\n"],"names":["stockLevels","Map","fulfillOrder","order","reservation","orderId","units","available","get","RangeError","set","reserveStock","token","process","env","TW_TOKEN","url","TW_OTLP_URL","mode","argv","async","provider","NodeTracerProvider","resource","defaultResource","merge","resourceFromAttributes","spanProcessors","BatchSpanProcessor","OTLPTraceExporter","headers","Authorization","register","tracer","trace","getTracer","span","startSpan","kind","SpanKind","SERVER","attributes","result","setAttribute","setStatus","code","SpanStatusCode","OK","console","log","err","ERROR","message","name","stack","end","recordException","error","shutdown","main","catch","exit"],"mappings":"2UAAA,MAAMA,EAAc,IAAIC,IAAI,CAAC,CAAC,WAAY,KCEnC,SAASC,EAAaC,GAC3B,MAAMC,EDDD,SAAsBC,EAASC,GACpC,MAAMC,EAAYP,EAAYQ,IAAIH,IAAY,EAC9C,GAAIC,EAAQC,EACV,MAAM,IAAIE,WACR,kBAAkBH,qBAAyBD,WAAiBE,cAIhE,OADAP,EAAYU,IAAIL,EAASE,EAAYD,GAC9B,CAAED,UAASC,QACpB,CCRsBK,CAAaR,EAAME,QAASF,EAAMG,OACtD,MAAO,CAAED,QAASF,EAAME,QAASD,cACnC,CCOA,MAAMQ,EAAQC,QAAQC,IAAIC,UAAY,mCAChCC,EACJH,QAAQC,IAAIG,aAAe,2CACvBC,EAAOL,QAAQM,KAAK,IAAM,SAEhCC,iBACE,MAAMC,EAAW,IAAIC,EAAmB,CACtCC,SAAUC,IAAkBC,MAC1BC,EAAuB,CAAE,eAAgB,4BAE3CC,eAAgB,CACd,IAAIC,EACF,IAAIC,EAAkB,CACpBb,MACAc,QAAS,CAAEC,cAAe,UAAUnB,WAK5CS,EAASW,WAET,MAAMC,EAASC,EAAMC,UAAU,0BAEzBC,EAAOH,EAAOI,UAAU,uBAAwB,CACpDC,KAAMC,EAASC,OACfC,WAAY,CACV,sBAAuB,OACvB,aAAc,kBACd,WAAY,qBAGhB,IACE,MAAMC,EAASxC,EAAa,CAAEG,QAAS,WAAYC,MAAO,IAC1D8B,EAAKO,aAAa,4BAA6B,KAC/CP,EAAKQ,UAAU,CAAEC,KAAMC,EAAeC,KACtCC,QAAQC,IAAI,mBAAoBP,EAClC,CAAE,MAAOQ,GAGP,GAFAd,EAAKO,aAAa,4BAA6B,KAC/CP,EAAKQ,UAAU,CAAEC,KAAMC,EAAeK,MAAOC,QAASF,EAAIE,UAC7C,SAATlC,EAAiB,CACGe,EAAOI,UAAU,YAAa,CAClDI,WAAY,CACV,iBAAkBS,EAAIG,KACtB,oBAAqBH,EAAIE,QACzB,uBAAwBF,EAAII,SAGlBC,KAChB,MACEnB,EAAKoB,gBAAgBN,GAEvBF,QAAQS,MAAM,YAAYP,EAAIG,iBAAiBnC,MAASgC,EAAIE,UAC9D,CACAhB,EAAKmB,YAEClC,EAASqC,WACfV,QAAQC,IAAI,cAAcjC,IAC5B,EAEA2C,GAAOC,MAAOV,IACZF,QAAQS,MAAM,SAAUP,GACxBrC,QAAQgD,KAAK"}
\ No newline at end of file
diff --git a/testing/symbolication/otel-collector-grafana/.gitignore b/testing/symbolication/otel-collector-grafana/.gitignore
new file mode 100644
index 00000000..67c14ca0
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/.gitignore
@@ -0,0 +1,4 @@
+bin/
+build/
+twcache/
+.env
diff --git a/testing/symbolication/otel-collector-grafana/config.yaml b/testing/symbolication/otel-collector-grafana/config.yaml
new file mode 100644
index 00000000..44367ba4
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/config.yaml
@@ -0,0 +1,44 @@
+receivers:
+ otlp:
+ protocols:
+ grpc:
+ endpoint: 0.0.0.0:4317
+ http:
+ endpoint: 0.0.0.0:4318
+ cors:
+ allowed_origins:
+ - "*"
+ allowed_headers:
+ - "*"
+
+processors:
+ source_map_symbolicator:
+ source_map_store: file_store
+ local_source_maps:
+ path: ./sourcemaps
+ cache_dir: ./twcache
+ cache_max_mb: 512
+ batch:
+ timeout: 2s
+
+exporters:
+ otlphttp/grafana:
+ endpoint: https://otlp-gateway-prod-us-east-3.grafana.net/otlp
+ headers:
+ Authorization: "Basic ${env:GRAFANA_OTLP_BASIC}"
+ debug:
+ verbosity: detailed
+
+service:
+ telemetry:
+ metrics:
+ level: none
+ pipelines:
+ traces:
+ receivers: [otlp]
+ processors: [source_map_symbolicator, batch]
+ exporters: [otlphttp/grafana, debug]
+ logs:
+ receivers: [otlp]
+ processors: [source_map_symbolicator, batch]
+ exporters: [otlphttp/grafana, debug]
diff --git a/testing/symbolication/otel-collector-grafana/manifest.yaml b/testing/symbolication/otel-collector-grafana/manifest.yaml
new file mode 100644
index 00000000..a898d05e
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/manifest.yaml
@@ -0,0 +1,19 @@
+dist:
+ name: otelcol-symbolicator
+ description: OTel Collector with the Traceway source map symbolicator
+ output_path: ./build
+
+receivers:
+ - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.154.0
+
+processors:
+ - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.154.0
+ - gomod: github.com/tracewayapp/traceway/backend v1.8.0
+ import: github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor
+
+exporters:
+ - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.154.0
+ - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.154.0
+
+replaces:
+ - github.com/tracewayapp/traceway/backend => /Users/dusanstanojevic/Documents/workspace/traceway/backend
diff --git a/testing/symbolication/otel-collector-grafana/run.sh b/testing/symbolication/otel-collector-grafana/run.sh
new file mode 100755
index 00000000..5be739a5
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/run.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+source .env
+
+export GRAFANA_OTLP_BASIC="$(printf '%s:%s' "$GRAFANA_OTLP_INSTANCE_ID" "$GRAFANA_CLOUD_TOKEN" | base64)"
+
+if [ ! -x build/otelcol-symbolicator ]; then
+ echo "build/otelcol-symbolicator not found, run ./bin/builder --config manifest.yaml first" >&2
+ exit 1
+fi
+
+exec ./build/otelcol-symbolicator --config config.yaml
diff --git a/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs b/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs
new file mode 100644
index 00000000..0449178c
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs
@@ -0,0 +1,3 @@
+import{trace as e,SpanKind as t,SpanStatusCode as r}from"@opentelemetry/api";import{NodeTracerProvider as o,BatchSpanProcessor as s}from"@opentelemetry/sdk-trace-node";import{OTLPTraceExporter as n}from"@opentelemetry/exporter-trace-otlp-http";import{defaultResource as a,resourceFromAttributes as c}from"@opentelemetry/resources";const i=new Map([["ord_1042",2]]);function p(e){const t=function(e,t){const r=i.get(e)??0;if(t>r)throw new RangeError(`cannot reserve ${t} units for order ${e}, only ${r} in stock`);return i.set(e,r-t),{orderId:e,units:t}}(e.orderId,e.units);return{orderId:e.orderId,reservation:t}}const d=process.env.TW_TOKEN||"5638c2de607f45169bcf98aa8774fe5c",l=process.env.TW_OTLP_URL||"http://localhost:8082/api/otel/v1/traces",u=process.argv[2]||"event";(async function(){const i=new o({resource:a().merge(c({"service.name":"symbolication-node-app"})),spanProcessors:[new s(new n({url:l,headers:{Authorization:`Bearer ${d}`}}))]});i.register();const m=e.getTracer("symbolication-node-app"),f=m.startSpan("POST /orders/fulfill",{kind:t.SERVER,attributes:{"http.request.method":"POST","http.route":"/orders/fulfill","url.path":"/orders/fulfill"}});try{const e=p({orderId:"ord_1042",units:3});f.setAttribute("http.response.status_code",200),f.setStatus({code:r.OK}),console.log("order fulfilled:",e)}catch(e){if(f.setAttribute("http.response.status_code",500),f.setStatus({code:r.ERROR,message:e.message}),"span"===u){m.startSpan("exception",{attributes:{"exception.type":e.name,"exception.message":e.message,"exception.stacktrace":e.stack}}).end()}else f.recordException(e);console.error(`reported ${e.name} via mode=${u}: ${e.message}`)}f.end(),await i.shutdown(),console.log(`flushed to ${l}`)})().catch(e=>{console.error("fatal:",e),process.exit(1)});
+
+//# sourceMappingURL=app.mjs.map
diff --git a/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs.map b/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs.map
new file mode 100644
index 00000000..4d784be8
--- /dev/null
+++ b/testing/symbolication/otel-collector-grafana/sourcemaps/app.mjs.map
@@ -0,0 +1 @@
+{"version":3,"file":"app.mjs","sources":["../src/inventory.js","../src/order.js","../src/index.js"],"sourcesContent":["const stockLevels = new Map([[\"ord_1042\", 2]]);\n\nexport function reserveStock(orderId, units) {\n const available = stockLevels.get(orderId) ?? 0;\n if (units > available) {\n throw new RangeError(\n `cannot reserve ${units} units for order ${orderId}, only ${available} in stock`,\n );\n }\n stockLevels.set(orderId, available - units);\n return { orderId, units };\n}\n","import { reserveStock } from \"./inventory.js\";\n\nexport function fulfillOrder(order) {\n const reservation = reserveStock(order.orderId, order.units);\n return { orderId: order.orderId, reservation };\n}\n","import { trace, SpanKind, SpanStatusCode } from \"@opentelemetry/api\";\nimport {\n NodeTracerProvider,\n BatchSpanProcessor,\n} from \"@opentelemetry/sdk-trace-node\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-http\";\nimport {\n defaultResource,\n resourceFromAttributes,\n} from \"@opentelemetry/resources\";\nimport { fulfillOrder } from \"./order.js\";\n\nconst token = process.env.TW_TOKEN || \"5638c2de607f45169bcf98aa8774fe5c\";\nconst url =\n process.env.TW_OTLP_URL || \"http://localhost:8082/api/otel/v1/traces\";\nconst mode = process.argv[2] || \"event\";\n\nasync function main() {\n const provider = new NodeTracerProvider({\n resource: defaultResource().merge(\n resourceFromAttributes({ \"service.name\": \"symbolication-node-app\" }),\n ),\n spanProcessors: [\n new BatchSpanProcessor(\n new OTLPTraceExporter({\n url,\n headers: { Authorization: `Bearer ${token}` },\n }),\n ),\n ],\n });\n provider.register();\n\n const tracer = trace.getTracer(\"symbolication-node-app\");\n\n const span = tracer.startSpan(\"POST /orders/fulfill\", {\n kind: SpanKind.SERVER,\n attributes: {\n \"http.request.method\": \"POST\",\n \"http.route\": \"/orders/fulfill\",\n \"url.path\": \"/orders/fulfill\",\n },\n });\n try {\n const result = fulfillOrder({ orderId: \"ord_1042\", units: 3 });\n span.setAttribute(\"http.response.status_code\", 200);\n span.setStatus({ code: SpanStatusCode.OK });\n console.log(\"order fulfilled:\", result);\n } catch (err) {\n span.setAttribute(\"http.response.status_code\", 500);\n span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });\n if (mode === \"span\") {\n const exceptionSpan = tracer.startSpan(\"exception\", {\n attributes: {\n \"exception.type\": err.name,\n \"exception.message\": err.message,\n \"exception.stacktrace\": err.stack,\n },\n });\n exceptionSpan.end();\n } else {\n span.recordException(err);\n }\n console.error(`reported ${err.name} via mode=${mode}: ${err.message}`);\n }\n span.end();\n\n await provider.shutdown();\n console.log(`flushed to ${url}`);\n}\n\nmain().catch((err) => {\n console.error(\"fatal:\", err);\n process.exit(1);\n});\n"],"names":["stockLevels","Map","fulfillOrder","order","reservation","orderId","units","available","get","RangeError","set","reserveStock","token","process","env","TW_TOKEN","url","TW_OTLP_URL","mode","argv","async","provider","NodeTracerProvider","resource","defaultResource","merge","resourceFromAttributes","spanProcessors","BatchSpanProcessor","OTLPTraceExporter","headers","Authorization","register","tracer","trace","getTracer","span","startSpan","kind","SpanKind","SERVER","attributes","result","setAttribute","setStatus","code","SpanStatusCode","OK","console","log","err","ERROR","message","name","stack","end","recordException","error","shutdown","main","catch","exit"],"mappings":"2UAAA,MAAMA,EAAc,IAAIC,IAAI,CAAC,CAAC,WAAY,KCEnC,SAASC,EAAaC,GAC3B,MAAMC,EDDD,SAAsBC,EAASC,GACpC,MAAMC,EAAYP,EAAYQ,IAAIH,IAAY,EAC9C,GAAIC,EAAQC,EACV,MAAM,IAAIE,WACR,kBAAkBH,qBAAyBD,WAAiBE,cAIhE,OADAP,EAAYU,IAAIL,EAASE,EAAYD,GAC9B,CAAED,UAASC,QACpB,CCRsBK,CAAaR,EAAME,QAASF,EAAMG,OACtD,MAAO,CAAED,QAASF,EAAME,QAASD,cACnC,CCOA,MAAMQ,EAAQC,QAAQC,IAAIC,UAAY,mCAChCC,EACJH,QAAQC,IAAIG,aAAe,2CACvBC,EAAOL,QAAQM,KAAK,IAAM,SAEhCC,iBACE,MAAMC,EAAW,IAAIC,EAAmB,CACtCC,SAAUC,IAAkBC,MAC1BC,EAAuB,CAAE,eAAgB,4BAE3CC,eAAgB,CACd,IAAIC,EACF,IAAIC,EAAkB,CACpBb,MACAc,QAAS,CAAEC,cAAe,UAAUnB,WAK5CS,EAASW,WAET,MAAMC,EAASC,EAAMC,UAAU,0BAEzBC,EAAOH,EAAOI,UAAU,uBAAwB,CACpDC,KAAMC,EAASC,OACfC,WAAY,CACV,sBAAuB,OACvB,aAAc,kBACd,WAAY,qBAGhB,IACE,MAAMC,EAASxC,EAAa,CAAEG,QAAS,WAAYC,MAAO,IAC1D8B,EAAKO,aAAa,4BAA6B,KAC/CP,EAAKQ,UAAU,CAAEC,KAAMC,EAAeC,KACtCC,QAAQC,IAAI,mBAAoBP,EAClC,CAAE,MAAOQ,GAGP,GAFAd,EAAKO,aAAa,4BAA6B,KAC/CP,EAAKQ,UAAU,CAAEC,KAAMC,EAAeK,MAAOC,QAASF,EAAIE,UAC7C,SAATlC,EAAiB,CACGe,EAAOI,UAAU,YAAa,CAClDI,WAAY,CACV,iBAAkBS,EAAIG,KACtB,oBAAqBH,EAAIE,QACzB,uBAAwBF,EAAII,SAGlBC,KAChB,MACEnB,EAAKoB,gBAAgBN,GAEvBF,QAAQS,MAAM,YAAYP,EAAIG,iBAAiBnC,MAASgC,EAAIE,UAC9D,CACAhB,EAAKmB,YAEClC,EAASqC,WACfV,QAAQC,IAAI,cAAcjC,IAC5B,EAEA2C,GAAOC,MAAOV,IACZF,QAAQS,MAAM,SAAUP,GACxBrC,QAAQgD,KAAK"}
\ No newline at end of file
diff --git a/website/app/globals.css b/website/app/globals.css
index c4be141c..53d05cf9 100644
--- a/website/app/globals.css
+++ b/website/app/globals.css
@@ -19,7 +19,7 @@
--ink-4: #1d2430;
--ink-5: #283041;
--hair: rgba(255, 255, 255, 0.06);
- --hair-2: rgba(255, 255, 255, 0.10);
+ --hair-2: rgba(255, 255, 255, 0.1);
/* Text */
--fg-0: #f4f6fb;
@@ -290,7 +290,7 @@
--ink-1: #0a0d14;
--ink-3: #151a24;
--hair: rgba(255, 255, 255, 0.06);
- --hair-2: rgba(255, 255, 255, 0.10);
+ --hair-2: rgba(255, 255, 255, 0.1);
--fg-0: #f4f6fb;
--fg-1: #c9d0dd;
--fg-2: #8a93a6;
@@ -306,9 +306,12 @@
/* Terminal stays a dark object inside the light band. */
.band-light .term {
--ink-1: #0a0d14;
+ --ink-2: #0f131c;
--hair: rgba(255, 255, 255, 0.06);
- --hair-2: rgba(255, 255, 255, 0.10);
+ --hair-2: rgba(255, 255, 255, 0.1);
+ --fg-0: #f4f6fb;
--fg-1: #c9d0dd;
+ --fg-2: #8a93a6;
--fg-3: #5a6374;
--a2: #00d4ff;
--ok: #22e0a8;
@@ -351,7 +354,10 @@
font-weight: 500;
font-size: 14px;
letter-spacing: -0.01em;
- transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+ transition:
+ background 0.15s ease,
+ border-color 0.15s ease,
+ color 0.15s ease;
border: 1px solid transparent;
white-space: nowrap;
cursor: pointer;
@@ -360,7 +366,9 @@
.btn-primary {
background: var(--fg-0);
color: var(--ink-0);
- box-shadow: 0 1px 0 rgba(255, 255, 255, 0.6) inset, 0 0 0 1px rgba(255, 255, 255, 0.12);
+ box-shadow:
+ 0 1px 0 rgba(255, 255, 255, 0.6) inset,
+ 0 0 0 1px rgba(255, 255, 255, 0.12);
}
.btn-primary:hover {
background: color-mix(in oklab, var(--fg-0) 92%, white);
@@ -394,7 +402,9 @@
border-radius: var(--radius-lg);
padding: 20px 22px;
text-decoration: none;
- transition: background 0.15s ease, border-color 0.15s ease;
+ transition:
+ background 0.15s ease,
+ border-color 0.15s ease;
}
.blog-card:hover {
background: var(--ink-3);
@@ -419,7 +429,10 @@
color: var(--fg-3);
text-decoration: none;
border: 1px solid transparent;
- transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+ transition:
+ background 0.15s ease,
+ border-color 0.15s ease,
+ color 0.15s ease;
}
.blog-tab:hover {
color: var(--fg-1);
@@ -576,11 +589,40 @@
color: var(--fg-3);
letter-spacing: 0.08em;
}
+ .term-tabs {
+ display: grid;
+ grid-auto-flow: column;
+ grid-auto-columns: 1fr;
+ }
+ .term-tabs .term-tab {
+ font-family: var(--font-mono);
+ font-size: 11px;
+ letter-spacing: 0.04em;
+ padding: 8px 12px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ color: var(--fg-2);
+ background: rgba(8, 11, 18, 0.8);
+ border-bottom: 1px solid var(--hair);
+ }
+ .term-tabs .term-tab + .term-tab {
+ border-left: 1px solid var(--hair);
+ }
+ .term-tabs .term-tab:not([aria-selected="true"]):hover {
+ color: var(--fg-1);
+ }
+ .term-tabs .term-tab[aria-selected="true"] {
+ color: var(--fg-0);
+ background: transparent;
+ border-bottom-color: transparent;
+ }
.term-body {
padding: 22px;
font-family: var(--font-mono);
font-size: 13px;
line-height: 1.75;
+ padding-top: 12px;
}
.term-line {
display: grid;
diff --git a/website/app/page.tsx b/website/app/page.tsx
index fbcec123..7a70c9ab 100644
--- a/website/app/page.tsx
+++ b/website/app/page.tsx
@@ -15,6 +15,8 @@ import { Eyebrow } from "@/components/eyebrow";
import { DiscordIcon } from "@/components/discord-icon";
import { FinalCTA } from "@/components/final-cta";
import { Terminal } from "@/components/terminal";
+import { SkillInstallCommand } from "@/components/skill-install-command";
+import { AgentDebugTerminal } from "@/components/agent-debug-terminal";
import { StatsStrip } from "@/components/stats-strip";
import { HeroEmailCTA } from "@/components/hero-email-cta";
import { getCalendlyUrl } from "@/lib/calendly";
@@ -130,8 +132,36 @@ export default function Home() {
</div>
</section>
- {/* WHITE BAND: community, deploy, detect/resolve, cost render on white */}
+ {/* WHITE BAND: AI-first, community, deploy, detect/resolve, cost render on white */}
<div className="band-light">
+ {/* AI-FIRST: install the agent skills, agent session terminal */}
+ <section className="pt-20">
+ <div className="wrap grid gap-14 md:grid-cols-[10fr_11fr] items-center">
+ <div>
+ <Eyebrow>AI-first</Eyebrow>
+ <h2 className="mt-4">
+ Your agents can fix production.{" "}
+ <em>Hand them the telemetry.</em>
+ </h2>
+ <p className="muted mt-4 max-w-[460px] text-pretty">
+ One command installs the skills into Claude Code, Cursor, or
+ any agent that reads SKILL.md. From there your agent queries
+ exceptions, logs, and metrics itself.
+ </p>
+ <div className="mt-7">
+ <SkillInstallCommand className="w-full max-w-[460px]" />
+ </div>
+ <div className="mt-6 flex flex-wrap gap-3">
+ <Link href="/product/agent-skills" className="btn btn-ghost">
+ Explore Agent Skills
+ <ArrowRight className="h-4 w-4" />
+ </Link>
+ </div>
+ </div>
+ <AgentDebugTerminal />
+ </div>
+ </section>
+
{/* COMMUNITY: built in the open */}
<section className="py-20">
<div className="wrap grid gap-14 md:grid-cols-[11fr_9fr] items-center">
diff --git a/website/app/product/agent-skills/page.tsx b/website/app/product/agent-skills/page.tsx
new file mode 100644
index 00000000..1083cbfa
--- /dev/null
+++ b/website/app/product/agent-skills/page.tsx
@@ -0,0 +1,339 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { Bot } from "lucide-react";
+
+import { Chip } from "@/components/chip";
+import { SectionHead } from "@/components/section-head";
+import { FeatureRow } from "@/components/feature-row";
+import { FaqList } from "@/components/faq-list";
+import { FinalCTA } from "@/components/final-cta";
+import { AuroraBackground } from "@/components/aurora-background";
+import { Eyebrow } from "@/components/eyebrow";
+import { Terminal } from "@/components/terminal";
+import { SkillInstallCommand } from "@/components/skill-install-command";
+import { AgentDebugTerminal } from "@/components/agent-debug-terminal";
+import { GITHUB_URL } from "@/lib/links";
+
+export const metadata: Metadata = {
+ title: "Agent Skills · Traceway",
+ description:
+ "Install the Traceway agent skills and your coding agent can instrument your app, query production telemetry through the agent-first traceway CLI, and debug issues end to end.",
+};
+
+const SKILLS = [
+ {
+ label: "01 · Setup",
+ name: "/traceway-setup",
+ description:
+ "Reads your repo and wires it up: OpenTelemetry for the backend, Traceway SDKs for web and mobile. Verifies data arrives clean and grouped.",
+ tags: ["OTel backends", "Web + mobile SDKs", "Source maps", "Verification"],
+ },
+ {
+ label: "02 · Debug",
+ name: "/traceway",
+ description:
+ "Installs the traceway CLI, then uses it: exceptions, logs, endpoints, and metrics, from bug report to root cause.",
+ tags: ["CLI install", "Telemetry queries", "Debugging", "Issue triage"],
+ },
+];
+
+const AGENTS = [
+ "Claude Code",
+ "Cursor",
+ "Codex",
+ "OpenCode",
+ "Gemini CLI",
+ "Copilot",
+];
+
+export default function AgentSkillsPage() {
+ return (
+ <main className="relative">
+ <section className="hero hero-product relative">
+ <AuroraBackground variant="hero" />
+ <div className="wrap relative z-10">
+ <div className="flex flex-col items-center text-center">
+ <Chip>
+ <Bot className="h-3 w-3 inline mr-1" />
+ Agent Skills
+ </Chip>
+ <h1 className="mt-6 max-w-[30ch]">
+ AI-first observability. <em>Your agent does the debugging.</em>
+ </h1>
+ <p className="hero-sub text-pretty">
+ Your agent sets up Traceway, queries production telemetry, and
+ finds the root cause.
+ </p>
+ <div className="mt-8 w-full max-w-[640px]">
+ <SkillInstallCommand size="lg" className="w-full" />
+ </div>
+ <p className="dim mt-5 font-mono text-[0.75rem]">
+ Works with Claude Code, Cursor, Codex, and any agent that reads
+ SKILL.md.
+ </p>
+ <p className="mt-3 font-mono text-[0.6875rem] uppercase tracking-[0.08em]">
+ <Link
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-fg-2 hover:text-a2 transition-colors"
+ >
+ View on GitHub →
+ </Link>
+ </p>
+ </div>
+ </div>
+ </section>
+
+ <div className="band-light">
+ <section className="wrap">
+ <div className="feature-row">
+ <div className="feat-copy">
+ <Eyebrow>Debug</Eyebrow>
+ <h2>
+ From bug report <em>to root cause</em>
+ </h2>
+ <p>
+ Paste the bug report as written. The agent pulls the matching
+ exceptions, the logs around the failure, and endpoint stats,
+ then opens the failing code.
+ </p>
+ <ul className="feat-bullets">
+ <li>Grouped exceptions with full stack traces</li>
+ <li>Logs correlated by trace id</li>
+ <li>First-seen times point at the breaking deploy</li>
+ <li>Ends with a proposed fix in your code</li>
+ </ul>
+ </div>
+ <AgentDebugTerminal />
+ </div>
+ </section>
+
+ <section className="wrap">
+ <div className="feature-row reverse">
+ <div className="feat-copy">
+ <Eyebrow>The CLI</Eyebrow>
+ <h2>
+ A command line <em>designed for agents first</em>
+ </h2>
+ <p>
+ Built for non-interactive use: JSON output, stable errors, and
+ nothing that hangs waiting for input. Humans on a TTY still
+ get tables.
+ </p>
+ <ul className="feat-bullets">
+ <li>JSON when piped, tables on a TTY</li>
+ <li>--fields trims responses to what was asked</li>
+ <li>Stable error identifiers and exit codes</li>
+ <li>Mutations require --yes, nothing hangs</li>
+ </ul>
+ </div>
+ <Terminal
+ title="bash · traceway-cli"
+ lines={[
+ {
+ ln: "1",
+ type: "tx",
+ content: (
+ <>
+ <span className="cmd">$</span> traceway exceptions list
+ --since 24h | head -1
+ </>
+ ),
+ },
+ {
+ ln: "2",
+ type: "mute",
+ content:
+ '{"hash":"82b58892","type":"TypeError","count":412}',
+ },
+ {
+ ln: "3",
+ type: "tx",
+ content: (
+ <>
+ <span className="cmd">$</span> traceway exceptions show
+ 82b58892 --fields type,stacktrace
+ </>
+ ),
+ },
+ {
+ ln: "4",
+ type: "mute",
+ content:
+ '{"type":"TypeError","stacktrace":"src/checkout/session.ts:42 …"}',
+ },
+ {
+ ln: "5",
+ type: "tx",
+ content: (
+ <>
+ <span className="cmd">$</span> traceway exceptions
+ archive 82b58892
+ </>
+ ),
+ },
+ {
+ ln: "6",
+ type: "mute",
+ content:
+ '{"error":"confirmation_required","hint":"re-run with --yes","exit_code":2}',
+ },
+ {
+ ln: "7",
+ type: "ok",
+ content: "# ✓ predictable for agents, readable for humans",
+ },
+ ]}
+ />
+ </div>
+ </section>
+
+ <section className="wrap">
+ <FeatureRow
+ eyebrow="Setup"
+ title={
+ <>
+ Set up by the agent, <em>not by the docs</em>
+ </>
+ }
+ description="/traceway-setup picks the right path for each part of the stack: OTel for backends, Traceway SDKs for browser and mobile. Then it verifies data is actually arriving."
+ bullets={[
+ "Detects frameworks and services from the repo",
+ "OTel for backends, SDKs for web and mobile",
+ "Covers background tasks, AI traces, and source maps",
+ "Verifies grouped endpoints in the dashboard",
+ ]}
+ image={{
+ src: "/images/performance-percentiles-overview.png",
+ alt: "Traceway endpoints grouped by route pattern with percentiles",
+ }}
+ />
+ </section>
+
+ <section className="wrap py-8">
+ <Eyebrow>The skills</Eyebrow>
+ <h2 className="mt-4 max-w-[24ch]">
+ Two skills, <em>one install.</em>
+ </h2>
+ <p className="muted mt-4 max-w-[640px] text-pretty">
+ Plain Markdown playbooks your agent loads on demand. One sets up
+ your project, the other queries and debugs it.
+ </p>
+
+ <dl className="mt-14 grid gap-12 md:grid-cols-2">
+ {SKILLS.map((skill) => (
+ <div key={skill.name} className="border-t border-hair pt-8">
+ <dt>
+ <p className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">
+ {skill.label}
+ </p>
+ <p className="mt-3 font-mono text-xl font-semibold text-fg-0 md:text-[1.375rem]">
+ {skill.name}
+ </p>
+ </dt>
+ <dd className="m-0">
+ <p className="muted mt-3 max-w-[440px] text-pretty">
+ {skill.description}
+ </p>
+ <div className="mt-5 flex flex-wrap gap-2">
+ {skill.tags.map((tag) => (
+ <span key={tag} className="tag">
+ {tag}
+ </span>
+ ))}
+ </div>
+ </dd>
+ </div>
+ ))}
+ </dl>
+ </section>
+
+ <section className="wrap py-16 text-center">
+ <div className="max-w-3xl mx-auto flex flex-col items-center gap-5">
+ <Eyebrow>Compatibility</Eyebrow>
+ <h2>One format, every agent</h2>
+ <p style={{ color: "var(--fg-1)", fontSize: 17 }}>
+ Skills are plain Markdown in the open SKILL.md format. No
+ marketplace, no lock-in. They live in the same MIT-licensed
+ repo as Traceway itself.
+ </p>
+ <div className="flex flex-wrap items-center justify-center gap-2.5 pt-2">
+ {AGENTS.map((agent) => (
+ <span key={agent} className="tag">
+ {agent}
+ </span>
+ ))}
+ </div>
+ </div>
+ </section>
+ </div>
+
+ <FinalCTA
+ title={
+ <>
+ Give your agent <em>production context.</em>
+ </>
+ }
+ description="Install the skills and let your agent take the next bug."
+ primary={{
+ label: "Star on GitHub",
+ href: GITHUB_URL,
+ external: true,
+ }}
+ secondary={{
+ label: "Start for free",
+ href: "https://cloud.tracewayapp.com/register",
+ }}
+ />
+
+ <section className="wrap pt-10 pb-24">
+ <div className="max-w-3xl mx-auto">
+ <SectionHead
+ align="center"
+ eyebrow="FAQ"
+ title="Questions about agent skills"
+ />
+ <div className="mt-4">
+ <FaqList
+ items={[
+ {
+ q: "What exactly is an agent skill?",
+ a: "A SKILL.md file: Markdown instructions your agent loads when a task matches. Traceway ships two, one that sets up a project and one that queries and debugs it. Both live in the open-source repo.",
+ },
+ {
+ q: "Which agents are supported?",
+ a: (
+ <>
+ <p>
+ Anything that reads SKILL.md: Claude Code, Cursor,
+ Codex, OpenCode, Gemini CLI, Copilot, and more.
+ </p>
+ <p>
+ <code>npx skills add tracewayapp/traceway</code>{" "}
+ installs the skills for every agent it finds on your
+ machine.
+ </p>
+ </>
+ ),
+ },
+ {
+ q: "Can an agent damage my production data?",
+ a: "No. The CLI is read-only apart from archiving exception groups, and that requires an explicit --yes flag.",
+ },
+ {
+ q: "Does this work with self-hosted Traceway?",
+ a: "Yes. traceway login --url works against any instance, and profiles let one machine use several.",
+ },
+ {
+ q: "Do I need the CLI installed first?",
+ a: "No. The /traceway skill installs and authenticates it before running its first query.",
+ },
+ ]}
+ />
+ </div>
+ </div>
+ </section>
+ </main>
+ );
+}
diff --git a/website/app/product/javascript-symbolication/page.tsx b/website/app/product/javascript-symbolication/page.tsx
new file mode 100644
index 00000000..7cdbe98d
--- /dev/null
+++ b/website/app/product/javascript-symbolication/page.tsx
@@ -0,0 +1,337 @@
+import Link from "next/link";
+import Image from "next/image";
+import type { Metadata } from "next";
+import { ArrowRight, Github, BookOpen, Workflow } from "lucide-react";
+
+import { Eyebrow } from "@/components/eyebrow";
+import { SectionHead } from "@/components/section-head";
+import { StatsStrip } from "@/components/stats-strip";
+import { FeatureRow } from "@/components/feature-row";
+import { FaqList } from "@/components/faq-list";
+import { FinalCTA } from "@/components/final-cta";
+import { AuroraBackground } from "@/components/aurora-background";
+import { OtelPipelineTabs } from "@/components/otel-pipeline-tabs";
+import { SymbolicationBeforeAfter } from "@/components/symbolication-before-after";
+import { GITHUB_URL } from "@/lib/links";
+
+export const metadata: Metadata = {
+ title: "JavaScript Stack Trace Symbolication · Traceway",
+ description:
+ "Open-source, OpenTelemetry-compatible source map symbolication. Resolve minified production errors back to the original file, line, and function at ingest. Pure Go, built to be fast.",
+};
+
+const BUNDLERS = [
+ "Vite",
+ "webpack",
+ "esbuild",
+ "Rollup",
+ "Metro",
+ "Next.js",
+ "SvelteKit",
+ "Cloudflare Workers",
+];
+
+export default function JavaScriptSymbolicationPage() {
+ return (
+ <main className="relative">
+ <section className="hero hero-product relative">
+ <AuroraBackground variant="hero" />
+ <div className="wrap relative z-10">
+ <div className="flex flex-col items-center text-center">
+ <div
+ className="grid place-items-center rounded-2xl"
+ style={{
+ width: 76,
+ height: 76,
+ background: "#ffffff",
+ border: "1px solid rgba(10, 14, 24, 0.08)",
+ boxShadow: "0 12px 28px -16px rgba(0, 0, 0, 0.6)",
+ }}
+ >
+ <Image
+ src="/images/frameworks/otel.png"
+ alt="OpenTelemetry"
+ width={42}
+ height={42}
+ />
+ </div>
+ <h1 className="mt-6">
+ <span style={{ fontFamily: "var(--font-mono)" }}>
+ app.min.js:1:63
+ </span>
+ <br />
+ <em>tells you nothing.</em>
+ </h1>
+ <p className="hero-sub text-pretty mx-auto">
+ Minified bundles reduce every production error to single letters
+ on line one. Traceway resolves each frame back to the file, line,
+ and function you wrote, the moment the error arrives.
+ </p>
+ <div className="hero-cta-row justify-center">
+ <Link
+ href="https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload"
+ className="btn btn-accent"
+ >
+ Upload your source maps <ArrowRight className="h-4 w-4" />
+ </Link>
+ <Link href={GITHUB_URL} className="btn btn-ghost" target="_blank" rel="noopener noreferrer">
+ <Github className="h-4 w-4" />
+ View on GitHub
+ </Link>
+ </div>
+ <p className="dim mt-5 font-mono text-[0.75rem]">
+ Open source · Pure Go · OpenTelemetry compatible
+ </p>
+ </div>
+ </div>
+ </section>
+
+ <div className="band-light">
+ <SymbolicationBeforeAfter />
+
+ <section className="wrap py-20">
+ <SectionHead
+ eyebrow="Performance"
+ title={
+ <>
+ Symbolication that <em>keeps up with ingest.</em>
+ </>
+ }
+ description="Most symbolicators re-parse source maps on every restart and hold them in RAM until the process dies. Ours compiles each map once, then memory-maps it from disk. Numbers below come from the benchmark workflows in the repo."
+ />
+ <StatsStrip
+ stats={[
+ { num: "<em>&lt;1</em>µs", label: "To open a compiled source map" },
+ { num: "<em>&lt;1</em>ms", label: "p99 lookup with a cold cache" },
+ { num: "<em>3</em>×", label: "Faster bundle parsing than SWC" },
+ { num: "<em>0</em>", label: "Maps re-parsed after a restart" },
+ ]}
+ />
+ <div className="mt-14 grid gap-12 md:grid-cols-2">
+ <div className="border-t border-hair pt-8">
+ <p className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">
+ Why it stays fast
+ </p>
+ <ul className="mt-4 space-y-3 text-[14px]" style={{ color: "var(--fg-2)" }}>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Parse once, compile to .tw.</strong>{" "}
+ Each map and bundle compiles into a binary format on first
+ use. Every lookup after that opens the file in under a
+ microsecond and binary-searches it.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Disk is the budget, not RAM.</strong>{" "}
+ Compiled maps are memory-mapped, so resident memory tracks
+ the hot set. A corpus of thousands of bundles costs disk
+ space, not heap.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Cold lookups don&rsquo;t hurt.</strong>{" "}
+ An in-RAM LRU churns the garbage collector every time an old
+ release throws. The mmap cache holds p99 under a millisecond
+ on the long tail.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Restarts warm from disk.</strong>{" "}
+ Nothing is re-parsed when the process comes back. The cache
+ is already there.
+ </li>
+ </ul>
+ </div>
+ <div className="border-t border-hair pt-8">
+ <p className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">
+ The fine print
+ </p>
+ <ul className="mt-4 space-y-3 text-[14px]" style={{ color: "var(--fg-3)" }}>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Two parser engines.</strong>{" "}
+ The default build is pure Go and parses bundles with{" "}
+ <code>dop251/goja</code>. A build flag swaps in{" "}
+ <code>oxc</code>, which{" "}
+ <Link
+ href="https://oxc.rs/docs/guide/usage/parser.html"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="underline decoration-dotted underline-offset-4 hover:text-[color:var(--a2)]"
+ >
+ parses 3x faster than SWC
+ </Link>
+ .
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Two cache modes.</strong>{" "}
+ Hold parsed maps in memory, or compile them to{" "}
+ <code>.tw</code> files and memory-map them from disk.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Not memory bound.</strong>{" "}
+ With oxc and the disk cache, the corpus is a disk budget: the
+ cache holds as many maps as the disk fits. Competing
+ symbolicators cache parsed maps in RAM, so their corpus caps
+ out at what the heap can hold.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>Benchmarked in the open.</strong>{" "}
+ Parser numbers come from <code>go test -bench</code> over
+ webpack, Metro, and Preact fixtures plus 1&nbsp;MB and
+ 5&nbsp;MB synthetic bundles. Cache numbers come from a sweep
+ of 1,000 to 12,000 bundles on a 2&nbsp;vCPU box. Both
+ workflows are in the repo; run them on your fork.
+ </li>
+ <li>
+ <strong style={{ color: "var(--fg-1)" }}>MIT licensed, actually open source.</strong>{" "}
+ The parsers, the cache, the collector processor, and the
+ whole backend live in one public repo. No open core, no
+ enterprise tier where symbolication really lives.
+ </li>
+ </ul>
+ </div>
+ </div>
+ </section>
+
+ <section className="wrap">
+ <div className="feature-row">
+ <div className="feat-copy">
+ <Eyebrow>OpenTelemetry</Eyebrow>
+ <h2>
+ Bring your own <em>pipeline.</em>
+ </h2>
+ <p>
+ The same engine ships as an OpenTelemetry Collector processor.
+ It&rsquo;s a drop-in replacement for Honeycomb&rsquo;s{" "}
+ <code>source_map_symbolicator</code>: same component type, same
+ attribute contract, same config keys. Existing pipelines and
+ web instrumentation work unchanged.
+ </p>
+ <ul className="feat-bullets">
+ <li>Symbolicates spans, span events, and log records</li>
+ <li>Cache bounded by disk size, not an entry count in RAM</li>
+ <li>Pure Go, so no glibc base image required</li>
+ <li>Works in any collector build, with or without Traceway behind it</li>
+ </ul>
+ </div>
+ <OtelPipelineTabs />
+ </div>
+ </section>
+
+ <section className="wrap pb-10">
+ <div
+ className="rounded-2xl px-6 py-8 md:px-10 md:py-10"
+ style={{ background: "var(--ink-1)", border: "1px solid var(--hair)" }}
+ >
+ <div className="grid gap-8 md:grid-cols-[1.2fr_1fr] items-center">
+ <div>
+ <Eyebrow>Built in the open</Eyebrow>
+ <h3 className="mt-3 text-[22px] leading-tight">
+ Read the parser. Run the benchmarks. Self-host all of it.
+ </h3>
+ <p className="mt-3 text-[14px] max-w-[520px]" style={{ color: "var(--fg-2)" }}>
+ The symbolicator, the benchmark harnesses, and the rest of
+ Traceway live in one MIT-licensed repo. Nothing about how
+ your stack traces get resolved is a black box.
+ </p>
+ <div className="mt-5 flex flex-wrap gap-2">
+ {BUNDLERS.map((b) => (
+ <span key={b} className="tag">
+ {b}
+ </span>
+ ))}
+ </div>
+ </div>
+ <div className="flex flex-wrap gap-x-6 gap-y-3 text-[13px]">
+ <Link
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"
+ style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}
+ >
+ <Github className="h-3.5 w-3.5" />
+ traceway →
+ </Link>
+ <Link
+ href="https://github.com/tracewayapp/traceway/tree/main/backend/app/symbolicator/otelprocessor"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"
+ style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}
+ >
+ <Workflow className="h-3.5 w-3.5" />
+ OTel processor →
+ </Link>
+ <Link
+ href="https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1.5 hover:text-[color:var(--a2)]"
+ style={{ color: "var(--fg-1)", fontFamily: "var(--font-mono)" }}
+ >
+ <BookOpen className="h-3.5 w-3.5" />
+ Documentation →
+ </Link>
+ </div>
+ </div>
+ </div>
+ </section>
+ </div>
+
+ <FinalCTA
+ title={
+ <>
+ Stop debugging <em>app.min.js.</em>
+ </>
+ }
+ description="Upload your source maps once. Every production error after that points at the code you wrote."
+ primary={{
+ label: "Get Started",
+ href: "https://docs.tracewayapp.com/client/js-sdk/sourcemap-upload",
+ }}
+ secondary={{
+ label: "Star on GitHub",
+ href: GITHUB_URL,
+ external: true,
+ }}
+ />
+
+ <section className="wrap pt-10 pb-24">
+ <div className="max-w-3xl mx-auto">
+ <SectionHead
+ align="center"
+ eyebrow="FAQ"
+ title="Questions about symbolication"
+ />
+ <div className="mt-4">
+ <FaqList
+ items={[
+ {
+ q: "What is stack trace symbolication?",
+ a: "Production JavaScript ships minified, so browsers report errors as positions in the bundle, like app.min.js:1:63 inside a function called n. Symbolication uses the source maps from your build to translate those frames back to the original file, line, column, and function name.",
+ },
+ {
+ q: "How do source maps get into Traceway?",
+ a: "Run npx traceway-sourcemaps --directory ./dist after your build, in CI or locally. It uploads every .map file and its sibling bundle. Under the hood it's a single multipart HTTP endpoint, so plain curl works from any pipeline. Uploads authenticate with a per-project token you can revoke.",
+ },
+ {
+ q: "Does it work with OpenTelemetry?",
+ a: "Yes, twice over. Errors arriving at Traceway over OTLP are symbolicated at ingest. And the engine ships as a standalone OpenTelemetry Collector processor that is drop-in compatible with Honeycomb's source_map_symbolicator, so you can symbolicate inside your own pipeline, with or without Traceway behind it.",
+ },
+ {
+ q: "Which bundlers and frameworks are supported?",
+ a: "Anything that emits standard source maps: Vite, webpack, esbuild, Rollup, Metro, and the frameworks built on them. Inline sourceMappingURL data URIs are supported, and maps with missing source file names still resolve line, column, and function name.",
+ },
+ {
+ q: "Are my source maps exposed publicly?",
+ a: "No. Maps are uploaded to your Traceway instance's blob storage and used server-side only. They are never served to browsers, so you can keep .map files out of your deployed assets entirely.",
+ },
+ {
+ q: "What happens to errors from a build without maps?",
+ a: "They stay minified but still group correctly. Column numbers keep frames distinct on line one, and resolved function names are excluded from the grouping hash, so existing groups don't reshuffle when you upload maps later.",
+ },
+ ]}
+ />
+ </div>
+ </div>
+ </section>
+ </main>
+ );
+}
diff --git a/website/components/agent-debug-terminal.tsx b/website/components/agent-debug-terminal.tsx
new file mode 100644
index 00000000..34b100cf
--- /dev/null
+++ b/website/components/agent-debug-terminal.tsx
@@ -0,0 +1,97 @@
+import Image from "next/image";
+import { cn } from "@/lib/utils";
+
+export function AgentDebugTerminal({ className }: { className?: string }) {
+ return (
+ <div className={cn("term", className)}>
+ <div className="term-body">
+ <div className="flex items-center gap-5">
+ <Image
+ src="/images/claudebot.png"
+ alt="Claude"
+ width={152}
+ height={97}
+ className="h-11 w-auto"
+ style={{ imageRendering: "pixelated" }}
+ />
+ <div>
+ <div>
+ <span className="font-semibold text-fg-0">Claude Code</span>{" "}
+ <span className="text-fg-3">v2.1.173</span>
+ </div>
+ <div className="text-fg-3">Fable 5 · Claude Max</div>
+ <div className="text-fg-3">~/shop-api</div>
+ </div>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-fg-3">❯</span>
+ <span className="whitespace-pre-wrap text-fg-0">
+ /traceway users report 500s on checkout since this morning
+ </span>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-ok">⏺</span>
+ <span className="whitespace-pre-wrap">
+ <span className="text-fg-0">Bash</span>
+ <span className="text-fg-2">
+ (traceway exceptions list --since 24h --search checkout)
+ </span>
+ </span>
+ </div>
+ <div className="grid grid-cols-[14px_1fr] gap-x-2">
+ <span />
+ <span className="whitespace-pre-wrap text-fg-3">
+ {"⎿ TypeError: cart is null · 412 events · first seen 09:14"}
+ </span>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-ok">⏺</span>
+ <span className="whitespace-pre-wrap">
+ <span className="text-fg-0">Bash</span>
+ <span className="text-fg-2">
+ (traceway logs query --trace-id 9f2c41d8)
+ </span>
+ </span>
+ </div>
+ <div className="grid grid-cols-[14px_1fr] gap-x-2">
+ <span />
+ <span className="whitespace-pre-wrap text-fg-3">
+ {"⎿ 12 log records · cart expired 09:13, reused 09:14"}
+ </span>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-ok">⏺</span>
+ <span className="whitespace-pre-wrap">
+ <span className="text-fg-0">Read</span>
+ <span className="text-fg-2">(src/checkout/session.ts)</span>
+ </span>
+ </div>
+ <div className="grid grid-cols-[14px_1fr] gap-x-2">
+ <span />
+ <span className="whitespace-pre-wrap text-fg-3">
+ {"⎿ Read 86 lines"}
+ </span>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-fg-0">⏺</span>
+ <span className="whitespace-pre-wrap text-fg-1">
+ Root cause: repeat purchase reuses an expired cart. Fix ready for
+ review in src/checkout/session.ts:42.
+ </span>
+ </div>
+
+ <div className="mt-1 grid grid-cols-[14px_1fr] gap-x-2">
+ <span className="text-fg-3">❯</span>
+ <span>
+ <span className="cursor bg-(--fg-2)" aria-hidden />
+ </span>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/website/components/otel-pipeline-tabs.tsx b/website/components/otel-pipeline-tabs.tsx
new file mode 100644
index 00000000..ca1e6984
--- /dev/null
+++ b/website/components/otel-pipeline-tabs.tsx
@@ -0,0 +1,103 @@
+"use client";
+
+import { useState } from "react";
+
+const TABS = [
+ {
+ filename: "builder-config.yaml",
+ code: (
+ <>
+ <span style={{ color: "var(--fg-3)" }}>
+ # compile the processor into your collector (ocb manifest)
+ </span>
+ {"\n"}
+ <span style={{ color: "var(--fg-1)" }}>processors:</span>
+ {"\n"}
+ {" - "}
+ <span style={{ color: "var(--a2)" }}>gomod:</span>{" "}
+ <span style={{ color: "var(--ok)" }}>
+ github.com/tracewayapp/traceway/backend v1.8.0
+ </span>
+ {"\n"}
+ {" "}
+ <span style={{ color: "var(--a2)" }}>import:</span>{" "}
+ <span style={{ color: "var(--ok)" }}>
+ github.com/tracewayapp/traceway/backend/app/symbolicator/otelprocessor
+ </span>
+ {"\n\n"}
+ <span style={{ color: "var(--a2)" }}>$</span>{" "}
+ <span style={{ color: "var(--fg-1)" }}>
+ ocb --config builder-config.yaml
+ </span>
+ </>
+ ),
+ },
+ {
+ filename: "otel-collector.yaml",
+ code: (
+ <>
+ <span style={{ color: "var(--fg-3)" }}>
+ # then reference it in the collector config
+ </span>
+ {"\n"}
+ <span style={{ color: "var(--fg-1)" }}>processors:</span>
+ {"\n"}
+ {" "}
+ <span style={{ color: "var(--a2)" }}>source_map_symbolicator:</span>
+ {"\n"}
+ <span style={{ color: "var(--fg-3)" }}>
+ {" source_map_store: file_store\n"}
+ {" local_source_maps:\n"}
+ {" path: /sourcemaps\n"}
+ {" cache_dir: /var/cache/symbolicator\n"}
+ {" cache_max_disk_pct: 50"}
+ </span>
+ {"\n\n"}
+ <span style={{ color: "var(--fg-1)" }}>
+ {"service:\n"}
+ {" pipelines:\n"}
+ {" traces:"}
+ </span>
+ {"\n"}
+ <span style={{ color: "var(--ok)" }}>
+ {" processors: [source_map_symbolicator]"}
+ </span>
+ </>
+ ),
+ },
+];
+
+export function OtelPipelineTabs() {
+ const [activeTab, setActiveTab] = useState(0);
+
+ return (
+ <div className="term">
+ <div className="term-head">
+ <span className="tdot" style={{ background: "#ff5a5f" }} />
+ <span className="tdot" style={{ background: "#ffd166" }} />
+ <span className="tdot" style={{ background: "#22e0a8" }} />
+ </div>
+ <div className="term-tabs" role="tablist">
+ {TABS.map((tab, i) => (
+ <button
+ key={tab.filename}
+ role="tab"
+ aria-selected={activeTab === i}
+ className="term-tab"
+ onClick={() => setActiveTab(i)}
+ >
+ {tab.filename}
+ </button>
+ ))}
+ </div>
+ <div className="overflow-x-auto">
+ <pre
+ className="px-[22px] py-4 text-[13px] leading-[1.75]"
+ style={{ fontFamily: "var(--font-mono)", margin: 0 }}
+ >
+ {TABS[activeTab].code}
+ </pre>
+ </div>
+ </div>
+ );
+}
diff --git a/website/components/site-footer.tsx b/website/components/site-footer.tsx
index 21ffb224..bf6897b0 100644
--- a/website/components/site-footer.tsx
+++ b/website/components/site-footer.tsx
@@ -23,9 +23,11 @@ const COLUMNS: Column[] = [
{
heading: "Specialized",
links: [
+ { label: "Agent Skills", href: "/product/agent-skills" },
{ label: "AI Tracing", href: "/product/ai-tracing" },
{ label: "Performance", href: "/product/performance" },
{ label: "Flutter Session Replay", href: "/product/flutter-session-replay" },
+ { label: "JavaScript Symbolication", href: "/product/javascript-symbolication" },
],
},
{
diff --git a/website/components/site-header.tsx b/website/components/site-header.tsx
index 341ccca9..1cb33a81 100644
--- a/website/components/site-header.tsx
+++ b/website/components/site-header.tsx
@@ -14,6 +14,8 @@ import {
Workflow,
Activity,
Smartphone,
+ Bot,
+ Braces,
} from "lucide-react";
import { MobileNav } from "@/components/mobile-nav";
import { DiscordIcon } from "@/components/discord-icon";
@@ -61,6 +63,12 @@ const PILLARS: NavItem[] = [
];
const SPECIALIZED: NavItem[] = [
+ {
+ title: "Agent Skills",
+ description: "Your AI agent debugs with Traceway.",
+ href: "/product/agent-skills",
+ icon: Bot,
+ },
{
title: "AI Tracing",
description: "LLM cost, tokens, latency, conversations.",
@@ -79,6 +87,12 @@ const SPECIALIZED: NavItem[] = [
href: "/product/flutter-session-replay",
icon: Smartphone,
},
+ {
+ title: "JavaScript Symbolication",
+ description: "Minified stack traces, resolved to your source.",
+ href: "/product/javascript-symbolication",
+ icon: Braces,
+ },
];
export function SiteHeader() {
diff --git a/website/components/skill-install-command.tsx b/website/components/skill-install-command.tsx
new file mode 100644
index 00000000..6ff5f005
--- /dev/null
+++ b/website/components/skill-install-command.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { useState } from "react";
+import { Check, Copy } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+const COMMAND = "npx skills add tracewayapp/traceway";
+
+export function SkillInstallCommand({
+ className,
+ size = "default",
+}: {
+ className?: string;
+ size?: "default" | "lg";
+}) {
+ const [copied, setCopied] = useState(false);
+
+ async function copyCommand() {
+ try {
+ await navigator.clipboard.writeText(COMMAND);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ } catch {
+ setCopied(false);
+ }
+ }
+
+ return (
+ <button
+ type="button"
+ onClick={copyCommand}
+ className={cn(
+ "group inline-flex max-w-full items-center rounded-lg border border-hair-2 bg-ink-1 text-left font-mono transition-colors hover:bg-ink-2",
+ size === "lg"
+ ? "gap-3 py-3 pl-4 pr-2.5 text-xs sm:gap-4 sm:py-4 sm:pl-6 sm:pr-3.5 sm:text-base"
+ : "gap-3 py-2.5 pl-4 pr-2.5 text-xs sm:text-[0.8125rem]",
+ className
+ )}
+ >
+ <span className="text-a2" aria-hidden>
+ $
+ </span>
+ <span className="flex-1 truncate text-fg-0">{COMMAND}</span>
+ <span
+ className={cn(
+ "grid shrink-0 place-items-center rounded-md border border-hair bg-ink-2 transition-colors",
+ size === "lg" ? "size-7 sm:size-9" : "size-7",
+ copied ? "text-ok" : "text-fg-2 group-hover:text-fg-0"
+ )}
+ aria-hidden
+ >
+ {copied ? (
+ <Check className={size === "lg" ? "size-4" : "size-3.5"} />
+ ) : (
+ <Copy className={size === "lg" ? "size-4" : "size-3.5"} />
+ )}
+ </span>
+ <span className="sr-only">
+ {copied ? "Copied to clipboard" : "Copy install command"}
+ </span>
+ </button>
+ );
+}
diff --git a/website/components/symbolication-before-after.tsx b/website/components/symbolication-before-after.tsx
new file mode 100644
index 00000000..7a5abb6e
--- /dev/null
+++ b/website/components/symbolication-before-after.tsx
@@ -0,0 +1,116 @@
+import { MoveRight, MoveDown } from "lucide-react";
+
+const RAW_LINES = [
+ "n()",
+ "",
+ "app.min.js:1:63",
+ "t()",
+ "",
+ "app.min.js:1:129",
+ "",
+ "app.min.js:1:146",
+ "",
+ "app.min.js:1:164",
+];
+
+const RESOLVED_FRAMES = [
+ { fn: "validateUser", loc: "../src/user.ts:8:11", top: true },
+ { fn: "handleSignup", loc: "../src/index.ts:4:10" },
+ { fn: "<anonymous>", loc: "../src/index.ts:7:1" },
+ { fn: "<anonymous>", loc: "../src/index.ts:7:29" },
+];
+
+const CARD_SHADOW = "0 18px 40px -24px rgba(10, 14, 24, 0.25)";
+
+function CardLabel({ text }: { text: string }) {
+ return (
+ <p
+ className="mb-3 text-center text-[11px] uppercase tracking-[0.14em]"
+ style={{ fontFamily: "var(--font-mono)", color: "var(--fg-2)" }}
+ >
+ {text}
+ </p>
+ );
+}
+
+export function SymbolicationBeforeAfter() {
+ return (
+ <section className="wrap pt-16 pb-4">
+ <div className="mx-auto grid max-w-5xl items-center gap-6 md:grid-cols-[1fr_auto_1fr] md:gap-5">
+ <div className="min-w-0">
+ <CardLabel text="What the browser sends" />
+ <div
+ className="overflow-hidden rounded-xl px-6 py-5 text-[12px] leading-[1.7]"
+ style={{
+ fontFamily: "var(--font-mono)",
+ overflowWrap: "anywhere",
+ background: "var(--ink-0)",
+ border: "1px solid var(--hair-2)",
+ boxShadow: CARD_SHADOW,
+ }}
+ >
+ <div style={{ color: "var(--crit)" }}>Error: user has no name</div>
+ <div className="mt-3" style={{ color: "var(--fg-3)" }}>
+ {RAW_LINES.map((line, i) => (
+ <div key={i} className="min-h-[1.2em]">
+ {line}
+ </div>
+ ))}
+ </div>
+ </div>
+ </div>
+
+ <div className="flex items-center justify-center py-1 md:py-0">
+ <MoveRight
+ className="hidden h-6 w-6 md:block"
+ style={{ color: "var(--fg-3)" }}
+ aria-hidden
+ />
+ <MoveDown
+ className="h-6 w-6 md:hidden"
+ style={{ color: "var(--fg-3)" }}
+ aria-hidden
+ />
+ </div>
+
+ <div className="min-w-0">
+ <CardLabel text="What Traceway shows you" />
+ <div
+ className="overflow-hidden rounded-xl text-[12px] leading-[1.7]"
+ style={{
+ fontFamily: "var(--font-mono)",
+ background: "var(--ink-0)",
+ border: "1px solid var(--hair-2)",
+ boxShadow: CARD_SHADOW,
+ }}
+ >
+ <div
+ className="px-5 py-3.5"
+ style={{
+ color: "var(--crit)",
+ background: "color-mix(in oklab, var(--ink-2) 70%, transparent)",
+ borderBottom: "1px solid var(--hair)",
+ }}
+ >
+ Error: user has no name
+ </div>
+ {RESOLVED_FRAMES.map((f, i) => (
+ <div
+ key={i}
+ className="flex flex-wrap items-baseline gap-x-3 px-5 py-3"
+ style={{
+ borderTop: i > 0 ? "1px solid var(--hair)" : "none",
+ borderLeft: `3px solid ${f.top ? "var(--a2)" : "var(--ink-5)"}`,
+ overflowWrap: "anywhere",
+ }}
+ >
+ <span style={{ color: "var(--fg-0)", fontWeight: 600 }}>{f.fn}</span>
+ <span style={{ color: "var(--fg-3)" }}>{f.loc}</span>
+ </div>
+ ))}
+ </div>
+ </div>
+ </div>
+ </section>
+ );
+}
diff --git a/website/public/images/claudebot.png b/website/public/images/claudebot.png
new file mode 100644
index 00000000..c83a2f13
Binary files /dev/null and b/website/public/images/claudebot.png differ