Table of contents
1.
Introduction
2.
Trace app latency
2.1.
Download and Deploy the application
2.2.
Create a trace
2.3.
View the trace data
2.3.1.
Overview Window
2.3.2.
Trace list window
2.4.
About the application
2.4.1.
Instrumentation
2.4.2.
How the application Works
2.4.3.
Clean up
3.
Viewing Trace Details
3.1.
Selected trace details pane
3.2.
Waterfall graph
3.3.
Tables with span details
3.4.
Annotating spans
3.4.1.
Annotating with time events
4.
Node.js and OpenTelemetry
5.
Installing, Initializing, and Using the client
5.1.
Auto-instrumentation
5.2.
Configure the Platform
5.2.1.
Running on Google Cloud
5.2.2.
Running Locally and Elsewhere
6.
Frequently Asked Questions
6.1.
Which method is used by the application's main function to construct the Flask middleware?
6.2.
Which file contains information that is necessary to capture and send trace data to the Google Cloud Project?
6.3.
What does getTracer return?
7.
Conclusion
Last Updated: Mar 27, 2024

Basic Concepts of Cloud Trace

Career growth poll
Do you think IIT Guwahati certified course can help you in your career?

Introduction

Cloud trace is defined as a distributed tracing system that collects latency data from the applications and then displays it on the Google Cloud Console. It automatically analyzes all of the application's traces in order to generate in-depth latency reports for surfacing the application's traces. This blog will cover the basics of Cloud Trace.

Trace app latency

A user can learn how to use cloud trace by following the below-mentioned steps:

  • A sample application must be deployed to the GKE cluster.
  • By sending an HTTP request to the application, create a trace.
  • View the latency information of the newly created trace using the Cloud Trace Interface.

Download and Deploy the application

Follow the below-mentioned steps to download and deploy the application:

  • Click on the Activate Cloud Shell in the Google Cloud console toolbar to open a Cloud Shell.
  • If you want to download the source code from GitHub, use the below-mentioned command
gcloud services enable container.googleapis.com
  • If you want to enable the GKE API, use the below-mentioned command in the cloud shell:
gcloud services enable container.googleapis.com
  • In order to create a GKE cluster with a name demo, use the below-mentioned command
gcloud container clusters create demo --zone us-west1-b
  • To verify successful creation, use the below-mentioned kubectl command:
kubectl get nodes
  • The cluster context can be set using the below-mentioned command:
gcloud container clusters get-credentials demo --zone us-west1-b
  • By using the below command, deploy the same application:
cd python-docs-samples/trace/cloud-trace-demo-app && ./setup.sh

Create a trace

The time that is taken by an application to complete a single operation is described by a trace. A trace can consist of one or more spans. How long it takes to perform a complete sub-operation is described by span.

A trace can be created using the following command:

curl $(kubectl get svc cloud-trace-demo-c -ojsonpath='{.status.loadBalancer.ingress[0].ip}')


A HTTP GET request is generated by the curl command, and an issue to the request to service names cloud-trace-demo-c. Helloworl! It is printed to the shell when the request is completed.

View the trace data

Click on the Navigation Menu and then Select Trace to open the cloud trace interface.

Overview Window

It is the default view in the trace. It provides latency data and summary information along with an analysis report. If a new project is created, then the most interesting pane of the Overview window is the pane labeled as the Recent traces, it lists all of the most recent traces with their latency.

Trace list window

To open the trace list window, click on the trace list in the trace navigation pane. The trace list window displays a graph and a table, where each dot on the graph represents a trace. Every dot also corresponds to a row in the table. Select a dot in the graph or a row in the table if you want to view a trace in detail. This opens two panes that display the details of the selected trace. One pane displays the trace in a waterfall graph, and the pane shows its details. Every row corresponds to a span in the waterfall graph. If you want to view the details about a span, then click on the corresponding row in the waterfall graph.

About the application

The same application which we used earlier is present in the GitHub repository. It contains information on how to use the application in various environments. 

Instrumentation

