@lineai/diagnose-log

Errors as structured messages to an agent.

When something fails, an agent will read the log, open the suspect files, and diagnose. The contract below is designed to give the agent everything it needs to start work — not to be skimmed by a human in a log viewer.

Install

pnpm add @lineai/diagnose-log

Usage

import { createDiagnoseLogger } from '@lineai/diagnose-log';

const log = createDiagnoseLogger({ service: 'service-api' });

try {
  await verifyStripeSignature(req);
} catch (err) {
  log.diagnose({
    msg: 'Stripe webhook signature verification failed',
    tag: 'webhook',
    suspectFiles: ['src/webhooks/stripe.ts', 'src/lib/stripe-config.ts'],
    suspectSymbols: ['verifyStripeSignature', 'getWebhookSecret'],
    reproSteps: 'POST /webhooks/stripe with a stale Stripe-Signature header',
    recentChanges: ['abc123: rotated webhook secret on 2026-04-15'],
    context: { eventId: req.headers['stripe-event-id'], receivedAt: Date.now() },
    err,
  });
  throw err;
}

What this produces

A single line of structured JSON, written via console.log. On Cloud Run / Cloud Functions / GKE with the Logging agent, the severity field is parsed and the rest lands in jsonPayload:

{
  "severity": "ERROR",
  "timestamp": "2026-04-17T17:42:00.123Z",
  "service": "service-api",
  "agentDiagnose": true,
  "diagnoseTag": "webhook",
  "message": "Stripe webhook signature verification failed",
  "suspectFiles": ["src/webhooks/stripe.ts", "src/lib/stripe-config.ts"],
  "suspectSymbols": ["verifyStripeSignature", "getWebhookSecret"],
  "reproSteps": "POST /webhooks/stripe with a stale Stripe-Signature header",
  "recentChanges": ["abc123: rotated webhook secret on 2026-04-15"],
  "context": { "eventId": "evt_...", "receivedAt": 1747000000000 },
  "err": { "name": "Error", "message": "...", "stack": "..." }
}

Pairing with a Cloud Logging sink

Route entries to Pub/Sub so an orchestrator can subscribe:

gcloud logging sinks create log-errors-sink \
  pubsub.googleapis.com/projects/PROJECT/topics/log-errors \
  --log-filter='(severity>=ERROR OR jsonPayload.agentDiagnose=true) AND resource.type="cloud_run_revision"'

agentDiagnose: true lets you trigger diagnosis at WARNING (or any severity) without polluting the severity-based channel.

Configuration

| Option | Type | Default | Purpose | |--------------|-----------------------------------------------|------------------|-----------------------------------------------------------| | service | string | required | Service name stamped on every entry | | defaultTag | string | none | Used when an entry omits tag | | write | (line: string) => void | console.log | Swap for testing or non-Cloud-Run environments | | redact | (ctx: Record) => Record | identity | Strip secrets/PII from context before logging |

Entry fields

All fields except msg are optional — but the more you give the agent, the better its first move.

| Field | Why the agent wants it | |------------------|------------------------------------------------------------------| | msg | One-line summary. Sets the frame. | | tag | Routes the entry to a specialized agent. | | severity | WARNING / ERROR / CRITICAL. Defaults to ERROR. | | suspectFiles | Files to open first — saves grep time. | | suspectSymbols | Functions/classes to inspect. | | reproSteps | How to trigger it again. | | recentChanges | Commits/PRs/deploys that may have introduced the regression. | | context | Runtime ids, payloads, headers (redact secrets via redact). | | err | Any thrown value. Serialized with stack and cause chain. | | trace | Cloud Trace id or request id for correlation. |