Use the trace UI

This section describes how to create a new debug session and view the request/response data. In additon, this section describes how to view previous debug sessions and apply filters to a debug session using the hybrid UI.

Create a new debug session in the hybrid UI

When you create a new debug session, you can view the request and response data in the UI—for requests created in either the UI or via an API or other external source. Behind the scenes, trace also records data for requests that were not initiated by the UI.

To create a new debug sesssion in the hybrid UI:

  1. Open the Apigee hybrid UI in a browser.
  2. Select API Proxies from the main view.
  3. Select the proxy that you want to debug.

    The Deployments view displays.

  4. Click the Trace tab in the upper right of the Deployments view:

    Tabs

    The Trace view displays:

    Trace view

  5. In the Start a trace session panel:
    1. From the Env drop-down list, select the environment + revision number of the API proxy you want to debug.
    2. The following example shows the Start a trace session panel:

      Start a trace view

    3. (Optional) From the Filter drop-down list, select a filter to apply to all transactions in the debug session you are creating. The default is "None", which includes all transactions in the trace data.

      For information on using filters, see Filters. For information about the built-in filters, see Use pre-defined filters.

    4. Click Start Trace Session.

      The hybrid UI now display details about the current trace session, including its ID, in the Trace details panel.

      Although the UI created a new debug session, but you still need to send the request before there is any data to collect.

      From the Trace details panel, you can do the following:

      Icon Function Description
      Download icon Download Download the active session's trace data, which you can then view offline.
      Return icon Return Return to the previous panel, where you can start another debug session. The current debug session continues until it reaches its timeout or transaction count.
      Delete icon Delete Delete the currently selected debug session's data. This deletes the session's data, but does not stop the sessions.

      There is a default timeout limit of 10 minutes for a trace session that you start in the UI (it's different for a session started with the API).

      The clock starts running as soon as you click Start Trace Session, so you can choose to wait until after the next step before you click Start Trace Session to maximize the amount of data you gather.

  6. In the Request/Response panel:
    1. In the URL field, enter the endpoint that you want to send a request to. Optionally, append query string parameters to the URL. You cannot submit requests other than GET.
    2. The Request/Response panel only shows the data for UI-based requests. Note, however, that trace also records data for requests that were not initiated by the UI.

    3. Click Send.

      Apigee sends a request to the specified URL. Each time you click Send, the hybrid UI logs the request in the Trace details panel.

      The following example shows several successul requests (resulting in an HTTP status code of 200):

      Captured trace requests

      In addition, the UI displays trace data in the Transaction Map and Phase Details sections of the Request/Response panel, and populates the Proxy Endpoint, Request Headers, Request Content, and Properties sections, as the following example shows:

      Captured trace requests

      For more information about the phases, transaction map, and other sections of the Request/Response view, see Using the Trace tool.

    The debug session is now active and records data about all requests (unless they are filtered out). The sessioni will remain active until either the timeout is reached or the number of requests recorded in the session is exceeeded.

  7. You can create any number of new debug sessions in the UI. For more information, see Start another debug session.

Stop an active session/delete session data

You cannot simply stop an active debug session. You can, however, delete an active session's data. To do this, click the Delete icon ( Delete icon ) in the Trace details panel for that session.

Alternatively, you can wait for the active session to end.

Start another debug session

During an active debug session, you can start another session in the hybrid UI. To do this, click the "back arrow" icon (keyboard_arrow_left) in the Trace details panel:

Back arrow that returns you to the Start a trace session panel

The UI returns to the Start a trace session panel, where you can start a new debug session.

View recent debug sessions

Apigee hybrid saves debug session data for 24 hours. You cannot configure this; after 24 hours, the data will no longer be available. Before that time, you can view the debug sessions in the hybrid UI.

If you want to save debug session data for future reference, Apigee recommends that you download it.

To view recent debug sessions:

  1. Open the Apigee hybrid UI in a browser.
  2. Select API Proxies from the main view.
  3. Select the proxy that you want to debug.
  4. Click the Trace tab in the upper right of the Deployments view.
  5. In the Recent trace sessions panel:
    1. From the Env drop-down list, select the environment of the API proxy whose debug session you want to view.
    2. From the Rev drop-down list, select the revision number of the API proxy whose debug session you want to view.

    The hybrid UI displays a list of debug sessions that are available, as the following example shows:

    Recent trace sessions

  6. Click the link for the session you want to view.

    The hybrid UI loads the debug session and populates the Request/Response panel with the trace data.

Debug session data

You can download a file of raw trace results for offline viewing. The downloaded file shows the complete details of the debug session including the contents of all headers, variables, and policies.

Debug session data is available to download or view in the UI for 24 hours only. After that point, hybrid deletes the session data.

Download debug session data

To downloaded the current debug session's trace data:

  • Active session: Click the Download icon ( Download icon ) in the Trace details panel.
  • Previous session: Click the name of the session in the Recent trace sessions panel, as described in View recent debug sessions. Then click Download icon in the Trace details panel.

Download data structure

Session data downloaded via hybrid's trace UI is different than data you download via hybrid's Use the trace APIs:

The UI download:

  • Includes all transactions in the entire session
  • Stores transactions in a Messages array
  • Includes metadata about the session (as a DebugSession object)

By contrast, when you download data via the API, you get a single, specified transaction at a time. For more information, see Download transactions.

Download data examples

The following example highlights a DebugSession metadata object in the downloaded data. This object is following by the Messages array that contains the transactions in the session.

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

If the debug session did not include any requests, then the Message array is empty, as the following example shows:

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": []
}

