Apigee Trace Viewer for Fast & Easy Trace Parsing

[tyayers]

Apigee Trace Viewer Tutorial: Capturing & Analyzing Proxy Traces

This guide provides end-to-end instructions for capturing API proxy debug traces in both Google Cloud Apigee X (or Hybrid) and the local Apigee Emulator, extracting the trace JSON data (via web UI or automated REST APIs), and analyzing the results using the Apigee Trace Viewer.

The Apigee Trace Viewer open source project provides an easy and fast way to view any Apigee trace file (all versions), and will be explored further below.

---

Table of Contents

1. Introduction
2. Capturing Traces in Apigee X (Cloud)
   • Method 1: Google Cloud Console UI
   • Method 2: Apigee Management REST API (Automated)
3. Capturing Traces with the Apigee Emulator (Local)
   • Method 1: VS Code (Cloud Code / Apigee Extension)
   • Method 2: Local Emulator Management API
4. Using Apigee Trace Viewer
   • Loading Trace Data
   • Interface Tour
   • Analyzing Proxy Executions
   • Panel Resizing & Responsive Navigation
5. Common Troubleshooting Scenarios
   • Diagnosing Policy Faults & Error Flows
   • Pinpointing Latency Bottlenecks
   • Verifying Variable Mutability & Conditional Logic

---

Introduction

Apigee proxies execute sequential flow steps—including policy execution, condition evaluation, target server communication, and variable assignments. When requests fail or exhibit unexpected latency, Apigee’s built-in debug tracing logs granular, point-in-time data for every step in the pipeline.

Apigee Trace Viewer normalizes trace formats across cloud and emulator environments, giving you a clean, interactive timeline to inspect execution flow, variable state changes, and latency metrics without having to decipher massive raw JSON blobs manually.

---

Capturing Traces in Apigee X (Cloud)

Apigee X supports tracing through both the Google Cloud Console and programmatic REST APIs.

Method 1: Google Cloud Console UI

1. Navigate to Proxies: Open the Google Cloud Console, navigate to Apigee > Proxy Development > API Proxies, and select your proxy.
2. Access Debug: Click the Debug tab at the top of the proxy editor.
3. Start Debug Session:
   • Choose the deployed Environment (e.g., eval, dev, prod).
   • Select the deployed Revision.
   • (Optional) Add request filters such as specific HTTP headers or query parameters to capture only matching traffic.
   • Click Start Debug Session. The session remains active for 10 minutes by default.

4. Send Test Traffic: Execute requests against your proxy endpoint:

   curl -i https://your-apigee-host.example.com/v1/my-proxy/endpoint
   

5. Inspect Captured Transactions: As transactions complete, they populate the left-hand transactions panel.

6. Download Trace JSON:

   • Click Download Trace (or Export Session) located above the transaction list.
   • Save the resulting JSON file locally (e.g., cloud-trace.json).

---

Method 2: Apigee Management REST API (Automated)

You can script and automate trace capture using the Apigee Management REST API.

Prerequisites

• gcloud CLI installed and authenticated.
• Required permissions: roles/apigee.admin or roles/apigee.environmentAdmin.

Set your shell environment variables:

export TOKEN=$(gcloud auth print-access-token)
export ORG="your-gcp-org-id"
export ENV="dev"
export API="your-proxy-name"
export REV="1"

Step 1: Create a Debug Session

Create an active debug session with a specified timeout (in seconds, up to 600):

curl -X POST \
  "https://apigee.googleapis.com/v1/organizations/${ORG}/environments/${ENV}/apis/${API}/revisions/${REV}/debugsessions?timeout=300" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": ""
  }'

The response includes the unique name identifier containing your SESSION_ID:

{
  "name": "organizations/my-org/environments/dev/apis/my-proxy/revisions/1/debugsessions/7dc02c30-553f-4f2c-82d8-fd0aa58b208a",
  "createTime": "2026-09-18T04:00:00Z",
  "timeout": "300s"
}

Store the session ID:

export SESSION_ID="7dc02c30-553f-4f2c-82d8-fd0aa58b208a"

Step 2: Send Test Traffic

Send test requests to your proxy hostname or IP address:

curl -i -X GET "https://${YOUR_APIGEE_HOSTNAME}/test-path" \
  -H "User-Agent: TraceTest/1.0"

Step 3: Fetch and Save Complete Trace Data

Retrieve the recorded debug trace messages and save them directly as a JSON file:

curl -X GET \
  "https://apigee.googleapis.com/v1/organizations/${ORG}/environments/${ENV}/apis/${API}/revisions/${REV}/debugsessions/${SESSION_ID}/data" \
  -H "Authorization: Bearer ${TOKEN}" \
  -o cloud-trace.json

The resulting cloud-trace.json file is ready to load into Apigee Trace Viewer.

---

Capturing Traces with the Apigee Emulator (Local)

