Sentro

🎉 v0.2.0 just shipped — OpenTelemetry ingestion, LLM proxy mode, prompt management, evals, drift alerts, session replay, playground, and more. See the changelog.

Open source, self-hosted, agent-first observability.

Sentro is an open-source error tracking and observability platform designed from the ground up for AI agents. Error tracking, performance monitoring, alerting, plus first-class agent observability: run tracing, step-by-step replay, tool call monitoring, LLM call tracking, and cost analysis. MIT licensed, runs anywhere Docker runs.

See what your agent was thinking when it broke — and how much it cost you.

Why Sentro?

Built for agents from day one, not bolted on. Open source and self-hosted — you own your data.

Agent-first data model — run → step → tool_call / llm_call is the core primitive, not an add-on to spans
Step replay — see the exact reasoning chain, which tools were called, what inputs/outputs were passed, where it went wrong
LLM call tracking — model, provider, tokens, cost, latency per call
Tool call monitoring — inputs, outputs, latency for every tool the agent used
Token & cost tracking — know what each run costs, set budgets, alert on pace
Event webhooks — 5 event types with HMAC signing and filters, so other agents can react
Prompt management + evals — version prompts, score runs with human or LLM judges
OTLP ingestion — accept OpenTelemetry traces from any OTEL-instrumented app
MIT licensed — self-host on your infra, no usage fees, no lock-in

Quick Start

git clone https://github.com/yzzztech/sentro.git
cd sentro
docker compose up -d

Open http://localhost:3000, create your admin account, and you're live.

Or deploy to a hosted platform

Platform	How
Railway	New project → Deploy from GitHub → point at this repo. Railway reads `docker-compose.yml` and provisions Postgres automatically.
Fly.io	`fly launch` from the repo root. The bundled `Dockerfile` is detected; provision a `fly postgres` cluster and set `DATABASE_URL`.
Render	New Web Service from this repo (Docker), plus a managed Postgres. Wire `DATABASE_URL` in the env tab.
Any Docker host	The image builds to a single standalone Next.js container. Point it at any Postgres 14+ with the right `DATABASE_URL`.

