Skip to content

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.

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

Treblle SDKs act as middleware that:

  1. Intercept requests before they reach your application
  2. Capture request/response data without modifying the API behavior
  3. Mask sensitive information before it leaves your server
  4. 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.

Every Treblle SDK must implement these essential components:

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.

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

Your SDK must format data according to Treblle’s JSON schema and send it to one of these endpoints:

https://rocknrolla.treblle.com
https://punisher.treblle.com
https://sicario.treblle.com

Load balancing: Randomly select an endpoint for each request to distribute load.

Identify how to hook into your framework’s request lifecycle:

// Example: Express.js middleware pattern
function 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
});
}

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 */
}
};

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
}

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
}

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.

Provide these configuration options:

const treblle = new TreblleSDK({
apiKey: "required",
projectId: "required",
additionalFieldsToMask: ["custom_field"], // optional
enabledEnvironments: ["production"], // optional
debug: false // optional
});
  1. Basic functionality: Verify requests appear in your Treblle dashboard
  2. Masking verification: Confirm sensitive fields are properly masked
  3. Error handling: Ensure SDK failures don’t break user APIs
  4. Performance: Test with high request volumes
  5. Edge cases: Empty responses, malformed data, network failures

Study existing SDKs for implementation patterns:

Once your SDK is working:

  1. Open source it on GitHub
  2. Submit it to our community SDKs list
  3. 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.