feat(bqjdbc): Implement Correlated OpenTelemetry Logging Bridge

[keshavdandeva]

b/496678357

This PR implements the Correlated GCP Logging Bridge for the OpenTelemetry integration in the BigQuery JDBC driver. It enables bridging standard Java logs (java.util.logging) to the OpenTelemetry Logs API, allowing users to correlate logs with distributed traces and isolate them by connection session.

Changes

• BigQueryDriver.java: Implemented Cloud-Only Mode matrix logic to suppress local file creation when enableGcpLogExporter=true and LogPath is omitted.
• BigQueryJdbcRootLogger.java: Updated setLevel to handle Level.OFF properly and skip file handler creation if path is null.
• BigQueryConnection.java: Attached OpenTelemetryJulHandler to the "com.google.cloud.bigquery" namespace during initialization.
• OpenTelemetryJulHandler.java: Created a new handler that bridges JUL logs to OTel Logs API with context harvesting and connection ID filtering.
• pom.xml: Added google-cloud-logging dependency with version 3.33.0-SNAPSHOT and auto-update marker.
• OpenTelemetryJulHandlerTest.java: Created unit tests using OpenTelemetryExtension to verify log emission and filtering.

[gemini-code-assist]

Code Review

This pull request introduces OpenTelemetry and Google Cloud Logging support for the BigQuery JDBC driver, including a new OpenTelemetryJulHandler to bridge logs and logic to suppress local logging in cloud-only mode. The review identified several critical issues regarding resource management and logging correctness: a significant handler leak occurs because new handlers are attached to a shared logger instance for every connection without being removed, the handler incorrectly logs raw message templates instead of formatted strings, and the root logger fails to clean up existing file handlers when switching to cloud-only logging.

[keshavdandeva]

/gemini review

[gemini-code-assist]

Code Review

This pull request implements a logging bridge from java.util.logging to OpenTelemetry and Google Cloud Logging, including a new OpenTelemetryJulHandler and connection-specific telemetry management. Key feedback focuses on making the handler registration idempotent to avoid duplicates, ensuring global logs are not silently dropped when connection IDs are absent, and correctly formatting trace IDs for GCP correlation. Further improvements were suggested regarding exception safety during client flushing and clarifying parameter naming in the telemetry configuration logic.

[logachev]

Feels weird to check this.customOpenTelemetry, but use openTelemetry. Is it intended?

[keshavdandeva]

Yes, this is intended. We want to register the connection for telemetry if either GCP logging is explicitly enabled OR if the user provided a customOpenTelemetry instance (which might want to receive logs)

Since the local openTelemetry variable above is resolved to customOpenTelemetry when it is present, passing openTelemetry to registerConnection is correct.

[logachev]

What's special about Level.OFF? If it is off, does it matter what logPath value is?

Also based on the comment, if intent is to suppress file logging, it should be done outside of if (logPath == null) check

[keshavdandeva]

Also based on the comment, if intent is to suppress file logging, it should be done outside of if (logPath == null) check

The intent here, as we discussed earlier, was to enable 'Cloud-Only Mode' by default when the user omits the LogPath property but enables GCP logging. If the user explicitly provides a LogPath AND enables GCP logging, we assume they want dual logging to both destinations. Moving this check outside would prevent users from logging to both file and GCP simultaneously.

What's special about Level.OFF? If it is off, does it matter what logPath value is?

Yeah, that seems redundant. Will remove it and refactor this if-else block

[logachev]

nit: Should it be jdbc namespace?

[keshavdandeva]

I did have that earlier but then realised the existing BigQueryJdbcRootLogger usescom.google.cloud.bigquer namespace as the root logger for the driver. So, changing it here would make it inconsistent with the file handler unless we change it there too

[logachev]

Should we proceed with null connectionId` instead?

[keshavdandeva]

If we proceed with a null connectionId (subsequently a null config), it will still return early because we don't have any configuration registered for global logs in our map. Gemini suggested to use GlobalOpenTelemetry.get(). But I didn't wanna pollute the host application's global telemetry space with driver logs by default.
Thinking about it now, I guess we can do the default config thing for all global logs. So, it would act as a catch-all fallback in our registry for any logs not mapped to a specific connection ID. WDYT?

[logachev]

Please replace with switch/case

[keshavdandeva]

Switch/case doesn't work for this function as java.util.logging.Level is a class with static constants, not an enum, so we cannot use it directly in a switch statement.

Doing so would require using hardcoded integer values in the case labels

[logachev]

What's the purpose of this config? Is there difference between openTelemetry clients/loggingClients?

[keshavdandeva]

The TelemetryConfig stores the telemetry settings for a specific JDBC connection. We are using a single global handler to prevent memory leaks, that handler uses the connectionId from the log context to look up this config and know how to route the logs for that specific connection.

Is there difference between openTelemetry clients/loggingClients?

• openTelemetry is the standard OTel SDK instance
• loggingClient is the direct Google Cloud Logging client. We use it for the "export to GCP Mode" to send logs directly to Cloud Logging, bypassing OTel, because OTel logs are not yet natively supported in GA by Google Cloud.