@agimon-ai/po-logsink

Log sink MCP server with HTTP ingestion and AI analysis

Packages

Package details

extension

Install @agimon-ai/po-logsink from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@agimon-ai/po-logsink
Package
@agimon-ai/po-logsink
Version
0.0.1-alpha.152
Published
Nov 19, 2026
Downloads
83K/mo · 18.3K/wk
Author
agiflow-ai
License
BUSL-1.1
Types
extension
Size
1.9 MB
Dependencies
26 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./dist/extensions/pi.mjs"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@agimon-ai/po-logsink

HTTP/OTLP telemetry collection, SQLite storage, and bounded log, trace and usage queries. This is Po's workspace port of @agimon-ai/log-sink-mcp.

Storage requires Node.js 22.13 or newer for node:sqlite. The /telemetry/node export can be used by Node.js 20 applications, but installation still observes this package's engine requirement.

Investigate without changing the collector

Po agents use the logsink code-mode namespace supplied by @agimon-ai/po-log and its codemode-how-to-logsink guide, not a per-agent MCP server. Start with the current session; select an explicit bounded window for historical analysis.

The standalone CLI queries existing telemetry. Run it from the application's repository and keep the same local/global selector throughout an investigation:

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 '<run-id>' --limit 20

Use logs metrics for token, workflow and per-tool consumption, logs stats for grouped counts, and logs services for service discovery. Each command's --help lists its current filters. Search supports structured filters and FTS; optional semantic/hybrid search needs separately enabled embeddings. A missing sink or empty result is not proof of a healthy run.

Keep the existing HTTP/OTEL collector under its lifecycle owner. Do not clear evidence, restart a shared collector, or kill a process to diagnose an incident. The CLI's logs clear is destructive, not a troubleshooting step.

Collector setup

Operators can install the package and explicitly start HTTP collection:

pnpm add -g @agimon-ai/po-logsink
po-logsink start --http-only
po-logsink status
po-logsink port --all --no-health-check

Use the reported port rather than assuming one. start coordinates a singleton collector through the port/process registries. Without --http-only, it also starts a stdio MCP transport. mcp-serve is the compatibility stdio entry; it can ensure the collector is running. It does not offer the old HTTP/SSE MCP transport flags.

The collector binds loopback. Its HTTP app has no built-in authentication boundary; do not expose its ingestion or dashboard APIs publicly without an independently managed access-control layer. Input validation, rate limits and CORS are not authorization.

The HTTP collector owns sampling and retention. --db-max-bytes, --db-target-bytes, --db-retention-interval-ms and --db-retention-batch-size configure trimming. Clients forward these settings rather than starting competing retention writers. Spawned collectors append to http.log beside the database; logs larger than 5 MiB rotate at spawn, not continuously.

stop is an operator lifecycle action. Changing a database path does not migrate old records. Preserve the old database before an authorized collector reconfiguration.

Local and shared instances

By default, instance resolution is repository-local. A .logsink.yaml can select a shared instance for exact service names:

global:
  port: 3100
  services:
    - '@agimon-ai/po-logsink'
    - '@agimon-ai/mcp-proxy'
    - '@agimon-ai/po-workflow'

Unlisted names stay local. Omit global.port for registry allocation. Use --instance local or --global to choose explicitly for one command.

Configuration lookup is --config or LOG_SINK_CONFIG, then the nearest .logsink.yaml above the working directory, then ~/.logsink.yaml. The shared database defaults to ~/.po-logsink/global/session.db; local data lives under <tmpdir>/po-logsink/<worktree>/session.db. Old files are not migrated or backfilled.

Compatibility retains the LOG_SINK_* settings, embedding caches and log-sink-mcp-http service key. The shared registry uses ~/.log-sink-mcp/global and the development environment. Existing shared registrations for @agimon-ai/log-sink-mcp also apply to this port. Here --global names a collector instance, not a Po server scope.

Ingestion and privacy

POST /logs accepts { logs: [...] }; each entry needs level, non-empty message and service. Optional fields include ISO timestamps, metadata, error details and session/workflow identities. Trace IDs are 32 hexadecimal characters; span IDs are 16. POST /v1/logs and /v1/traces accept OTLP JSON. GET /health reports collector health. The schema and limits live in src/server/http.ts.

Telemetry can contain private application data even when described as metadata. Review exporters and destinations before enabling them.

Setting Effect
LOG_SINK_ENDPOINT Explicit running collector endpoint
OTEL_EXPORTER_OTLP_ENDPOINT Standard OTLP endpoint; signal-specific variants take precedence
OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TIMEOUT Export headers and timeout; signal-specific variants are supported
OTEL_SDK_DISABLED Disable OpenTelemetry export
AGENT_TELEMETRY_DISABLED=1 Disable the Pi telemetry extension
AGENT_OTEL_TRACES Enable span export alongside logs
AGENT_OTEL_REDACT=0 Include sensitive prompt/tool payloads at the exporter
LOG_SINK_ALLOW_SENSITIVE_TELEMETRY Permit payload fields at ingestion; hard-sensitive keys remain redacted
LOG_SINK_PI_FILE_FALLBACK=1 Opt into file fallback when no sink is reachable
LOG_SINK_FILE_MAX_BYTES, LOG_SINK_FILE_MAX_FILES File-backend rotation limits
LOG_SINK_ENABLE_EMBEDDINGS Opt into local embedding model loading and semantic indexing

Prompts and tool payloads are omitted by default. Collector sanitization is a further filter, not a guarantee that arbitrary strings contain no secrets. Pi telemetry drops records when no sink is reachable unless file fallback is explicitly enabled. The extension registers no commands or tools and does not let exporter failures end the agent session.

AGENT_SESSION_ID, PARENT_AGENT_SESSION_ID and WORKFLOW_* correlation fields support scoped queries. Verify their coverage before treating attribution or token totals as complete. Optional embeddings require ruvector-onnx-embeddings-wasm; without it, the collector falls back to FTS.

Read-only library queries

Use createAsyncLogQueryReader({ dbPath }) with an admitted absolute database path. It exposes status, search, agentIssues, trace, stats, services and metrics, with detached JSON results and optional abort signals. Close it in finally. Cancellation, timeout or disposal terminates the worker and rejects pending queries.

import { createAsyncLogQueryReader } from '@agimon-ai/po-logsink';

const reader = createAsyncLogQueryReader({ dbPath });
try {
  const result = await reader.search({ sessionId, limit: 20 });
  console.log(result);
} finally {
  await reader.close();
}

The reader opens an existing database read-only. It does not create directories or databases, migrate schemas, build indexes or write semantic caches. SQLite may still coordinate WAL/SHM sidecars to read live records. Search supports structured filters and FTS only. A missing database is reported separately from empty successful data.

All query methods accept session/time filters, but the library does not authorize them: embedding hosts must enforce scope. resolveGlobalLogQueryDbPath(homeDirectory) resolves the shared path without creating it. @agimon-ai/po-logsink/queryContracts provides host-neutral input schemas and types. Worker-backed metrics also remain available through createAsyncLogMetricsReader; synchronous readers belong in worker/server contexts, not latency-sensitive UI paths.

Troubleshooting and development

For missing records, check instance selection, status, endpoint configuration and the collector log. For database locks, check for competing writers and filesystem permissions; use separate databases for tests. Do not delete registry files or logs as a first response.

pnpm exec nx run-many -t lint typecheck build test -p @agimon-ai/po-logsink

CLI commands live in src/commands, ingestion in src/server/http.ts, read-only APIs in src/api, storage/query logic in src/services, and Pi export in src/extensions/piTelemetry.ts.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.