micsapp Linear Debug Bundle
Contents
Overview
Comprehensive debugging tools for Linear API integrations: debug client wrapper with request/response logging, request tracer with performance metrics, health check endpoint, interactive debug console, and environment validator.
Prerequisites
- Linear SDK configured
- Node.js environment
- Optional: logging library (pino, winston)
Instructions
Step 1: Create Debug Client Wrapper
Build createDebugClient() that wraps LinearClient with a custom fetch interceptor. Log all requests (query preview + variables), responses (duration, error presence, data keys), and errors (duration, message). Support onRequest, onResponse, and onError callback hooks for custom integrations.
Step 2: Request Tracer
Implement LinearTracer class that records trace entries (id, operation, start/end time, duration, success, error, metadata). Provide startTrace()/endTrace() lifecycle, getSlowTraces(thresholdMs) for performance analysis, getFailedTraces() for error tracking, and getSummary() for aggregate stats (total, completed, failed, avg/max duration). Cap at 100 traces with automatic trimming.
Step 3: Health Check Utility
Create checkLinearHealth() that parallel-fetches viewer info and teams, returning latency, user details, team count, and healthy/unhealthy status. Expose as an Express/Koa endpoint via healthEndpoint() returning 200 or 503.
Step 4: Debug Console Commands
Build an interactive REPL with readline that provides commands: me (current user), teams (list teams with keys), issues (recent 10 issues), states (workflow states per team), help, and exit.
Step 5: Environment Validator
Create validateLinearEnv() that checks LINEAR_API_KEY presence and format (lin_api_ prefix), warns about missing LINEAR_WEBHOOK_SECRET, and flags non-production keys in production environments. Auto-run on import with console output.
See detailed implementation for complete debug client, tracer, health check, CLI console, and environment validator code.
Output
- Debug client with request/response logging
- Request tracer with performance metrics
- Health check endpoint (200/503)
- Interactive debug console (REPL)
- Environment validator with warnings
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Circular JSON | Logging full Linear objects | Use selective logging |
| Memory leak | Unbounded trace storage | Set maxTraces limit |
| Missing env | Validation failed | Check environment setup |
Examples
Basic usage: Apply linear debug bundle to a standard project setup with default configuration options.
Advanced scenario: Customize linear debug bundle for production environments with multiple constraints and team-specific requirements.
Resources
Next Steps
Learn rate limiting strategies with linear-rate-limits.