Skip to content
This repository was archived by the owner on Oct 20, 2026. It is now read-only.

Commit 5142ba4

Browse files
committed
feat: (observability, samples): add tracing end-to-end sample
This change documents an end-to-end observability tracing sample using OpenTelemetry, which then exports trace spans to Google Cloud Trace. Updates #2079
1 parent 37e0346 commit 5142ba4

2 files changed

Lines changed: 281 additions & 2 deletions

File tree

‎samples/observability.js‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
/*!
2+
* Copyright 2024 Google LLC. All Rights Reserved.
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+
* http://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+
// sample-metadata:
18+
// title: Observability (Tracing) with OpenTelemetry
19+
// usage: node observability.js trace <INSTANCE> <DATABASE> <PROJECT-ID>
20+
21+
'use strict';
22+
23+
// Setup OpenTelemetry and the trace exporter.
24+
// [start spanner_trace_and_export_spans]
25+
const {Resource} = require('@opentelemetry/resources');
26+
const {NodeSDK} = require('@opentelemetry/sdk-node');
27+
const {
28+
NodeTracerProvider,
29+
TraceIdRatioBasedSampler,
30+
} = require('@opentelemetry/sdk-trace-node');
31+
const {
32+
BatchSpanProcessor,
33+
ConsoleSpanExporter,
34+
SimpleSpanProcessor,
35+
} = require('@opentelemetry/sdk-trace-base');
36+
const {
37+
SEMRESATTRS_SERVICE_NAME,
38+
SEMRESATTRS_SERVICE_VERSION,
39+
} = require('@opentelemetry/semantic-conventions');
40+
41+
const resource = Resource.default().merge(
42+
new Resource({
43+
[SEMRESATTRS_SERVICE_NAME]: 'spanner-sample',
44+
[SEMRESATTRS_SERVICE_VERSION]: 'v1.0.0', // The version of your app running.,
45+
})
46+
);
47+
48+
// Create the Google Cloud Trace exporter for OpenTelemetry.
49+
const {
50+
TraceExporter,
51+
} = require('@google-cloud/opentelemetry-cloud-trace-exporter');
52+
const exporter = new TraceExporter();
53+
54+
function traceAndExportSpans(instanceId, databaseId, projectId) {
55+
// Wire up the OpenTelemetry SDK instance with the exporter and sampler.
56+
const sdk = new NodeSDK({
57+
resource: resource,
58+
traceExporter: exporter,
59+
// Trace every single request to ensure that we generate
60+
// enough traffic for proper examination of traces.
61+
sampler: new TraceIdRatioBasedSampler(1.0),
62+
});
63+
sdk.start();
64+
65+
// Create the tracerProvider that the exporter shall be attached to.
66+
const provider = new NodeTracerProvider({resource: resource});
67+
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
68+
69+
// This makes a global tracerProvider but you could optionally
70+
// instead pass in the provider while creating the Spanner client.
71+
provider.register();
72+
73+
// Acquire the tracer.
74+
const tracer = provider.getTracer('MyApp');
75+
76+
// Start our user defined trace.
77+
tracer.startActiveSpan('deleteAndCreateDatabase', async span => {
78+
// Create the Cloud Spanner Client.
79+
const {Spanner} = require('@google-cloud/spanner');
80+
const spanner = new Spanner({
81+
projectId: projectId,
82+
observability: {
83+
// Optional, can rather register the global tracerProvider
84+
tracerProvider: provider,
85+
enableExtendedTracing: true, // Optional but can also use SPANNER_EXTENDED_TRACING=true
86+
},
87+
});
88+
89+
// Acquire the database and databaseAdminClient handles.
90+
const instance = spanner.instance(instanceId);
91+
const database = instance.database(databaseId);
92+
const databaseAdminClient = spanner.getDatabaseAdminClient();
93+
94+
const databasePath = databaseAdminClient.databasePath(
95+
projectId,
96+
instanceId,
97+
databaseId
98+
);
99+
100+
// Mimicking how in real world code, there will be a pause after
101+
// application startup, as the service waits to serve traffic.
102+
await new Promise((resolve, reject) => setTimeout(resolve, 5000));
103+
104+
/*
105+
* This code path exercises deleting then creating a Cloud Spanner database,
106+
* inserting data into the database and then reading from it.
107+
*/
108+
deleteDatabase(databaseAdminClient, databasePath, () => {
109+
createDatabase(
110+
databaseAdminClient,
111+
projectId,
112+
instanceId,
113+
databaseId,
114+
() => {
115+
insertUsingDml(tracer, database, async () => {
116+
try {
117+
const query = {
118+
sql: 'SELECT SingerId, FirstName, LastName FROM Singers',
119+
};
120+
const [rows] = await database.run(query);
121+
122+
for (const row of rows) {
123+
const json = row.toJSON();
124+
125+
console.log(
126+
`SingerId: ${json.SingerId}, FirstName: ${json.FirstName}, LastName: ${json.LastName}`
127+
);
128+
}
129+
} catch (err) {
130+
console.error('ERROR:', err);
131+
await new Promise((resolve, reject) => setTimeout(resolve, 2000));
132+
} finally {
133+
span.end();
134+
spanner.close();
135+
console.log('main span.end');
136+
}
137+
138+
// This sleep gives ample time for the trace
139+
// spans to be exported to Google Cloud Trace.
140+
await new Promise((resolve, reject) => {
141+
setTimeout(() => {
142+
console.log('finished delete and creation of the database');
143+
}, 8800);
144+
});
145+
});
146+
}
147+
);
148+
});
149+
});
150+
151+
// [END spanner_trace_and_export_spans]
152+
}
153+
154+
/*
155+
* insertUsingDml exercises the path of inserting
156+
* data into the Cloud Spanner database.
157+
*/
158+
function insertUsingDml(tracer, database, callback) {
159+
tracer.startActiveSpan('insertUsingDML', span => {
160+
database.runTransaction(async (err, transaction) => {
161+
if (err) {
162+
span.end();
163+
console.error(err);
164+
return;
165+
}
166+
167+
try {
168+
const [delCount] = await transaction.runUpdate({
169+
sql: 'DELETE FROM Singers WHERE 1=1',
170+
});
171+
172+
console.log(`Deletion count ${delCount}`);
173+
174+
const [rowCount] = await transaction.runUpdate({
175+
sql: 'INSERT Singers (SingerId, FirstName, LastName) VALUES (10, @firstName, @lastName)',
176+
params: {
177+
firstName: 'Virginia',
178+
lastName: 'Watson',
179+
},
180+
});
181+
182+
console.log(
183+
`Successfully inserted ${rowCount} record into the Singers table.`
184+
);
185+
186+
await transaction.commit();
187+
} catch (err) {
188+
console.error('ERROR:', err);
189+
} finally {
190+
// Close the database when finished.
191+
console.log('exiting insertUsingDml');
192+
tracer.startActiveSpan('timingOutToExport-insertUsingDML', eSpan => {
193+
setTimeout(() => {
194+
if (callback) {
195+
callback();
196+
}
197+
eSpan.end();
198+
span.end();
199+
}, 500);
200+
});
201+
}
202+
});
203+
});
204+
}
205+
206+
function createDatabase(
207+
databaseAdminClient,
208+
projectId,
209+
instanceId,
210+
databaseId,
211+
callback
212+
) {
213+
async function doCreateDatabase() {
214+
if (databaseId) {
215+
callback();
216+
return;
217+
}
218+
219+
// Create the database with default tables.
220+
const createSingersTableStatement = `
221+
CREATE TABLE Singers (
222+
SingerId INT64 NOT NULL,
223+
FirstName STRING(1024),
224+
LastName STRING(1024),
225+
SingerInfo BYTES(MAX)
226+
) PRIMARY KEY (SingerId)`;
227+
228+
const [operation] = await databaseAdminClient.createDatabase({
229+
createStatement: 'CREATE DATABASE `' + databaseId + '`',
230+
extraStatements: [createSingersTableStatement],
231+
parent: databaseAdminClient.instancePath(projectId, instanceId),
232+
});
233+
234+
console.log(`Waiting for creation of ${databaseId} to complete...`);
235+
await operation.promise();
236+
console.log(`Created database ${databaseId}`);
237+
callback();
238+
}
239+
doCreateDatabase();
240+
}
241+
242+
function deleteDatabase(databaseAdminClient, databasePath, callback) {
243+
async function doDropDatabase() {
244+
if (databasePath) {
245+
callback();
246+
return;
247+
}
248+
249+
const [operation] = await databaseAdminClient.dropDatabase({
250+
database: databasePath,
251+
});
252+
253+
await operation;
254+
console.log('Finished dropping the database');
255+
callback();
256+
}
257+
258+
doDropDatabase();
259+
}
260+
261+
require('yargs')
262+
.demand(1)
263+
.command(
264+
'trace <instanceName> <databaseName> <projectId>',
265+
'Run an end-to-end traced sample.',
266+
{},
267+
opts =>
268+
traceAndExportSpans(opts.instanceName, opts.databaseName, opts.projectId)
269+
)
270+
.example('node $0 trace "my-instance" "my-database" "my-project-id"')
271+
.wrap(120)
272+
.recommendCommands()
273+
.epilogue('For more information, see https://cloud.google.com/spanner/docs')
274+
.strict()
275+
.help().argv;

‎samples/package.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,14 @@
1616
},
1717
"dependencies": {
1818
"@google-cloud/kms": "^4.0.0",
19+
"@google-cloud/opentelemetry-cloud-trace-exporter": "^2.4.1",
1920
"@google-cloud/precise-date": "^4.0.0",
2021
"@google-cloud/spanner": "^7.14.0",
21-
"yargs": "^17.0.0",
22-
"protobufjs": "^7.0.0"
22+
"@opentelemetry/api": "^1.9.0",
23+
"@opentelemetry/resources": "^1.26.0",
24+
"@opentelemetry/sdk-node": "^0.53.0",
25+
"protobufjs": "^7.0.0",
26+
"yargs": "^17.0.0"
2327
},
2428
"devDependencies": {
2529
"chai": "^4.2.0",

0 commit comments

Comments
 (0)
⌂ 换网址