Skip to content

Commit 1ae622f

Browse files
Neenu1995Neenu1995
authored
feat(bigquery-jdbc): add telemetry configuration class (#13710)
## Summary Introduces the internal `TelemetryConfiguration` class and builder to manage client-side telemetry settings for the BigQuery JDBC driver. This is **PR 3** of the multi-phase client-side telemetry implementation plan. ## Changes Introduced - **`TelemetryConfiguration`**: Immutable configuration class holding upload intervals, batch size thresholds, log source ID, target endpoint, and environment metadata (`DriverEnvironment`). - **`TelemetryConfiguration.Builder`**: Fluent builder pattern for constructing configuration instances. - **`TelemetryConfigurationTest`**: Unit test suite covering default property initialization, custom property overrides, and `equals`/`hashCode` contracts. - **Visibility Scoping**: Restricted all classes, builders, getters, and constants to package-private (`com.google.cloud.bigquery.jdbc.telemetry.v1`) to prevent exposing internal telemetry implementation details outside the driver package. ## Default Configuration Parameters | Parameter | Default Value | Description | | :--- | :--- | :--- | | `enabled` | `true` | Telemetry is enabled by default per open-source telemetry guidelines (`go/telemetry-oss`). | | `logSource` | `-1` | Placeholder until Clearcut log source ID registration is assigned for BigQuery JDBC. | | `endpointUrl` | `https://play.googleapis.com/log` | Default Clearcut HTTPS log ingestion endpoint. | | `uploadIntervalMs` | `300000` (5 mins) | Periodic background flush interval. | | `batchSizeThreshold` | `100` | Maximum buffered events before triggering an immediate flush. |
1 parent a4fa21f commit 1ae622f

2 files changed

Lines changed: 243 additions & 0 deletions

File tree

‎java-bigquery-jdbc/src/main/java/com/google/cloud/bigquery/jdbc/telemetry/v1/TelemetryConfiguration.java‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.bigquery.jdbc.telemetry.v1;
18+
19+
import java.util.Objects;
20+
21+
/** Configuration settings for the BigQuery JDBC driver telemetry client. */
22+
final class TelemetryConfiguration {
23+
static final boolean DEFAULT_ENABLED = true;
24+
// TODO: change DEFAULT_LOG_SOURCE value once the value is assigned.
25+
static final int DEFAULT_LOG_SOURCE = -1;
26+
static final String DEFAULT_ENDPOINT_URL = "https://play.googleapis.com/log";
27+
static final long DEFAULT_UPLOAD_INTERVAL_MS = 300_000L;
28+
static final int DEFAULT_BATCH_SIZE_THRESHOLD = 100;
29+
30+
private final boolean enabled;
31+
private final int logSource;
32+
private final String endpointUrl;
33+
private final long uploadIntervalMs;
34+
private final int batchSizeThreshold;
35+
private final DriverEnvironment driverEnvironment;
36+
37+
private TelemetryConfiguration(Builder builder) {
38+
this.enabled = builder.enabled;
39+
this.logSource = builder.logSource;
40+
this.endpointUrl = builder.endpointUrl;
41+
this.uploadIntervalMs = builder.uploadIntervalMs;
42+
this.batchSizeThreshold = builder.batchSizeThreshold;
43+
this.driverEnvironment = builder.driverEnvironment;
44+
}
45+
46+
boolean isEnabled() {
47+
return enabled;
48+
}
49+
50+
int getLogSource() {
51+
return logSource;
52+
}
53+
54+
String getEndpointUrl() {
55+
return endpointUrl;
56+
}
57+
58+
long getUploadIntervalMs() {
59+
return uploadIntervalMs;
60+
}
61+
62+
int getBatchSizeThreshold() {
63+
return batchSizeThreshold;
64+
}
65+
66+
DriverEnvironment getDriverEnvironment() {
67+
return driverEnvironment;
68+
}
69+
70+
@Override
71+
public boolean equals(Object o) {
72+
if (this == o) {
73+
return true;
74+
}
75+
if (o == null || getClass() != o.getClass()) {
76+
return false;
77+
}
78+
TelemetryConfiguration that = (TelemetryConfiguration) o;
79+
return enabled == that.enabled
80+
&& logSource == that.logSource
81+
&& uploadIntervalMs == that.uploadIntervalMs
82+
&& batchSizeThreshold == that.batchSizeThreshold
83+
&& Objects.equals(endpointUrl, that.endpointUrl)
84+
&& Objects.equals(driverEnvironment, that.driverEnvironment);
85+
}
86+
87+
@Override
88+
public int hashCode() {
89+
return Objects.hash(
90+
enabled, logSource, endpointUrl, uploadIntervalMs, batchSizeThreshold, driverEnvironment);
91+
}
92+
93+
@Override
94+
public String toString() {
95+
return "TelemetryConfiguration{"
96+
+ "enabled="
97+
+ enabled
98+
+ ", logSource="
99+
+ logSource
100+
+ ", endpointUrl='"
101+
+ endpointUrl
102+
+ '\''
103+
+ ", uploadIntervalMs="
104+
+ uploadIntervalMs
105+
+ ", batchSizeThreshold="
106+
+ batchSizeThreshold
107+
+ ", driverEnvironment="
108+
+ driverEnvironment
109+
+ '}';
110+
}
111+
112+
static Builder newBuilder() {
113+
return new Builder();
114+
}
115+
116+
/** Builder for {@link TelemetryConfiguration}. */
117+
static class Builder {
118+
private boolean enabled = DEFAULT_ENABLED;
119+
private int logSource = DEFAULT_LOG_SOURCE;
120+
private String endpointUrl = DEFAULT_ENDPOINT_URL;
121+
private long uploadIntervalMs = DEFAULT_UPLOAD_INTERVAL_MS;
122+
private int batchSizeThreshold = DEFAULT_BATCH_SIZE_THRESHOLD;
123+
private DriverEnvironment driverEnvironment;
124+
125+
Builder setEnabled(boolean enabled) {
126+
this.enabled = enabled;
127+
return this;
128+
}
129+
130+
Builder setLogSource(int logSource) {
131+
this.logSource = logSource;
132+
return this;
133+
}
134+
135+
Builder setEndpointUrl(String endpointUrl) {
136+
this.endpointUrl = endpointUrl;
137+
return this;
138+
}
139+
140+
Builder setUploadIntervalMs(long uploadIntervalMs) {
141+
this.uploadIntervalMs = uploadIntervalMs;
142+
return this;
143+
}
144+
145+
Builder setBatchSizeThreshold(int batchSizeThreshold) {
146+
this.batchSizeThreshold = batchSizeThreshold;
147+
return this;
148+
}
149+
150+
Builder setDriverEnvironment(DriverEnvironment driverEnvironment) {
151+
this.driverEnvironment = driverEnvironment;
152+
return this;
153+
}
154+
155+
TelemetryConfiguration build() {
156+
return new TelemetryConfiguration(this);
157+
}
158+
}
159+
}

‎java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/telemetry/v1/TelemetryConfigurationTest.java‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.bigquery.jdbc.telemetry.v1;
18+
19+
import static org.junit.jupiter.api.Assertions.assertEquals;
20+
import static org.junit.jupiter.api.Assertions.assertFalse;
21+
import static org.junit.jupiter.api.Assertions.assertNotEquals;
22+
import static org.junit.jupiter.api.Assertions.assertNull;
23+
import static org.junit.jupiter.api.Assertions.assertTrue;
24+
25+
import org.junit.jupiter.api.Test;
26+
27+
public class TelemetryConfigurationTest {
28+
29+
@Test
30+
public void testDefaultValues() {
31+
TelemetryConfiguration config = TelemetryConfiguration.newBuilder().build();
32+
33+
assertTrue(config.isEnabled());
34+
assertEquals(-1, config.getLogSource());
35+
assertEquals("https://play.googleapis.com/log", config.getEndpointUrl());
36+
assertEquals(300_000L, config.getUploadIntervalMs());
37+
assertEquals(100, config.getBatchSizeThreshold());
38+
assertNull(config.getDriverEnvironment());
39+
}
40+
41+
@Test
42+
public void testCustomValues() {
43+
DriverEnvironment environment =
44+
DriverEnvironment.newBuilder()
45+
.setDriverName("BigQuery JDBC")
46+
.setDriverVersion("1.0.0")
47+
.build();
48+
49+
TelemetryConfiguration config =
50+
TelemetryConfiguration.newBuilder()
51+
.setEnabled(false)
52+
.setLogSource(1234)
53+
.setEndpointUrl("https://custom.endpoint.com/log")
54+
.setUploadIntervalMs(60_000L)
55+
.setBatchSizeThreshold(50)
56+
.setDriverEnvironment(environment)
57+
.build();
58+
59+
assertFalse(config.isEnabled());
60+
assertEquals(1234, config.getLogSource());
61+
assertEquals("https://custom.endpoint.com/log", config.getEndpointUrl());
62+
assertEquals(60_000L, config.getUploadIntervalMs());
63+
assertEquals(50, config.getBatchSizeThreshold());
64+
assertEquals(environment, config.getDriverEnvironment());
65+
}
66+
67+
@Test
68+
public void testEqualsAndHashCode() {
69+
TelemetryConfiguration config1 =
70+
TelemetryConfiguration.newBuilder().setEnabled(true).setLogSource(1234).build();
71+
72+
TelemetryConfiguration config2 =
73+
TelemetryConfiguration.newBuilder().setEnabled(true).setLogSource(1234).build();
74+
75+
TelemetryConfiguration config3 =
76+
TelemetryConfiguration.newBuilder().setEnabled(false).setLogSource(1234).build();
77+
78+
assertEquals(config1, config2);
79+
assertEquals(config1.hashCode(), config2.hashCode());
80+
assertNotEquals(config1, config3);
81+
assertNotEquals(config1, null);
82+
assertNotEquals(config1, "string");
83+
}
84+
}

0 commit comments

Comments
 (0)