GCP Cloud Trace Integration

The GCP Cloud Trace Integration package provides you with the ability to monitor and display your Wix backend operations in Google Cloud Platform’s Cloud Trace. You can trace latencies in a waterfall graph, with a root span for displaying an operation’s total run time, and a breakdown of its child spans for displaying individual run times.

In the image above, we demonstrate how you can use this package to trace a single backend call to a web module using the GCP Cloud Trace tool.

• We show a waterfall graph displaying the root span (top span) and the child spans of internal operations.
• Notice the root span’s total run time at 1.486 sec, and the child span operations such as a call to the Wix Members API, Wix Data API, and a call to the external service using fetch.
• We annotate the spans and waterfall with additional information by adding events to the trace and attributes to each span.

You can see the code for the generated trace below. To better understand both the image above and the code example below, note the following definitions:

• trace: Represents a single backend call to the web module. In our example, this is the search() function.
• span: The trace can be divided into different operations, which represent a single piece of the trace workflow. There are 2 types of spans:
  • root span: Each trace has a single top-level span. It can contain child spans. In our example, the root span is the ‘search action’ span. We call the traceRoot() function to trace the root span.
  • child span: Operations inside the root span. Our example contains following child spans: The wixDataTraced.insert() function. We call the traceModule() function to trace the wix-data module. The wixMembersBackendTraced.currentMember.getRoles() function. We call the traceModule() function to trace the wix-members-backend module. Fetch operation to thecocktaildb.com endpoint called ‘searching thecocktaildb.com’. We call the traceChild() function to trace this child span separately from the modules.
• events: An event is a message on a span that represents some activity during its lifetime. In our example, the event triggers when the action of inserting data is completed.
• attributes: Used to effectively describe and observe each span/operation to help in the tracing process. In our example, we use it to define which span is related to which search query parameter.

Setup

Before using the package, set up the following:

Google Cloud Platform

1. Go to the Google developer site and select an existing GCP project, or create a new one using the top bar projects dropdown as shown below.

2. Make sure you have the following permissions on GCP. If not, grant yourself these permissions by following the steps below.

   GCP Permissions Needed:

   • Project IAM Admin
   • Create Service Accounts
   • Service Account Key Admin
   • Service Usage Admin
   • Cloud Trace User

   Steps to grant yourself the required permissions:

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

   2. Find the row that contains your email, and click the Edit principal icon in that row.

   3. In the Edit permissions area, click Add another role.
      

   4. In the Role drop-down menu, add each GCP permission one by one. To do this, search for the products/services listed in the table below. Click Save.

      Product or service to search for	Role to select	Why it’s needed
      Service Accounts	Create Service Accounts	To create a service account
      Service Accounts	Service Account Key Admin	To create a service account key and download it
      Service Usage	Service Usage Admin	To be able to check/enable the Cloud Trace API
      Resource Manager	Project IAM Admin	To grant the service account access to the cloud trace
      Cloud Trace	Cloud Trace User	To view list of traces

      
      When done, your roles should look like this:

3. In the left sidebar, click Library. Search for Cloud Trace API. If API enabled is displayed, this API is already enabled and no action is required. If API enabled is not displayed, click Enable.

4. In the left sidebar, click Credentials. In the top menu, click Create Credentials and select Service Account. Provide the following information during the creation process, and complete the steps.

   1. In Grant this service account access to the project in the Select a role drop-down menu, select Cloud Trace and then the Cloud Trace Agent role as shown below.

5. On the Credentials main page, you should see a new entry in the Service Accounts table. Click the entry’s edit icon.

6. Scroll down to the Keys section, and click Add Key > Create New key and select JSON. This will cause a file to download. Copy the values from this file, as you will need them in the next Wix Platform section.

Wix Platform

Go to your Wix site and open the Wix Secrets Manager. Create a new secret called gcp_credentials, and store the content from the downloaded JSON file (in the previous step) as the key value.

Optional:

To define a custom secret name or easily change the existing one, create a config.json file and add the following line:

Package Content

The following backend files are included in the package. Note that only exported functions that you can use in your site are listed here.

telemetry.js

The code in this file contains the functions responsible for tracing specified backend functions.

To use the functions below in your code, import them with the following syntax:

• traceRoot()

  Creates a root span (top level span) and traces it. The root span can include child spans using the traceChild() or traceModule() functions.

  Syntax:

  Copy

  Parameters:

  • description: The name of the root span as it appears in GCP Cloud Trace.
  • callback: A callback function to trace.

  Returns:

  A promise that resolves to the callback function value when the callback function is successful.

  Example:

  Copy

• traceModule()

  Implements a module with a proxy for the specified Wix module object, and traces the APIs in that object. Note that this is the recommended way of working with Wix APIs.

  Syntax:

  Copy

  Parameters:

  • obj: Wix module object.
  • name: Wix module name.

  Returns:

  The Wix module object that was traced.

  Example:

  Copy

• traceChild()

  Creates a child span and traces the callback with the span. Child spans can be nested. Note that traceChild() is the recommended way of working with fetch or getJSON APIs.

  Syntax:

  Copy

  Parameters:

  • description: The name of the child span as it appears in GCP Cloud Trace.
  • callback: A callback function to trace.

  Returns:

  A promise that resolves to the callback function value when the callback function is successful.

  Example:

  Copy

• currentSpan()

  Gets the current instance of Span. You can add events and attributes to the current span.

  Syntax:

  Copy

  Returns:

  The current span instance.

  Example:

  Annotate the spans and waterfall with additional information by adding events to the trace and attributes to each span.

  Use the following code to add events and attributes to a span:

  Copy

setup.js

The code in this file contains unexposed functions that initialize GCP’s Cloud Tracing with your Wix site.

NPM Packages

• @opentelemetry/api
• @opentelemetry/sdk-trace-base
• @opentelemetry/semantic-conventions.
• @opentelemetry/resources
• @google-cloud/opentelemetry-cloud-trace-exporter
• async-retry
• googleapis

Release Notes

2.0 version.

Tags

gcp, cloudTrace, openTelemetry