WSO2 Plugin

The Treblle WSO2 SDK integrates with WSO2’s API Handler chain (AbstractHandler) to intercept API requests and responses inside the gateway. By running after the APIAuthenticationHandler and APIMgtUsageHandler, it has access to enriched context including tenant domain, application info, subscriber data, and API publisher. It operates asynchronously to ensure zero impact on API performance.

Supported Versions

Overview

How It Works

1. Request Capture — Intercepts incoming API requests, capturing headers, body, IP, method, path, and enriched properties (tenant, application, user, publisher)
2. Response Capture — Captures response data including status code, headers, body, and load time
3. Async Processing — Adds captured data to a bounded in-memory queue (non-blocking)
4. Worker Threads — Background threads dequeue events and send them to Treblle
5. Data Masking — Automatically masks sensitive fields before transmission

Key Features

• Non-blocking: Never blocks or slows down API requests, even on failures
• Thread-safe: Uses concurrent queues and atomic operations
• Load-balanced: Distributes traffic across multiple Treblle endpoints
• Sensitive data masking: Automatically redacts passwords, tokens, credit cards, etc.
• Multi-tenant support: Filter by tenant domains
• Enriched context: Captures application name, user ID, API publisher, and tenant domain
• Configurable: Queue size, worker threads, custom endpoints, and masking rules

Prerequisites

Before you begin, ensure you have:

• WSO2 API Manager: Version 4.0.x or higher
• Java: Version 8 or higher
• Maven: Version 3.x (for building from source)
• Treblle Account: With SDK token and API key (Get started )

Build from Source

Building for Default Version (WSO2 APIM 4.3.x)

mvn clean install

The JAR artifact will be created in the target/ directory as treblle-wso2-3.0.0.jar.

Building for Specific WSO2 Versions

# For WSO2 APIM 4.0.x
mvn clean install -P wso2am-4.0
 
# For WSO2 APIM 4.1.x
mvn clean install -P wso2am-4.1
 
# For WSO2 APIM 4.2.x
mvn clean install -P wso2am-4.2
 
# For WSO2 APIM 4.3.x (default)
mvn clean install -P wso2am-4.3
 
# For WSO2 APIM 4.4.x
mvn clean install -P wso2am-4.4
 
# For WSO2 APIM 4.6.x
mvn clean install -P wso2am-4.6

All profiles produce the same JAR name: treblle-wso2-3.0.0.jar.

Build All Versions at Once

mvn clean install -P wso2am-4.0,wso2am-4.1,wso2am-4.2,wso2am-4.3,wso2am-4.4,wso2am-4.6

Installation

Step 1: Deploy the JAR

Copy the built JAR to your API Manager gateway:

cp target/treblle-wso2-3.0.0.jar <APIM_HOME>/repository/components/lib/

Replace <APIM_HOME> with your WSO2 API Manager installation directory (e.g., /opt/wso2am-4.3.0).

Step 2: Configure the Handler

Add the Treblle handler to <APIM_HOME>/repository/resources/api_templates/velocity_template.xml.

Find the handlers section with the SchemaValidator and add the Treblle handler after it:

## check and set enable schema validation
#if($enableSchemaValidation)
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator"/>
#end
## Treblle API Observability Handler Injection
#if( $apiObj.additionalProperties.get("treblle_enabled") == "true" )
<handler class="com.treblle.wso2publisher.handlers.APILogHandler">
    #set($treblleMaskKw = $apiObj.additionalProperties.get("treblle_mask_keywords"))
    #if( $treblleMaskKw && "$treblleMaskKw" != "" )
    <property name="treblleMaskKeywords" value="$util.escapeXml($treblleMaskKw)"/>
    #end
    #set($treblleDisableBody = $apiObj.additionalProperties.get("treblle_disable_response_body"))
    #if( $treblleDisableBody && "$treblleDisableBody" != "" )
    <property name="treblleDisableResponseBody" value="$util.escapeXml($treblleDisableBody)"/>
    #end
</handler>
#end
</handlers>

Step 3: Configure Logging

Add the following to <APIM_HOME>/repository/conf/log4j2.properties:

# Add treblle_publisher to the loggers list (find the existing loggers line and append)
loggers = treblle_publisher, AUDIT_LOG, ...
 
# Add these lines at the end of the file
logger.treblle_publisher.name = com.treblle.wso2publisher
logger.treblle_publisher.level = INFO
logger.treblle_publisher.appenderRef.CARBON_LOGFILE.ref = CARBON_LOGFILE

Step 4: Set Environment Variables

Before starting the WSO2 API Manager, configure the required environment variables.

For macOS/Linux:

export TREBLLE_SDK_TOKEN=your-sdk-token
export TREBLLE_API_KEY=your-api-key
export TREBLLE_GATEWAY_URL="https://your-gateway.com"  # Optional
export TREBLLE_QUEUE_SIZE=20000                         # Optional
export TREBLLE_WORKER_THREADS=1                         # Optional
export ADDITIONAL_MASK_KEYWORDS=customToken,apiSecret   # Optional
export TREBLLE_ENABLED_TENANT_DOMAINS=carbon.super      # Optional