API download data structure

Debug session data that you download via the trace APIs contains a single transaction object that looks like the following:

{
  "completed": true,
  "point": [
    ...
  ...
}

You can download a single transaction at a time via the trace APIs; you cannot download an entire session in a single API call. For more information, see Download transactions.

View downloaded trace data

After you have downloaded trace data, you can view it "offline" in the hybrid UI.

To view downloaded trace data:

  1. Open the Apigee hybrid UI in a browser.
  2. Select API Proxies from the main view.
  3. Select Develop > Offline Trace.

    The Offline Trace view displays:

    Offline
    Trace view

  4. To load data into the Offline Trace view, click either of the Choose File buttons.

    The hybrid UI loads the trace file's data and displays it:

    A view of actual offline trace data in the hybrid UI.

    Note the following regions of the Offline Trace view:

    • Top Left: Displays the request type. Use this area to navigate among the requests.
    • Bottom Left: Displays configuration options, as described in Using the Trace tool.
    • Top right: Displays details about the trace session.
    • Middle right: Shows the path of the request through the API proxy; this path is known as the transaction map; it shows which policies were encountered and indicates if any errors occurred during the execution of those policies.
    • Bottom right: Shows the request headers for the currently selected request.

    When viewing trace data in the hybrid UI, you can toggle various options such as whether to view policies that are disabled or variables and properties. For more information, see Debugging with trace in the Edge documentation.

Use pre-defined filters

The hybrid UI makes a set of pre-defined filters available to you so that you can use common filters without having to write your own.

When you create a new debug session in the UI, you can choose a pre-defined filter to apply in the Start a trace session panel.

The following table describes these pre-defined filters:

Filter Name Description
Response Time Greater Than

Checks for latency issues where:

  • target.duration is the target latency, or the amount of time, in milliseconds, that a request takes to be sent to and received from the target (calculated as the difference between target.received.end.timestamp and target.sent.start.timestamp)
  • client.duration is the client latency, or the amount of time, in milliseconds, that a request takes to be sent to and received from the client (calculated as the difference between client.received.end.timestamp and client.sent.start.timestamp)

For example:

target.duration > 420 && client.duration > 1000

For more information, see client and target in the Flow variables reference.

Response Code

Checks if the HTTP response code matches the specified value; for example:

response.status.code <= 599
Header

Checks if the specified request header is equal to the specified value; for example:

request.header.cache-control.1 == "16544"
Path

Checks if the request matches the specified path. You can use wildcard matching in your value; for example:

request.path == /myproxy/customer/4*
Query Param

Checks if the specified request query parameter is equal to the specified value; for example:

request.queryparam.lang == "language:en-us"
Custom

Lets you insert your own expressions. You can use any objects in the Flow variables reference and the syntax in Conditions reference. In addition, you can use custom variables.

For more information about creating custom filters, see Filters.