maple-agent-tracing-ag…
Trace Agno agents with Maple: installs the OpenInference Agno instrumentor with an OTLP exporter and GenAI attributes, and sets…
Trace a web frontend with Maple: install @maple-dev/browser, link browser and backend traces, add route navigation and data-loading spans, report errors the framework catches, and join the first page load to the server render. Per-framework references for TanStack Router/Start,
Claude Code
$ npx -y skills add mapletechlabs/maple --skill maple-frontend-tracing --agent claude-code
Codex
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a codex -y
Cursor
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a cursor -y
Gemini CLI
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a gemini-cli -y
GitHub Copilot
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a github-copilot -y
OpenCode
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a opencode -y
Windsurf
$ npx skills add mapletechlabs/maple --skill maple-frontend-tracing -a windsurf -y
name: maple-frontend-tracing description: "Trace a web frontend with Maple: install @maple-dev/browser, link browser and backend traces, add route navigation and data-loading spans, report errors the framework catches, and join the first page load to the server render. Per-framework references for TanStack Router/Start, React Router, Next.js, Vue/Nuxt, SvelteKit, Angular and Astro. Triggers on 'trace my frontend', 'add frontend observability', 'instrument the browser with Maple', 'trace route changes', 'connect frontend and backend traces', 'add session replay'."
The goal: **one click is one trace**. A navigation span, the data-loading spans under it, the `fetch` spans they make, and the backend spans behind those. The first page load joins the server render's trace. Errors the framework catches are reported. Session replay links to the traces through a shared `session.id`.
The human-readable version of this skill is the guide at https://maple.dev/docs/frontend. Read it if you need the reasoning behind a step.
Read the `package.json` of each web frontend in the repo, then read **only** the matching reference in `frameworks/`:
| Dependency | Reference | | --- | --- | | `@tanstack/react-router`, `@tanstack/react-start` | `frameworks/tanstack.md` | | `react-router` (v7, v8), `react-router-dom` | `frameworks/react-router.md` | | `next` | `frameworks/nextjs.md` | | `vue-router`, `nuxt` | `frameworks/vue.md` | | `@sveltejs/kit` | `frameworks/sveltekit.md` | | `@angular/router` | `frameworks/angular.md` | | `astro` | `frameworks/astro.md` | | anything else (Solid, Qwik, plain SPA, hand-rolled router) | `frameworks/other.md` |
The steps below are the same for every framework. The reference tells you where each one goes. If the references are not next to this file, read them from https://github.com/MapleTechLabs/maple/tree/main/skills/maple-frontend-tracing.
Backends are out of scope for this skill. If the API the frontend calls isn't instrumented with OpenTelemetry yet, use the `maple-onboard` skill for it first, or say in the hand-off that browser traces won't connect to it until it is.
Maple has two regions. A key only works in the region that issued it.
Browser code takes the **public** ingest key (`maple_pk_…`) only. It is write-only and safe to ship, like a Sentry DSN. Inline it in the init call. Never put a private key (`maple_sk_…`) in browser code: if the prompt only has a private key, use `MAPLE_TEST` in the browser and tell the user to swap in the public key. With no key at all, inline the sentinel `MAPLE_TEST` (ingest accepts it and stores nothing) and keep going.
Install `@maple-dev/browser` 0.14.0 or later with the project's package manager. It has two entries only: `@maple-dev/browser` and `@maple-dev/browser/react`. There are no per-framework or `/server` entries; never import `@maple-dev/browser/<framework>`. Add `@opentelemetry/api` only if app code imports it (the `await` rule's `context`, or where a reference says so): strict package managers (pnpm) won't resolve it as the SDK's transitive dependency. Initialize the SDK once, before the app renders, at the place the framework reference names:
import { MapleBrowser } from "@maple-dev/browser"
MapleBrowser.init({
ingestKey: "MAPLE_TEST", // public key, maple_pk_…
serviceName: "acme-web",
region: "us", // "eu" for EU organizations
serviceVersion: "<commit sha from the build env, if the bundler exposes one>",
environment: import.meta.env.MODE,
tracing: {
// First-party APIs on another origin. Same-origin requests are covered already.
propagateTraceHeaderCorsUrls: [/^https:\/\/api\.acme\.com\//], // RegExp: a plain string only matches as a prefix from 0.14.1
},
})1. Find every first-party API base URL the frontend calls (API client config, env vars like `VITE_API_URL`). Same-origin requests already carry `traceparent`. List each cross-origin first-party API in `propagateTraceHeaderCorsUrls` as an anchored regex. 2. **Never list third-party origins** (analytics, payment providers, CDNs). It leaks trace ids and often breaks their CORS preflight. 3. Check the API's CORS config. Many setups already echo the requested headers (the `cors` npm package default). If there's an explicit allow-list, add `traceparent` and keep the existing entries (plus `baggage` if the app sets OpenTelemetry baggage). Without this, the browser blocks the request after the preflight.
React Router (data routers) and TanStack Router: use `instrumentReactRouter` / `instrumentTanStackRouter` from `@maple-dev/browser/react` as the reference says. Every other framework: copy the reference's router glue, which calls the SDK's three navigation methods from the router's hooks:
Trace Agno agents with Maple: installs the OpenInference Agno instrumentor with an OTLP exporter and GenAI attributes, and sets…
Trace Claude Agent SDK agents (TypeScript and Python) and Claude Code CLI sessions with Maple: configure Claude Code's built-in…
Trace Cloudflare Agents SDK agents (AIChatAgent, Agent on Durable Objects, npm `agents` / `@cloudflare/ai-chat`) with Maple:…
Trace CrewAI crews and flows with Maple: OpenInference CrewAI instrumentor plus the model-SDK instrumentor, GenAI dual-write, one…
Trace DSPy programs and ReAct agents with Maple: OpenInference DSPy instrumentor with GenAI dual-write, a DSPy callback for…
Trace eve agents (Vercel's eve framework, npm `eve`) with Maple: add one OpenTelemetry destination file under…
Kubeshark installation and deployment skill. Use this skill whenever the user wants to install Kubeshark, deploy Kubeshark to a…
Call the user on the phone for real-time voice conversations. Use this when you need input, want to report on completed work, or…