Skip to content

Commit cfed357

Browse files
odeke-emodeke-em
committed
Update with code review comments
1 parent c6b6220 commit cfed357

File tree

3 files changed

+114
-242
lines changed

3 files changed

+114
-242
lines changed

‎README.md

+72-66
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,11 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
3535
* [Installing the client library](#installing-the-client-library)
3636
* [Using the client library](#using-the-client-library)
3737
* [Observability](#observability)
38-
* [Enabling gRPC instrumentation](#enabling-grpc-instrumentation)
38+
* [OpenTelemetry Dependencies](#opentelemetry-dependencies)
39+
* [OpenTelemetry Configuration](#opentelemetry-configuration)
40+
* [SQL Statement span annotation](#sql-statement-span-annotation)
41+
* [OpenTelemetry gRCP instrumentation](#opentelemetry-grpc-instrumentation)
42+
* [Sample](#sample)
3943
* [Samples](#samples)
4044
* [Versioning](#versioning)
4145
* [Contributing](#contributing)
@@ -85,28 +89,33 @@ rows.forEach(row => console.log(row));
8589

8690
## Observability
8791

88-
This package has been instrumented with [OpenTelemetry](https://opentelemetry.io/docs/languages/js/) for tracing.
89-
For correct operation, please make sure to firstly import and enable OpenTelemetry before importing this Spanner library.
92+
This Cloud Spanner client supports [OpenTelemetry Traces](https://opentelemetry.io/), which gives insight into the client internals and aids in debugging/troubleshooting production issues.
9093

91-
> :warning: **Make sure that the OpenTelemetry imports are the first, before importing the Spanner library**
92-
> :warning: **In order for your spans to be annotated with the executed SQL, you MUST opt-in by setting environment variable
93-
`SPANNER_ENABLE_EXTENDED_TRACING=true`, this is because SQL statements can contain
94-
sensitive personally-identifiable-information (PII).**
94+
By default, the functionality is disabled. You shall need to add OpenTelemetry dependencies, and must configure and
95+
enable OpenTelemetry with appropriate exporters at the startup of your application:
9596

96-
To observe traces, you'll need to examine them in a trace viewer such as Google Cloud Trace,
97-
after having initialized like this:
97+
### OpenTelemetry Dependencies
98+
99+
Use a trace exporter of your choice, such as Google Cloud Trace like below:
100+
101+
```javascript
102+
const {
103+
TraceExporter,
104+
} = require('@google-cloud/opentelemetry-cloud-trace-exporter');
105+
const exporter = new TraceExporter();
106+
```
107+
108+
### OpenTelemetry Configuration
98109

99110
```javascript
100-
const {Resource} = require('@opentelemetry/resources');
101111
const {NodeSDK} = require('@opentelemetry/sdk-node');
112+
const {Resource} = require('@opentelemetry/resources');
102113
const {
103114
NodeTracerProvider,
104115
TraceIdRatioBasedSampler,
105116
} = require('@opentelemetry/sdk-trace-node');
106117
const {
107118
BatchSpanProcessor,
108-
ConsoleSpanExporter,
109-
SimpleSpanProcessor,
110119
} = require('@opentelemetry/sdk-trace-base');
111120
const {
112121
SEMRESATTRS_SERVICE_NAME,
@@ -120,65 +129,59 @@ const resource = Resource.default().merge(
120129
})
121130
);
122131

123-
// Create the Google Cloud Trace exporter for OpenTelemetry.
124-
const {
125-
TraceExporter,
126-
} = require('@google-cloud/opentelemetry-cloud-trace-exporter');
127-
const exporter = new TraceExporter();
132+
// Wire up the OpenTelemetry SDK instance with the exporter and sampler.
133+
const sdk = new NodeSDK({
134+
resource: resource,
135+
traceExporter: exporter,
136+
// Trace every single request to ensure that we generate
137+
// enough traffic for proper examination of traces.
138+
sampler: new TraceIdRatioBasedSampler(1.0),
139+
});
140+
sdk.start();
141+
142+
// Create the tracerProvider that the exporter shall be attached to.
143+
const provider = new NodeTracerProvider({resource: resource});
144+
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
145+
146+
// Create the Cloud Spanner Client.
147+
const {Spanner} = require('@google-cloud/spanner');
148+
const spanner = new Spanner({
149+
projectId: projectId,
150+
observabilityConfig: {
151+
// Inject the TracerProvider via SpannerOptions or
152+
// register it as a global by invoking `provider.register()`
153+
tracerProvider: provider,
154+
},
155+
});
156+
```
128157

129-
function traceAndExportSpans(instanceId, databaseId, projectId, next) {
130-
// Wire up the OpenTelemetry SDK instance with the exporter and sampler.
131-
const sdk = new NodeSDK({
132-
resource: resource,
133-
traceExporter: exporter,
134-
// Trace every single request to ensure that we generate
135-
// enough traffic for proper examination of traces.
136-
sampler: new TraceIdRatioBasedSampler(1.0),
137-
});
138-
sdk.start();
139-
140-
// Create the tracerProvider that the exporter shall be attached to.
141-
const provider = new NodeTracerProvider({resource: resource});
142-
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
143-
144-
// This makes a global tracerProvider but you could optionally
145-
// instead pass in the provider while creating the Spanner client.
146-
provider.register();
147-
148-
// Acquire the tracer.
149-
const tracer = provider.getTracer('MyApp');
150-
151-
// Create the Cloud Spanner Client.
152-
const {Spanner} = require('@google-cloud/spanner');
153-
const spanner = new Spanner({
154-
projectId: projectId,
155-
observabilityConfig: {
156-
// Optional, can rather register the global tracerProvider
157-
tracerProvider: provider,
158-
enableExtendedTracing: true, // Optional but can also use SPANNER_EXTENDED_TRACING=true
159-
},
160-
});
158+
### SQL Statement span annotation
161159

162-
// Start your user defined trace.
163-
tracer.startActiveSpan('deleteAndCreateDatabase', async span => {
164-
// Use the Cloud Spanner API connection normally.
165-
const [rows] = await database.run('SELECT * FROM Transactions');
166-
for (const row of rows) {
167-
const json = row.toJSON();
168-
169-
console.log(
170-
`TransactionId: ${json.tId}, Amount: ${json.amount}, Currency: ${json.currency}`
171-
);
172-
}
173-
span.end();
174-
next();
175-
});
176-
}
160+
To allow your SQL statements to be annotated in the appropriate spans, you need to opt-in, because
161+
SQL statements can contain sensitive personally-identifiable-information (PII).
162+
163+
You can opt-in by either:
164+
165+
* Setting the environment variable `SPANNER_ENABLE_EXTENDED_TRACING=true` before your application is started
166+
* In code, setting `enableExtendedTracing: true` in your SpannerOptions before creating the Cloud Spanner client
167+
168+
```javascript
169+
const spanner = new Spanner({
170+
projectId: projectId,
171+
observabilityConfig: {
172+
// Inject the TracerProvider via SpannerOptions or
173+
// register it as a global by invoking `provider.register()`
174+
tracerProvider: provider,
175+
176+
// This option can also be enabled by setting the environment
177+
// variable `SPANNER_ENABLE_EXTENDED_TRACING=true`.
178+
enableExtendedTracing: true,
179+
},
177180
```
178181
179-
### Enabling gRPC instrumentation
182+
### OpenTelemetry gRPC instrumentation
180183
181-
Optionally, you can enable gRPC instrumentation which produces traces of executed remote procedure calls (RPCs)
184+
Optionally, you can enable OpenTelemetry gRPC instrumentation which produces traces of executed remote procedure calls (RPCs)
182185
in your programs by these imports and instantiation before creating the tracerProvider:
183186
184187
```javascript
@@ -189,6 +192,9 @@ in your programs by these imports and instantiation before creating the tracerPr
189192
});
190193
```
191194
195+
### Sample
196+
For more information please see this [sample code](./samples/observability.js)
197+
192198
## Samples
193199
194200
Samples are in the [`samples/`](https://github.com/googleapis/nodejs-spanner/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample.

0 commit comments

Comments
 (0)