Skip to content
Treblle

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:

  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.

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

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

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.

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",
  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

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",
  "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

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

  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

Examples and Reference

Study existing SDKs for implementation patterns:

Getting Support

Contributing Back

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