This page describes how to enable client-side traces with OpenTelemetry when you use the Cloud Storage client libraries to interact with Cloud Storage. You can collect and view trace data using the following supported Cloud Storage client libraries:
Overview
Enabling traces in the Cloud Storage client libraries lets you monitor performance, pinpoint latency issues, and quickly perform debugging for Cloud Storage requests. Traces let you see the sequence of a completed request, providing a detailed view of how the request was received, managed, and responded to by Cloud Storage. A single trace is composed of multiple spans, which are detailed, time-stamped records of each function or operation your application performed throughout the Cloud Storage request.
Benefits
Collecting and propagating trace data provides the following benefits to your application:
Enhanced performance visibility: because trace data is generated in near real-time as Cloud Storage completes each request you make, you can quickly identify bottlenecks in performance and detect latency issues.
Error handling: you can pinpoint where issues arise, speeding up root cause analysis and reducing downtime using the information about each Cloud Storage request that's provided in a trace.
How client-side traces work
The following sections provide a detailed look at how trace collection works.
How trace collection works with OpenTelemetry
The Cloud Storage client libraries supports trace data collection using the OpenTelemetry SDK to set up the following components required to collect and propagate trace data:
Trace provider: used by the Cloud Storage client libraries, the trace provider is responsible for creating and managing the tracing system, including generating and managing traces and spans in your application.
Trace exporter: used by the OpenTelemetry SDK, the trace exporter is responsible for sending trace data to a backend observability platform such as Cloud Trace, where you can analyze and visualize trace data. To learn more about the trace exporter, see How trace exporters work.
How trace exporters work
Configuring traces using the OpenTelemetry SDK includes selecting an observability backend to export your data to where it is analyzed, stored, and visualized. While you can export your trace data to any observability backend of your choice, we recommend using Cloud Trace, which can be accessed using the Google Cloud console and provides integration with other Google Cloud services.
Once the trace provider and the trace exporter are configured and enabled, you can view trace data in near real-time as traces and spans are generated for each Cloud Storage request.
Using the Cloud Trace explorer in the Google Cloud console, you can view each trace which contains the following:
A high-level view of a Cloud Storage request from end to end.
Multiple spans, each span capturing a time-stamped single operation within the Cloud Storage request that was performed.
To read more about traces and spans, see the OpenTelemetry documentation about traces and spans.
Pricing
Trace data is chargeable. Charges are based on the number of trace spans ingested and scanned by Cloud Trace. To learn more about chargeable trace spans and pricing examples, see Cloud Trace costs.
Before you begin
Before you can collect traces for your Cloud Storage API usage, you must complete the following steps:
-
Enable the Cloud Trace API.
Enable the Cloud Storage API.
Required roles
To get the permission that you need to write traces to Cloud Trace,
ask your administrator to grant you the
Cloud Trace Agent (roles/coudtrace.agent
) IAM role on the project used by the client.
This predefined role contains the
cloudtrace.traces.patch
permission,
which is required to
write traces to Cloud Trace.
You might also be able to get these permissions with predefined roles, or you can create custom roles to grant specific permissions. For instructions on granting roles on projects, see Grant or revoke a role. For more information about the Cloud Trace Agent role, see Identity and Access Management (IAM) documentation.
Configure tracing for your application
Use the following instructions to configure tracing and begin collecting trace data using the Cloud Storage client library:
Java
Install the following Cloud Storage Java client library versions:
com.google.cloud:google-cloud-storage:2.47.0
or latercom.google.cloud:libraries-bom:26.53.0
or later
Install the Cloud Trace exporter for OpenTelemetry. You can also use any exporter of your choice.
Install the Cloud Trace propagator.
Create an instance of the Cloud Storage client with OpenTelemetry traces enabled.
Python
Install the Cloud Storage Python client library:
pip install google-cloud-storage[tracing]>=2.18.0
Install the Cloud Trace exporter and propagator. You can also use any exporter of your choice.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
Install the OpenTelemetry requests instrumentation to trace the underlying HTTP requests.
pip install opentelemetry-instrumentation-requests
Set the environment variable to selectively opt in to tracing for the Python storage client:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
Configure the trace exporter and trace provider.
View your traces
Use the Cloud Trace explorer to view your trace data in the Google Cloud console:
-
In the Google Cloud console, go to the Trace explorer page:
You can also find this page by using the search bar.
In the Trace explorer page, click a specific trace in the scatter plot to view the trace details.
The Trace details pane displays a table of trace spans.
Optional: click a span row to view detailed information about a specific span such as the following information:
Attributes: key-value pairs that provide additional information about the span.
Logs & events: log entries that are associated with the span.
Stack traces: stack traces that are associated with the span.
Metadata & Links: links to other Google Cloud services that are associated with the span.
For more information about using the Cloud Trace explorer, see Find and explore traces.