Skip to content
Treblle

WSO2

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 /path/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.

  4. Subscribe to the API:

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

  • Provide details such as:

    • Application Name.
    • Description.
    • Shared Quota.

  • Generate the access token and copy it. You will use this token to authenticate your requests.

Step 3: Define API Resources

  • In the WSO2 Publisher, go to the Resources section.

  • Define the endpoints for your API, such as /users.

Step 4: 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 5: 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 6: Install Treblle Data Publisher Extension

  1. Clone the Treblle Data Publisher repository:
    Terminal window
    git clone https://github.com/Treblle/treblle-wso2.git
    cd /path/treblle-wso2/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 7: Configure WSO2 API Manager for Treblle

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

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

  2. Update log4j2.properties:

Following to enable the logs to populate under default wso2carbon.log. You can create a custom appender to log the entries to a separate log file.

Terminal window
 /path/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
  1. 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.

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

Step 8: 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 5: Restart WSO2 API Manager

Restart the server to apply the configurations:

Terminal window
cd /path/wso2am-4.3.0/bin
./api-manager.sh restart

Step 9: Test API Observability with Treblle

  1. Use cURL to send a request:
  • Replace “access_token” with a valid OAuth2 token.
Terminal window
  curl -k -X GET "https://localhost:8243/<api-context>/<version>" -H "Authorization: Bearer <access_token>"

Dashboard Overview

  1. The Treblle dashboard provides real-time insights into API requests, compliance checks, and potential issues.
  1. Customize the View: Use the customization options from the top right of the dashboard to tailor the displayed information according to your needs.

Detailed API Request Logs

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