flow-mate-bot

AI-powered GitHub App for automated PR summaries and workflow assistance.

Logging Levels

This project uses Pino for structured logging. Understanding log levels helps with debugging and monitoring.

Level	Numeric	Use Case	What Happens After
trace	10	Extremely detailed debugging info	Continue
debug	20	Detailed debugging (development only)	Continue
info	30	Informational messages (operations)	Continue
warn	40	Warning - unexpected but handled	Continue
error	50	Error occurred but app can continue	Continue
fatal	60	Critical error - app cannot continue	Usually exit

Examples from the codebase:

fatal - Application must terminate:

if (!WEBHOOK_SECRET) {
  logger.fatal('WEBHOOK_SECRET is not set in .env file');
  process.exit(1);
}

error - Something failed but app continues:

catch (error) {
  logError(error, 'Command processing failed');
  // App continues, only this request failed
}

info - Normal operations:

logger.info({ port: PORT }, 'Server listening');

debug - Development debugging:

logger.debug({ delivery_id: deliveryId }, 'Signature verified');

Setting Log Level

Use the LOG_LEVEL environment variable:

# Development (shows debug and above)
LOG_LEVEL=debug npm start

# Production (shows info and above)
LOG_LEVEL=info npm start

# Only errors
LOG_LEVEL=error npm start

Default levels:

• Development (NODE_ENV != production): debug
• Production (NODE_ENV = production): info

Tracing with Delivery ID

Every webhook event from GitHub includes a unique delivery_id (UUID) that is automatically included in all logs throughout the request lifecycle. This is critical for debugging and tracing.

What is delivery_id?

• Source: Generated by GitHub for every webhook delivery
• Format: UUID (e.g., 23ad84d0-d0f3-11f0-8736-799f4594f648)
• Scope: Unique per webhook event (retries reuse the same ID)
• Purpose: Trace a single webhook request from receipt to completion

How to use delivery_id for tracing

1. Find all logs for a specific webhook:

# Using jq to filter logs by delivery_id
cat logs.json | jq 'select(.delivery_id=="23ad84d0-d0f3-11f0-8736-799f4594f648")'

# Using grep
grep "23ad84d0-d0f3-11f0-8736-799f4594f648" logs.json

2. Example log flow with delivery_id:

{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","event_type":"issue_comment","msg":"Webhook event received"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","command":"pr-summary","msg":"Command execution started"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","pr_number":4,"msg":"Fetching PR data"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","file_count":1,"msg":"PR data collected"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","msg":"Generating PR summary with Chatrix"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","summary_length":791,"msg":"PR summary generated"}
{"level":30,"delivery_id":"23ad84d0-d0f3-11f0","msg":"Command processing complete"}

3. Cross-reference with GitHub:

• GitHub's webhook delivery dashboard shows the same delivery_id
• Use it to correlate server-side logs with GitHub's delivery attempts
• Helpful for debugging webhook failures or retries

Where delivery_id appears

The delivery_id is included in logs from:

• Webhook receipt and validation
• Command execution start/end
• PR data collection
• Chatrix API calls
• PR description updates
• Error handling

This makes it easy to trace the entire flow of a single request through all components.