@openrouter/devtools package provides pre-release telemetry hooks for compatible integrations. It stores captured data locally as JSON; it no longer includes a maintained viewer.
Telemetry capture
For compatible operations that complete successfully, the hooks record:- Request and response data
- Token usage
- Timing information for performance analysis
- Errors and failure modes
- Model information
Installation
Install the DevTools package as a development dependency:NODE_ENV === 'production' to prevent accidental production deployment.
Client Compatibility
The Agent SDK is not an alternative Client SDK setup. Although@openrouter/agent accepts the hooks, its callModel method always uses a streaming Responses API request. DevTools currently attempts to parse the response as JSON, does not parse the SSE stream, and does not normalize the Responses API request or response schema.
How It Works
Telemetry Capture Flow
With a compatible hook integration:- SDK hooks intercept requests before they’re sent
- Hook processing parses the request or response body
- Data is stored in
.devtools/openrouter-generations.json - An optional notification is sent to the configured local endpoint; notification failures are ignored
Failure Isolation
- Request preservation - Hooks return the original SDK request or response
- Graceful degradation - Capture errors are swallowed instead of replacing the SDK result
- Hook overhead - Body parsing runs inside the SDK hook lifecycle; capture is not zero-cost
- Development-only - Throws error if used in production (
NODE_ENV === 'production')
Storage Location
By default, telemetry is stored in:- Runs - Top-level tracking of SDK operations
- Steps - Individual request/response pairs within each run
- Metadata - Timestamps, status, token usage, errors
Configuration Options
Hook Configuration
When callingcreateOpenRouterDevtools(), you can customize:
Recognized Operation IDs
The hooks recognize these internal SDK operation IDs:createResponses- Responses API callssendChatCompletionRequest- Chat completions API calls
createResponses, but its streaming response is unsupported. The generated Client SDK reaches sendChatCompletionRequest, but it cannot attach the plain hooks through its typed public options. All other SDK operations, including embeddings, are ignored.
Data Captured Per Step
For each compatible operation that completes successfully, DevTools captures: Request Data:- Model name
- Messages/prompts
- Parameters (temperature, max_tokens, etc.)
- Generated content
- Token usage (prompt + completion tokens)
- Provider and model used
- Finish reason
- Start and completion timestamps
- Duration in milliseconds
- Status (success, error, in_progress)
- Error details (if failed)
Safety & Best Practices
Production Environment Protection
Creating DevTools hooks throws an error whenNODE_ENV === 'production'. Only initialize the package in a development environment and only from a compatible integration.
Capture Failure Isolation
- Hook body parsing is awaited by the SDK hook lifecycle
- DevTools capture errors do not replace your SDK result
- Failed writes are silently ignored and don’t break your application
Error Handling
DevTools catches failures in request parsing, response parsing, storage, and server notification. A capture failure can leave telemetry missing or incomplete, but it does not replace the SDK request or response.Troubleshooting
Storage Location Issues
If you can’t find the telemetry file:- Check the default location:
.devtools/openrouter-generations.json - Ensure you have write permissions in your working directory
- Check for custom
storagePathconfiguration
Common Setup Issues
Issue: DevTools package not foundIssue: Accidental production usage