PingOps

PingOps is an open-source observability platform for external APIs and services. Ingest OTLP telemetry, explore logs and traces, manage services and alerts, and operate multi-tenant projects from a modern dashboard—all from a single monorepo.

Status: Actively developed. Suitable for local development and early self-hosting. Production SaaS hardening and a full self-host runbook are works in progress.

---

Table of contents

• Why PingOps
• Features
• Architecture
• Repository layout
• Prerequisites
• Quick start
• Local development
• Configuration
• Common commands
• Testing and CI
• Contributing
• Security
• Documentation
• License

---

Why PingOps

Teams increasingly depend on third-party APIs (LLM providers, payments, cloud services). When those dependencies slow down or fail, product reliability suffers. PingOps is built to make external API reliability visible: who called what, how long it took, what failed, and when to alert—without bolting yet another black-box SaaS onto your stack.

---

Features

Area	What you get
Ingest	OTLP trace ingestion with API-key auth and plan-based rate limits
Analytics	High-volume log/trace storage and queries on ClickHouse
Control plane	Organizations, projects, services, API keys, alerts, MCP tools
Dashboard	Next.js UI for exploration, onboarding, billing hooks, and ops workflows
Async workers	BullMQ pipelines for ingestion, alerts, usage metering, and email
Multi-tenant	Org/project scoping with membership-aware web APIs

---

Architecture

PingOps is split into three planes:

1. Dashboard (apps/web) — user-facing UI and BFF API routes
2. Control plane (apps/api) — authenticated REST + MCP
3. Ingest plane (apps/collector) — OTLP intake and background workers

Data stores

Store	Role
PostgreSQL	Users, orgs, projects, services, alerts, API keys, auth
ClickHouse	High-volume logs, traces, metrics, analytics
Redis	BullMQ queues, scheduled jobs, rate-limit state

flowchart TB
  User["User"]
  UI["UI\nNext.js dashboard"]
  Backend["Backend\nHono REST + MCP API"]
  Application["Application\ninstrumented service"]
  SDK["SDK / OTLP exporter"]
  Collector["Collector\ntelemetry ingest API"]
  Redis["Redis + BullMQ\nqueues and rate limits"]
  Workers["Workers\ningestion, alerts, usage, email"]
  ClickHouse[("ClickHouse\nlogs, traces, metrics, analytics")]
  Postgres[("PostgreSQL\nusers, orgs, projects, services, alerts, API keys")]

  User --> UI
  UI -->|dashboard requests| Backend
  Backend -->|metadata and auth state| Postgres
  Backend -->|analytics queries| ClickHouse
  Backend -->|background jobs| Redis

  Application --> SDK
  SDK -->|OTLP traces| Collector
  Collector -->|validated ingest jobs| Redis
  Collector -->|API-key lookup and limits| Postgres
  Redis --> Workers
  Workers -->|write telemetry| ClickHouse
  Workers -->|read and update domain state| Postgres
  Workers -->|schedule alerts, usage, email| Redis

Loading

For layering rules and subsystem contracts, see docs/ARCHITECTURE.md.

---

Repository layout

pingops/
├── apps/
│   ├── web/          # Next.js dashboard + route handlers
│   ├── api/          # Hono REST + MCP control plane
│   └── collector/    # OTLP ingest API + workers
├── packages/
│   ├── db/           # Prisma schema, repositories, domain services
│   ├── clickhouse/   # Analytics client and query builders
│   ├── queue/        # BullMQ queue contracts
│   ├── env/          # Shared environment validation
│   ├── logger/       # Structured logging
│   ├── common/       # Shared utilities (e.g. rate limiter)
│   └── types/        # Shared TypeScript types
├── docs/             # Architecture, policies, exec plans
├── scripts/          # Tooling, generators, ops helpers
├── tools/            # Agent / structural lints
├── docker-compose.yml
├── .env.example
└── package.json

---

Prerequisites

Tool	Notes
Node.js	≥ 18 (repo tooling often runs via mise; see mise.toml)
pnpm	9.x (packageManager in root package.json)
Docker	For local PostgreSQL, ClickHouse, and Redis
Git	Clone and contribute

Optional: mise to pin the Node version used by this repo.

---

Quick start

1. Clone and install

git clone [email protected]:pingops-io/pingops.git
cd pingops

# Recommended if you use mise:
mise exec -- pnpm install

# Or with system Node + pnpm:
pnpm install

2. Start infrastructure

docker compose up -d

This starts PostgreSQL, ClickHouse, and Redis on local ports (see docker-compose.yml). Intended for local development only—default credentials are not production-safe.

3. Configure environment

cp .env.example .env.local

Edit .env.local and set at least:

