observability: add base for instrumentation + tests

This change adds the scaffolding for instrumentation
along with tests for the tracing mechanisms that'll
be used to trace the entire package.

Built from googleapis#2087
Updates googleapis#2079

observability-test/observability.test.ts

@@ -0,0 +1,245 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const assert = require('assert');
+
+const {
+  AlwaysOffSampler,
+  AlwaysOnSampler,
+  NodeTracerProvider,
+  InMemorySpanExporter,
+} = require('@opentelemetry/sdk-trace-node');
+const {SimpleSpanProcessor} = require('@opentelemetry/sdk-trace-base');
+const {
+  SPAN_PREFIX,
+  disableContextAndManager,
+  setGlobalContextManager,
+  startTrace,
+  setTracerProvider,
+} = require('../src/instrument');
+const {
+  SEMATTRS_DB_NAME,
+  SEMATTRS_DB_SQL_TABLE,
+  SEMATTRS_DB_STATEMENT,
+  SEMATTRS_DB_SYSTEM,
+} = require('@opentelemetry/semantic-conventions');
+
+const {ContextManager} = require('@opentelemetry/api');
+const {
+  AsyncHooksContextManager,
+} = require('@opentelemetry/context-async-hooks');
+
+const projectId = process.env.SPANNER_TEST_PROJECTID || 'test-project';
+
+// const {DiagConsoleLogger, DiagLogLevel, diag} = require('@opentelemetry/api');
+// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
+
+describe('Test startTrace', () => {
+  const exporter = new InMemorySpanExporter();
+  const sampler = new AlwaysOnSampler();
+
+  const provider = new NodeTracerProvider({
+    sampler: sampler,
+    exporter: exporter,
+  });
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+  provider.register();
+  setTracerProvider(provider);
+
+  const contextManager = new AsyncHooksContextManager();
+  setGlobalContextManager(contextManager);
+
+  after(async () => {
+    exporter.forceFlush();
+    await provider.shutdown();
+    disableContextAndManager(contextManager);
+  });
+
+  it('startTrace with TracerProvider in global configuration', () => {
+    startTrace('mySpan', {}, async span => {
+      await new Promise((resolve, reject) => setTimeout(resolve, 400));
+      span.end();
+
+      const spans = exporter.getFinishedSpans();
+      assert.ok(spans.length, 1, 'exactly 1 span must have been exported');
+      const span0 = spans[0];
+
+      // The span MUST start with the prefix of this library.
+      const gotName = span0.name;
+      const wantName = SPAN_PREFIX + '/mySpan';
+      assert.equal(
+        gotName,
+        wantName,
+        'name mismatch:\n\tGot: ' + gotName + '\n\tWant: ' + wantName
+      );
+    });
+  });
+
+  it('startTrace with TracerProvider in options, skips using global TracerProvider', () => {
+    const exporter2 = new InMemorySpanExporter();
+    const provider2 = new NodeTracerProvider({
+      sampler: sampler,
+      exporter: exporter2,
+    });
+    provider2.addSpanProcessor(new SimpleSpanProcessor(exporter2));
+    provider2.register();
+
+    startTrace('aSpan', {tracerProvider: provider2}, async span => {
+      await new Promise((resolve, reject) => setTimeout(resolve, 400));
+      span.end();
+
+      const gotSpansFromGlobal = exporter.getFinishedSpans();
+      assert.ok(
+        gotSpansFromGlobal.length,
+        0,
+        'no spans should be registered to the global'
+      );
+
+      const gotSpansFromCurrent = exporter2.getFinishedSpans();
+      assert.ok(
+        gotSpansFromCurrent.length,
+        1,
+        'a span should be retrieved from this exporter'
+      );
+
+      exporter2.forceFlush();
+      await provider2.shutdown();
+    });
+  });
+
+  it('startTrace with semantic attributes', () => {
+    const opts = {tableName: 'table', dbName: 'db'};
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_SYSTEM],
+        'spanner',
+        'Missing DB_SYSTEM attribute'
+      );
+
+      assert.equal(
+        span.attributes[SEMATTRS_DB_SQL_TABLE],
+        'table',
+        'Missing DB_SQL_TABLE attribute'
+      );
+
+      assert.equal(
+        span.attributes[SEMATTRS_DB_NAME],
+        'db',
+        'Missing DB_NAME attribute'
+      );
+    });
+  });
+
+  it('startTrace with enableExtendedTracing=true, no sql value set', () => {
+    const opts = {enableExtendedTracing: true};
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_STATEMENT],
+        undefined,
+        'Unexpected DB_STATEMENT attribute'
+      );
+    });
+  });
+
+  it('startTrace with enableExtendedTracing=true, sql string value set', () => {
+    const opts = {
+      enableExtendedTracing: true,
+      sql: 'SELECT CURRENT_TIMESTAMP()',
+    };
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_STATEMENT],
+        'SELECT CURRENT_TIMESTAMP()',
+        'Mismatched DB_STATEMENT attribute'
+      );
+    });
+  });
+
+  it('startTrace with enableExtendedTracing=false, sql string value set', () => {
+    const opts = {
+      enableExtendedTracing: false,
+      sql: 'SELECt CURRENT_TIMESTAMP()',
+    };
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_STATEMENT],
+        undefined,
+        'Mismatched DB_STATEMENT attribute'
+      );
+    });
+  });
+
+  it('startTrace with enableExtendedTracing=true, sql ExecuteSqlRequest value set', () => {
+    const req = {sql: 'SELECT 1=1'};
+    const opts = {
+      enableExtendedTracing: true,
+      sql: req,
+    };
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_STATEMENT],
+        'SELECT 1=1',
+        'Mismatched DB_STATEMENT attribute'
+      );
+    });
+  });
+
+  it('startTrace with enableExtendedTracing=false, sql ExecuteSqlRequest value set', () => {
+    const req = {sql: 'SELECT 1=1'};
+    const opts = {
+      enableExtendedTracing: true,
+      sql: req,
+    };
+    startTrace('aSpan', opts, async span => {
+      assert.equal(
+        span.attributes[SEMATTRS_DB_STATEMENT],
+        undefined,
+        'Mismatched DB_STATEMENT attribute'
+      );
+    });
+  });
+
+  it('alwaysOffSampler used', () => {
+    const exporter2 = new InMemorySpanExporter();
+    const provider2 = new NodeTracerProvider({
+      sampler: new AlwaysOffSampler(),
+      exporter: exporter2,
+    });
+    provider2.addSpanProcessor(new SimpleSpanProcessor(exporter2));
+    provider2.register();
+
+
+    startTrace('aSpan', {tracerProvider: provider2}, async span => {
+      await new Promise((resolve, reject) => setTimeout(resolve, 400));
+      span.end();
+
+      const gotSpansFromGlobal = exporter.getFinishedSpans();
+      assert.ok(
+        gotSpansFromGlobal.length,
+        0,
+        'no spans should be exported
+      );
+
+      const gotSpansFromCurrent = exporter2.getFinishedSpans();
+      assert.ok(
+        gotSpansFromCurrent.length,
+        0,
+        'no span should have been exported'
+      );
+
+      exporter2.forceFlush();
+      await provider2.shutdown();
+    });
+  });
+});