The Apigee Emulator enables local proxy development and testing without deploying to the cloud.

Method 1: VS Code (Cloud Code / Apigee Extension)

1. Deploy Proxy Locally: Right-click your proxy directory and deploy to the local Apigee Emulator.

2. Start Debug Session:

   • In the Apigee explorer side panel in VS Code, expand your running emulator container.
   • Under Active Deployments, find your proxy revision.
   • Right-click and choose Start Debug Session.

3. Send Local Requests: Send requests to your emulator endpoint (typically on localhost port 8998 or 8080):

   curl -i http://localhost:8998/test-proxy/json
   

4. Export Debug Output:

   • In the Debug session panel, click Export or save the debug session JSON output to a local file (e.g., emulator-trace.json).

---

Method 2: Local Emulator Management API

If you run the Apigee Emulator container directly in Docker or CI/CD pipelines, interact with its local management endpoints:

1. Create Local Debug Session:

   curl -X POST \
     "http://localhost:8998/v1/organizations/emulator/environments/test/apis/DefaultProxy/revisions/1/debugsessions?timeout=300" \
     -H "Content-Type: application/json" \
     -d '{}'
   

2. Trigger Traffic:

   curl -i http://localhost:8998/v1/my-local-endpoint
   

3. Fetch Emulator Trace JSON:

   curl -X GET \
     "http://localhost:8998/v1/organizations/emulator/environments/test/apis/DefaultProxy/revisions/1/debugsessions/${SESSION_ID}/data" \
     -o emulator-trace.json
   

---

Using Apigee Trace Viewer

Apigee Trace Viewer runs as a single-page web app either hosted on Cloud Run or run locally via Go or Docker.

• Hosted URL: https://apigee-trace-viewer-323709580283.europe-west1.run.app
• Local URL: http://localhost:8080 (after running go run main.go)
• Source Code Repository: GitHub - tyayers/apigee-trace-viewer: A simple trace JSON viewer for all Apigee trace file formats. · GitHub

Loading Trace Data

You can load trace files in three ways:

1. Drag-and-Drop: Drag your downloaded cloud-trace.json or emulator-trace.json anywhere onto the browser window.
2. File Picker: Click Load File in the top navigation header and pick your JSON file.
3. Paste Raw JSON: Click Load JSON in the header, paste the raw trace JSON into the modal dialog, and click Parse & Load.
4. Quick Samples: Use the Emulator Example or Cloud Example links in the empty state view to explore pre-loaded trace data immediately.

---

---

Analyzing Proxy Executions

Each card in the timeline details a specific point in the transaction lifecycle:

• Step Title & Type: Identifies the policy name (e.g. VerifyApiKey, SpikeArrest, JavaScript-1), state transition (e.g. REQ_START -> REQ_HEADERS_PARSED), or condition.
• Timing Badges:
  • Step Duration: Time spent inside the specific policy or phase (e.g. 45 ms). Steps taking 15 ms or longer are highlighted for immediate visibility.
  • Elapsed Time: Cumulative time elapsed since the request entered the proxy (e.g. +120 ms).
• Properties Table: Shows runtime configuration, evaluated route rules, headers, client IP, and target response headers.
• Variable Access Section: Highlights flow variable mutations with color-coded tags:
  • GET: Variables read by the step.
  • SET: Variables created or modified by the step.
  • REMOVE: Variables cleared from the context.
• Payload / Content Box: Formatted message content (request payload, fault response, or converted body).

---

Common Troubleshooting Scenarios

Diagnosing Policy Faults & Error Flows

When a request returns a 4xx or 5xx status code:

1. Select the failing request from the left panel (marked with a red status badge like 500).
2. Click the Errors filter chip above the timeline.
3. The visualizer isolates the exact step where the fault occurred.
4. Expand the Properties and Variable Access sections to inspect fault.name, error.message, and the condition that triggered the fault rule.

Pinpointing Latency Bottlenecks

1. Examine the request summary in the left panel to identify transactions with high total duration.
2. Scroll through the timeline and look for execution badges with highlighted borders.
3. Common latency sources include external network hops:
   • ServiceCallout policies calling third-party APIs.
   • Heavy script execution in JavaScript or Python policies.
   • TargetEndpoint backend connection and transfer times (targetendpoint_default.totalConnectionTimeMs).

Verifying Variable Mutability & Conditional Logic

1. When testing routing rules or security policies (such as OAuth2 scopes or JWT claims), click the Variables filter chip.
2. Trace how variables like jwt.VerifyJWT-1.claim.role or request.header.Authorization are set and later referenced by subsequent routing conditions.
3. Verify that sensitive variables are properly cleared before responses are sent back to the client.

---

Conclusion

I hope this was a useful guide to debug tracing across Apigee X and the Apigee Emulator, and how traces from any Apigee environment and version can be viewed with the Apigee Trace Viewer tool.

---

Let’s talk — Google Cloud Sales Specialist awaits