Logging Apigee access logs

This page applies to Apigee, but not to Apigee hybrid.

View Apigee Edge documentation.

Apigee Subscription and Pay-as-you-go customers can enable Cloud Logging ingress access logs for each Apigee instance in their organization. Once enabled, this feature allows you to view the logs generated by ingress gateways in your Apigee infrastructure, such as an external Application Load Balancer or an Anthos gateway, to assist in troubleshooting Apigee API calls.

It is important to note that if this feature is enabled for one or more of your Apigee instances, you will be charged for logs shipped to your project. For more information on Google Cloud charges for logging, see Cloud Logging pricing.

This topic describes how Apigee customers can enable and use Cloud Logging ingress access logs for the Apigee instances in their organization.

Before you begin

To enable the feature, you must have the following role and permissions:

  • Roles: Apigee Organization Admin (roles/apigee.admin)
  • Permissions:
    • apigee.instances.create
    • apigee.instances.update

Check for the roles

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.

  3. In the Principal column, find the row that has your email address.

    If your email address isn't in that column, then you do not have any roles.

  4. In the Role column for the row with your email address, check whether the list of roles includes the required roles.

Grant the roles

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM
  2. Select the project.
  3. Click Grant access.
  4. In the New principals field, enter your email address.
  5. In the Select a role list, select a role.
  6. To grant additional roles, click Add another role and add each additional role.
  7. Click Save.

Enable ingress access logging for your Apigee instances

You can enable Cloud Logging ingress access logging when you create or edit an Apigee instance using the Apigee UI in Cloud console or the API.

To enable the feature when creating or updating an Apigee instance, follow the instructions in Managing instances to begin creating or editing an instance.

Apigee in Cloud console

In the Logging section of the Create an instance or Edit instance page:

  1. Click the Enable logging toggle to enable the feature.
  2. Optionally, select an HTTP response code from the response code box to act as a filter for the access logs.

    If you want to include all logs, regardless of HTTP response code, select None (all HTTP responses).

    To create a custom filter, select Custom and enter the filter in the following format:

    status_code > XX && status code <= YY

    For example:

    status_code >= 500 && status_code < 504

  3. After providing all the information required to create or edit your instance, click Save.

Apigee API

To update an existing instance using the Apigee API, use the following command: 

curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/instances/INSTANCE_NAME?updateMask=access_logging_config.enabled,access_logging_config.filter" \
    -X PATCH -H "Authorization: Bearer $TOKEN" \
    -H 'Accept: application/json' -H 'Content-Type: application/json' \
    -d '{
      "name": "INSTANCE_NAME",
      "accessLoggingConfig":
        {
          "enabled": "true",
          "filter": "status_code >= 0 && status_code < 600 "
        }
      }'

Where:

  • ORG_NAME is the name of your Apigee organization.
  • INSTANCE_NAME is the name of the Apigee instance you want to edit.

Note that in this command, the value specified for the filter property will return all logs. If you wish to filter the logs based on HTTP or other status codes, you can adjust the filter value.

Once the instance is successfully created or updated, the ingress access logs for that instance should be available in your project within minutes.

View the ingress access logs

Once the feature is enabled, you can view the ingress access logs for instances in your project within minutes using Logs Explorer in the Google Cloud console.

To view log entries in Logs Explorer:

  1. In the Google Cloud console, select Logging > Logs Explorer.

    Go to Logs Explorer

  2. Make sure your Google Cloud project is selected.
  3. From the Query tab, enter the log name into the Query editor field using either of the following methods:
    • To use the Log name select box:
      1. Click the Log name select box to open the Log name pane.
      2. Enter ingress_instance in the Select log names box.
      3. Click Apply.
      4. The log name appears in the Query editor field.
    • In the Query editor field, enter the log name directly:

      logName="projects/ORG_NAME/logs/apigee.googleapis.com/ingress_instance"

  4. Build the rest of your query in the Query editor field. The logs will appear in the Query results list.
  5. Click on any log entry for more detail.

Troubleshooting with ingress access logs

Once the feature enabled and logs are available in Logs Explorer, you can leverage a number of Cloud Logging features to assist with troubleshooting, including:

  • Building queries using the Cloud Logging query language

    You can retrieve and analyze logs when you use the Logs Explorer by writing queries in the query-editor field and by making selections from the filter menus options included with log entries. To learn more about building queries and analyzing data in Logs Explorer, see Build and save queries by using the Cloud Logging query language.

  • Enabling log-based metrics and alerts

    You can define your own log-based metric to capture information specific to your Apigee instances. For more information, see Log-based metrics overview.

    You can create a log-based alerting policy from the Logs Explorer. For more information and detailed steps, see Creating a log-based alerting policy by using the Logs Explorer.

  • Filtering by HTTP status codes

    You can refine your queries in the Logs Explorer to filter by HTTP status codes, even if you did not elect to filter your ingress access logs by HTTP status code when enabling the feature. To add this filter to your query, use the following format:

    status_code > XX && status code <= YY

    For example:

    status_code >= 500 && status_code < 504

  • Filtering by ingress status codes

    In addition to filtering by HTTP status codes, you can create a query to filter for ingress status_code 0. This code often indicates a network or connectivity issue preventing the client from receiving a server response.

For a detailed explanation of all the functionality available in Logs Explorer, see View logs by using the Logs Explorer.

Disable the feature

Once you have finished troubleshooting your Apigee instance, you can edit the instance to disable the feature. Disabling the feature will turn off access to the ingress_instance logs in your project and will stop billing.

You can edit the instance to disable the feature using the Apigee UI in Cloud console or the API.

Apigee in Cloud console

To disable the feature using the Apigee in Cloud console:

  • Open the Apigee UI in Cloud console in your browser.
  • Select Management > Instances.
  • Click the instance that you want to edit.
  • In the Instance details page, click Edit.
  • In the Edit Instance page, click the Enable logging toggle to disable the feature.
  • Click Save.

    • Apigee API

    Use the following command to disable the feature in your instance: 

    curl "https://apigee.googleapis.com/v1/organizations/ORG_NAME/instances/INSTANCE_NAME?updateMask=access_logging_config.enabled,access_logging_config.filter" \
    -X PATCH -H "Authorization: Bearer $TOKEN" \
    -H 'Accept: application/json' -H 'Content-Type: application/json' \
    -d '{
      "name": "INSTANCE_NAME",
      "accessLoggingConfig":
        {
            "enabled": "false"
        }
        }'

    Where:

    • ORG_NAME is the name of your Apigee organization.
    • INSTANCE_NAME is the name of the Apigee instance you want to edit.