Observability & Request Context
Relevant source files
The following files were used as context for generating this wiki page:
The Observability and Request Context system provides a structured foundation for logging, monitoring, and tracing operations throughout the AI Reviewer application. By leveraging unified logging and asynchronous context storage, the system ensures that every operation—from an incoming GitHub webhook to an AI-driven code review—is traceable via consistent metadata.
This system is primarily implemented in the @repo/observability package and integrated into the apps/web and apps/worker processes. It utilizes Pino for high-performance structured logging and AsyncLocalStorage to maintain execution context without manual prop-drilling of request IDs or user information.
Sources: README.md:124-131, README.md:209-211
Logging Architecture
The project employs a Pino-based structured logger that ensures every log line is output as a consistent JSON object. This approach facilitates easy ingestion by log management platforms and enables complex querying across different services.
Core Logger Configuration
The system provides a base logger that can be extended with child loggers to add specific context (e.g., component names or operation IDs).
Sources: README.md:125-127, packages/review/src/llm-client.ts:80-80
| Component | Description |
|---|---|
| Pino | The underlying high-performance structured logging library. |
| Child Loggers | Specialized logger instances that append contextual data like component, repositoryId, or correlationId. |
| Log Levels | Standard levels including debug, info, warn, and error used to categorize operational data. |
Logging Flow in Review Orchestration
When a review job is processed, the orchestrator creates a highly specific child logger to track the lifecycle of that specific PR review.
Request Context Management
Request Context management allows the application to carry essential metadata (like requestId, userId, and installationId) through the entire execution path of a request or background job without explicitly passing these values through every function signature.
AsyncLocalStorage Integration
The system uses Node.js AsyncLocalStorage to store context. This is particularly useful for logging, as the logger can automatically pull the current requestId from the store.
Sources: README.md:128-131, README.md:209-211
Middleware Implementation
In the web application, the withRouteContext middleware is responsible for initializing this context for every incoming HTTP request, including webhooks.
Implementation in Webhooks
The GitHub webhook endpoint serves as a critical integration point for observability. It captures unique delivery IDs and initializes the context for downstream asynchronous processing.
- Delivery Tracking: Every delivery from GitHub includes an
x-github-deliveryheader, which is logged and stored for deduplication. - Size Guards: The system logs and rejects payloads exceeding 25 MB to prevent resource exhaustion.
- Job Correlation: When enqueuing a background job (e.g.,
webhook.process), thedeliveryIdis passed along to maintain the chain of custody in logs.
Sources: apps/web/app/api/webhooks/github/route.ts:1-25, apps/web/app/api/webhooks/github/route.ts:113-115
Webhook Metadata Table
The following headers and identifiers are prioritized for observability in the webhook flow:
| Header/Field | Purpose | Source |
|---|---|---|
x-github-delivery | Unique ID for the specific webhook transmission. Used for deduplication. | apps/web/app/api/webhooks/github/route.ts:70-71 |
x-github-event | Type of event (e.g., pull_request). Determines routing logic. | apps/web/app/api/webhooks/github/route.ts:72-73 |
correlationId | Used to link web requests to background worker jobs. | packages/review/src/orchestrator.ts:43-43 |
status | Tracks the state of the AI review (e.g., PENDING, RUNNING, COMPLETED). | packages/review/src/orchestrator.ts:55-70 |
Error Observability
The system implements strict error boundaries, especially within the AI Review Orchestrator. When a review fails, the error is caught, logged with the full error object, and persisted to the database to provide visibility into why a review did not complete.
Sources: packages/review/src/orchestrator.ts:72-79, README.md:175-177
Conclusion
Observability and Request Context in the AI Reviewer project are designed for high transparency and minimal developer overhead. By combining Pino's structured logging with AsyncLocalStorage, the system creates an "engineering memory" not just for the code being reviewed, but for the operation of the reviewer itself. This architecture ensures that even complex, multi-step AI workflows are fully auditable and debuggable.
Sources: README.md:209-211, README.md:124-131