package.json

@@ -33,15 +33,17 @@
     "samples-test-with-archived": "cd samples/ && npm link ../ && npm test-with-archived && cd ../",
     "samples-test": "cd samples/ && npm link ../ && npm test && cd ../",
     "system-test": "mocha build/system-test --timeout 1600000",
+    "observability-test": "mocha build/observability-test --timeout 1600000",
     "cleanup": "mocha scripts/cleanup.js --timeout 30000",
-    "test": "mocha build/test build/test/common",
+    "test": "mocha build/test build/test/common build/observability-test",
     "ycsb": "node ./benchmark/ycsb.js  run -P ./benchmark/workloada -p table=usertable -p cloudspanner.instance=ycsb-instance -p operationcount=100 -p cloudspanner.database=ycsb",
     "fix": "gts fix",
     "clean": "gts clean",
     "compile": "tsc -p . && cp -r protos build && cp -r test/data build/test",
     "prepare": "npm run compile-protos && npm run compile",
     "pretest": "npm run compile",
     "presystem-test": "npm run compile",
+    "preobservability-test": "npm run compile",
     "proto": "compileProtos src",
     "docs-test": "linkinator docs",
     "predocs-test": "npm run docs",
@@ -57,6 +59,10 @@
     "@google-cloud/projectify": "^4.0.0",
     "@google-cloud/promisify": "^4.0.0",
     "@grpc/proto-loader": "^0.7.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^1.25.1",
+    "@opentelemetry/sdk-trace-node": "^1.25.1",
+    "@opentelemetry/semantic-conventions": "^1.25.1",
     "@types/big.js": "^6.0.0",
     "@types/stack-trace": "0.0.33",
     "arrify": "^2.0.0",