feat(bigquery-jdbc): Add clearcut telemetry client

java-bigquery-jdbc/.gitignore

@@ -9,6 +9,8 @@ tools/**/*.class
 tools/**/drivers/**
 tools/**/logs/**
 tools/**/*.jfr
+tools/**/odbc/
+tools/**/native_odbc_perf
 
 # Gemini/Jetski agent custom skills
 .agents/

java-bigquery-jdbc/README.MD

@@ -44,6 +44,64 @@ See the [Authentication][authentication] section in the base directory's README.
 
 The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired BigQuery JDBC APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the BigQuery JDBC API calls.
 
+## Client-side usage telemetry
+
+The JDBC driver for BigQuery includes client-side telemetry that
+automatically collects anonymous usage and diagnostic metrics to help Google
+improve driver stability and features. Client-side usage telemetry collection is
+designed to run in the background without affecting driver performance or JDBC
+functionality. Any telemetry transmission failures fail silently and don't
+surface errors to the application or incur any cost.
+
+Client-side usage telemetry never collects SQL query text, parameter values,
+database schema information, or data contents. Telemetry collection doesn't work
+in environments using custom endpoint URLs or restricted network access that
+blocks outbound connections to Google's public logging services.
+
+### Collected diagnostics
+
+The driver collects the following information:
+
+* Environment information: The Driver version, JVM major version, operating
+system platform and version, and an anonymous device correlation ID stored
+locally in the `~/.bigquery-jdbc/telemetry-tag` folder.
+* Connection metrics: Connection outcome status (success, failure, or
+cancellation) and authentication method used (such as service account, ADC,
+or token).
+* Execution metrics: High-level query operation types (such as `SELECT`,
+INSERT, and CREATE TABLE), execution engine substrate used (standard REST API
+or high-throughput API), and duration latency distributions.
+* Error and feature metrics: Internal exception codes, origin methods, and
+feature usage counters (such as prepared statements, batching, and connection
+pooling).
+
+<a id="telemetry-configuration"></a>
+### Client-side usage telemetry configuration
+
+Client-side usage telemetry behaves as a global background service for
+the application's JVM. Settings can be configured using JDBC connection
+properties, environment variables, or Java system properties. The driver
+resolves settings in the following priority: system property > environment
+variable > JDBC connection property.
+
+Due to its global nature, client-side usage telemetry connection properties
+exhibit the following lifecycle behaviors:
+
+* Opt-Out Control: If client-side usage telemetry is disabled at any point using
+a connection property (`EnableDiagnosticTelemetry=0`), environment variable,
+or system property, the service immediately shuts down and remains permanently
+off for the remainder of the JVM lifecycle. It will only restart when
+the JVM restarts.
+
+#### Configuration Keys
+
+To configure these properties, you can use the following keys:
+
+* Opt-Out Control:
+  * Connection Property: `EnableDiagnosticTelemetry=0;`
+  * Environment Variable: `BIGQUERY_JDBC_TELEMETRY_ENABLED=false`
+  * System Property: `-DBIGQUERY_JDBC_TELEMETRY_ENABLED=false`
+
 ## Developer Guide
 
 ### Prerequisites

java-bigquery-jdbc/pom.xml

@@ -36,6 +36,13 @@
   </properties>
 
   <build>
+    <extensions>
+      <extension>
+        <groupId>kr.motd.maven</groupId>
+        <artifactId>os-maven-plugin</artifactId>
+        <version>1.7.1</version>
+      </extension>
+    </extensions>
     <resources>
       <resource>
         <directory>src/main/resources</directory>
@@ -225,6 +232,23 @@
               </execution>
             </executions>
           </plugin>
+          <plugin>
+            <groupId>org.xolstice.maven.plugins</groupId>
+            <artifactId>protobuf-maven-plugin</artifactId>
+            <version>0.6.1</version>
+            <configuration>
+              <protocArtifact>com.google.protobuf:protoc:3.25.5:exe:${os.detected.classifier}</protocArtifact>
+              <checkStaleness>true</checkStaleness>
+            </configuration>
+            <executions>
+              <execution>
+                <goals>
+                  <goal>compile</goal>
+                  <goal>test-compile</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
     </plugins>
   </build>
 

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/exception/BigQueryConversionException.java

@@ -24,6 +24,9 @@
 public class BigQueryConversionException extends SQLException {
 
   public BigQueryConversionException(String message, Throwable cause) {
-    super(BigQueryJdbcExceptionUtils.formatMessage(message, cause), cause);
+    super(
+        BigQueryJdbcExceptionUtils.formatMessage(message, cause),
+        BigQueryJdbcSqlStates.DATA_EXCEPTION,
+        cause);
   }
 }

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/exception/BigQueryJdbcException.java

