@agimon-ai/po-logsink weekly downloads statistics

po-logsink

AI-powered log analysis MCP server with HTTP ingestion and SQLite storage.

Runtime requirement: Node.js 22.13 or newer. Log storage uses the built-in node:sqlite module, which is unavailable on Node.js 20. Other servers that use this package's /telemetry/node export may run on Node.js 20, but strict engine checks still apply to the installed log-sink package.

Agent integration: skill and CLI

Po agents use the logsink code-mode namespace supplied by @agimon-ai/po-log and its packaged codemode-how-to-logsink guide, not a dedicated MCP connection. The CLI remains available for standalone investigations. Run it from the application's repository so configuration and instance resolution match the existing collector.

po-logsink status
po-logsink logs search 'timeout' --mode fts --limit 20
po-logsink logs trace '<trace-id>'
po-logsink logs agent-issues --global --workflow-run-id '<workflow-run-id>' --limit 20

Use the same local/global instance selector for every query. Query commands reuse stored telemetry without starting a per-agent server. Keep the HTTP/OTEL ingestion service running under its existing lifecycle owner. Never clear logs or restart a shared collector to inspect an incident. The MCP interface documented below remains available for compatibility and transport testing.

Read-only programmatic queries

createAsyncLogQueryReader({ dbPath }) exposes status, search, agentIssues, trace, stats, services, and metrics with structured JSON results and ISO timestamps. Pass an admitted absolute database path; resolveGlobalLogQueryDbPath(homeDirectory) resolves Po's global path without creating directories. Query methods accept an optional AbortSignal; close the reader in finally. Cancellation, timeout, or disposal terminates its worker and rejects pending queries.

The reader opens an existing database with SQLite readOnly: true. It never creates the database or parent directories, migrates schema, builds indexes, or writes semantic caches. SQLite may create or coordinate its own WAL/SHM sidecars so live WAL records remain visible. A missing database is distinct from an empty successful result. Search supports structured filters and FTS only; existing CLI/MCP semantic modes are unchanged.

All methods accept session/time filters, including trace and service reads. The library does not authorize those selectors: embedding hosts must enforce their own scope policy. Po Log defaults to the current session and requires explicit bounded history selection. The host-neutral @agimon-ai/po-logsink/queryContracts subpath exports LOG_QUERY_INPUT_SCHEMAS, parseLogQueryInput, and input/result types without importing Node infrastructure.

Overview

po-logsink provides a complete log analysis solution for AI assistants like Claude. It combines:

• HTTP Server: REST endpoint for log ingestion from any application
• MCP Server: 5 application-focused tools for searching/filtering, tracing, and inspecting logs
• CLI Analysis Commands: Local shell commands for deeper error and agent-issue analysis
• Pi Extension: Ships a Pi extension that exports the agent's own session telemetry into the sink
• SQLite Database: Fast local storage with FTS5 full-text search plus cached local embeddings
• Real-time Analysis: Query logs, trace distributed requests, analyze error patterns

Perfect for debugging, monitoring, and understanding application behavior through AI-powered analysis.

Features

• ✅ HTTP Log Ingestion: POST logs from any application via REST API
• ✅ 5 MCP Tools: Search/filter, trace, agent-issue analysis, and inspect stats/services
• ✅ Agent Telemetry: Pi extension records prompts, turns, tool calls, token usage, and cost
• ✅ Hybrid Search: FTS5-powered search plus optional local semantic retrieval across messages and errors
• ✅ Distributed Tracing: Timeline view for trace IDs and span relationships
• ✅ Error Analysis: Pattern detection and error categorization
• ✅ Structured Logging: JSON metadata, trace IDs, span IDs
• ✅ Auto-Migration: Drizzle ORM with automatic schema migrations
• ✅ Type-Safe: Full TypeScript coverage with Drizzle schema inference

Architecture

┌─────────────┐        HTTP POST         ┌─────────────────┐
│ Application │ ───────────────────────> │  HTTP Server    │
│  (Pino,     │     /logs endpoint       │  (Hono)         │
│  Winston)   │                          │  Port 3100      │
└─────────────┘                          └────────┬────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │  LogStorage     │
                                         │  Service        │
                                         └────────┬────────┘
                                                  │
                                                  ▼
┌──────────────┐       MCP Protocol      ┌─────────────────┐
│   Claude /   │ <─────────────────────> │   MCP Server    │
│   AI Agent   │    5 App Log Tools      │   (stdio)       │
└──────────────┘                         └────────┬────────┘
                                                  │
                                                  ▼
                                         ┌─────────────────┐
                                         │ SQLite + FTS5 + │
                                         │  local vectors   │
                                         │  ./logs/        │
                                         │  session.db     │
                                         └─────────────────┘

Singleton HTTP Server Management

po-logsink implements automatic singleton coordination to prevent port conflicts when multiple MCP servers run concurrently.

How It Works…