# Maple Documentation

Every Maple doc. Append `.md` to any docs URL, or send `Accept: text/markdown`, to receive the raw markdown source.

The full docs as a single file: [https://maple.dev/llms-full.txt](https://maple.dev/llms-full.txt)

## Getting Started

- [Introduction](https://maple.dev/docs/getting-started/introduction.md) — What Maple is, what it includes, and how to send your first telemetry.
- [Quickstart](https://maple.dev/docs/getting-started/quickstart.md) — Send your first trace to Maple in about five minutes, from your own stack or with a single curl request.
- [Use Maple with AI agents](https://maple.dev/docs/getting-started/ai-agents.md) — Connect Claude Code, Cursor, Windsurf or any MCP client to Maple, then let the agent debug production errors, chase latency, build dashboards, set up alerts and instrument your code.

## Concepts

- [OpenTelemetry conventions](https://maple.dev/docs/concepts/otel-conventions.md) — Maple's expected OpenTelemetry attributes, status codes, span kinds, and data model conventions.
- [Sampling and throughput estimation](https://maple.dev/docs/concepts/sampling-throughput.md) — How Maple weights sampled spans at ingest so throughput, error rate and service map call counts reflect the traffic you actually served.

## Explore

- [Traces](https://maple.dev/docs/explore/traces.md) — Search traces by service, route, status, duration, and any span or resource attribute, then open a trace to inspect its spans, logs, and session replay.
- [Logs](https://maple.dev/docs/explore/logs.md) — Search log messages by text or trace ID, filter by severity, service, and environment, and move between a log line and the trace it belongs to.
- [Metrics](https://maple.dev/docs/explore/metrics.md) — Browse every OpenTelemetry metric Maple has received, then chart one with an aggregation, a filter, and a breakdown by attribute.
- [Services](https://maple.dev/docs/explore/services.md) — Latency percentiles, error rate, throughput, and Apdex for every service that sends traces, with a detail page per service for its endpoints, operations, and dependencies.
- [Service map](https://maple.dev/docs/explore/service-map.md) — A live graph of your services and the databases they call, drawn from trace context, with call volume, error rate, and latency on every node and edge.

## Errors

- [Errors and issues](https://maple.dev/docs/errors/overview.md) — How Maple groups error spans into issues, how an issue moves from triage to done, and how to claim, prioritize, and get notified about them.

## Session Replay

- [Browser SDK](https://maple.dev/docs/session-replay/browser-sdk.md) — Instrument a website with OpenTelemetry tracing, logs, Web Vitals, error capture and session replay using the @maple-dev/browser SDK.
- [Replays](https://maple.dev/docs/session-replay/replays.md) — Find a browser session on the Session Replays page, play it back next to its events and backend traces, and move between a trace and the replay that produced it.

## Product Events

- [Product events](https://maple.dev/docs/product-events/overview.md) — Track the steps that matter, like signup, checkout and plan started, from the browser, a span you already emit, or any backend, and build funnels, drop-off and path analysis on them.
- [Product events from traces](https://maple.dev/docs/product-events/from-traces.md) — Turn a span you already emit into a product event by annotating it with maple.product_event.* attributes. No second SDK call, and each event links back to the request that performed it.
- [Product events API](https://maple.dev/docs/product-events/api.md) — Post product events from a backend or mobile app to POST /v1/events on the Maple ingest gateway. The raw NDJSON contract every server-side track() call uses.
- [Web analytics](https://maple.dev/docs/product-events/web-analytics.md) — What the Web Analytics page shows: visitors, sessions, page views, referrers, devices, countries and custom events from the Maple browser SDK, and what data each part needs.

## Agent Sessions

- [Agent Sessions](https://maple.dev/docs/agent-sessions/overview.md) — Agent Sessions groups the OpenTelemetry traces of one AI agent conversation into a single view of its turns, model calls, tool calls, tokens, cost and failures.

## Dashboards

- [Build dashboards](https://maple.dev/docs/dashboards/build-dashboards.md) — Create a Maple dashboard from scratch or a template, add charts, stats, tables and funnels over traces, logs, metrics and product events, add variables, and share it.
- [Embed dashboard charts in your own product](https://maple.dev/docs/dashboards/embed-charts.md) — Put a live Maple chart in your admin panel, internal tool or customer-facing page with a plain iframe. Make the dashboard public, copy the chart's embed snippet, and set theme, time range, refresh and variables in the URL.

## Alerting

- [Alert rules](https://maple.dev/docs/alerting/alert-rules.md) — Create an alert rule in Maple: pick a signal, scope it to services and environments, set the threshold and evaluation timing, attach destinations, and preview it against past data. In the app or over the API.
- [Incidents](https://maple.dev/docs/alerting/incidents.md) — What happens after a Maple alert rule fires: how an incident opens, renotifies, waits on missing data and resolves, what each notification contains, and where to see incidents.
- [Apdex alerts](https://maple.dev/docs/alerting/apdex-alerts.md) — How to set up an Apdex alert in Maple: pick the target latency T, choose the score worth paging for, scope and tune the rule, and create the same rule over the API.
- [Notification destinations](https://maple.dev/docs/alerting/notification-destinations.md) — Route Maple alerts to Slack, email, PagerDuty, Discord, Telegram, Hazel or any HTTP endpoint. How to add a destination, send a test, and get the right credentials for each provider.

## Integrations

- [Prometheus scraping](https://maple.dev/docs/integrations/prometheus.md) — Point Maple at any Prometheus exposition endpoint. Maple scrapes it on a schedule, converts the samples to OpenTelemetry metrics, and records the health of every scrape.
- [WarpStream](https://maple.dev/docs/integrations/warpstream.md) — Monitor WarpStream clusters in Maple. Scrape Agent /metrics endpoints directly, or pull consumer lag, request latency, and object-store health from WarpStream's hosted Prometheus endpoint.
- [PlanetScale](https://maple.dev/docs/integrations/planetscale.md) — Connect a PlanetScale organization to Maple. Maple discovers every database branch's metrics endpoint, scrapes connections, WAL size, and pod CPU, and adds your databases to the service map.
- [GitHub](https://maple.dev/docs/integrations/github.md) — Install the Maple GitHub App to sync repositories and commit history, resolve commit SHAs in your telemetry, and give the MCP server read access to your source code.
- [Slack](https://maple.dev/docs/integrations/slack.md) — Add the Maple bot to a Slack workspace. Mention it in a channel to ask about your traces, logs, metrics, and errors, and use the same workspace as an alert destination.
- [Cloudflare](https://maple.dev/docs/integrations/cloudflare.md) — Connect a Cloudflare account with OAuth. Maple polls zone traffic, Workers, security, DNS, Queues, and Durable Objects analytics every 5 minutes and shows them under Infrastructure and on the service map.

## Instrumentation

- [Instrument your application](https://maple.dev/docs/instrumentation.md) — Setup guides for every language, framework and runtime Maple supports.
- [Effect SDK](https://maple.dev/docs/sdks/effect.md) — OpenTelemetry traces, logs, and metrics for Effect applications across Node.js, Bun, Deno, browsers, and Cloudflare Workers.
- [Effect SDK on servers](https://maple.dev/docs/sdks/effect-server.md) — Set up the Effect SDK on Node.js, Bun, or Deno with environment-variable auto-detection.
- [Effect SDK in the browser](https://maple.dev/docs/sdks/effect-client.md) — Set up the Effect SDK in browser environments with explicit configuration and auto-captured browser metadata.
- [Effect SDK on Cloudflare Workers](https://maple.dev/docs/sdks/effect-cloudflare.md) — Set up the Effect SDK on Cloudflare Workers with explicit flush() in ctx.waitUntil and in-isolate buffering.
- [Cloudflare Workers instrumentation](https://maple.dev/docs/guides/instrumentation-cloudflare-workers.md) — Send traces and logs from any Cloudflare Worker to Maple with Workers Observability OTLP destinations. No SDK or code changes.
- [Node.js instrumentation](https://maple.dev/docs/guides/instrumentation-nodejs.md) — Instrument a Node.js application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Next.js instrumentation](https://maple.dev/docs/guides/instrumentation-nextjs.md) — Instrument a Next.js application with @vercel/otel and send traces, logs, and metrics to Maple.
- [Python instrumentation](https://maple.dev/docs/guides/instrumentation-python.md) — Instrument a Python application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Go instrumentation](https://maple.dev/docs/guides/instrumentation-go.md) — Instrument a Go application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Rust instrumentation](https://maple.dev/docs/guides/instrumentation-rust.md) — Instrument a Rust application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Java instrumentation](https://maple.dev/docs/guides/instrumentation-java.md) — Instrument a Java application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Kotlin instrumentation](https://maple.dev/docs/guides/instrumentation-kotlin.md) — Instrument a Kotlin JVM application (Ktor, Spring Boot) with OpenTelemetry and send traces, logs, and metrics to Maple.
- [C# / .NET instrumentation](https://maple.dev/docs/guides/instrumentation-csharp.md) — Instrument a .NET application with OpenTelemetry and send traces, logs, and metrics to Maple.
- [Laravel instrumentation](https://maple.dev/docs/guides/instrumentation-laravel.md) — Instrument a Laravel application with OpenTelemetry and send traces, logs, and metrics to Maple.

## AI Agents

- [Trace your AI agent](https://maple.dev/docs/agent-tracing.md) — Setup guides for sending each supported agent framework and LLM gateway to Maple as one Agent Session per conversation.
- [Trace Vercel AI SDK agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/vercel-ai-sdk.md) — Send the Vercel AI SDK's OpenTelemetry spans to Maple and group each chat into one Agent Session.
- [Trace Mastra agents and workflows with OpenTelemetry](https://maple.dev/docs/agent-tracing/mastra.md) — Export Mastra's built-in spans to Maple with @mastra/otel-exporter and group each conversation into one Agent Session.
- [Trace OpenAI Agents SDK runs with OpenTelemetry](https://maple.dev/docs/agent-tracing/openai-agents.md) — Send OpenAI Agents SDK runs to Maple as one Agent Session per conversation, with the transcript, tool calls and tokens.
- [Trace LangChain and LangGraph agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/langchain.md) — Send LangChain and LangGraph runs to Maple with OpenInference, one Agent Session per thread.
- [Trace Claude Agent SDK agents and Claude Code sessions with OpenTelemetry](https://maple.dev/docs/agent-tracing/claude-agent-sdk.md) — Turn on Claude Code's built-in OpenTelemetry so each Agent SDK conversation or Claude Code session shows up in Maple as one Agent Session.
- [Trace Cloudflare Agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/cloudflare-agents.md) — Export the AI SDK spans of a Cloudflare Agents SDK agent from its Durable Object to Maple and group each chat into one Agent Session.
- [Trace Genkit agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/genkit.md) — Send Genkit's OpenTelemetry spans to Maple and group each chat into one Agent Session.
- [Trace Pydantic AI agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/pydantic-ai.md) — Send Pydantic AI's built-in OpenTelemetry spans to Maple so each conversation shows up as one Agent Session.
- [Trace CrewAI crews and flows with OpenTelemetry](https://maple.dev/docs/agent-tracing/crewai.md) — Send CrewAI crews and flows to Maple with OpenInference, one Agent Session per conversation.
- [Trace Google ADK agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/google-adk.md) — Send Google Agent Development Kit (ADK) traces to Maple with the transcript, tool calls and tokens, one session per ADK session.
- [Trace LlamaIndex agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/llamaindex.md) — Send LlamaIndex agent and workflow runs to Maple with OpenInference, one Agent Session per conversation.
- [Trace Strands Agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/strands.md) — Send Strands Agents traces to Maple with the full transcript and one Agent Session per conversation.
- [Trace Hugging Face smolagents with OpenTelemetry](https://maple.dev/docs/agent-tracing/smolagents.md) — Send smolagents runs to Maple through the OpenInference instrumentor so each conversation shows up as one Agent Session.
- [Trace Agno agents and teams with OpenTelemetry](https://maple.dev/docs/agent-tracing/agno.md) — Send Agno agent, team and tool spans to Maple as one Agent Session per conversation, with transcript, tokens and failed tools.
- [Trace DSPy programs and ReAct agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/dspy.md) — Send DSPy programs to Maple as one Agent Session per conversation, with transcript, model and tool calls, tokens and cost.
- [Trace Haystack agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/haystack.md) — Send Haystack 3 Agent and pipeline runs to Maple as one Agent Session per conversation, with transcript, model, tokens, cost and failed tool calls.
- [Trace Microsoft Agent Framework and Semantic Kernel agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/microsoft-agent-framework.md) — Send Microsoft Agent Framework and Semantic Kernel traces from Python or .NET to Maple as one Agent Session per conversation.
- [Trace Spring AI agents with OpenTelemetry](https://maple.dev/docs/agent-tracing/spring-ai.md) — Send Spring AI ChatClient, model and tool spans to Maple, with one session per chat memory conversation.
- [Trace LiteLLM agents and the LiteLLM Proxy with OpenTelemetry](https://maple.dev/docs/agent-tracing/litellm.md) — Send LiteLLM's model-call spans to Maple from the Python SDK or the LiteLLM Proxy, and add the agent and tool spans that group each conversation into one Agent Session.
- [Trace OpenRouter calls in Maple with Broadcast](https://maple.dev/docs/agent-tracing/openrouter.md) — Send every OpenRouter model call to Maple with OpenRouter Broadcast, grouped into one Agent Session per conversation.
- [Trace agents built on the OpenAI, Anthropic and Gemini SDKs](https://maple.dev/docs/agent-tracing/provider-sdks.md) — Trace your own agent loop on the OpenAI, Anthropic or Google Gen AI SDK so each conversation becomes one Maple Agent Session, in Python or TypeScript.
- [Trace any AI agent with the OpenTelemetry GenAI conventions](https://maple.dev/docs/agent-tracing/opentelemetry.md) — Write the OpenTelemetry GenAI spans Maple reads by hand, in any language, so a custom agent loop shows up in Agent Sessions.

## Infrastructure

- [Hosts](https://maple.dev/docs/infrastructure/hosts.md) — Send host CPU, memory, disk, network and load metrics to Maple with the OpenTelemetry Collector hostmetrics receiver, and read them on the Hosts page.
- [Kubernetes infrastructure](https://maple.dev/docs/infrastructure/kubernetes.md) — Deploy Maple's Kubernetes infrastructure collector with Helm to stream host, kubelet and cluster metrics, and wire the service map's Infrastructure tab to your workloads.
- [Docker infrastructure](https://maple.dev/docs/infrastructure/docker.md) — Run the Maple Docker agent as a single container to stream per-container CPU, memory, network, block I/O and logs, and correlate them with your app's traces.

## Local Mode

- [Maple Local](https://maple.dev/docs/local-mode.md) — Run the whole of Maple as one binary on your machine: OTLP ingest, an embedded ClickHouse, a query API, the dashboard and a CLI. No account, no containers, nothing to deploy.
- [Checkpoints and archives](https://maple.dev/docs/local-mode/checkpoints-and-archives.md) — How Maple Local protects your telemetry: automatic restore points, what happens after an unclean shutdown, reset and restore, and Parquet archives for long-term history.

## Reference

- [Maple API](https://maple.dev/docs/reference/api.md) — The Maple REST API: base URLs, API keys and scopes, the resources it exposes, pagination, the error envelope, rate limits, and where the OpenAPI specification lives.
- [Maple MCP server](https://maple.dev/docs/reference/mcp.md) — Connect Claude, Cursor and other AI agents to your Maple telemetry over the Model Context Protocol: endpoints, authentication, and every tool the server exposes.
- [CLI reference](https://maple.dev/docs/reference/cli.md) — Every maple command, argument and flag, plus the local server's endpoints, environment variables and a troubleshooting guide.
- [Authentication](https://maple.dev/docs/reference/authentication.md) — The credentials Maple accepts: public and private ingest keys for sending telemetry, API keys for the REST API and MCP server, OAuth for MCP clients, and which endpoint takes which.
- [Regions](https://maple.dev/docs/reference/regions.md) — Maple runs in a US region and an EU region. The hosts for the app, ingest, API and MCP server in each, how to find your organization's region, and how to point SDKs and tools at it.
- [Ingest API](https://maple.dev/docs/reference/ingest.md) — The OTLP ingest endpoint: paths, authentication, content types, compression, request limits, status codes, and how to retry.
- [SQL reference](https://maple.dev/docs/reference/sql.md) — Query your telemetry with ClickHouse SQL: the tables and columns you can read, the required macros, result shapes for each chart type, and limits.
- [Alert webhooks](https://maple.dev/docs/reference/webhooks.md) — The webhook destination contract: request headers, the JSON payload for each event, verifying the HMAC signature, retries, and idempotency.
- [Retention](https://maple.dev/docs/reference/retention.md) — How long hosted Maple keeps each kind of data: traces, logs, metrics, session replays, product events, error issues, alert history and the audit log.
- [Limits](https://maple.dev/docs/reference/limits.md) — Every limit in one place: ingest request size and concurrency, query time ranges, raw SQL, alert rules, event fields, and API and MCP rate limits.