Apigee API Gateway

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 and 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 and 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 api 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.

Note

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 api settings
YOUR_TREBLLE_API_KEY: From your Treblle api settings

Option A: Using Apigee Management API (Recommended)


# 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

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

Tip

For most use cases, environment-level deployment is recommended as it provides automatic coverage for all APIs with minimal configuration.

Configuration

Data Masking

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


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';

Note

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-*';

Caution

Ensure your blocked endpoint patterns don’t inadvertently exclude APIs you want to monitor. Test thoroughly after configuration changes.

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

Treblle Docs

Apigee API Gateway

Supported Apigee Versions

Prerequisites

Required Permissions

Network Requirements

Architecture Overview

API-Level Architecture

Environment-Level Architecture

Flow Execution Order

Installation

Step 1: Get Your Treblle Credentials

Step 2: Clone the Repository

Step 3: Create Environment Configuration

Note

Deployment

Deployment Option 1: API-Level

Deployment Option 2: Environment-Level

Tip

Configuration

Data Masking

Note

Endpoint Blocking

Caution

How It Works

Data Capture