@@ -28,7 +28,7 @@ public class BigQueryJdbcException extends SQLException {
    * @param message The detail message.
    */
   public BigQueryJdbcException(String message) {
-    super(message);
+    super(message, BigQueryJdbcSqlStates.GENERAL_ERROR);
   }
 
   /**
@@ -37,7 +37,7 @@ public BigQueryJdbcException(String message) {
    * @param ex The InterruptedException to be thrown.
    */
   public BigQueryJdbcException(InterruptedException ex) {
-    super(ex);
+    super(ex.getMessage(), BigQueryJdbcSqlStates.QUERY_CANCELED, ex);
   }
 
   /**
@@ -47,7 +47,10 @@ public BigQueryJdbcException(InterruptedException ex) {
    * @param ex The BigQueryException to be thrown.
    */
   public BigQueryJdbcException(String message, BigQueryException ex) {
-    super(BigQueryJdbcExceptionUtils.formatMessage(message, ex), ex);
+    super(
+        BigQueryJdbcExceptionUtils.formatMessage(message, ex),
+        BigQueryJdbcExceptionUtils.sqlStateForCause(ex),
+        ex);
     this.bigQueryException = ex;
   }
 
@@ -58,7 +61,10 @@ public BigQueryJdbcException(String message, BigQueryException ex) {
    * @param cause Throwable that is being converted.
    */
   public BigQueryJdbcException(String message, Throwable cause) {
-    super(BigQueryJdbcExceptionUtils.formatMessage(message, cause), cause);
+    super(
+        BigQueryJdbcExceptionUtils.formatMessage(message, cause),
+        BigQueryJdbcExceptionUtils.sqlStateForCause(cause),
+        cause);
   }
 
   /**
@@ -70,13 +76,23 @@ public BigQueryJdbcException(String message, Throwable cause) {
    */
   public BigQueryJdbcException(Throwable cause) {
     super(
-        cause instanceof BigQueryJdbcException ? cause.getMessage() : String.valueOf(cause),
-        cause instanceof SQLException ? ((SQLException) cause).getSQLState() : null,
-        cause instanceof SQLException ? ((SQLException) cause).getErrorCode() : 0,
+        cause == null
+            ? null
+            : (cause instanceof BigQueryJdbcException
+                ? cause.getMessage()
+                : (cause.getMessage() != null ? cause.getMessage() : cause.toString())),
+        cause instanceof SQLException && ((SQLException) cause).getSQLState() != null
+            ? ((SQLException) cause).getSQLState()
+            : BigQueryJdbcExceptionUtils.sqlStateForCause(cause),
+        cause instanceof SQLException
+            ? ((SQLException) cause).getErrorCode()
+            : (cause instanceof BigQueryException ? ((BigQueryException) cause).getCode() : 0),
         cause instanceof BigQueryJdbcException ? cause.getCause() : cause);
     if (cause instanceof BigQueryJdbcException) {
-      bigQueryException = ((BigQueryJdbcException) cause).bigQueryException;
+      this.bigQueryException = ((BigQueryJdbcException) cause).bigQueryException;
       setStackTrace(cause.getStackTrace());
+    } else if (cause instanceof BigQueryException) {
+      this.bigQueryException = (BigQueryException) cause;
     }
   }
 

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/exception/BigQueryJdbcExceptionUtils.java

@@ -16,6 +16,8 @@
 
 package com.google.cloud.bigquery.exception;
 
+import com.google.cloud.bigquery.BigQueryException;
+
 /** Utility class for JDBC exceptions. */
 final class BigQueryJdbcExceptionUtils {
 
@@ -37,4 +39,49 @@ public static String formatMessage(String message, Throwable cause) {
             ? "\n" + (cause.getMessage() != null ? cause.getMessage() : cause.toString())
             : "");
   }
+
+  /**
+   * Maps a cause to a standard SQL:2003 SQLState.
+   *
+   * <p>Returns {@code HY000} (general error) for anything unrecognised, so the result is always a
+   * valid 5-character state and never null.
+   *
+   * @param cause the underlying cause, may be null.
+   * @return a 5-character SQLState.
+   */
+  static String sqlStateForCause(Throwable cause) {
+    if (!(cause instanceof BigQueryException)) {
+      return BigQueryJdbcSqlStates.GENERAL_ERROR;
+    }
+    String reason = ((BigQueryException) cause).getReason();
+    if (reason == null) {
+      return BigQueryJdbcSqlStates.GENERAL_ERROR;
+    }
+    switch (reason) {
+      case "invalidQuery":
+      case "invalid":
+      case "badRequest":
+        return BigQueryJdbcSqlStates.SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION;
+      case "accessDenied":
+        return BigQueryJdbcSqlStates.INSUFFICIENT_PRIVILEGE;
+      case "invalidUser":
+        return BigQueryJdbcSqlStates.INVALID_AUTHORIZATION;
+      case "quotaExceeded":
+      case "rateLimitExceeded":
+      case "resourcesExceeded":
+        return BigQueryJdbcSqlStates.INSUFFICIENT_RESOURCES;
+      case "responseTooLarge":
+        return BigQueryJdbcSqlStates.PROGRAM_LIMIT_EXCEEDED;
+      case "stopped":
+        return BigQueryJdbcSqlStates.QUERY_CANCELED;
+      case "backendError":
+      case "internalError":
+      case "jobInternalError":
+        return BigQueryJdbcSqlStates.SYSTEM_ERROR;
+      case "notImplemented":
+        return BigQueryJdbcSqlStates.FEATURE_NOT_SUPPORTED;
+      default:
+        return BigQueryJdbcSqlStates.GENERAL_ERROR;
+    }
+  }
 }

java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/exception/BigQueryJdbcSqlFeatureNotSupportedException.java

@@ -27,7 +27,7 @@ public class BigQueryJdbcSqlFeatureNotSupportedException extends SQLFeatureNotSu
    * @param message The detail message.
    */
   public BigQueryJdbcSqlFeatureNotSupportedException(String message) {
-    super(message);
+    super(message, BigQueryJdbcSqlStates.FEATURE_NOT_SUPPORTED);
   }
 
   /**
@@ -36,6 +36,6 @@ public BigQueryJdbcSqlFeatureNotSupportedException(String message) {
    * @param ex The BigQueryException to be thrown.
    */
   public BigQueryJdbcSqlFeatureNotSupportedException(BigQueryException ex) {
-    super(ex);
+    super(ex.getMessage(), BigQueryJdbcSqlStates.FEATURE_NOT_SUPPORTED, ex);
   }
 }