For Windows:

set TREBLLE_SDK_TOKEN=your-sdk-token
set TREBLLE_API_KEY=your-api-key
set TREBLLE_GATEWAY_URL=https://your-gateway.com
set TREBLLE_QUEUE_SIZE=20000
set TREBLLE_WORKER_THREADS=1
set ADDITIONAL_MASK_KEYWORDS=customToken,apiSecret
set TREBLLE_ENABLED_TENANT_DOMAINS=carbon.super

Step 5: Start WSO2 API Manager

cd <APIM_HOME>/bin
./api-manager.sh  # or api-manager.bat on Windows

Check the logs to verify the extension loaded successfully:

tail -f <APIM_HOME>/repository/logs/wso2carbon.log | grep -i treblle

Configuration Reference

Default Masked Keywords

The following keywords are automatically masked in headers and request/response bodies:

• password, pwd, secret, password_confirmation
• cc, card_number, ccv
• ssn, credit_score

Use ADDITIONAL_MASK_KEYWORDS to add more sensitive fields (e.g., Authorization,X-API-Key,token).

Per-API Masking Keywords

In addition to global masking, you can define masking keywords on a per-API basis through WSO2 API custom properties. This allows each API to have its own set of sensitive fields masked, on top of the global defaults.

How to configure:

1. Open the WSO2 Publisher portal
2. Navigate to your API and go to Properties
3. Add a custom property:
   • Name: treblle_mask_keywords
   • Value: Comma-separated field names (e.g., ssn,dob,account_number)
4. Save and re-deploy the API

Disabling Response Body Capture Per API

You can prevent the response body from being sent to Treblle on a per-API basis. This is useful for large responses, PII concerns, or compliance requirements.

How to configure:

1. Open the WSO2 Publisher portal
2. Navigate to your API and go to Properties
3. Add a custom property:
   • Name: treblle_disable_response_body
   • Value: true
4. Save and re-deploy the API

Per-API Configuration Cache

Both treblle_mask_keywords and treblle_disable_response_body are resolved once per API and cached in memory to avoid re-parsing MessageContext properties on every request.

Custom Endpoint Configuration

Load Balancing (Default Behavior):

If TREBLLE_GATEWAY_URL is NOT set, the extension automatically load-balances across Treblle’s endpoints:

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

Custom Endpoint:

If TREBLLE_GATEWAY_URL is set, all data is sent to your specified endpoint:

export TREBLLE_GATEWAY_URL="https://custom-treblle.your-domain.com"

Use cases for custom endpoints:

• On-premise Treblle installations
• Custom routing or proxy configurations
• Regional endpoints for compliance
• Development/testing environments

Troubleshooting

Extension Not Loading

Check logs in <APIM_HOME>/repository/logs/wso2carbon.log:

grep -i treblle wso2carbon.log

Verify JAR location:

ls -la <APIM_HOME>/repository/components/lib/treblle-wso2-3.0.0.jar

Verify velocity_template.xml configuration:

grep -i "treblle" <APIM_HOME>/repository/resources/api_templates/velocity_template.xml

Ensure the #if( $apiObj.additionalProperties.get("treblle_enabled") ... ) block and the handler entry are present in the handlers section after the SchemaValidator.

No Data in Treblle Dashboard

1. Verify environment variables are set:

   echo $TREBLLE_SDK_TOKEN
   echo $TREBLLE_API_KEY

2. Check for errors in logs:

   grep -i "treblle.*error" wso2carbon.log

3. Verify the API has treblle_enabled set to true in its custom properties in the WSO2 Publisher portal, and that the API has been redeployed after setting the property.

4. Verify tenant domain filtering (if using TREBLLE_ENABLED_TENANT_DOMAINS):

   • Ensure your API’s tenant domain is in the allowed list
   • Default tenant is usually carbon.super

5. Check content type — Only application/json requests/responses are captured

Queue Full Errors

If you see “Event queue is full” errors in logs:

1. Increase queue size:

   export TREBLLE_QUEUE_SIZE=50000

2. Add more worker threads:

   export TREBLLE_WORKER_THREADS=2

3. Check network connectivity to Treblle endpoints:

   curl -I https://rocknrolla.treblle.com
   curl -I https://punisher.treblle.com
   curl -I https://sicario.treblle.com

Memory Issues

If experiencing memory pressure:

1. Reduce TREBLLE_QUEUE_SIZE (default 20,000)
2. Reduce TREBLLE_WORKER_THREADS (default 1)
3. Use TREBLLE_ENABLED_TENANT_DOMAINS to filter which APIs are monitored

Getting Help

If you continue to experience issues:

1. Enable debug logging in log4j2.properties:

   logger.treblle_publisher.level = DEBUG

2. Verify credentials are correct in the Treblle dashboard

3. Test with a simple endpoint first before complex APIs

4. Check Treblle documentation  for the latest updates

5. Contact support at support@treblle.com