Skip to content
Treblle

WSO2 Plugin for Treblle

treblle-wso2

The official Treblle plugin for WSO2.

The extension retrieves data from Global Synapse Handler in the API Gateway and creates a payload to send to Treblle. The data is added onto a queue once received and is processed by a worker thread. The worker thread sends the data asynchronously to Treblle, if the data is successfully sent, the data is removed from the queue. If the data is not successfully sent, the worker thread will attempt to send the data again, after 1 retry attempt, the event will be dropped.

Prerequisites

Before you begin, make sure you have:

  • Java: Version 8 or later (java -version)
  • Maven: Version 3.6.0 or later (mvn -version)

Step 1: Install WSO2 API Manager

  1. Download the WSO2 API Manager 4.3.0 from the official WSO2 website.
  1. Unzip the archive:
    Terminal window
    unzip wso2am-4.3.0.zip
    cd wso2am-4.3.0/bin/
    ./api-manager.sh
  2. Open the Admin Console in your browser:
    • URL: https://localhost:9443/carbon
    • Username: admin
    • Password: admin

Step 2: Create an API in WSO2 API Manager

  1. Log in to the Publisher Portal at https://localhost:9443/publisher.

  1. Use the default credentials:

    • Username: admin
    • Password: admin

  2. Create a New API:

    • Choose the API type (e.g., REST API, SOAP API).
    • Provide details like API Name, Context Path, Version, and Endpoint URL.
    • Publish the API.

  3. Test the API:

    • Log in to the Developer Portal at https://localhost:9443/devportal/apis.

  4. Subscribe to the API:

    • Go to the Subscription section.
    • Use the Subscription and Key Generation Wizard to generate an access token:

Step 3: Test the API

  • Return to the Developer Portal and locate the API you subscribed to.

  • Click the Try Out option to test your API directly within the portal.

  • Select the key type for testing:

    • Sandbox: For testing the API in a non-production environment.
    • Production: For live use in production.

  • Choose the method you want to test (e.g., GET).

  • Execute the request by providing the required parameters.

Step 4: Set Up Treblle

Follow these steps to integrate Treblle with your WSO2 API Manager:

  1. Visit the Treblle website and log in or sign up for an account if you don’t have one.

  2. Once logged in, create a new project by providing the following details:

    • API Name.
    • Base URL.
    • Environment.
    • Platform.

  3. After creating the project, Treblle will generate:

    • API Key
    • Project ID

    These credentials are essential for integrating Treblle with your WSO2 API Manager.

Step 5: Install Treblle Data Publisher Extension

  1. Clone the Treblle Data Publisher repository:

    Terminal window
    git clone https://github.com/Treblle/treblle-wso2.git
    cd wso2am-4.3.0

  2. Build the project:

    Terminal window
    mvn clean install

    This will generate the necessary .jar file for the Treblle Data Publisher extension.

  3. Copy the generated JAR file to WSO2 API Manager:

    Terminal window
    cp target/treblle-data-publisher-*.jar /path/wso2am-4.3.0/repository/components/lib

Step 6: Configure WSO2 API Manager for Treblle

  1. Stop WSO2 if it’s running:

    Terminal window
    cd /path/to/your/wso2am-4.3.0/bin
    ./api-manager.sh stop
    # Or force kill if needed:
    # pkill -f "org.wso2.carbon.bootstrap.Bootstrap"

  2. Update the deployment.toml file (Add at the beginning of the file):

    Terminal window
    /wso2am-4.3.0/repository/conf/deployment.toml
    [synapse_handlers.treblle_publisher]
    enabled=true
    class="com.treblle.wso2publisher.handlers.APILogHandler"

  3. Update log4j2.properties:

    To enable the logs to populate under the default wso2carbon.log, you can create a custom appender to log the entries to a separate log file.

    Terminal window
     /wso2am-4.3.0/repository/conf/log4j2.properties
    logger.treblle_publisher.name = com.treblle.wso2publisher
    logger.treblle_publisher.level = INFO
    logger.treblle_publisher.appenderRef.CARBON_LOGFILE.ref = CARBON_LOGFILE

  4. Set environment variables:

    Open a terminal and add the following environment variables. Alternatively, set these variables in your .bash_profile or .bashrc to make them persistent across sessions.

    IMPORTANT: Set these environment variables before starting WSO2. Open a terminal and run:

    For MacOS/Linux:

    Terminal window
    # Required variables
    export TREBLLE_API_KEY="your-api-key"           # Your Treblle API key
    export TREBLLE_PROJECT_ID="your-project-id"      # Your Treblle project ID
    export TREBLLE_GATEWAY_URL="your-gateway-url"    # Your WSO2 gateway URL
    

    # Optional variables with defaults
    export TREBLLE_QUEUE_SIZE=20000                  # Max size of the request queue
    export TREBLLE_WORKER_THREADS=1                  # Number of worker threads
    export ADDITIONAL_MASK_KEYWORDS="Authorization,token"  # Fields to mask
    export TREBLLE_ENABLED_TENANT_DOMAINS="carbon.super"  # Enabled tenant domains

    For Windows:

    Terminal window
    :: Required variables
    set TREBLLE_API_KEY=your-api-key
    set TREBLLE_PROJECT_ID=your-project-id
    set TREBLLE_GATEWAY_URL=https://your-wso2-gateway-url
    

    :: Optional variables
    set TREBLLE_QUEUE_SIZE=20000                     :: Default queue size
    set TREBLLE_WORKER_THREADS=1                     :: Default worker threads
    set ADDITIONAL_MASK_KEYWORDS=Authorization,token  :: Default masked fields
    set TREBLLE_ENABLED_TENANT_DOMAINS=carbon.super  :: Default tenant domain

    Verifying Environment Variables:

    To check that your environment variables are properly set up for Treblle:

    Terminal window
    # For Linux/macOS
    echo $TREBLLE_API_KEY
    echo $TREBLLE_PROJECT_ID
    echo $TREBLLE_GATEWAY_URL
    

    # For Windows
    echo %TREBLLE_API_KEY%
    echo %TREBLLE_PROJECT_ID%
    echo %TREBLLE_GATEWAY_URL%