The necessary information regarding capturing and tracing data to the Google cloud project is in the app.py file in the GitHub repository.

  • A middleware component is created by the application that uses Flask as the HTTP framework.
  • Create a Flask middleware that uses the StackdriverExporter() in the application's main function.


How the application Works

The application creates three services which are named a,b, and c. it configures the service c to call the service b and the service b to call service a. When an HTTP request to service c is issued, the following command is used:

curl $(kubectl get svc cloud-trace-demo-c -ojsonpath='{.status.loadBalancer.ingress[0].ip}')


The curl command works in a below-mentioned way:

  • The IP address of the service names cloud-trace-demo-c is fetched by kubectl.
  • A HTTP request to service c is sent using the curl command.
  • When service c receives the HTTP request, it sends a request to service b.
  • When service b receives the HTTP request, it sends a request to service a.
  • When the service receives the request, it returns the string Hello. The string Hello is a keyword passes as a default argument to this service.
  • When service b receives the response from service a, it appends the string with string world and then returns Helloworld. The string world is a keyword that is passed as a default argument to this service.
  • When service c receives the response from service b, it appends !, and then returns Helloworld!
  • Finally, the response from the services c is printed in the Cloud Shell.


Clean up

Follow the below-mentioned steps if you want to avoid any incurring charger to your Google cloud account for the resources used.

  • If a new project was created for the quickstart, then delete the project to stop accruing charges. To delete the project, follow the below-mentioned steps:
    • Click on the Navigation Menu and Select Home in the google cloud console.
    • Click on Go to project settings in the Project info pane.
    • Click on Shut down in the Settings window and complete the remaining steps.
  • If a new project wasn't created for the quickstart, then delete the GKE cluster named as a demo using the below-mentioned command:
gcloud container clusters delete demo --zone us-west1-b

Viewing Trace Details

  • Go to the Trace list page from the Google cloud console.
  • The information about a trace can be displayed in multiple ways:
    • Click on the URL listed in the table.
    • Click on the dot in the graph.
    • Enter the trace ID in the hex format in the Selected trace details. 

Selected trace details pane

The following mentioned details are shown when a trace is chosen for examination.

  • The identifier of that trace is displayed in the Selected trace details text box.
  • Using a waterfall graph, the pane displays the graphical representation of latency data for the request. By default, only the selected trace of the root span is highlighted.
  • A pane displays a series of tables showing detailed information about the span highlighted in the waterfall graph.

Waterfall graph

Each row corresponds to a span in the trace in the waterfall graph:

  • If in case a clock symbol is displayed, it means that the cloud trace has found a span whose start time is earlier than the start time of it's parent. The Cloud trace automatically compensates for the inconsistency in time.
  • If the (!) symbol is displayed, it signifies that the span contains an HTTP error.
  • The name of the RPC call is in the format: service_name.call_name.
  • It is the time that it took to complete the round-trip RPC call.

Tables with span details

They contain detailed information about the row that is currently highlighted in the waterfall graph. Each row in the waterfall graph corresponds to the trace span. When a row is highlighted, then the details for that span include its URL name as well as the relative start time and the name of the RPC call.

Though, the type of Data and Information displayed by these tables varies which depends on the element that is highlighted. The following mentioned fields are always displayed in the table:

a table to define the properties with description that is displayed using tables with span details

The table that has the title Detail lists the metadata about the span. The properties mentioned in the below table are always displayed:

enteries of table: detail list

There are some additional properties that might be listed when the type of request is HTTP. the below-mentioned table displays a list of some commonly observed properties:

additional properties with description

Annotating spans

A user can add user-defined content to a trace. The Cloud Trace API v1 lets the user add labels, while the v2 lets the user add time events. The time events are more flexible, as they let the user specify a message in the form of a string along with the set of attributes. A key-value pair is used to represent each attribute.

Annotating with time events

The user can add annotations and message events to spans by simply creating a TimeEvents object and attaching it to the Span object when it is being used in Cloud Trace API v2 batchWrite. The TimeEvents object is basically an array of TimeEvent objects, it contains a message event and an annotation. To view the TimeEvents, click on the Show events in the trace's waterfall graph. 

Node.js and OpenTelemetry

