repository·main·Indexed 23 days ago
https://github.com/mapletechlabs/mapleAn open-source observability platform for traces, logs, and metrics built on OpenTelemetry and ClickHouse. The project features a monorepo architecture with an Effect-based backend, a TanStack Router SPA frontend, and AI-driven components including @maple/chat-flue for headless triage and investigations, and an MCP server with deterministic and LLM-based evaluation layers.
@maple/unitflow is a vendored and ported version of the unitflow library. It includes both @unitflow/core and @unitflow/react functionality, specifically adapted to work with the workspace's version of effect.
Because the upstream library requires a specific version of effect that may conflict with the workspace's bun-patched version, this package is maintained as a vendored copy to ensure compatibility and stability across effect beta releases.
The Maple v2 API is a structured, two-tier API surface. It uses snake_case for wire schemas and provides access to various resources including authentication, observability, and alerting.
Key Resource Groups:
api_keys (pilot), ingest_keys.traces, logs, metrics, services, service_map, session_replays.alerts/rules, alerts/destinations, alerts/incidents, alerts/deliveries.dashboards, investigations, anomalies, error_issues, scrape_targets, instrumentation/audit.attribute_mappings, organization, integrations/slack.The @maple/slack-agent is a general-purpose Slack agent built on the eve framework. It is designed to be self-deployed to Railway (not Vercel) and supports multi-workspace distribution.
Key capabilities include:
@mentions and Direct Messages (DMs).@maple/chat-flue is Maple's AI chat and headless triage system. It is built on the Flue framework and runs on Cloudflare Workers AI. It powers three primary surfaces:
/chat and the global chat sheet for general telemetry questions./investigations/*. apps/api initiates the first autonomous turn, and the browser can join the same agent instance to continue it.apps/api when an incident opens to handle automated triage.Maple is an open-source observability platform built on OpenTelemetry designed for distributed systems. It provides a unified interface for exploring:
Maple SDKs are opinionated wrappers around OpenTelemetry (OTel) designed to auto-detect platform conventions. They automatically capture metadata such as commit SHAs, deployment environments (e.g., Vercel, Cloudflare, Railway), and runtime details. This allows you to ship traces, logs, and metrics with minimal configuration, typically via a single layer() call.
Key features of an official Maple SDK include:
MAPLE_ENDPOINT is not configured, the SDK becomes a no-op, allowing local development without a Maple project.The OpenTelemetry Specification Map is a collection of documentation files used for spec-compliance checks, best-practice generation, and fact-checking.
| File | Scope |
|---|---|
traces.md | Trace API & SDK: span model, SpanKind, status, samplers, processors, span limits, ID generators |
metrics.md | Metrics API, SDK & data model: instruments, temporality, exemplars, views, exponential histograms, cardinality |
logs.md | Log data model, severity, bridge API, SDK, events-as-logs |
context-propagation.md | Context, W3C traceparent/tracestate, baggage, B3/Jaeger interop |
otlp.md | OTLP protocol: transports, partial success, retry semantics, JSON encoding, exporter env vars |
resource-and-config.md | Resource spec & merge rules, resource semconv, consolidated SDK env-var table, declarative config, entities |
semantic-conventions.md | Naming rules, requirement levels, HTTP/DB/messaging/RPC/exceptions/code/gen-ai domains, schema-URL migrations |
stability-and-compliance.md | Stability taxonomies, versioning guarantees, compliance matrix, error-handling & performance principles, instrumentation guidelines |
emerging-and-compat.md | Profiles signal, telemetry schemas deep-dive, Prometheus/OpenMetrics interop, OpenTracing/OpenCensus shims |
Maple is an open-source OpenTelemetry observability platform designed for high-speed incident triage, capacity review, and service-health checks. It surfaces traces, logs, metrics, errors, alerts, infrastructure, and service maps.
bench-queries is a CLI tool used to measure the performance cost of dashboard queries by replaying exact SQL captured from production traces. It allows you to mine recent queries from Tinybird, replay them against a ClickHouse target, inspect execution plans, and compare performance metrics (p95 wall-time, read bytes, and memory) between different runs to validate optimizations.
By default, output JSON files are saved to apps/api/scripts/.bench/ (this directory is gitignored).
# Commands
bun bench:fetch [--context name] [--profile name] [--since 24h] [--top 20] [--out path] [--org id]
bun bench:run <file> [--runs 5] [--warmup 1] [--out path]
bun bench:inspect <file>
bun bench:compare <a.json> <b.json>Choose the best ingestion method based on your deployment needs:
| Option | Description | Best For |
|---|---|---|
| Option A: Maple OTel Collector | Custom otelcol-contrib with mapleexporter. | Recommended; easiest setup, k8s metadata support. |
| Option B: Tinybird exporter + shim | Uses standard Tinybird exporter pointing to a custom shim service. | Advanced users who want to write their own shim. |
| Option C: Tinybird-Local | A Tinybird-API-compatible local server backed by ClickHouse. | Users who want the Tinybird UI side-by-side. |
| Option D: Direct INSERTs | Application sends INSERT INTO traces FORMAT JSONEachRow directly. | Small, well-defined ingest paths via custom SDKs. |
dashboard-builder skill is used when a user asks to build, add, edit, or fix Maple dashboards or specific dashboard widgets such as stats, tables, charts, or lists.The maple-otel deployment consists of:
ghcr.io/makisuo/maple/otel-collector-maple:<chart appVersion>.memory_limiter, batch, and an optional k8sattributes processor (enabled by default, which uses cluster-scoped RBAC to look up pod/namespace/deployment metadata).mapleexporter which writes to the following Maple schema tables: traces, logs, metrics_sum, metrics_gauge, metrics_histogram, and metrics_exponential_histogram.