Enable telemetry signals in Cloud Client Libraries for Java

Google Cloud provides powerful monitoring, logging, and diagnostics for Java applications.

The Java client libraries are instrumented to emit tracing, metrics, and logging data. The instrumentation is opt-in; you need to explicitly enable it. This document describes the available signals and how to enable them.

Available signals

Golden Signals include the following telemetry data, adhering to OpenTelemetry Semantic Conventions:

• Traces: Low-level HTTP/gRPC traces representing the network requests made by the client libraries.
• Metrics: Client request metrics, tracking latency and request rates. The primary metric is gcp.client.request.duration.
• Logs: Actionable error logs at the DEBUG level, providing details for failed requests at the transport layer, even if they are eventually retried successfully.

The signals include standard OpenTelemetry attributes (for example, http.response.status_code and rpc.system.name) and Google Cloud-specific custom attributes, which may include these and similar attributes:

• gcp.client.service: The service name (for example, pubsub or storage).
• gcp.client.repo: The client library repository (for example, googleapis/google-cloud-java).
• gcp.client.version: The client library version.
• gcp.client.artifact: The specific module path (for example, com.google.cloud:google-cloud-secretmanager).
• gcp.resource.destination.id: The ID of the resource being acted upon.
• gcp.errors.domain: The error domain for actionable error logs.
• gcp.errors.metadata.<key>: Additional error metadata keys for failed requests (flattened).

For a full list of standard attributes, see the OpenTelemetry HTTP and gRPC semantic conventions.

Enabling telemetry

To protect sensitive data, telemetry signals are disabled by default. You must explicitly opt in to enable them.

Traces, logs, or metrics may contain sensitive data such as resource names, full URLs, and error messages.

Before configuring subscribers or exporters for traces, logs, or metrics, review the contents of the spans and consult the OpenTelemetry documentation to set up filters and formatters to prevent leaking sensitive information, depending on your intended use case.

Tracing and metrics

In the generated Java client libraries, you must enable tracing and metrics programmatically by providing the appropriate tracer factory to your client's settings during initialization:

• Tracing: Configure the client with an OpenTelemetryTracingFactory.
• Metrics: Configure the client with an OpenTelemetryMetricsFactory.
• Both: If you want to enable both tracing and metrics, configure the client with a CompositeTracerFactory that wraps both factories.

For the Java BigQuery SDK, enable tracing by setting BigQueryOptions.newBuilder().setEnableOpenTelemetryTracing(true) and providing the OpenTelemetry tracer.

Logging

Actionable error logs are integrated directly into the core ApiTracer framework. To turn on actionable error logs globally across your Google Cloud client libraries, use the following environment variable:

export GOOGLE_SDK_JAVA_LOGGING=true

Trace context propagation

Trace context propagation in the Java client libraries requires tracing to be explicitly enabled.

When trace generation is enabled (for example, by configuring an OpenTelemetryTracingFactory) and your application has an active OpenTelemetry span in the current context when a client library method is called, the library uses it to provide a tracing context for the outgoing requests. This ensures that your application-level traces can be correlated with backend service logs and behaviors.

Exporting telemetry

Once telemetry is enabled in the client libraries, your application must be configured to collect and export this data to your observability backend.

Tracing and metrics

To export the traces and metrics generated by the Java client libraries, initialize the OpenTelemetry SDK with your preferred exporter (for example, OTLP) and set up the global text map propagator in your application.

For more details on collecting and exporting OpenTelemetry data to Cloud Monitoring or Cloud Trace, see Choose an instrumentation approach.

Logging

The Java client libraries use standard logging frameworks like SLF4J and java.util.logging. When GOOGLE_SDK_JAVA_LOGGING=true is set, actionable error logs are emitted at the DEBUG level.

To route these structured logs to Cloud Logging, configure your logging framework (for example, Logback) to write JSON to standard output (stdout). If you are deploying to an environment like Google Kubernetes Engine or Cloud Run, the built-in agents automatically scrape these logs.

For detailed instructions on configuring Logback or java.util.logging to output Cloud Logging compatible JSON, including trace correlation, see Configure structured logging for Java.