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:

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

• Technical questions: Discord community
• SDK submission: Email hello@treblle.com
• Documentation: This guide and JSON schema reference

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.