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

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

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

Zero Performance Impact

Your API performance is never affected. Data collection happens alongside your normal request processing without blocking or slowing down responses.

Core Requirements

Every Treblle SDK must implement these essential components:

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

Caution

Sensitive data must be masked before leaving your server. Never send unmasked sensitive information to Treblle’s servers.

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

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

Tip

Randomly select an endpoint for each request to distribute load across Treblle’s infrastructure.

Implementation Steps

Step 1: Framework Integration

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
  });
}

Step 2: Data Collection

Gather the required information:


const treblleData = {
  api_key: "YOUR_API_KEY",
  SDK_TOKEN: "YOUR_SDK_TOKEN", 
  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

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

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

Your payload must match this structure:


{
  "api_key": "string",
  "SDK_TOKEN": "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"
  }
}

Note

View the complete JSON schema reference for detailed field requirements and validation rules.

Configuration

Provide these configuration options:


const treblle = new TreblleSDK({
  apiKey: "required",
  sdkToken: "required", 
  additionalFieldsToMask: ["custom_field"], // optional
  enabledEnvironments: ["production"], // optional
  debug: false // optional
});

Testing Your SDK

Basic functionality verified - requests appear in Treblle dashboard

Masking verification - sensitive fields properly masked

Error handling - SDK failures don’t break user APIs

Performance tested with high request volumes

Edge cases handled - empty responses, malformed data, network failures

Examples and Reference

Study existing SDKs for implementation patterns:

PHP SDK - Framework-agnostic approach
Express.js SDK - Middleware pattern
Laravel SDK - Framework-specific integration

Frequently Asked Questions

How do I ensure my SDK doesn't impact API performance?

All data sending should be done asynchronously, after the response is sent to the user. Use non-blocking requests and implement proper error handling so that any SDK failures don’t affect your user’s API calls.

What happens if the Treblle endpoint is unavailable?

Your SDK should handle errors gracefully and fail silently. The user’s API should continue working normally even if Treblle is unreachable. Consider implementing retry logic with exponential backoff.

How do I test that my SDK is working correctly?

Use the provided testing tools and follow the checklist to verify that your SDK is capturing and sending data as expected. Monitor the Treblle dashboard for incoming requests and their details.

Can I add custom fields to mask beyond the defaults?

Yes, your SDK should allow users to configure additional fields to mask through the configuration options. This is especially important for industry-specific sensitive data.

What if I need to mask fields in nested objects?

Your SDK should support masking fields in nested objects and arrays. Implement a recursive masking function that traverses the entire request and response payloads.

How do I test that masking is working correctly?

Send test requests with known sensitive data and verify in your Treblle dashboard that the values appear as asterisks. Test nested objects, arrays, and different data types to ensure comprehensive masking.

Getting Support

SDK submission: Email hello@treblle.com
Documentation: This guide and JSON schema reference

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 Intelligence.

Treblle Docs