feat(jdbc): basic OpenTelemetry tracing integration for BigQuery JDBC Statement (#12124)

b/491239772
b/491239773

### Changes

- New connection properties: `enableGcpTraceExporter` (Boolean, default:
false) and `enableGcpLogExporter` (Boolean, default: false)

- `customOpenTelemetry` (Instance): Programmatic injection of a custom
SDK (User Application-Managed setup) via
`BigQueryDataSource.setCustomOpenTelemetry()`

- Added the core initialization logic for `OpenTelemetry`. During
connection setup, it evaluates whether tracing is enabled and constructs
an OpenTelemetry Tracer instance. Then, it passes this newly minted
tracer strictly downward into the core `BigQueryOptions.Builder` via
`.setOpenTelemetryTracer()`

- Intercepted the execution functions (`execute`, `executeQuery`,
`executeLargeUpdate`, `executeBatch`) to spawn child spans wrapping each
database call.

Author: keshavdandeva

java-bigquery/google-cloud-bigquery-jdbc/pom.xml

@@ -133,6 +133,17 @@
                     <relocation>
                       <pattern>io</pattern>
                       <shadedPattern>com.google.bqjdbc.shaded.io</shadedPattern>
+                      <excludes>
+                        <!-- 
+                          OpenTelemetry API and Context must remain unshaded to ensure interoperability.
+                          Shading these would prevent the driver from participating in the application's 
+                          existing tracing context. We are aware that unshaded dependencies can lead to 
+                          version mismatches, but this is a necessary trade-off for the OpenTelemetry 
+                          integration to function correctly across different applications.
+                        -->
+                        <exclude>io.opentelemetry.api.*</exclude>
+                        <exclude>io.opentelemetry.context.*</exclude>
+                      </excludes>
                     </relocation>
                   </relocations>
                   <filters>
@@ -277,6 +288,16 @@
       <artifactId>httpcore5</artifactId>
     </dependency>
 
+    <!-- OpenTelemetry APIs (unshaded) -->
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-context</artifactId>
+    </dependency>
+
     <!--  Test Dependencies  -->
     <dependency>
       <groupId>com.google.truth</groupId>

java-bigquery/google-cloud-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryConnection.java

@@ -41,6 +41,8 @@
 import com.google.cloud.bigquery.storage.v1.BigQueryWriteClient;
 import com.google.cloud.bigquery.storage.v1.BigQueryWriteSettings;
 import com.google.cloud.http.HttpTransportOptions;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
 import java.io.IOException;
 import java.io.InputStream;
 import java.sql.CallableStatement;
@@ -138,6 +140,11 @@ public class BigQueryConnection extends BigQueryNoOpsConnection {
   Long connectionPoolSize;
   Long listenerPoolSize;
   String partnerToken;
+  Boolean enableGcpTraceExporter;
+  Boolean enableGcpLogExporter;
+  OpenTelemetry customOpenTelemetry;
+  Tracer tracer =
+      OpenTelemetry.noop().getTracer(BigQueryJdbcOpenTelemetry.INSTRUMENTATION_SCOPE_NAME);
   DatabaseMetaData databaseMetaData;
 
   BigQueryConnection(String url) throws IOException {
@@ -243,6 +250,9 @@ public class BigQueryConnection extends BigQueryNoOpsConnection {
     this.connectionPoolSize = ds.getConnectionPoolSize();
     this.listenerPoolSize = ds.getListenerPoolSize();
     this.partnerToken = ds.getPartnerToken();
+    this.enableGcpTraceExporter = ds.getEnableGcpTraceExporter();
+    this.enableGcpLogExporter = ds.getEnableGcpLogExporter();
+    this.customOpenTelemetry = ds.getCustomOpenTelemetry();
 
     this.headerProvider = createHeaderProvider();
     this.bigQuery = getBigQueryConnection();
@@ -939,6 +949,14 @@ private BigQuery getBigQueryConnection() {
       bigQueryOptions.setTransportOptions(this.httpTransportOptions);
     }
 
+    OpenTelemetry openTelemetry =
+        BigQueryJdbcOpenTelemetry.getOpenTelemetry(
+            this.enableGcpTraceExporter, this.enableGcpLogExporter, this.customOpenTelemetry);
+    if (this.enableGcpTraceExporter || this.customOpenTelemetry != null) {
+      this.tracer = BigQueryJdbcOpenTelemetry.getTracer(openTelemetry);
+      bigQueryOptions.setOpenTelemetryTracer(this.tracer);
+    }
+
     BigQueryOptions options = bigQueryOptions.setHeaderProvider(this.headerProvider).build();
     options.setDefaultJobCreationMode(
         this.useStatelessQueryMode
@@ -987,6 +1005,13 @@ private BigQueryReadClient getBigQueryReadClientConnection() throws IOException
 
     bigQueryReadSettings.setTransportChannelProvider(activeProvider);
 
+    OpenTelemetry openTelemetry =
+        BigQueryJdbcOpenTelemetry.getOpenTelemetry(
+            this.enableGcpTraceExporter, this.enableGcpLogExporter, this.customOpenTelemetry);
+    if (this.enableGcpTraceExporter || this.customOpenTelemetry != null) {
+      bigQueryReadSettings.setOpenTelemetryTracerProvider(openTelemetry.getTracerProvider());
+    }
+
     return BigQueryReadClient.create(bigQueryReadSettings.build());
   }
 
@@ -1087,4 +1112,8 @@ public CallableStatement prepareCall(
     }
     return prepareCall(sql);
   }
+
+  public Tracer getTracer() {
+    return this.tracer;
+  }
 }

java-bigquery/google-cloud-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryDriver.java

@@ -20,6 +20,7 @@
 import com.google.cloud.bigquery.exception.BigQueryJdbcRuntimeException;
 import io.grpc.LoadBalancerRegistry;
 import io.grpc.internal.PickFirstLoadBalancerProvider;
+import io.opentelemetry.api.OpenTelemetry;
 import java.io.IOException;
 import java.sql.Connection;
 import java.sql.Driver;
@@ -121,16 +122,22 @@ public Connection connect(String url, Properties info) throws SQLException {
     LOG.finest("++enter++");
     try {
       if (acceptsURL(url)) {
-        // strip 'jdbc:' from the URL, add any extra properties
+        Properties connectInfo = info == null ? new Properties() : (Properties) info.clone();
+        Object customOpenTelemetryObj = connectInfo.remove("customOpenTelemetry");
+
         String connectionUri =
-            BigQueryJdbcUrlUtility.appendPropertiesToURL(url.substring(5), this.toString(), info);
+            BigQueryJdbcUrlUtility.appendPropertiesToURL(
+                url.substring(5), this.toString(), connectInfo);
         try {
           BigQueryJdbcUrlUtility.parseUrl(connectionUri);
         } catch (BigQueryJdbcRuntimeException e) {
           throw new BigQueryJdbcException(e.getMessage(), e);
         }
 
         DataSource ds = DataSource.fromUrl(connectionUri);
+        if (customOpenTelemetryObj instanceof OpenTelemetry) {
+          ds.setCustomOpenTelemetry((OpenTelemetry) customOpenTelemetryObj);
+        }
 
         // LogLevel
         String logLevelStr = ds.getLogLevel();

java-bigquery/google-cloud-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryJdbcOpenTelemetry.java

@@ -0,0 +1,52 @@
+/*
+ * 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.bigquery.jdbc;
+
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+public class BigQueryJdbcOpenTelemetry {
+
+  static final String INSTRUMENTATION_SCOPE_NAME = "com.google.cloud.bigquery.jdbc";
+
+  private BigQueryJdbcOpenTelemetry() {}
+
+  /**
+   * Initializes or returns the OpenTelemetry instance based on hybrid logic. Prefer
+   * customOpenTelemetry if provided; fallback to an auto-configured GCP exporter if requested.
+   */
+  public static OpenTelemetry getOpenTelemetry(
+      boolean enableGcpTraceExporter,
+      boolean enableGcpLogExporter,
+      OpenTelemetry customOpenTelemetry) {
+    if (customOpenTelemetry != null) {
+      return customOpenTelemetry;
+    }
+
+    if (enableGcpTraceExporter || enableGcpLogExporter) {
+      // TODO(b/491238299): Initialize and return GCP-specific auto-configured SDK
+      return OpenTelemetry.noop();
+    }
+
+    return OpenTelemetry.noop();
+  }
+
+  /** Gets a Tracer for the JDBC driver instrumentation scope. */
+  public static Tracer getTracer(OpenTelemetry openTelemetry) {
+    return openTelemetry.getTracer(INSTRUMENTATION_SCOPE_NAME);
+  }
+}

java-bigquery/google-cloud-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/BigQueryJdbcUrlUtility.java

@@ -162,6 +162,10 @@ protected boolean removeEldestEntry(Map.Entry<String, Map<String, String>> eldes
   static final int DEFAULT_SWA_APPEND_ROW_COUNT_VALUE = 1000;
   static final String SWA_ACTIVATION_ROW_COUNT_PROPERTY_NAME = "SWA_ActivationRowCount";
   static final int DEFAULT_SWA_ACTIVATION_ROW_COUNT_VALUE = 3;
+  static final String ENABLE_GCP_TRACE_EXPORTER_PROPERTY_NAME = "enableGcpTraceExporter";
+  static final boolean DEFAULT_ENABLE_GCP_TRACE_EXPORTER_VALUE = false;
+  static final String ENABLE_GCP_LOG_EXPORTER_PROPERTY_NAME = "enableGcpLogExporter";
+  static final boolean DEFAULT_ENABLE_GCP_LOG_EXPORTER_VALUE = false;
   private static final BigQueryJdbcCustomLogger LOG =
       new BigQueryJdbcCustomLogger(BigQueryJdbcUrlUtility.class.getName());
   static final String FILTER_TABLES_ON_DEFAULT_DATASET_PROPERTY_NAME =
@@ -607,6 +611,18 @@ protected boolean removeEldestEntry(Map.Entry<String, Map<String, String>> eldes
                       .setDescription(
                           "Reason for the request, which is passed as the x-goog-request-reason"
                               + " header.")
+                      .build(),
+                  BigQueryConnectionProperty.newBuilder()
+                      .setName(ENABLE_GCP_TRACE_EXPORTER_PROPERTY_NAME)
+                      .setDescription(
+                          "Enables or disables GCP OpenTelemetry Trace exporter. Disabled by default.")
+                      .setDefaultValue(String.valueOf(DEFAULT_ENABLE_GCP_TRACE_EXPORTER_VALUE))
+                      .build(),
+                  BigQueryConnectionProperty.newBuilder()
+                      .setName(ENABLE_GCP_LOG_EXPORTER_PROPERTY_NAME)
+                      .setDescription(
+                          "Enables or disables GCP OpenTelemetry Log exporter. Disabled by default.")
+                      .setDefaultValue(String.valueOf(DEFAULT_ENABLE_GCP_LOG_EXPORTER_VALUE))
                       .build())));
 
   private static final List<String> NETWORK_PROPERTIES =