WSO2 Plugin

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 .

2. Unzip the archive:

   unzip wso2am-4.3.0.zip
   cd wso2am-4.3.0/bin/
   ./api-manager.sh

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

2. Use the default credentials:

   • Username: admin
   • Password: admin

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

4. Test the API:

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

5. 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 api by providing the following details:

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

3. After adding an API, Treblle will generate:

   • API Key
   • SDK Token
   

Step 5: Install Treblle Data Publisher Extension

1. Clone the Treblle Data Publisher repository:

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

2. Build the project:

   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:

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

mv ~/Downloads/aspectjweaver-1.8.5.jar ~/.m2/repository/org/aspectj/aspectjweaver/1.8.5/

Step 6: Configure WSO2 API Manager for Treblle

1. Stop WSO2 if it’s running:

   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):

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

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

For MacOS/Linux:

# Required variables
export TREBLLE_API_KEY="your-api-key"           # Your Treblle API key
export TREBLLE_SDK_TOKEN="your-sdk-token"      # Your Treblle SDK Token
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:

:: Required variables
set TREBLLE_API_KEY=your-api-key
set TREBLLE_SDK_TOKEN=your-sdk-token
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:

# For Linux/macOS
echo $TREBLLE_API_KEY
echo $TREBLLE_SDK_TOKEN
echo $TREBLLE_GATEWAY_URL
 
# For Windows
echo %TREBLLE_API_KEY%
echo %TREBLLE_SDK_TOKEN%
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:

   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 sdk token: your-sdk-token with status code: 403

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

Troubleshooting

Common Issues and Solutions:

1. Database Lock Error:

# 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 SDK Token, 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:

# 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:

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

POST Request:

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:

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:

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: