instrument: allow SQL annotation if SPANNER_NODEJS_ANNOTATE_PII_SQL=1…

… is set in environment

README.md

@@ -92,6 +92,10 @@ Please use a tracer named "nodejs-spanner".
 
 > :warning: **Make sure that the OpenTelemetry imports are the first, before importing the Spanner library**
 
+> :warning: **In order for your spans to be annotated with SQL, you MUST opt-in by setting environment variable
+`SPANNER_NODEJS_ANNOTATE_PII_SQL=1`, this is because SQL statements can be
+sensitive personally-identifiable-information (PII).**
+
 To test out trace examination, you can use the Zipkin tracing service like this.
 
 ```javascript

src/database.ts

@@ -2700,7 +2700,7 @@ class Database extends common.GrpcServiceObject {
     optionsOrCallback?: TimestampBounds | RunCallback,
     cb?: RunCallback
   ): void | Promise<RunResponse> {
-    const span = startTrace('Database.run');
+    const span = startTrace('Database.run', query);
 
     let stats: ResultSetStats;
     let metadata: ResultSetMetadata;

src/transaction.ts

@@ -1011,7 +1011,7 @@ export class Snapshot extends EventEmitter {
     query: string | ExecuteSqlRequest,
     callback?: RunCallback
   ): void | Promise<RunResponse> {
-    const span = startTrace('Transaction.run');
+    const span = startTrace('Transaction.run', query);
     const rows: Rows = [];
     let stats: google.spanner.v1.ResultSetStats;
     let metadata: google.spanner.v1.ResultSetMetadata;
@@ -1138,7 +1138,7 @@ export class Snapshot extends EventEmitter {
    * ```
    */
   runStream(query: string | ExecuteSqlRequest): PartialResultStream {
-    const span = startTrace('Transaction.runStream');
+    const span = startTrace('Transaction.runStream', query);
     if (typeof query === 'string') {
       query = {sql: query} as ExecuteSqlRequest;
     }
@@ -1542,7 +1542,7 @@ export class Dml extends Snapshot {
     query: string | ExecuteSqlRequest,
     callback?: RunUpdateCallback
   ): void | Promise<RunUpdateResponse> {
-    const span = startTrace('Transaction.runUpdate');
+    const span = startTrace('Transaction.runUpdate', query);
     if (typeof query === 'string') {
       query = {sql: query} as ExecuteSqlRequest;
     }

src/v1/instrument.ts

@@ -39,14 +39,30 @@ registerInstrumentations({
   instrumentations: [new GrpcInstrumentation(), new HttpInstrumentation()],
 });
 
+var optedInPII = process.env.SPANNER_NODEJS_ANNOTATE_PII_SQL === '1';
+
+interface SQLStatement {
+  sql: string;
+}
+
 // startSpan synchronously returns a span to avoid the dramatic
 // scope change in which trying to use tracer.startActiveSpan
 // would change the meaning of this, and also introduction of callbacks
 // would radically change all the code structures making it more invasive.
-export function startTrace(spanNameSuffix: String): Span {
+export function startTrace(spanNameSuffix: string, sql?: string | SQLStatement): Span {
   const span = tracer.startSpan(
     'cloud.google.com/nodejs/spanner/' + spanNameSuffix
   );
+
+  if (optedInPII && sql) {
+    if (typeof sql === 'string') {
+      span.setAttribute('sql', sql as string);
+    } else {
+      const stmt = sql as SQLStatement;
+      span.setAttribute('sql', stmt.sql);
+    }
+  }
+
   // Now set the span as the active one in the current context so that
   // future invocations to startTrace will have this current span as
   // the parent.