• JWT_SECRET / BETTER_AUTH_SECRET — long random strings for local use
• DATABASE_URL / Postgres fields — match docker-compose defaults or your own
• ClickHouse + Redis hosts — defaults work with the compose stack
• SMTP + Stripe placeholders — required by env validation; use dummy values for pure UI/API local work where appropriate

See Configuration for important flags.

4. Run database migrations

mise exec -- pnpm db:migrate
# or: pnpm db:migrate

5. Start the monorepo

mise exec -- pnpm dev
# or: pnpm dev

Typical local ports:

Service	Default
Web dashboard	http://localhost:3000
Collector (ingest)	http://localhost:3001
Control plane API	http://localhost:3002

---

Local development

First login

1. Set SIGNUP_DISABLED=false and NEXT_PUBLIC_SIGNUP_DISABLED=false in .env.local if you need the signup UI.
2. Open the dashboard and create an account.
3. Create an organization/project and an API key for OTLP senders.

Do not commit real credentials or reuse production passwords.

Collector admin UI (Bull Board)

Queue admin (/admin/queues) is disabled by default. To enable locally on a trusted machine only:

ENABLE_BULL_BOARD=true
BULL_BOARD_USER=admin
BULL_BOARD_PASSWORD=choose-a-strong-password

Agent-first workflow

This repository is maintained with an agent-friendly harness. For non-trivial changes:

1. Read root AGENTS.md and any scoped AGENTS.md under apps/packages.
2. Track work in docs/exec-plans/active/ using the plan template.
3. Keep generated and canonical docs in sync.
4. Respect high-risk change classes in docs/AUTONOMY_POLICY.md.

Prefer running toolchains through mise exec -- ... so the pinned Node version is used.

---

Configuration

All runtime configuration is loaded from the project root (.env / .env.local). A complete template lives in .env.example.

Category	Examples	Notes
App	NODE_ENV, PORT, API_PORT	Collector vs API ports
PostgreSQL	DATABASE_URL, POSTGRES_*	Auth and product data
ClickHouse	CLICKHOUSE_*	Telemetry analytics
Redis	REDIS_*	Queues and rate limits
Auth	BETTER_AUTH_*, JWT_SECRET, OAuth client IDs	Session + social login
Signup	SIGNUP_DISABLED	Often true in shared envs
Email	SMTP_*	Transactional mail
Billing	STRIPE_*	Checkout / webhooks
Ops	ENABLE_BULL_BOARD, BULL_BOARD_*	Queue UI (off by default)

Never commit .env.local or production secrets. Report credential exposure via SECURITY.md.

---

Common commands

# Development
pnpm dev                 # Start apps via Turborepo
pnpm build               # Build all packages/apps
pnpm db:migrate          # Apply Prisma migrations
pnpm db:studio           # Prisma Studio

# Quality
pnpm lint                # Lint workspaces
pnpm test                # Unit tests where defined
pnpm typecheck           # TypeScript noEmit across packages
pnpm format              # Biome format
pnpm agent:check         # Format + lint + test + docs + soft agent lints

# Docs (generated surfaces + drift)
pnpm docs:generate
pnpm docs:lint
pnpm docs:drift
pnpm docs:check

# UI smoke (Chrome DevTools Protocol)
pnpm ui:smoke:cdp

With mise:

mise exec -- pnpm agent:check

---

Testing and CI

• Unit tests live next to packages/apps (Vitest where configured).
• UI smoke uses CDP (pnpm ui:smoke:cdp).
• CI runs on push/PR via .github/workflows/tests.yml (lint, test, docs, agent soft checks, optional UI smoke).

Soft agent/docs jobs can be made blocking by setting the repository variable AGENT_ENFORCEMENT_MODE=hard.

---

Contributing

Contributions are welcome once the project is open for external PRs.

1. Fork and create a feature branch from main.
2. Follow code style and boundaries in the relevant AGENTS.md / docs/*.
3. Prefer small, reviewable PRs with tests for behavioral changes.
4. High-risk areas (auth, billing, migrations, secrets, CI permissions) require careful human review—see docs/SECURITY.md and docs/AUTONOMY_POLICY.md.
5. Open a PR with a clear problem statement and validation notes.

A dedicated CONTRIBUTING.md and issue/PR templates may be added as the community process matures. Until then, this README and docs/ are the source of truth.

---

Security

Please do not open public issues for vulnerabilities.

Report security problems privately using the process in SECURITY.md.

---

Documentation

Doc	Description
docs/ARCHITECTURE.md	System boundaries and layering
docs/SECURITY.md	Engineering security policy
SECURITY.md	Vulnerability disclosure
docs/RELIABILITY.md	Reliability objectives
docs/PLANS.md	Execution-plan workflow
docs/FRONTEND.md	Web conventions
docs/README.md	Full docs index
AGENTS.md	Agent / contributor harness

---

License

This project is licensed under the MIT License.

Copyright © 2026 ByteForge and PingOps contributors.