Duration : 30 mins
Persona : API Team
Apigee provides extension policies to allow you to quickly leverage third party cloud services as part of the API proxies you deploy. It is common for API teams to need logging and monitoring to be able to diagnose and troubleshoot issues which may arise in production for the client applications they support through the platform. In this lab we'll explore using the Google Cloud Stackdriver Logging Extension to write log data to Stackdriver Logging.
Apigee provides Extensions policies to integrate external resources into API proxies. For example, you can integrate Google Cloud Platform services such as Google Stackdriver Logging. At run time, an API proxy uses the extension to exchange requests and responses with the external resource. The Extension configuration is a one time setup after which you can leverage the extension policy in your API proxies to perform actions that the third party service can provide. In this lab, we will write log message to Google Stackdriver Logging using the extension policy provided.
- If you don't already have a Google Account (Gmail or Google Apps), you must create one.
- Once created, go to https://cloud.google.com/ and click the "Get started for free" button in the top right corner of the page.
- Next, you will be asked to login to your Gmail account, choose your country then accept the terms & conditions.
- Fill in the details required to create your account. After completed click on “Start my free trial“. A valid credit card is required to create a Google Cloud Platform account.
- When you begin the free trial, Google creates a billing account for you and credits $300 to your account. Anything you do that would normally result in a charge is billed against this credit. You will receive billing statements indicating how much of your free credit has been spent. Further details about GCP Free Tiers and billing credits during a free trial can be found here.
- Last, you need to create a project. Sign in to Google Cloud Platform console and create a new project by clicking the new project button in the modal popup that appears after clicking on the project dropdown on the top navigation bar.
You must have a service account key associated with your project to do the next steps in this lab.
To create a service account for this lab:
- Go to the Google Cloud Platform Console.
- From the Project drop-down menu, select the project you created in the pre-requisites section to add an API key to.
- From the Navigation menu, select APIs & Services → Library.
- At the top search box do a search for "Stackdriver Logging API" and select the result that matches that title exactly.
- In the next screen, enable the API and wait for the green indicator.
- From the Navigation menu, select APIs & Services → Credentials.
- On the Credentials page, click Create credentials → Service account key.
- In the Create service account key window enter the following:
- Service account: Select New service account
- Service account name: apigee-logs
- Role: Project → Owner
Click Create. This will download a service account file to your local machine. We will use the contents to setup our Google Stackdriver Logging Extension.
This completes the service account setup.
- Note: The Role field authorizes your service account to access resources. You can view and change this field later by using the GCP Console. If you are developing a production app, specify more granular permissions than Project > Owner. For more information, see granting roles to service accounts.
-
In Apigee Edge console, go to Admin → Extensions and click the +Add Extension button in the top right corner of the screen.
-
Search for Stackdriver in the New Extension creation wizard and click Google Stackdriver Logging
- Give the extension the following properties:
- Name: Stackdriver
- Description: Leverage Google Stackdriver for logging.
Click Create when finished.
-
Under Environment Configurations click on the test environment to configure it's properties.
-
In the Configurations: test modal box that appears, set the following properties:
- GCP Project ID: {{INSERT_YOUR_GCP_PROJECT_ID_HERE}}
- Credential: {{Copy and paste the entire contents of the JSON Service Account file here}}
Click Save.
- Click Deploy for the test environment and wait for the Extension to deploy. This may take a few minutes.
-
Go to Develop → API Proxies and click the +Proxy button in the top right corner of the page.
-
Select Reverse Proxy then click Next.
-
Enter the following for the proxy details:
- Proxy Name: StackdriverLogging
- Proxy Base Path: /log
- Existing API: http://cloud.hipster.s.apigee.com/products
- Description: Example showing how to use Google Stackdriver Logging with Apigee.
Click Next.
-
In the Security step, click Pass Through then click the Next button.
-
In the Virtual Hosts step, un-select default. Click Next.
-
In the last step click, Build and Deploy. Once created, click the link at the bottom of the screen to be taken to the proxy.
-
Go to the Develop tab of the proxy editor.
-
Click the +Step button of the proxy endpoint PreFlow Response.
- Scroll all the way down to the bottom of the Add Step modal and select Extension Callout. Add the following properties:
- Display Name: EC-Stackdriver
- Extension: StackdriverLogging
- Action: log
Click Add.
- Replace the contents of the XML configuration for the Extension Callout with the following snippet (you will need to replace the GCP PROJECT ID with your own):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="EC-Stackdriver">
<DisplayName>EC-Stackdriver</DisplayName>
<Connector>StackdriverLogging</Connector>
<Action>log</Action>
<Input><![CDATA[{
"logName" : "apigee-log-data",
"metadata": {
"resource": {
"type": "global",
"labels": {
"project_id": "INSERT_YOUR_GCP_PROJECT_ID_HERE"
}
}
},
"message" : {response.content}
}]]></Input>
</ConnectorCallout>
-
Switch over to the Trace tab of the proxy editor and click Start Trace Session.
-
Press send a few times to send log data to our newly created Global log entry apigee-log-data. We will confirm that logs were sent to Stackdriver Logging in our GCP project in the next steps. Click the elements in the trace pointed out in the image below to confirm you are seeing the same data that is returned from our products API to Stackdriver Logging.
- Switch back to your GCP project console. From the Navigation menu, select Logging → Logs Viewer under Stackdriver
- Select the following values for the first two drop down menus of the Log Viewer to see the log data we recently created. You should see the same number of entries that you created in the trace of the API proxy.
- Global
- apigee-log-data
This concludes the hands on portion of this lab. If you experience any issues viewing log data please ask your instructor for assistance.
If you like to learn by watching, here is a short video on leveraging extension policies in API proxies - ????
Now that you understand how to log data with the Google Stackdriver Logging extension. See if you can configure and deploy other Extensions available from the list of supported Extensions page.
- What are Extension policies designed to do?
- Which Google Cloud Platform services do Extension policies current support (name 3)?
- Why would an API Team want to leverage an Extension policy rather than make service callouts?
That completes this hands-on lesson. In this lab you learned how to create an Extension Policy that leverages Google Stackdriver Logging and send data to a Google Cloud Platform project without the need to understand the underlying REST APIs that Google Cloud exposes for interacting with its services or implementing complex authentication logic.
-
Useful Apigee documentation links on Policy Composition -
-
Extensions Overview - https://docs.apigee.com/api-platform/extensions/extensions-overview
-
Extensions Reference - https://docs.apigee.com/api-platform/reference/extensions/reference-overview-extensions
-
How did you like this lab? Rate here.
Now go to Module-4