Custom SDK
Building a custom Treblle SDK allows you to integrate Treblle with frameworks or languages we don’t officially support yet.
This guide walks you through creating a production-ready SDK that captures API data and sends it to Treblle.
When to Build a Custom SDK
Section titled “When to Build a Custom SDK”Consider building a custom SDK when:
- Your framework/language isn’t in our official integrations
- You need specialized functionality for your infrastructure
- You’re building a proprietary framework that needs Treblle integration
- You want to contribute back to the Treblle ecosystem
How Treblle SDKs Work
Section titled “How Treblle SDKs Work”Treblle SDKs act as middleware that:
- Intercept requests before they reach your application
- Capture request/response data without modifying the API behavior
- Mask sensitive information before it leaves your server
- Send data asynchronously to Treblle’s servers for analysis
The key principle: Your API performance is never affected. Data collection happens alongside your normal request processing.
Core Requirements
Section titled “Core Requirements”Every Treblle SDK must implement these essential components:
1. Request/Response Capture
Section titled “1. Request/Response Capture”Your SDK needs access to:
- Request method, URL, headers, and body
- Response status code, headers, body, and timing
- Server information (IP, timezone, OS details)
Most frameworks provide this through middleware hooks or request interceptors.
2. Data Masking
Section titled “2. Data Masking”Sensitive data must be masked before leaving your server. Implement masking for:
Default masked fields:
password, pwd, secret, password_confirmation,cc, card_number, ccv, ssn, credit_score, api_key
Masking strategy:
- Replace field values with asterisks (
*
) matching the original length - Apply to request/response bodies, headers, and nested objects
- Allow custom field configuration
3. Treblle Payload Format
Section titled “3. Treblle Payload Format”Your SDK must format data according to Treblle’s JSON schema and send it to one of these endpoints:
https://rocknrolla.treblle.comhttps://punisher.treblle.comhttps://sicario.treblle.com
Load balancing: Randomly select an endpoint for each request to distribute load.
Implementation Steps
Section titled “Implementation Steps”Step 1: Framework Integration
Section titled “Step 1: Framework Integration”Identify how to hook into your framework’s request lifecycle:
// Example: Express.js middleware patternfunction treblleMiddleware(req, res, next) { // Capture request data const startTime = Date.now();
// Continue to application next();
// Capture response data after completion res.on('finish', () => { const endTime = Date.now(); // Send to Treblle });}
Step 2: Data Collection
Section titled “Step 2: Data Collection”Gather the required information:
const treblleData = { api_key: "YOUR_API_KEY", project_id: "YOUR_PROJECT_ID", version: 1.0, sdk: "your-framework-name", data: { server: { /* server info */ }, language: { /* runtime info */ }, request: { /* request details */ }, response: { /* response details */ }, errors: [] /* any captured errors */ }};
Step 3: Implement Masking
Section titled “Step 3: Implement Masking”Create a masking function that processes nested objects:
function maskSensitiveData(data, maskingKeywords) { // Recursively traverse objects/arrays // Replace values for keys matching maskingKeywords // Return masked copy of data}
Step 4: Send to Treblle
Section titled “Step 4: Send to Treblle”Make an asynchronous POST request:
function sendToTreblle(data) { const endpoints = [ 'https://rocknrolla.treblle.com', 'https://punisher.treblle.com', 'https://sicario.treblle.com' ];
const endpoint = endpoints[Math.floor(Math.random() * endpoints.length)];
// Send POST request with data // Handle errors gracefully - don't break user's API}
JSON Schema Reference
Section titled “JSON Schema Reference”Your payload must match this structure:
{ "api_key": "string", "project_id": "string", "version": "number|string", "sdk": "string", "data": { "server": { "ip": "string", "timezone": "string", "os": { "name": "string", "release": "string", "architecture": "string" }, "software": "string|null", "signature": "string|null", "protocol": "string", "encoding": "string" }, "language": { "name": "string", "version": "string" }, "request": { "timestamp": "string", "ip": "string", "url": "string", "user_agent": "string", "method": "string", "headers": "object", "body": "object" }, "response": { "headers": "object", "code": "integer", "size": "integer|string", "load_time": "number", "body": "string|object|null" }, "errors": "array" }}
View complete JSON schema for detailed field requirements.
Configuration
Section titled “Configuration”Provide these configuration options:
const treblle = new TreblleSDK({ apiKey: "required", projectId: "required", additionalFieldsToMask: ["custom_field"], // optional enabledEnvironments: ["production"], // optional debug: false // optional});
Testing Your SDK
Section titled “Testing Your SDK”- Basic functionality: Verify requests appear in your Treblle dashboard
- Masking verification: Confirm sensitive fields are properly masked
- Error handling: Ensure SDK failures don’t break user APIs
- Performance: Test with high request volumes
- Edge cases: Empty responses, malformed data, network failures
Examples and Reference
Section titled “Examples and Reference”Study existing SDKs for implementation patterns:
- PHP SDK - Framework-agnostic approach
- Express.js SDK - Middleware pattern
- Laravel SDK - Framework-specific integration
Getting Support
Section titled “Getting Support”- Technical questions: Discord community
- SDK submission: Email hello@treblle.com
- Documentation: This guide and JSON schema reference
Contributing Back
Section titled “Contributing Back”Once your SDK is working:
- Open source it on GitHub
- Submit it to our community SDKs list
- Consider making it an official Treblle SDK
Building a custom SDK helps expand Treblle’s ecosystem and enables more developers to benefit from API Intelligance.