After first boot on any platform, run npx prisma db push against the target database (or let the container do it on its first start if you add that to your platform's release command).

Framework Integrations — Plug and Play

One-line drop-ins for popular agent frameworks. See packages/integrations for details.

Framework	Install	Type
Claude Code	`curl -fsSL https://raw.githubusercontent.com/yzzztech/sentro/main/packages/integrations/claude-code/install.sh \| bash -s -- "DSN"`	Shell hook
OpenClaw	`curl -fsSL https://raw.githubusercontent.com/yzzztech/sentro/main/packages/integrations/openclaw/install.sh \| bash -s -- "DSN"`	SKILL.md
LangChain	`pip install sentro-sdk` → `from sentro.integrations.langchain import SentroMiddleware`	Python middleware
CrewAI	`pip install sentro-sdk` → `from sentro.integrations.crewai import SentroCrewListener`	Event listener
Vercel AI SDK	`npm install @sentro/sdk` → `import { sentroMiddleware } from '@sentro/sdk/vercel-ai'`	TypeScript middleware
Any OTEL-instrumented app	Point OTLP exporter at `POST /api/v1/traces` with Bearer token	OpenTelemetry ingestion

OpenTelemetry (OTLP)

Works with any OpenTelemetry-instrumented app — OpenLLMetry, Traceloop, OpenInference, or raw OTEL SDKs. No Sentro SDK required.

# Point your OTLP exporter at Sentro
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3000/api/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_DSN_TOKEN"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"

Sentro maps OTLP spans to its data model automatically — LLM spans (gen_ai.* attributes) become LLM calls, tool spans (tool.*) become tool calls, and root spans become agent runs.

Features

Core Observability

Error tracking — fingerprinted issue groups, stack traces, affected runs
Agent run tracing — goal, model, trigger, full step-by-step replay
Tool call monitoring — inputs, outputs, latency per tool
LLM call tracking — model, provider, tokens, cost per call
Step timeline — vertical timeline of every step the agent took, with expandable tool and LLM call details
Session replay — animated timeline scrubber with play/pause, 1x-10x speed, click-to-seek

Integrations

OpenTelemetry (OTLP) — accept traces from any OTEL-instrumented app
LLM proxy mode — zero-code instrumentation via /api/v1/proxy/*
Framework adapters — Claude Code, OpenClaw, LangChain, CrewAI, Vercel AI SDK

Workflow

Prompt management — version, tag (production/staging), and fetch prompts via SDK with dashboard version promotion
Session grouping — thread related runs (e.g., chat turns) into sessions with dashboard UI
Scoring & evals — human, LLM-as-judge, and programmatic scoring with aggregate stats dashboard
Dataset evaluations — sentro.runEval() / sentro.run_eval() with built-in evaluators (exactMatch, contains, regexMatch)
Playground — edit and re-run any LLM call from the UI with your own API key
Datasets — save runs as test fixtures for regression testing, with dashboard UI
Drift & guardrail alerts — auto-detect looping agents, token burn, repeated tool calls
Event webhooks — error.new, run.failed, cost.spike, drift_detected (HMAC signed)
Alerts — error spike, failure rate, cost threshold with webhook notifications

Operational

Self-hosted — single docker compose up
PostgreSQL — no Redis, ClickHouse, or Kafka required for v1
Security hardened — SSRF protection, rate limiting, session cleanup, CORS
Open source — MIT licensed

SDK — 5 Lines to Full Agent Observability

npm install @sentro/sdk

Track errors

import { Sentro } from '@sentro/sdk';

const sentro = new Sentro({ dsn: 'http://token@localhost:3000/api/ingest/proj_1' });

sentro.captureException(new Error('Payment failed'));

Track agent runs — built for agents from day one

const result = await sentro.trace('order-processor', {
  goal: 'Process refund for order #456',
  model: 'claude-sonnet-4-6',
}, async (run) => {

  return await run.trace('Looking up order', async (step) => {
    // Track tool calls
    const order = await step.traceToolCall('database.query', 
      { sql: 'SELECT * FROM orders WHERE id = 456' },
      async () => db.query('SELECT * FROM orders WHERE id = 456')
    );

    // Track LLM calls
    const llm = step.llmCall({ model: 'claude-sonnet-4-6' });
    const decision = await callLLM('Should we approve this refund?');
    llm.end({ promptTokens: 150, completionTokens: 20, cost: 0.001 });

    return decision;
  });
});
// Automatically captures: duration, tokens, cost, success/failure

Python SDK

pip install sentro-sdk

Zero dependencies. Pythonic context managers. Async support.

from sentro import Sentro

sentro = Sentro(dsn="http://token@localhost:3000/api/ingest/proj_1")

# Error tracking
sentro.capture_exception(error)

# Agent observability with context managers
with sentro.trace("order-processor", goal="Process refund #456") as run:
    with run.trace("Looking up order") as step:
        with step.trace_tool_call("db.query", input={"sql": "SELECT 1"}) as tool:
            result = db.query("SELECT 1")
            tool.set_result(result)
        
        llm = step.llm_call(model="claude-sonnet-4-6")
        response = call_llm("Approve refund?")
        llm.end(prompt_tokens=150, completion_tokens=20, cost=0.001)
# Auto-ends on exit, auto-errors on exception

The Dashboard

Create a project, grab the DSN, and every run you trace shows up here.

Issues — error tracking

Errors grouped by fingerprint, with event counts, recency, and a badge showing how many agent runs were affected.

Agent Runs — the flagship view

Every agent execution with: status, step count, duration, cost, and token usage. Stats bar shows success rate, total cost, and aggregate metrics.

Step Replay — the killer feature

A vertical timeline of every step the agent took. Expand each step to see tool call inputs/outputs and LLM call details. See exactly where and why the agent failed.

Performance

Slowest tool calls, LLM latency by model, cost breakdown. Find the bottlenecks in your agent's workflow.

Alerts

Three alert types: error spike, agent failure rate, cost threshold. Webhook notifications to Slack, Discord, PagerDuty, or anywhere.

Architecture

[Your Agents] → [@sentro/sdk] → POST /api/ingest → [Next.js App] → [PostgreSQL]
                                                     ├── Dashboard UI
                                                     ├── REST API
                                                     └── Background Jobs (pg-boss)

Deployment: docker compose up → 2 containers (app + postgres)

Scalability-ready monolith. Simple to deploy today, designed to scale tomorrow:

Stage	What changes
v1 (now)	App + Postgres — `docker compose up`
v1.5	Add Redis for caching + job queue
v2	Separate ingestion service
v2.5	Add ClickHouse for event analytics

Tech Stack

TypeScript everywhere — one language, frontend to SDK
Next.js 15 App Router — SSR dashboard + API in one process
PostgreSQL — JSONB for flexible payloads, battle-tested
Prisma — type-safe database access
Tailwind CSS + dark theme — looks good out of the box
pg-boss — Postgres-backed job queue, no Redis needed for v1
Docker Compose — self-hosted in one command

Core Data Model

project
  ├── event_groups (deduplicated issues)
  │    └── events (individual errors/logs)
  ├── agent_runs
  │    └── steps (ordered reasoning chain)
  │         ├── tool_calls (with inputs, outputs, latency)
  │         └── llm_calls (with tokens, cost, latency)
  └── alert_rules
       └── alert_history

The run → step → tool_call/llm_call hierarchy is the core differentiator. It maps directly to how agents actually work.

Documentation

Full documentation available at /docs when running, or open apps/web/public/docs/index.html directly.

Covers: SDK guide, dashboard walkthrough, API reference, configuration, self-hosting, and architecture.

Configuration

Variable	Default	Description
`DATABASE_URL`	—	PostgreSQL connection string
`SESSION_SECRET`	—	Secret for session cookies
`NEXT_PUBLIC_APP_URL`	`http://localhost:3000`	Public URL of the app

Per-project settings (configurable via API/dashboard):

Retention days — how long to keep event data (default: 30)
Rate limit — max events per minute per project (default: 1000)

Event Webhooks — Agents Monitoring Agents

Sentro fires real-time webhooks when things happen, so other agents can react automatically.

Event	Fires when
`error.new`	First occurrence of a new error
`error.regression`	A resolved error comes back
`run.failed`	An agent run fails or times out
`run.completed`	Any agent run finishes
`cost.spike`	A run exceeds your cost threshold

Rich payloads — every webhook includes full context (error details, run steps, token counts, cost) so the receiving agent can act without calling back.

HMAC signing — optional X-Sentro-Signature header for payload verification.

Filters — scope webhooks by agent name, error level, or cost threshold.

Example: auto-create GitHub issues on new errors

Sentro → error.new webhook → your agent → gh issue create

Roadmap

Contributing

Sentro is open source. PRs welcome.

# Development
git clone https://github.com/yzzztech/sentro.git
cd sentro
npm install
docker run --name sentro-db -e POSTGRES_USER=sentro -e POSTGRES_PASSWORD=sentro -e POSTGRES_DB=sentro -p 5432:5432 -d postgres:16-alpine
cd apps/web && npx prisma db push
cd ../.. && npm run dev

License

MIT

Sentro — because your agents deserve better than stack traces.

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
.github/workflows		.github/workflows
apps/web		apps/web
docs		docs
packages		packages
tools/migrate-from-sentry		tools/migrate-from-sentry
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
BACKLOG.md		BACKLOG.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
sentro-docs.html		sentro-docs.html
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Sentro

Open source, self-hosted, agent-first observability.

Why Sentro?

Quick Start

Or deploy to a hosted platform

Framework Integrations — Plug and Play

OpenTelemetry (OTLP)

Features

Core Observability

Integrations

Workflow

Operational

SDK — 5 Lines to Full Agent Observability

Track errors

Track agent runs — built for agents from day one

Python SDK

The Dashboard

Issues — error tracking

Agent Runs — the flagship view

Step Replay — the killer feature

Performance

Alerts

Architecture

Tech Stack

Core Data Model

Documentation

Configuration

Event Webhooks — Agents Monitoring Agents

Roadmap

Contributing

License

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages