Apigee API Gateway

treblle-apigee

The official Treblle SDK for Apigee API Gateway. Capture data in real-time with zero-latency and monitor your APIs seamlessly.

The Treblle Apigee SDK brings native support to Google Apigee API Gateway across all Apigee versions. The SDK captures data in real-time with zero-latency and sends that data to Treblle for processing.

This integration captures detailed API request and response data without requiring code changes to your existing APIs and is designed to be non-blocking, ensuring zero impact on client response times.

The Apigee API Gateway integration automatically:

Zero-Latency Monitoring: Non-blocking data collection that doesn’t impact API response times
Real-time Capture: Captures requests, responses, and performance metrics instantly
Data Masking: Automatically masks sensitive information with customizable keywords
Endpoint Blocking: Block specific endpoints from being tracked with wildcard support
Load Balancing: Automatically selects from multiple Treblle endpoints for reliability
Error Reporting: Captures Apigee fault variables and HTTP error states automatically
Flexible Deployment: Deploy at API level or environment level

Supported Apigee Versions

Framework	Supported Versions	Status
Apigee Edge	All Versions	✅ Full Support
Apigee X	All Versions	✅ Full Support
Apigee Hybrid	All Versions	✅ Full Support

Prerequisites

Before you begin, ensure you have:

Apigee Edge, Apigee X, or Apigee Hybrid account
Treblle account with API key and SDK token
Access to Apigee Management Console or Apigee API access
gcloud CLI configured (for API-based deployment)

Required Permissions

API Proxy Developer: To deploy policies and resources
Environment Admin: To create and manage Key Value Maps
Shared Flow Developer: To create the async logging flow

Network Requirements

Outbound HTTPS access to Treblle endpoints:
- rocknrolla.treblle.com
- punisher.treblle.com
- sicario.treblle.com
Ports: 443 (HTTPS)

Architecture Overview

API-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Client    │───▶│  Apigee Proxy   │───▶│  Backend API    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                       ┌────────┴────────┐              │
                       │                 │              │
                  ┌────▼──────┐    ┌────▼──────┐      │
                  │  Request  │    │ Response  │      │
                  │  PreFlow  │    │ PreFlow   │◀─────┘
                  └───────────┘    └─────┬─────┘
                                         │
                                         ▼
                                ┌─────────────────┐
                                │  JS-treblle     │ (PreFlow Response)
                                │ Captures Data   │
                                └─────────────────┘
                                         │
                       ┌─────────────────┴─────────────────┐
                       │                                   │
                  ┌────▼──────┐                     ┌─────▼──────┐
                  │  Request  │                     │  Response  │
                  │ PostFlow  │                     │  PostFlow  │
                  └─────┬─────┘                     └─────┬──────┘
                        │                                 │
                        ▼                                 ▼
                ┌────────────────┐            ┌──────────────────┐
                │  KVM-Treblle   │            │  FC-Async-       │
                │Get Credentials │            │  Treblle-Logger  │
                └────────────────┘            └────────┬─────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │  Shared Flow:   │
                                              │ treblle-logger  │
                                              │ SC-SendToTreblle│
                                              └────────┬────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │  Treblle API    │
                                              │ (Load Balanced) │
                                              └─────────────────┘

Environment-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Client    │───▶│  Any API Proxy  │───▶│  Backend API    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                │                       ▼
                                │              ┌─────────────────┐
                                │              │ Backend Response│
                                │              └────────┬────────┘
                                │                       │
                                ▼                       ▼
                       ┌──────────────────────────────────────┐
                       │   PostTargetFlow Hook (Env Level)    │
                       │                                      │
                       │  Shared Flow: treblle-env-monitor   │
                       │                                      │
                       │  ┌────────────────────────────┐     │
                       │  │ 1. KVM-GetCredentials      │     │
                       │  └────────────┬───────────────┘     │
                       │               ▼                      │
                       │  ┌────────────────────────────┐     │
                       │  │ 2. JS-ProcessPayload       │     │
                       │  └────────────┬───────────────┘     │
                       │               ▼                      │
                       │  ┌────────────────────────────┐     │
                       │  │ 3. SC-SendToTreblle        │     │
                       │  └────────────────────────────┘     │
                       └──────────────────┬───────────────────┘
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │  Treblle API    │
                                 │ (Load Balanced) │
                                 └─────────────────┘

Flow Execution Order

API-Level:

Request PreFlow: Client request enters Apigee proxy
Backend Call: Request forwarded to backend API
Response PreFlow: Backend response received
PreFlow Response: JS-treblle captures complete request/response data
PostFlow Request: KVM-Treblle retrieves credentials (SDK Token & API Key)
PostFlow Response: FC-Async-Treblle-Logger calls shared flow
Shared Flow: SC-SendToTreblle sends data to Treblle API
Client Response: Original response sent to client (zero latency)

Environment-Level:

Request: Client request to any API proxy in environment
Backend Call: Request forwarded to backend
Response: Backend responds
PostTargetFlow Hook: Environment-level shared flow executes
- KVM retrieves credentials
- JS captures and processes data
- SC sends to Treblle API
Client Response: Original response sent to client (zero latency)

Installation

Choose your deployment method based on your monitoring needs:

Deployment Method	Use Case	Coverage
API-Level	Monitor specific API proxies individually	Selected APIs only
Environment-Level	Monitor all APIs in an environment automatically	All APIs in environment

Step 1: Get Your Treblle Credentials

Sign up for a free account at treblle.com
Create a new API in your Treblle dashboard
Copy your SDK Token and API Key from the project settings

Step 2: Clone the Repository

git clone https://github.com/Treblle/treblle-apigee.git
cd treblle-apigee

Step 3: Create Environment Configuration

Create an encrypted Key Value Map (KVM) to store your Treblle credentials securely.

Option A: Using Apigee Management API (Recommended)

Replace the placeholders with your actual values:

YOUR_ORGANIZATION: Your Apigee organization name
YOUR_ENVIRONMENT: Target environment (test, prod, etc.)
YOUR_TREBLLE_SDK_TOKEN: From your Treblle project
YOUR_TREBLLE_API_KEY: From your Treblle project

# Create the KVM
curl -X POST "https://apigee.googleapis.com/v1/organizations/YOUR_ORGANIZATION/environments/YOUR_ENVIRONMENT/keyvaluemaps" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "treblle-kvm",
    "encrypted": true
  }'

# Add SDK Token
curl -X POST "https://apigee.googleapis.com/v1/organizations/YOUR_ORGANIZATION/environments/YOUR_ENVIRONMENT/keyvaluemaps/treblle-kvm/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "treblle_sdk_token",
    "value": "YOUR_TREBLLE_SDK_TOKEN"
  }'

# Add API Key
curl -X POST "https://apigee.googleapis.com/v1/organizations/YOUR_ORGANIZATION/environments/YOUR_ENVIRONMENT/keyvaluemaps/treblle-kvm/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "treblle_api_key",
    "value": "YOUR_TREBLLE_API_KEY"
  }'

# Verify the setup
curl "https://apigee.googleapis.com/v1/organizations/YOUR_ORGANIZATION/environments/YOUR_ENVIRONMENT/keyvaluemaps/treblle-kvm/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

Option B: Using Apigee UI

Navigate to Admin > Environments in Apigee Console
Select your target environment
Go to Key Value Maps
Click + Key Value Map
Configure:
- Name: treblle-kvm
- Encrypted: Yes (recommended)
Click Create
Add entries:
- Key: treblle_sdk_token, Value: Your Treblle SDK token
- Key: treblle_api_key, Value: Your Treblle API key

Deployment

Deployment Option 1: API-Level

Deploy Treblle monitoring to specific API proxies individually. This approach gives you granular control over which APIs are monitored.

When to Use API-Level Deployment

You want to monitor only specific APIs
You need different configurations for different APIs
You’re testing Treblle integration on a single API first
You have a small number of APIs to monitor

Step 4: Create Shared Flow for Service Callout

Create a shared flow to handle asynchronous service callouts to Treblle.

In Apigee UI, go to Develop > Shared Flows
Click + Shared Flow
Name: treblle-logger
Create a new policy: Service Callout

Service Callout Policy (SC-SendToTreblle.xml):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout continueOnError="true" enabled="true" name="SC-SendToTreblle">
    <DisplayName>SC-SendToTreblle</DisplayName>
    <Request clearPayload="true" variable="treblleRequest">
        <Set>
            <Headers>
                <Header name="Content-Type">application/json</Header>
                <Header name="x-api-key">{treblle_sdk_token}</Header>
            </Headers>
            <Payload contentType="application/json">{treblle_payload}</Payload>
            <Verb>POST</Verb>
        </Set>
    </Request>
    <Response>treblle_response</Response>
    <HTTPTargetConnection>
        <URL>https://{treblle_selected_host}</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Configure the shared flow:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="treblle-logger">
  <Step>
    <n>SC-SendToTreblle</n>
  </Step>
</SharedFlow>

Deploy treblle-logger to your target environment

Step 5: Configure Your API Proxy

Upload JavaScript Resource

Go to Develop > API Proxies > [Your Proxy]
Navigate to Resources > JavaScript
Click + Resource
Upload treblle-payload-processor.js from the repository

Create Policies

Create the following three policies in your API proxy:

1. Key Value Map Policy (KVM-GetTreblleCredentials.xml):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyValueMapOperations mapIdentifier="treblle-kvm" continueOnError="false" enabled="true" name="KVM-GetTreblleCredentials">
    <DisplayName>KVM-GetTreblleCredentials</DisplayName>
    <Get assignTo="treblle_sdk_token">
        <Key>
            <Parameter>treblle_sdk_token</Parameter>
        </Key>
    </Get>
    <Get assignTo="treblle_api_key">
        <Key>
            <Parameter>treblle_api_key</Parameter>
        </Key>
    </Get>
    <Scope>environment</Scope>
</KeyValueMapOperations>

2. JavaScript Policy (JS-ProcessTrebllePayload.xml):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript continueOnError="false" enabled="true" timeLimit="200" name="JS-ProcessTrebllePayload">
    <DisplayName>JS-ProcessTrebllePayload</DisplayName>
    <Properties/>
    <ResourceURL>jsc://treblle-payload-processor.js</ResourceURL>
</Javascript>

3. Flow Callout Policy (FC-TreblleAsyncLogger.xml):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout continueOnError="true" enabled="true" name="FC-TreblleAsyncLogger">
    <DisplayName>FC-TreblleAsyncLogger</DisplayName>
    <SharedFlowBundle>treblle-logger</SharedFlowBundle>
</FlowCallout>

Attach Policies to Proxy Flow

Configure your proxy endpoint to execute policies in the correct order:

Complete Proxy Endpoint Configuration:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  <Description/>
  <FaultRules/>

  <!-- PreFlow Response: Capture request/response data -->
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <n>JS-ProcessTrebllePayload</n>
      </Step>
    </Response>
  </PreFlow>

  <!-- PostFlow: Retrieve credentials and send to Treblle -->
  <PostFlow name="PostFlow">
    <Request>
      <Step>
        <n>KVM-GetTreblleCredentials</n>
      </Step>
    </Request>
    <Response>
      <Step>
        <n>FC-TreblleAsyncLogger</n>
      </Step>
    </Response>
  </PostFlow>

  <Flows/>
  <HTTPProxyConnection>
    <BasePath>/your-api-path</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Step 6: Save and Deploy

Save all changes to your API proxy
Deploy the new revision to your environment
Test with a request to verify monitoring is working

Deployment Option 2: Environment-Level

Deploy Treblle monitoring to all APIs in an environment automatically using Flow Hooks. This approach monitors every API in the environment without individual proxy configuration.

When to Use Environment-Level Deployment

You want to monitor all APIs in an environment automatically
You have many API proxies and want centralized management
You want consistent monitoring configuration across all APIs
You need to add/remove monitoring quickly across all APIs

Step 4: Create Environment-Level Shared Flow

Create a single shared flow that contains all Treblle policies in the correct execution order.

In Apigee UI, go to Develop > Shared Flows
Click + Shared Flow
Name: treblle-env-monitor

Upload JavaScript Resource to Shared Flow

In the shared flow, navigate to Resources > JavaScript
Click + Resource
Upload treblle-payload-processor.js from the repository

Add Policies to Shared Flow

Add the following three policies to your shared flow in this exact order:

Policy Execution Order: KVM → JS → SC

KVM-GetTreblleCredentials (First - retrieves credentials)
JS-ProcessTrebllePayload (Second - captures and processes data)
SC-SendToTreblle (Third - sends to Treblle API)

1. Key Value Map Policy:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<KeyValueMapOperations mapIdentifier="treblle-kvm" continueOnError="false" enabled="true" name="KVM-GetTreblleCredentials">
    <DisplayName>KVM-GetTreblleCredentials</DisplayName>
    <Get assignTo="treblle_sdk_token">
        <Key>
            <Parameter>treblle_sdk_token</Parameter>
        </Key>
    </Get>
    <Get assignTo="treblle_api_key">
        <Key>
            <Parameter>treblle_api_key</Parameter>
        </Key>
    </Get>
    <Scope>environment</Scope>
</KeyValueMapOperations>

2. JavaScript Policy:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript continueOnError="false" enabled="true" timeLimit="200" name="JS-ProcessTrebllePayload">
    <DisplayName>JS-ProcessTrebllePayload</DisplayName>
    <Properties/>
    <ResourceURL>jsc://treblle-payload-processor.js</ResourceURL>
</Javascript>

3. Service Callout Policy:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout continueOnError="true" enabled="true" name="SC-SendToTreblle">
    <DisplayName>SC-SendToTreblle</DisplayName>
    <Request clearPayload="true" variable="treblleRequest">
        <Set>
            <Headers>
                <Header name="Content-Type">application/json</Header>
                <Header name="x-api-key">{treblle_sdk_token}</Header>
            </Headers>
            <Payload contentType="application/json">{treblle_payload}</Payload>
            <Verb>POST</Verb>
        </Set>
    </Request>
    <Response>treblle_response</Response>
    <HTTPTargetConnection>
        <URL>https://{treblle_selected_host}</URL>
    </HTTPTargetConnection>
</ServiceCallout>

Configure Shared Flow

Configure the shared flow to execute policies in order:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="treblle-env-monitor">
    <Step>
        <n>KVM-GetTreblleCredentials</n>
    </Step>
    <Step>
        <n>JS-ProcessTrebllePayload</n>
    </Step>
    <Step>
        <n>SC-SendToTreblle</n>
    </Step>
</SharedFlow>

Step 5: Deploy Shared Flow

Save the shared flow configuration
Click Deploy
Select your target environment
Verify deployment is successful

Step 6: Configure Flow Hooks

Flow Hooks allow you to attach shared flows at the environment level, applying them to all API proxies automatically.

Navigate to Flow Hooks

Navigate to Admin > Environments in Apigee Console
Select your target environment (e.g., test, prod)
Click on the Flow Hooks tab

Attach Shared Flow to PostTargetFlow

Locate the PostTargetFlow section
Click + Flow Hook (or edit if one exists)
Configure:
- Shared Flow: Select treblle-env-monitor
- Flow Hook Position: PostTargetFlow
Click Save

What is PostTargetFlow?

The PostTargetFlow executes after the target (backend) responds but before the response is sent to the client. This is the ideal position for Treblle monitoring because:

The complete request/response cycle is available
Execution happens after backend processing
Non-blocking (doesn’t add latency to client response)
Applies to all APIs in the environment automatically

Flow Hooks Execution Flow:

Client Request
      │
      ▼
PreProxyFlow Hook (Optional)
      │
      ▼
API Proxy Logic
      │
      ▼
PreTargetFlow Hook (Optional)
      │
      ▼
Backend/Target API
      │
      ▼
PostTargetFlow Hook ← [Treblle Monitor Attached Here]
      │              (treblle-env-monitor executes)
      │              1. KVM gets credentials
      │              2. JS captures data
      │              3. SC sends to Treblle
      ▼
PostProxyFlow Hook (Optional)
      │
      ▼
Client Response (Zero latency)

Step 7: Verify Environment-Level Monitoring

Test that all APIs in the environment are now being monitored:

# Test with any API proxy in the environment
curl -X GET "https://YOUR_ORG-YOUR_ENV.apigee.net/api-1/users"
curl -X POST "https://YOUR_ORG-YOUR_ENV.apigee.net/api-2/orders" \
  -H "Content-Type: application/json" \
  -d '{"item": "product"}'
curl -X GET "https://YOUR_ORG-YOUR_ENV.apigee.net/api-3/products"

Verification Steps:

Make requests to multiple different APIs in the environment
Check your Treblle Dashboard to verify all requests appear
Enable Trace on any API proxy to see the shared flow execution in PostTargetFlow
Verify the execution order: KVM → JS → SC in the Trace

Configuration

Data Masking

Customize sensitive data detection by modifying the maskingKeywords variable in treblle-payload-processor.js:

// Default masking keywords
var maskingKeywords = 'password,secret,token,key,authorization,auth,credential,private,confidential,ssn,social_security,credit_card,card_number,cvv,pin,api_key,access_token,refresh_token,bearer,x-api-key,x-auth-token';

// Add your custom keywords
var maskingKeywords = 'password,secret,token,key,authorization,auth,credential,private,confidential,ssn,social_security,credit_card,card_number,cvv,pin,api_key,access_token,refresh_token,bearer,x-api-key,x-auth-token,customer_id,user_id,email,phone';

Masking Behavior:

Preserves original string length
Replaces all characters with *
Works in request/response bodies and headers
Case-insensitive matching
Supports nested JSON objects and arrays

Example:

// Before masking
{
  "username": "john.doe",
  "password": "secret123",
  "credit_card": "4532015112830366",
  "email": "john@example.com"
}

// After masking
{
  "username": "john.doe",
  "password": "*********",
  "credit_card": "****************",
  "email": "john@example.com"
}

Endpoint Blocking

Block specific endpoints from being tracked by modifying the blockedEndpoints variable:

// Basic blocking
var blockedEndpoints = 'health,status,ping';

// Wildcard patterns
var blockedEndpoints = 'health,status,ping,admin/*,internal/*,v1/auth/*';

// Complex patterns
var blockedEndpoints = 'health,status,ping,admin/*,internal/*,*/private/*,test-*';

Wildcard Support:

admin/* - Blocks all paths starting with admin/
*/private/* - Blocks any path containing /private/
test-* - Blocks paths starting with test-

Examples:

// Block health check endpoints
var blockedEndpoints = 'health,healthz,ready,alive';

// Block admin and internal APIs
var blockedEndpoints = 'admin/*,internal/*,private/*';

// Block test and debug endpoints
var blockedEndpoints = 'test-*,debug/*,*/test/*';

Debug Mode

Enable detailed logging for troubleshooting:

var debugMode = true;  // Enable debug logging

Debug Output Includes:

Configuration validation results
Payload building process
Endpoint blocking decisions
Error details and stack traces
Performance timing information

Sample Debug Output:

DEBUG: Starting Treblle SDK processing
DEBUG: Configuration validated successfully
DEBUG: Endpoint allowed for tracking: /api/users
DEBUG: Payload built successfully
DEBUG: Payload serialized successfully - size: 1337 bytes
DEBUG: Selected host: rocknrolla.treblle.com
DEBUG: All validations passed - Treblle call prepared successfully
DEBUG: Treblle SDK processing completed

Environment-Specific Configuration

Use different KVM names for different environments:

Development:

<KeyValueMapOperations mapIdentifier="treblle-kvm-dev">
  <!-- ... -->
</KeyValueMapOperations>

Staging:

<KeyValueMapOperations mapIdentifier="treblle-kvm-staging">
  <!-- ... -->
</KeyValueMapOperations>

Production:

<KeyValueMapOperations mapIdentifier="treblle-kvm-prod">
  <!-- ... -->
</KeyValueMapOperations>

Testing the Integration

API-Level Testing

Step 1: Make a Test Request

Send a test request to your monitored API proxy:

curl -X GET "https://YOUR_ORG-YOUR_ENV.apigee.net/your-api-path/users" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Test-Client/1.0"

Step 2: Enable Trace Mode

Navigate to your API proxy in Apigee Console
Click the Trace tab
Start a trace session
Make another test request
Review the policy execution flow:
- PreFlow Response: JS-ProcessTrebllePayload should execute and capture data
- PostFlow Request: KVM-GetTreblleCredentials should retrieve credentials
- PostFlow Response: FC-TreblleAsyncLogger should call the shared flow
- Shared Flow: SC-SendToTreblle should execute

Step 3: Verify in Treblle Dashboard

Visit your Treblle Dashboard
Navigate to your project
Verify that the API request appears with:
- Request method, path, headers, body
- Response status, headers, body
- Response time and performance metrics
- Any captured errors or faults

Environment-Level Testing

Step 1: Test Multiple APIs

Make requests to different APIs in the environment:

# Test API 1
curl -X GET "https://YOUR_ORG-YOUR_ENV.apigee.net/api-1/users"

# Test API 2
curl -X POST "https://YOUR_ORG-YOUR_ENV.apigee.net/api-2/orders" \
  -H "Content-Type: application/json" \
  -d '{"product": "item1", "quantity": 2}'

# Test API 3
curl -X GET "https://YOUR_ORG-YOUR_ENV.apigee.net/api-3/products"

Step 2: Verify Flow Hook Execution

Navigate to any API proxy in the environment
Click the Trace tab
Start a trace session
Make a test request
Look for the PostTargetFlow hook execution
Verify the shared flow treblle-env-monitor executes with all three policies

Step 3: Verify All APIs in Dashboard

Check your Treblle Dashboard
Verify that requests from all different APIs appear
Confirm that all APIs in the environment are being monitored automatically

How It Works

Data Capture

The JavaScript policy captures the following data:

Request Data:

HTTP method (GET, POST, PUT, DELETE, etc.)
Full URL and path
Request headers
Query parameters
Request body
Client IP address
Timestamp

Response Data:

HTTP status code
Response headers
Response body
Response time (in microseconds)
Payload size

Server Information:

Server IP
Timezone
Protocol
Software signature

Error Information:

Apigee fault variables
HTTP error states
Error messages and stack traces

Performance Metrics:

Response time
Payload size
Load time