Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion java-spanner/google-cloud-spanner/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -518,7 +518,20 @@
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
<exclusions>
<exclusion>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-sender-okhttp</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-sender-grpc-managed-channel</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
/*
* Copyright 2026 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package com.google.cloud.spanner;

import com.google.auth.Credentials;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.Strings;
import com.google.common.collect.ImmutableList;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributesBuilder;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.sdk.trace.export.SpanExporter;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import java.io.IOException;
import java.net.URI;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.function.BiFunction;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.jspecify.annotations.Nullable;

/**
* Creates and caches the OpenTelemetry instances that are used for built-in tracing. One instance
* is created per project and sampling rate, so that spans are always exported to the project of the
* client that created them.
*/
final class BuiltInTracingProvider {

static final BuiltInTracingProvider INSTANCE = new BuiltInTracingProvider();

private static final Logger logger = Logger.getLogger(BuiltInTracingProvider.class.getName());

private static final String TELEMETRY_API_ENDPOINT = "https://telemetry.googleapis.com";
private static final String CLOUD_PLATFORM_SCOPE =
"https://www.googleapis.com/auth/cloud-platform";
private static final AttributeKey<String> GCP_PROJECT_ID_KEY =
AttributeKey.stringKey("gcp.project_id");
private static final AttributeKey<String> SERVICE_NAME_KEY =
AttributeKey.stringKey("service.name");
private static final String OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME";

private final Map<List<Object>, OpenTelemetrySdk> openTelemetries = new HashMap<>();
private BiFunction<String, Credentials, SpanExporter> spanExporterFactory =
BuiltInTracingProvider::createTelemetryApiExporter;
private Thread shutdownHook;
private boolean openCensusWarningLogged;
private boolean customTracingInfoLogged;

private BuiltInTracingProvider() {}

@Nullable
synchronized OpenTelemetry getOrCreateOpenTelemetry(
String projectId, Credentials credentials, double samplingRate) {
List<Object> key = ImmutableList.of(projectId, samplingRate);
OpenTelemetrySdk openTelemetry = openTelemetries.get(key);
if (openTelemetry == null) {
try {
openTelemetry =
createOpenTelemetry(
projectId, spanExporterFactory.apply(projectId, credentials), samplingRate);
} catch (Throwable throwable) {
logger.log(
Level.WARNING,
"Unable to create the exporter for built-in tracing, built-in tracing is disabled",
throwable);
return null;
}
openTelemetries.put(key, openTelemetry);
if (shutdownHook == null) {
shutdownHook = new Thread(this::shutdown);
Runtime.getRuntime().addShutdownHook(shutdownHook);
}
Comment on lines +95 to +98

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Registering a shutdown hook via Runtime.getRuntime().addShutdownHook can throw an IllegalStateException if the JVM is already in the process of shutting down. Since this call is outside the try-catch block, it can cause unexpected crashes for callers initializing or using a client during JVM shutdown. Wrapping the registration in a try-catch block for IllegalStateException resolves this safely.

      if (shutdownHook == null) {
        Thread hook = new Thread(this::shutdown);
        try {
          Runtime.getRuntime().addShutdownHook(hook);
          shutdownHook = hook;
        } catch (IllegalStateException e) {
          // JVM is shutting down, ignore
        }
      }

}
return openTelemetry;
}

synchronized void logOpenCensusWarningOnce() {
if (!openCensusWarningLogged) {
openCensusWarningLogged = true;
logger.log(
Level.WARNING,
"Built-in tracing is enabled, but this application uses OpenCensus tracing. Built-in"
+ " tracing requires OpenTelemetry and is not used. Call"
+ " SpannerOptions.enableOpenTelemetryTraces() before creating any Spanner client to"
+ " use built-in tracing.");
}
}

synchronized void logCustomTracingInfoOnce(boolean setInOptions) {
if (!customTracingInfoLogged) {
customTracingInfoLogged = true;
logger.log(
Level.INFO,
setInOptions
? "Built-in tracing is enabled, but an OpenTelemetry instance was set with"
+ " SpannerOptions.Builder#setOpenTelemetry. Spanner uses that instance instead"
+ " of built-in tracing."
: "Built-in tracing is enabled, but a global OpenTelemetry instance with tracing is"
+ " registered, for example by the OpenTelemetry Java agent. Spanner uses that"
+ " instance instead of built-in tracing.");
}
}

@VisibleForTesting
synchronized void setSpanExporterFactory(
BiFunction<String, Credentials, SpanExporter> spanExporterFactory) {
this.spanExporterFactory = spanExporterFactory;
}

@VisibleForTesting
synchronized void reset() {
shutdown();
openTelemetries.clear();
spanExporterFactory = BuiltInTracingProvider::createTelemetryApiExporter;
openCensusWarningLogged = false;
customTracingInfoLogged = false;
}

private synchronized void shutdown() {
for (OpenTelemetrySdk openTelemetry : openTelemetries.values()) {
openTelemetry.close();
}
}

private static OpenTelemetrySdk createOpenTelemetry(
String projectId, SpanExporter spanExporter, double samplingRate) {
SdkTracerProvider tracerProvider =
SdkTracerProvider.builder()
.setResource(createResource(projectId, System.getenv(OTEL_SERVICE_NAME)))
.setSampler(Sampler.parentBased(Sampler.traceIdRatioBased(samplingRate)))
.addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
.build();
return OpenTelemetrySdk.builder()
.setTracerProvider(tracerProvider)
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.build();
}

@VisibleForTesting
static Resource createResource(String projectId, @Nullable String serviceName) {
AttributesBuilder attributes = Attributes.builder().put(GCP_PROJECT_ID_KEY, projectId);
if (!Strings.isNullOrEmpty(serviceName)) {
attributes.put(SERVICE_NAME_KEY, serviceName);
}
return Resource.getDefault().merge(Resource.create(attributes.build()));
}

private static SpanExporter createTelemetryApiExporter(
String projectId, Credentials credentials) {
Credentials scopedCredentials =
credentials instanceof GoogleCredentials
&& ((GoogleCredentials) credentials).createScopedRequired()
? ((GoogleCredentials) credentials).createScoped(CLOUD_PLATFORM_SCOPE)
: credentials;
return OtlpGrpcSpanExporter.builder()
.setEndpoint(TELEMETRY_API_ENDPOINT)
.setHeaders(() -> getRequestHeaders(scopedCredentials))
.build();
}

@VisibleForTesting
static Map<String, String> getRequestHeaders(Credentials credentials) {
try {
Map<String, String> headers = new HashMap<>();
for (Map.Entry<String, List<String>> header :
credentials.getRequestMetadata(URI.create(TELEMETRY_API_ENDPOINT)).entrySet()) {
if (!header.getValue().isEmpty()) {
headers.put(header.getKey(), header.getValue().get(0));
}
}
return headers;
} catch (IOException exception) {
logger.log(Level.WARNING, "Unable to get credentials for built-in tracing", exception);
return Collections.emptyMap();
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ class SpannerImpl extends BaseService<SpannerOptions> implements Spanner {
new TraceWrapper(
Tracing.getTracer(),
getOptions()
.getOpenTelemetry()
.getTracingOpenTelemetry()
.getTracer(
MetricRegistryConstants.INSTRUMENTATION_SCOPE,
GaxProperties.getLibraryVersion(this.getOptions().getClass())),
Expand Down Expand Up @@ -174,6 +174,11 @@ private void logSpannerOptions(SpannerOptions options) {
+ options.isEnableExtendedTracing()
+ "\nEnd to end tracing enabled: "
+ options.isEndToEndTracingEnabled()
+ "\nBuilt-in tracing enabled: "
+ options.isEnableBuiltInTracing()
+ (options.isEnableBuiltInTracing()
? "\nBuilt-in tracing sampling rate: " + options.getBuiltInTracingSamplingRate()
: "")
+ "\nBuilt-in metrics enabled: "
+ options.isEnableBuiltInMetrics());
if (options.getSessionPoolOptions() != null) {
Expand Down
Loading
Loading