SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmaple-onboard

maple-onboard

Deployment & operations

View repository

Updated 10-16 00:05

About this skill

Maple onboarding

Wire OpenTelemetry traces, logs, and metrics into every app and service in the repo so telemetry streams to Maple. Use native OpenTelemetry APIs and each framework's documented bootstrap. If a stack stumps you, read the OTel docs for that language; don't guess.

Companion skills

Read maple-onboarding-style first (span pattern, resource attributes, framework notes, signal quality, verification), then the skill for each stack in the repo: maple-nextjs-style, maple-nodejs-style, maple-python-style, maple-effect-style, maple-go-style, maple-rust-style, maple-java-style, maple-csharp-style, maple-kotlin-style. If they are not installed next to this skill, fetch them from https://raw.githubusercontent.com/MapleTechLabs/maple/main/skills/<skill-name>/SKILL.md, only the ones this repo needs. Stacks without one (Ruby, Elixir, PHP, Deno, ...) use maple-onboarding-style and the upstream OTel docs. A service that calls an LLM also gets maple-agent-tracing.

Step 0: Region, endpoint, and key

A key only works in the region that issued it; the other region answers 401.

Region Ingest endpoint Dashboard MCP server
US (default) https://ingest.maple.dev https://app.maple.dev https://api.maple.dev/mcp
EU https://ingest.eu.maple.dev https://app.eu.maple.dev https://api.eu.maple.dev/mcp

Pick the region in this order: an ingest endpoint in the prompt (use it verbatim), an EU mention or eu.maple.dev URL, otherwise US. <dashboard> and <mcp> below mean that region's hosts.

Inline the endpoint and the ingest key in the bootstrap source. The key is project-scoped and write-only (think Sentry DSN): no .env files, no process.env.OTEL_EXPORTER_OTLP_*, no deploy wiring. The public key (maple_pk_…) is safe everywhere, browser and mobile included. The private key (maple_sk_…) is server-only.

  • Public key in the prompt: inline it in every bootstrap file.
  • Private key in the prompt: server bootstrap files only. Put MAPLE_TEST in browser and mobile code and tell the user to swap in the public key there (it also works on servers, so one key can cover the repo).
  • No key: inline the sentinel MAPLE_TEST. Both regions return 200 for it and store nothing, so the bootstrap runs end to end. Tell the user briefly up front: "I'm using MAPLE_TEST as a placeholder so the bootstrap can run. Copy your public ingest key from Settings → Ingestion (/settings?tab=ingestion), or create an account at /sign-up first, and search-replace MAPLE_TEST in the files I write." Then keep going. Don't block on signup.

Step 1: Map every service

Enumerate from workspace manifests (pnpm/bun/npm workspaces, go.work, Cargo, Python workspaces) and apps/* / services/*: web frontends, APIs, workers, background jobs, CLIs, demo apps, mobile apps, serverless and edge functions. Skip only packages with no runtime entry point. Instrument everything in this run; there may be no follow-up. Print the list so the user can correct it, then continue without waiting.

Step 2: Install native OTel and bootstrap each service

Use the language's native SDK:

  • Node servers: @opentelemetry/sdk-node. Next.js server side: @vercel/otel in instrumentation.ts.
  • Browser frontends (Vite, SPA, Next.js client): @maple-dev/browser (traces, errors and session replay sharing one session.id).
  • Expo / React Native: @opentelemetry/sdk-trace-web with an OTLP HTTP exporter.
  • Python: opentelemetry-sdk + opentelemetry-instrumentation-*. Go: go.opentelemetry.io/otel. Effect: @maple-dev/effect-sdk.

Rules:

  • The bootstrap runs before any framework import, through the documented hook (--import, instrumentation.ts, top of main.py).
  • HTTP OTLP exporters, never gRPC.
  • Servers get traces, logs and metrics. Logs go through OTLP via the language's log bridge under the existing logger, so they carry trace_id / span_id.
  • Set service.name, service.version, deployment.environment.name, vcs.repository.url.full (required on servers) and vcs.ref.head.revision (best effort).
  • No wrapper APIs (sendMapleSpan, recordCounter, withTelemetry): module-scope tracers and meters, the SDK's own calls.
  • Use the repo's package manager. Edit existing config; don't overwrite it.
  • Keep existing vendors (Sentry, Datadog, New Relic, Pino transports, ...). OTel runs alongside them.

Per-framework details (browser init and CORS, Expo, Workers, FastAPI) are in maple-onboarding-style "Framework notes" and the stack skills.

Step 3: Business spans, logs, and metrics

Auto-instrumentation is the floor. Read the code and add, per maple-onboarding-style "Business signals":

  • Spans around every critical business operation (order.process, payment.charge, job.<type>): entity ids and outcomes as attributes, exceptions recorded, Error status on failure, always ended. Skip trivial helpers. No PII.
  • Logs that are structured and trace-correlated. Error level only when manual intervention is needed.
  • Metrics: counters for state transitions, histograms for latency and sizes, low-cardinality dimensions only.

Step 4: Verify

Per service:

  1. The project's own dev or build command still starts cleanly, and a smoke run (start or import the app, then one request through an instrumented route or a real CLI command) initializes the bootstrap. Broken startup is a regression: fix it.
  2. Telemetry leaves the process: run with exporter diagnostics on and see no export error after the shutdown flush. maple-onboarding-style "Verify export" has the per-language switches and what to do on a 401.
  3. With a real key and Maple MCP tools, wait about a minute, call list_services to confirm each service.name, then audit_setup and fix what it reports. Skip this with MAPLE_TEST, which stores nothing; without MCP, tell the user Settings → Ingestion shows when data arrives.

A bootstrap that loads but never exports is not done.

Step 5: Hand-off

  • What changed: 3 to 7 short bullets: packages, files, business spans and metrics, vendors you left in place. If you added @maple-dev/browser, say session replay is on with inputs masked (replay: { enabled: false } turns it off) and that it keeps a visitor id in localStorage and a cookie (privacy: { persistVisitorId: false } turns it off).
  • Placeholder: if MAPLE_TEST is still inline, tell the user: "The bootstrap uses MAPLE_TEST as a placeholder so the install could complete end to end. Copy your public ingest key from Settings → Ingestion (/settings?tab=ingestion); if you don't have a Maple account yet, create one at /sign-up first. Then search-replace MAPLE_TEST in the files I wrote and redeploy. If your organization is in the EU region (app.eu.maple.dev), also replace ingest.maple.dev with ingest.eu.maple.dev, or set region: "eu" in the Maple SDKs." Leave out the EU sentence if you used the EU endpoint.
  • Deploy: as they normally do. There is nothing to configure: the key is in the source.

Step 6: Maple MCP

Skip if Maple MCP tools are already connected to <mcp> (a server in the other region answers 401 or reads another organization). Otherwise offer to run, and confirm first: claude mcp add --transport http maple <mcp>. Mention without running: Codex codex mcp add maple --url <mcp>; Cursor and others copy the snippet at <dashboard>/mcp.

Hard rules

  • Never modify files outside the project root. Never commit, push, or open PRs.
  • Never put a private key (maple_sk_…) in browser or mobile code.
  • Never remove an existing observability vendor unless the user asks.
  • If the dev or build command fails because of your instrumentation, fix it or report it.