Step 7: Configure OAuth2 Authentication

  • To generate an OAuth2 Token, log in to the Developer Portal at https://localhost:9443/devportal.

  • Under the Subscription section, click on your created application.

  • Select either Production or Sandbox as the key type.

  • Click Generate Key for the chosen environment and copy the generated access token.

  • This token is essential for accessing protected resources in your API.

Step 8: Verify Treblle Integration

  1. Check WSO2 logs for Treblle activity:

    Terminal window
    tail -f /path/to/your/wso2am-4.3.0/repository/logs/wso2carbon.log | grep -i treblle

  2. Look for success messages (not 403 Forbidden errors):

    • ✅ Good: Event successfully published.
    • ❌ Bad: Event publishing failed for project id: your-project-id with status code: 403

  3. Check your Treblle dashboard to see captured API requests.

Troubleshooting

Common Issues and Solutions:

1. Database Lock Error:

Terminal window
# Kill any running WSO2 processes
pkill -f "org.wso2.carbon.bootstrap.Bootstrap"


# Remove lock files
cd /path/to/your/wso2am-4.3.0/repository/database/
rm -f *.lock *.lck *.tmp

2. 403 Forbidden Errors in Logs:

  • Verify your Treblle credentials are correct
  • Make sure you’re using actual API key and project ID, not placeholder text
  • Check that TREBLLE_GATEWAY_URL contains only the base URL

3. Extension Not Loading:

  • Ensure the JAR file is in the correct location: /repository/components/lib/
  • Verify the deployment.toml configuration is at the beginning of the file
  • Check that log4j2.properties has been updated correctly

4. SSL Certificate Issues:

  • Use the -k flag with cURL for testing
  • In Postman, disable SSL certificate verification in settings
  • For development, you can use HTTP port 8280 instead of HTTPS 8243

5. View detailed logs:

Terminal window
# View all WSO2 logs
tail -f /path/to/your/wso2am-4.3.0/repository/logs/wso2carbon.log


# Filter for Treblle-specific logs
tail -f /path/to/your/wso2am-4.3.0/repository/logs/wso2carbon.log | grep "treblle\|PublisherClient\|APILogHandler"

Example API Testing Commands

Here are example curl commands for different HTTP methods:

GET Request:

Terminal window
curl -k -X GET \
  "https://localhost:8243/test/v1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST Request:

Terminal window
curl -k -X POST \
  "https://localhost:8243/user-management/v1/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "john.doe@example.com", "first_name": "John", "last_name": "Doe"}'

PUT Request:

Terminal window
curl -k -X PUT \
  "https://localhost:8243/user-management/v1/users/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "john.doe@example.com", "first_name": "John", "last_name": "Smith"}'

DELETE Request:

Terminal window
curl -k -X DELETE \
  "https://localhost:8243/user-management/v1/users/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Dashboard Overview

The Treblle dashboard provides real-time insights into API requests, compliance checks, and potential issues.

Customize the View: Use the customization options at the top right of the dashboard to tailor the information displayed according to your needs.

Detailed API Request Logs

Request List: View a detailed list of API requests, including key metrics and diagnostic information.

Inspect Individual Requests:

That’s it!

Your WSO2 API Manager is now integrated with Treblle. All API requests will be automatically captured and sent to your Treblle dashboard.