GitHub - shinzo-labs/shinzo: Complete observability platform for AI agents and MCP servers. Improve your AI deployment outcomes, identify inference inefficiencies, and gain insights into real agent usage patterns.

🤖 About Shinzo

Shinzo is an open source observability platform that enables developers to ingest and analyze the performance data of their agentic AI systems. All data is OpenTelemetry compliant and can be connected to other OpenTelemetry-compatible software.

🏗️ Platform Architecture

• OpenTelemetry Collector: High-performance OpenTelemetry backend service that ingests and serves telemetry data from agent interactions.
• Postgres Database: Stores OpenTelemetry data efficiently and securely.
• Analytics Web App: Frontend dashboard for real-time analytics, trace analysis, performance profiling, tool usage stats, and more.

⚙️ Installation

Prerequisites

Database

• PostgreSQL 15+ (running externally, not in Docker)
• See db/README.md for setup instructions

Docker Deployment

• Docker
• Docker Compose

Local Development

• Node.js 18+
• pnpm

Env Configs

Fill out env files with given variables:

• .env
• backend/.env
• frontend/.env

Quick Start

1. Database Setup

Follow steps in db/README.md to set up your external PostgreSQL database.

2. Environment Configuration

Copy the example environment files and update them:

# Backend configuration
cp backend/.env.example backend/.env
# Edit backend/.env with your database URL and other settings

# Frontend configuration
cp frontend/.env.example frontend/.env
# Edit frontend/.env with your API URL and other frontend settings

Important Port Configuration:

• Backend runs on port 8000 (configurable via BACKEND_PORT)
• Frontend runs on port 3000 (configurable via PORT in frontend/.env)
• OpenTelemetry GRPC on port 4317 (configurable via OTEL_GRPC_PORT)
• OpenTelemetry HTTP on port 4318 (configurable via OTEL_HTTP_PORT)

3. Local Development

# Install dependencies
cd backend && pnpm install

# Start the backend
pnpm start

4. Docker Deployment

# Start supporting services (Redis, Kafka)
docker-compose up -d redis kafka

# Or start all services including backend and frontend
docker-compose up --build -d

5. Verify Setup

Check that the backend is running:

curl http://localhost:8000/health

Managing Services

Stop all services

Start specific service

docker-compose up -d <backend|frontend|redis|kafka>

View logs

docker-compose logs -f <service-name>

Troubleshooting

Database Connection Issues

• Local development: Use localhost in your DATABASE_URL
• Docker backend connecting to host database: Use host.docker.internal instead of localhost in DATABASE_URL
• Connection refused: Ensure PostgreSQL is running and accepting connections on the correct port
• Authentication failed: Verify username, password, and database name in DATABASE_URL

Docker Issues

• If using sudo with docker-compose, use sudo -E to preserve environment variables
• Ensure pnpm is up-to-date: pnpm up --latest
• For build issues, try: docker-compose build --no-cache

Environment Variables

• Copy .env.example files and customize them for your environment
• Ensure JWT_SECRET is set to a secure value in production
• Verify all required environment variables are set

🗺️ Roadmap

Note: For the complete roadmap timeline with all issues, see the Roadmap page on Github.

• ✅ Phase 0 (June 2025)

  • ✅ 🏗️ System Architecture Design
  • ✅ 🤝 Contributor Operations

• ✅ Phase 1 (July 2025)

  • ✅ 📏 OpenTelemetry MCP Semantic Conventions
  • ✅ 🛠️ TypeScript Instrumentation SDK

• ✅ Phase 2 (August 2025)

  • ✅ 📡 Telemetry Collector
  • ✅ 📊 Analytics Dashboard

• ✅ Phase 3 (September 2025)

  • ✅ 🐍 Python Instrumentation SDK
  • ✅ 🏅 SOC2 Type II Kick-Off

• ⬜️ Phase 4 (Q4 2025)

  • ✅ 🟡 Token Analytics
  • ✅ 🛡️ Session Management Insights
  • ⬜️ 🧠 Agent Interaction Analytics

• ⬜️ Phase 5 & Beyond (Q1 2026)

  • ⬜️ 🏅 SOC2 Type II Certification
  • ⬜️ 🧠 Agentic Recommendations
  • ⬜️ 🦦 Go MCP Instrumentation SDK
  • ⬜️ 💠 C# MCP Instrumentation SDK

• ⬜️ Phase 6 (Q2 2026+)

  • ⬜️ 🚀 AI Routing Gateway
  • ⬜️ 🚨 Incident Alerting System
  • ⬜️ ☕ Java MCP Instrumentation SDK
  • ⬜️ 🦀 Rust MCP Instrumentation SDK

🤝 Contributing

Contributions to Shinzo are appreciated, whether you are a veteran building sophisticated enterprise AI agent systems or a newcomer just testing the waters. Shinzo accepts contributions both in terms of direct code contributions as well as non-technical support like community engagement, user testing, and professional partnerships. Feel free to join the conversation on our Discord server and checkout the Contributing page to learn how you can become a contributor.

📄 License

Shinzo is fair-code software distributed under the Sustainable Use License and Shinzo Enterprise License.

• Source Available: Always visible source code
• Self-Hostable: Deploy anywhere
• Extensible: Add your own features or functionality

Enterprise licenses are available for additional features and support through Shinzo Labs.

We believe that the fair-code license model offers a strong compromise between democratizing the benefits of open software while ensuring long-term sustainability of software maintenance and operations. Our specific license model is adapted from n8n, with additional context for the origin of the licenses here.

Some of this software's capabilities enable developers and businesses to collect data on usage of products by respective end users. Shinzo Labs accepts no responsibility for how this software is used by other developers, and by using this software you accept all terms of the relevant licenses, including the section on No Liability.

📞 Contact

Contact Austin Born (austin@shinzolabs.com, @austinbuilds) if you have any questions or comments related to this software.

📚 Additional Resources

• Model Context Protocol
• OpenTelemetry

(back to top)