Agent skill · software engineering · aiskillstore
storage-debug-instrumentation
Add comprehensive debugging and observability tooling for backend storage layers (PostgreSQL, ChromaDB) and startup metrics. Includes storage drift detection, raw data inspection endpoints, and a Next.js admin dashboard.
Why this skill is useful
Adds comprehensive executable scripts for backend storage instrumentation and debugging that enhance observability and performance diagnostics.
What it needs
Requires fastapi, nextjs installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Storage Debug Instrumentation Purpose Enable rapid diagnosis of storage state, synchronization health, and backend performance bottlenecks by exposing: Raw article inspection from both PostgreSQL and ChromaDB Storage drift detection (missing/dangling entries) Detailed startup timeline breakdown (DB init, cache preload, vector store, RSS refresh) One-page debug dashboard consolidating all diagnostics Scope Backend: app/services/startupmetrics.py, app/main.py, app/vectorstore.py, app/database.py, app/api/routes/debug.py Frontend: frontend/lib/api.ts, frontend/app/debug/page.tsx No schema changes; purely additive instrumentation and debug routes Workflow 1. Create startup metrics service File: backend/app/services/startupmetrics.py Implement thread-safe StartupMetrics class to record phase timings Expose recordevent(name, startedat, detail, metadata) for phase capture Support addnote(key, value) for arbitrary annotations Export singleton startupmetrics for app-wide use 2. Instrument vector store initialization File: backend/app/vectorstore.py Import startupmetrics In VectorStore.init(), wrap initialization with time.time() timer Record event with metadata: host, port, collection, documents Catch connection errors and annotate them 3. Instrument FastAPI startup sequence File: backend/app/main.py Call startupmetrics.markappstarted() at beginning of onstartup() Wrap each phase (DB init, schedulers, cache preload, RSS refresh, migration) with recordevent() Include metadata: cachesize, articlecount, oldestarticlehours Call startupmetrics.markappcompleted() at end Add app version notes via addnote() 4. Add database pagination helpers File: backend/app/database.py Implement fetcharticlespage() to support: Limit/offset pagination Optional source filter Missing-embeddings-only flag Published date range filters Sort direction (asc/desc) Return oldest/newest timestamp bounds Implement fetcharticlechromamappings() to return all article→chroma ID mappings for drift analysis 5. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/storage-debug-instrumentation