Merge branch 'main' into release-please

.github/workflows/unit-test.yml

@@ -113,7 +113,7 @@ jobs:
           chown -R 1001:121 "/github/home/.npm"
           [ -e /__w/opentelemetry-js-contrib/opentelemetry-js-contrib/package-lock.json ] && chown 1001:121 /__w/opentelemetry-js-contrib/opentelemetry-js-contrib/package-lock.json
       - name: Bootstrap Dependencies
-        run: npx lerna bootstrap --no-ci --hoist --nohoist='zone.js'
+        run: npx lerna bootstrap --no-ci --hoist --nohoist='zone.js' --nohoist='mocha' --nohoist='ts-mocha'
       - name: Unit tests
         run: npm run test:ci:changed
       - name: Report Coverage

packages/opentelemetry-test-utils/README.md

@@ -2,6 +2,60 @@
 
 This is a internal utils package used across the contrib packages. No guarantees are given to uses outside of [open-telemetry/opentelemetry-js-contrib](https://github.com/open-telemetry/opentelemetry-js-contrib/) repository.
 
+## Instrumentation Testing
+This package exports a mocha [root hook plugin](https://mochajs.org/#root-hook-plugins), which implements common boilerplate code a developer probably needs for writing instrumentation unit tests in node.
+
+This package:
+- Initializes and registers a global trace provider for tests.
+- Registers a global memory exporter which can be referenced in test to access span. 
+- Make sure there is only a single instance of an instrumentation class that is used across different `.spec.ts` files so patching is consistent, deterministic and idiomatic.
+- Reset the memory exporter before each test, so spans do not leak from one test to another.
+- Optionally - export the test traces to Jaeger for convenience while debugging and developing.
+
+By using this package, testing instrumentation code can be shorter, and good practices for writing tests are more easily applied.
+
+### Supporter Version
+Since [root hook plugin](https://mochajs.org/#root-hook-plugins) are used, this package is compatible to mocha v8.0.0 and above. 
+
+### Usage
+1. Add dev dependency on this package: 
+
+```
+npm install @opentelemetry/test-utils --save-dev
+```
+2. [`require`](https://mochajs.org/#-require-module-r-module) this package in mocha invocation:
+
+As command line argument option to mocha:
+```js
+    "scripts": {
+        "test": "mocha --require @opentelemetry/test-utils",
+        "test:jaeger": "OTEL_EXPORTER_JAEGER_AGENT_HOST=localhost mocha --require @opentelemetry/test-utils",
+    },
+``
+
+Or by using config file / package.json config:
+```js
+    "mocha": {
+        "require": [ "@opentelemetry/test-utils" ]
+    }
+```
+
+3. In your `.spec` file, import `registerInstrumentationTesting` and `getTestSpans` functions and use them to create instrumentation class instance and make assertions in the test:
+
+```js
+import { getTestSpans, registerInstrumentationTesting } from '@opentelemetry/test-utils';
+
+const instrumentation = registerInstrumentationTesting(new MyAwesomeInstrumentation());
+
+it('some test', () => {
+    // your code that generate spans for this test
+    const spans: ReadableSpan[] = getTestSpans();
+    // your code doing assertions with the spans array
+});
+```
+
+That's it - supper short and easy.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/opentelemetry-test-utils/package.json

@@ -2,7 +2,8 @@
   "name": "@opentelemetry/contrib-test-utils",
   "version": "0.25.0",
   "description": "Test utilities for opentelemetry components",
-  "main": "build/index.js",
+  "main": "build/src/index.js",
+  "types": "build/src/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -44,6 +45,9 @@
   },
   "dependencies": {
     "@opentelemetry/core": "0.25.0",
+    "@opentelemetry/exporter-jaeger": "0.25.0",
+    "@opentelemetry/instrumentation": "0.25.0",
+    "@opentelemetry/sdk-trace-node": "0.25.0",
     "@opentelemetry/resources": "0.25.0",
     "@opentelemetry/sdk-trace-base": "0.25.0",
     "@opentelemetry/semantic-conventions": "0.25.0"

packages/opentelemetry-test-utils/index.ts → packages/opentelemetry-test-utils/src/index.ts

@@ -16,3 +16,4 @@
 
 export * from './resource-assertions';
 export * from './test-utils';
+export * from './instrumentations';

packages/opentelemetry-test-utils/src/instrumentations/index.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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
+ *
+ *      https://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.
+ */
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { getInstrumentation } from './instrumentation-singelton';
+import { registerInstrumentationTestingProvider } from './otel-default-provider';
+import { resetMemoryExporter } from './otel-provider-api';
+
+export * from './instrumentation-singelton';
+export * from './otel-provider-api';
+export * from './otel-default-provider';
+
+export const mochaHooks = {
+  beforeAll(done: Function) {
+    // since we run mocha executable, process.argv[1] will look like this:
+    // ${root instrumentation package path}/node_modules/.bin/mocha
+    // this is not very robust, might need to refactor in the future
+    let serviceName = 'unknown_instrumentation';
+    if (process.env.OTEL_SERVICE_NAME) {
+      serviceName = process.env.OTEL_SERVICE_NAME;
+    } else {
+      try {
+        serviceName = require(process.argv[1] + '/../../../package.json').name;
+      } catch {
+        // could not determine serviceName, continue regardless of this
+      }
+    }
+    const provider = registerInstrumentationTestingProvider({
+      resource: new Resource({
+        [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+      }),
+    });
+    getInstrumentation()?.setTracerProvider(provider);
+    done();
+  },
+
+  beforeEach(done: Function) {
+    resetMemoryExporter();
+    // reset the config before each test, so that we don't leak state from one test to another
+    getInstrumentation()?.setConfig({});
+    done();
+  },
+};

packages/opentelemetry-test-utils/src/instrumentations/instrumentation-singelton.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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
+ *
+ *      https://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.
+ */
+import { InstrumentationBase } from '@opentelemetry/instrumentation';
+
+const OTEL_TESTING_INSTRUMENTATION_SINGLETON = Symbol.for(
+  'opentelemetry.testing.instrumentation_singleton'
+);
+
+type OTelInstrumentationSingeltonGlobal = {
+  [OTEL_TESTING_INSTRUMENTATION_SINGLETON]?: InstrumentationBase;
+};
+const _global = global as OTelInstrumentationSingeltonGlobal;
+
+export const getInstrumentation = <T extends InstrumentationBase>():
+  | T
+  | undefined => {
+  return _global[OTEL_TESTING_INSTRUMENTATION_SINGLETON] as T;
+};
+
+export const registerInstrumentationTesting = <T extends InstrumentationBase>(
+  instrumentation: T
+): T => {
+  const existing = getInstrumentation<T>();
+  if (existing) {
+    return existing;
+  }
+  _global[OTEL_TESTING_INSTRUMENTATION_SINGLETON] = instrumentation;
+  return instrumentation;
+};

packages/opentelemetry-test-utils/src/instrumentations/otel-default-provider.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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
+ *
+ *      https://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.
+ */
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+import {
+  NodeTracerProvider,
+  NodeTracerConfig,
+} from '@opentelemetry/sdk-trace-node';
+import {
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import {
+  getTestMemoryExporter,
+  setTestMemoryExporter,
+} from './otel-provider-api';
+
+export const registerInstrumentationTestingProvider = (
+  config?: NodeTracerConfig
+): NodeTracerProvider => {
+  const otelTestingProvider = new NodeTracerProvider(config);
+
+  setTestMemoryExporter(new InMemorySpanExporter());
+  otelTestingProvider.addSpanProcessor(
+    new SimpleSpanProcessor(getTestMemoryExporter()!)
+  );
+
+  if (process.env.OTEL_EXPORTER_JAEGER_AGENT_HOST) {
+    otelTestingProvider.addSpanProcessor(
+      new SimpleSpanProcessor(new JaegerExporter())
+    );
+  }
+
+  otelTestingProvider.register();
+  return otelTestingProvider;
+};

packages/opentelemetry-test-utils/src/instrumentations/otel-provider-api.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * 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
+ *
+ *      https://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.
+ */
+import {
+  InMemorySpanExporter,
+  ReadableSpan,
+} from '@opentelemetry/sdk-trace-base';
+
+const OTEL_TESTING_MEMORY_EXPORTER = Symbol.for(
+  'opentelemetry.testing.memory_exporter'
+);
+
+type OTelProviderApiGlobal = {
+  [OTEL_TESTING_MEMORY_EXPORTER]?: InMemorySpanExporter;
+};
+const _global = global as OTelProviderApiGlobal;
+
+export const getTestMemoryExporter = (): InMemorySpanExporter | undefined => {
+  return _global[OTEL_TESTING_MEMORY_EXPORTER];
+};
+
+export const setTestMemoryExporter = (memoryExporter: InMemorySpanExporter) => {
+  _global[OTEL_TESTING_MEMORY_EXPORTER] = memoryExporter;
+};
+
+export const getTestSpans = (): ReadableSpan[] => {
+  return getTestMemoryExporter()!.getFinishedSpans();
+};
+
+export const resetMemoryExporter = () => {
+  getTestMemoryExporter()?.reset();
+};

packages/opentelemetry-test-utils/tsconfig.json

@@ -5,6 +5,6 @@
     "outDir": "build"
   },
   "include": [
-    "*.ts"
+    "src/**/*.ts"
   ]
 }

plugins/node/opentelemetry-instrumentation-mongodb/package.json

@@ -7,7 +7,7 @@
   "repository": "open-telemetry/opentelemetry-js-contrib",
   "scripts": {
     "docker:start": "docker run -e MONGODB_DB=opentelemetry-tests -e MONGODB_PORT=27017 -e MONGODB_HOST=localhost -p 27017:27017 --rm mongo",
-    "test": "nyc ts-mocha --parallel -p tsconfig.json 'test/**/*.test.ts'",
+    "test": "nyc ts-mocha --parallel -p tsconfig.json --require '@opentelemetry/contrib-test-utils' 'test/**/*.test.ts'",
     "test-all-versions": "tav",
     "codecov": "nyc report --reporter=json && codecov -f coverage/*.json -p ../../",
     "tdd": "npm run test -- --watch-extensions ts --watch",
@@ -50,6 +50,7 @@
   },
   "devDependencies": {
     "@opentelemetry/api": "1.0.2",
+    "@opentelemetry/contrib-test-utils": "^0.25.0",
     "@opentelemetry/context-async-hooks": "0.25.0",
     "@opentelemetry/sdk-trace-base": "0.25.0",
     "@opentelemetry/sdk-trace-node": "0.25.0",
@@ -70,4 +71,4 @@
     "@opentelemetry/semantic-conventions": "^0.25.0",
     "@types/mongodb": "3.6.20"
   }
-}
+}