The Node.js applications can be used to collect the Cloud Trace data using OpenTelemetry. The following steps needs to be followed if the user wants to collect traces with OpenTelemetry and Node.js.

Installing, Initializing, and Using the client

There are three ways which are offered by the openTelemetry to instrument the application:

  • Auto-instrumentation for the Node.js applications
  • When this approach is used, then the user can configure the application to include the @opentelemetry/sdk-trace-node SDK. No changes are required in the code.
  • Manual Tracing
  • When this approach is used, the user needs to modify the libraries that the user is using to collect trace information.
  • Auto-instrumentation for the web applications
  • When this approach is used, the user needs to configure the application to include the @opentelemetry/sdk-trace-web SDK. The SDK collects user-side performance data, including latency and distributed traces, which gives the user information to diagnose front-end issues.

Auto-instrumentation

The auto-instrumentation for Node.js applications is provided by the @opentelemetry/sdk-trace-node module. It automatically identifies the following within the application:

  • Frameworks like Express
  • Protocols like HTTP, HTTPS
  • Databases such as MYSQL, MongoDB

It provides ready-to-use tracing so that the user doesn't need to make any changes in the code. The instrumentation code automatically performs the below-mentioned actions:

  • To allow distributed tracing, it extracts a trace-context identifier from the inbound requests.
  • It guarantees that the current trace context is propagated while the transaction traverses an application.
  • It allows the distributed trace to continue to the next hop by adding the trace-context identifier to outbound requests.
  • Creates and ends spans

Configure the Platform

The user can use Cloud Trace on Google Cloud as well as on other platforms.

Running on Google Cloud

If your application is running on the Google Cloud, then no authentication credentials are needed in the form of a service account to the client library. Though, the user must ensure that the Google Cloud Platform has the Cloud Trace API access scope enabled. 

The default access-scope settings enable the cloud trace API for the following mentioned configurations:

  • App Engine flexible environment
  • App Engine standard environment
  • GKE
  • Compute Engine
  • Cloud Run

If any custom access scopes are used, then it must be ensured that the Cloud Trace API access scope is enabled.

Running Locally and Elsewhere

If the application is running outside of Google Cloud, then the user must provide authentication credentials in the form of a service account to the client library. The service account must have a Cloud Trace agent role. To find the application's credentials, the google cloud client libraries use Application Default Credentials. The credentials can be provided in one of the three ways:

  • Run gcloud auth application-default login
  • Place the service account in a default path for your OS. The default paths for Windows and Linux are mentioned below:
  • Windows
%APPDATA%/gcloud/application_default_credentials.json
  • Linux
HOME/.config/gcloud/application_default_credentials.json
  • Configure the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path to your service account:
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Frequently Asked Questions

Which method is used by the application's main function to construct the Flask middleware?

The application's main function uses the StackdriverExporter() method to construct the Flask middleware.

Which file contains information that is necessary to capture and send trace data to the Google Cloud Project?

The app.py file in the GitHub repository contains information that is necessary to capture and send trace data to the Google Cloud Project.

What does getTracer return?

The getTracer returns an instance of the tracer. It tells OpenTelemetry who is creating the spans.

Conclusion

In this article, we have extensively discussed the basic level concepts of Cloud Trace.

After reading about the basic level concepts of Cloud Trace, are you not feeling excited to read/explore more articles on Google Cloud? Don't worry; Coding Ninjas has you covered. To learn about GCP certification: Google Cloud Platform, the difference between AWS, Azure & Google Cloud, and which platform is best: AWS vs. Google Cloud.

If you wish to enhance your skills in Data Structures and AlgorithmsCompetitive ProgrammingJavaScript, etc., you should check out our Guided path column at Coding Ninjas Studio. We at Coding Ninjas Studio organize many contests in which you can participate. You can also prepare for the contests and test your coding skills by giving the mock test series available. In case you have just started the learning process, and your dream is to crack major tech giants like Amazon, Microsoft, etc., then you should check out the most frequently asked problems and the interview experiences of your seniors that will surely help you in landing a job in your dream company. 

Do upvote if you find the blogs helpful.

Happy Learning!

Thankyou image

Live masterclass