Use the hybrid trace APIs

This section describes how to use the Apigee APIs to work with debug sessions in Apigee hybrid.

Create a debug session

To create a debug session:

  1. On the command line, get your gcloud authentication credentials, as the following example shows:

    TOKEN=$(gcloud auth print-access-token)

    To check that your token was populated, use echo, as the following example shows:

    echo $TOKEN

    This should print an encoded string to stdout.

    For more information, see gcloud command-line tool overview.

  2. Send an authenticated POST request to the Debug Sessions API.

    The following example shows the structure of a request that creates a new debug session:

    curl -H "Authorization: Bearer $TOKEN" -X "POST"
      https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions

    On a successful request, hybrid responds with a JSON object that describes the newly created debug session, as the following example shows:

    {
      "name":"56382416-c4ed-4242-6381-591bbf2788cf",
      "validity":300,
      "count":10,
      "tracesize":5120,
      "timeout":"600"
    }

    Subsequent requests to your API proxy (until the session length or maximum number of requests is reached) will be evaluated and potentially stored in the debug session data.

Set debug session length

To create a session with a specific duration, use the following as a payload in your debug session creation request:

{
  "timeout":"debug_session_length_in_seconds"
}

The following example creates a new debug session that is just 42 seconds long:

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions
  -d ' {
    "timeout":"42"
  } '

You can set a session's timeout in debug session creation requests only; you cannot change a session's duration after you create the session.

The default value of timeout is 300 (5 minutes). The maximum value is 600 seconds (10 minutes).

Create a debug session with a filter

You can optionally use a filter in your debug session so that the data collected by hybrid includes only requests that you want. For example, you can filter out all requests with an HTTP response code that is less than 599 or compare values in the request against custom variables.

Requests that are not included in a debug session because they are filtered out do not count towards the maximum number of transactions in the debug session.

To create a session with a filter, use the following as a payload in your debug session creation request:

{
  "filter":"filter_body"
}

The following example creates a new debug session that includes only transactions in which header "A" equals 42 and header "B" equals 43, or the fault code is "ExpectedEOF":

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

You can define a filter in debug session creation requests only; you cannot add a filter to an existing debug session, and you cannot remove a filter from an active debug session.

For more information on constructing filters, see Filters.

List debug sessions

To get a list of debug sessions:

  1. On the command line, get or refresh your gcloud authentication credentials, as the following example shows:

    TOKEN=$(gcloud auth print-access-token)
  2. Send an authenticated GET request to the Debug Sessions API.

    The following example shows the structure of a request that gets a list of debug sessions:

    curl -H "Authorization: Bearer $TOKEN"
      https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions

    The Apigee API responds with a sessions object that contains a list of currently active debug sessions, as the following example shows:

    {
      "sessions": [
        {
          "id": "a423ac73-0902-4cfa-4242-87a353a84d87",
          "timestamp_ms": 1566330186000
        },
        {
          "id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
          "timestamp_ms": 1566330286000
        }
      ]
    }

The Debug Sessions API does not indicate whether a debug session is active.

If you create a session but the session does not yet have any transactions in it, then the API does not include the session in this list. The API only includes sessions in the response if the session contains at least one transaction.

List transactions in a debug session

To list transactions in a debug session:

  1. On the command line, get or refresh your gcloud authentication credentials, as the following example shows:

    TOKEN=$(gcloud auth print-access-token)
  2. Send an authenticated GET request to the List Debug Session Data API.

    The following example shows the structure of a request that gets a list of transactions in the specified debug session:

    curl -H "Authorization: Bearer $TOKEN"
      https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data

    You can get the value of the debug_session_ID from a request that gets a list of debug sessions.

    The Apigee API responds with an array of transaction IDs, as the following example shows:

    [
      "myorg-myenv-ver-5qxdb-64",
      "myorg-myenv-ver-5qxdb-65",
      "myorg-myenv-ver-5qxdb-66",
      "myorg-myenv-ver-5qxdb-67",
      "myorg-myenv-ver-5qxdb-68",
      "myorg-myenv-ver-5qxdb-69",
      "myorg-myenv-ver-5qxdb-70",
      "myorg-myenv-ver-5qxdb-71",
      "myorg-myenv-ver-5qxdb-72"
    ]
    

Get transaction data

You can download transaction data by the transaction ID with the Get Debug Session Data API. You cannot use this API to get an entire sessions' data at one time; to do that, you must use the UI, as described in Download trace data.

The transaction data saved during a debug session is formatted in JSON. You can load this data in the Offline Trace tool.

To get the data for a specific transaction in a debug session:

  1. On the command line, get or refresh your gcloud authentication credentials, as the following example shows:

    TOKEN=$(gcloud auth print-access-token)
  2. Send an authenticated GET request to the Get Debug Session Data API.

    The following example shows the structure of a request that gets transaction data from a debug session:

    curl -H "Authorization: Bearer $TOKEN"
      https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data/transaction_ID

    You can get the value of the transaction_ID from a request that gets a list of transactions in a session.

    The Apigee API responds with a JSON payload that contains the data for the specified transaction, as described in Download data structure.

    Trace data contains all information about the request and response for each part of the flow in a proprietary JSON format. You can save this data and later use it in the Offline Trace tool.

    If no requests were added to the session before it ended, then the response will look like the following:

    []

Stop a debug session

You cannot explicitly stop a debug session once it has started. The debug session will continue until the timeout or the transaction count has been reached.

Delete debug session data

To delete all trace data:

  1. On the command line, get or refresh your gcloud authentication credentials, as the following example shows:

    TOKEN=$(gcloud auth print-access-token)
  2. Send an authenticated DELETE request to the Debug Sessions API.

    The following example shows the structure of a request that deletes all trace data:

    curl -H "Authorization: Bearer $TOKEN" -X DELETE
      "https://apigee.googleapis.com/v1/organizations/org_name/environments/env_name/apis/api_proxy_name/revisions/revision_number/debugsessions/debug_session_ID/data"

    On a successful deletion, the Apigee API response contains no data.

Debug session data is persisted for 24 hours only. If you do not explicitly delete it before that time, then hybrid deletes it for you.