feat: create bootstrap span on demand (DASH0_BOOTSTRAP_SPAN)

Author: basti1302

README.md

@@ -14,6 +14,11 @@ If no `OTEL_SERVICE_NAME` has been set, a service name is automatically derived
 (if it is present) as `${packageJson.name}@${packageJson.version}`.
 This can be disabled either by setting `OTEL_SERVICE_NAME` or by setting `DASH0_AUTOMATIC_SERVICE_NAME=false`.
 
+### <a id="DASH0_BOOTSTRAP_SPAN">DASH0_BOOTSTRAP_SPAN</a>
+
+If set to a non-empty string, the distribution will create a span immediately at startup with the span name set to the
+value of DASH0_BOOTSTRAP_SPAN.
+
 ### <a id="DASH0_DEBUG">DASH0_DEBUG</a>
 
 Additional debug logs can be enabled by setting `DASH0_DEBUG=true`.

src/init.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: Copyright 2024 Dash0 Inc.
 // SPDX-License-Identifier: Apache-2.0
 
+import { SpanKind, trace } from '@opentelemetry/api';
 import { getNodeAutoInstrumentations, getResourceDetectors } from '@opentelemetry/auto-instrumentations-node';
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-proto';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
@@ -84,6 +85,16 @@ const sdk = new NodeSDK(configuration);
 
 sdk.start();
 
+if (process.env.DASH0_BOOTSTRAP_SPAN != null) {
+  const tracer = trace.getTracer('dash0-nodejs-distribution');
+  tracer //
+    .startSpan(process.env.DASH0_BOOTSTRAP_SPAN, {
+      root: true,
+      kind: SpanKind.INTERNAL,
+    })
+    .end();
+}
+
 if (process.env.DASH0_DEBUG) {
   console.log('Dash0 OpenTelemetry distribution for Node.js: NodeSDK started.');
 }

test/integration/rootHooks.ts

@@ -21,10 +21,6 @@ export const mochaHooks = {
     console.debug('[rootHooks] global mock collector started');
   },
 
-  async beforeEach() {
-    collectorInstance.clear();
-  },
-
   async afterAll() {
     console.debug('[rootHooks] stopping global mock collector');
     await collectorInstance.stop();

test/integration/test.ts

@@ -34,7 +34,11 @@ describe('attach', () => {
     expectedDistroVersion = JSON.parse(String(await readFile('package.json'))).version;
   });
 
-  describe('tracing', () => {
+  beforeEach(async function () {
+    collector().clear();
+  });
+
+  describe('basic tracing', () => {
     let appUnderTest: ChildProcessWrapper;
 
     before(async () => {
@@ -49,7 +53,7 @@ describe('attach', () => {
 
     it('should attach via --require and capture spans', async () => {
       await waitUntil(async () => {
-        const telemetry = await waitForTelemetry();
+        const telemetry = await sendRequestAndWaitForTraceData();
         expectMatchingSpan(
           telemetry.traces,
           [
@@ -59,7 +63,7 @@ describe('attach', () => {
             resource => expectResourceAttribute(resource, 'telemetry.distro.version', expectedDistroVersion),
           ],
           [
-            span => expect(span.kind).to.equal(SpanKind.SERVER),
+            span => expect(span.kind).to.equal(SpanKind.SERVER, 'span kind should be server'),
             span => expectSpanAttribute(span, 'http.route', '/ohai'),
           ],
         );
@@ -83,12 +87,12 @@ describe('attach', () => {
 
     it('should attach via --require and detect the pod uid', async () => {
       await waitUntil(async () => {
-        const telemetry = await waitForTelemetry();
+        const telemetry = await sendRequestAndWaitForTraceData();
         expectMatchingSpan(
           telemetry.traces,
           [resource => expectResourceAttribute(resource, 'k8s.pod.uid', 'f57400dc-94ce-4806-a52e-d2726f448f15')],
           [
-            span => expect(span.kind).to.equal(SpanKind.SERVER),
+            span => expect(span.kind).to.equal(SpanKind.SERVER, 'span kind should be server'),
             span => expectSpanAttribute(span, 'http.route', '/ohai'),
           ],
         );
@@ -111,22 +115,56 @@ describe('attach', () => {
 
     it('should attach via --require and derive a service name from the package.json file', async () => {
       await waitUntil(async () => {
-        const telemetry = await waitForTelemetry();
+        const telemetry = await sendRequestAndWaitForTraceData();
         expectMatchingSpan(
           telemetry.traces,
           [
             resource =>
               expectResourceAttribute(resource, 'service.name', '[email protected]'),
           ],
           [
-            span => expect(span.kind).to.equal(SpanKind.SERVER),
+            span => expect(span.kind).to.equal(SpanKind.SERVER, 'span kind should be server'),
             span => expectSpanAttribute(span, 'http.route', '/ohai'),
           ],
         );
       });
     });
   });
 
+  describe('bootstrap span', () => {
+    let appUnderTest: ChildProcessWrapper;
+
+    before(async () => {
+      const appConfiguration = defaultAppConfiguration(appPort);
+      appConfiguration.env!.DASH0_BOOTSTRAP_SPAN = 'Dash0 Test Bootstrap Span';
+      appUnderTest = new ChildProcessWrapper(appConfiguration);
+    });
+
+    after(async () => {
+      await appUnderTest.stop();
+    });
+
+    it('should create an internal span on bootstrap', async () => {
+      // It is important for this test that we do not start the app in the before hook, since the beforeEach from the
+      // top level suite clears the mock collector's spans, thus we would accidentally delete the bootstrap span
+      // (because the top level beforeHook is executed after this suite's before hook).
+      await appUnderTest.start();
+      await waitUntil(async () => {
+        const telemetry = await waitForTraceData();
+        expectMatchingSpan(
+          telemetry.traces,
+          [
+            resource => expectResourceAttribute(resource, 'telemetry.sdk.name', 'opentelemetry'),
+            resource => expectResourceAttribute(resource, 'telemetry.sdk.language', 'nodejs'),
+            resource => expectResourceAttribute(resource, 'telemetry.distro.name', 'dash0-nodejs'),
+            resource => expectResourceAttribute(resource, 'telemetry.distro.version', expectedDistroVersion),
+          ],
+          [span => expect(span.name).to.equal('Dash0 Test Bootstrap Span')],
+        );
+      });
+    });
+  });
+
   describe('print spans to file', () => {
     let appUnderTest: ChildProcessWrapper;
     const spanFilename = join(__dirname, 'spans.json');
@@ -185,7 +223,7 @@ describe('attach', () => {
             resourceAttributes =>
               expect(resourceAttributes['telemetry.distro.version']).to.equal(expectedDistroVersion),
           ],
-          [spanAttributes => expect(spanAttributes.kind).to.equal(SpanKind.SERVER)],
+          [spanAttributes => expect(spanAttributes.kind).to.equal(SpanKind.SERVER, 'span kind should be server')],
           [spanAttributes => expect(spanAttributes['http.route']).to.equal('/ohai')],
         );
       });
@@ -217,12 +255,9 @@ describe('attach', () => {
     });
   });
 
-  async function waitForTelemetry() {
+  async function sendRequestAndWaitForTraceData() {
     await sendRequestAndVerifyResponse();
-    if (!(await collector().hasTraces())) {
-      throw new Error('The collector never received any spans.');
-    }
-    return await collector().fetchTelemetry();
+    return waitForTraceData();
   }
 
   async function sendRequestAndVerifyResponse() {
@@ -232,6 +267,13 @@ describe('attach', () => {
     expect(responsePayload).to.deep.equal({ message: 'We make Observability easy for every developer.' });
   }
 
+  async function waitForTraceData() {
+    if (!(await collector().hasTraces())) {
+      throw new Error('The collector never received any spans.');
+    }
+    return await collector().fetchTelemetry();
+  }
+
   async function verifyFileHasBeenCreated(filename: string): Promise<FileHandle> {
     let file;
     try {

test/util/expectMatchingSpan.ts

@@ -4,15 +4,15 @@
 import { ExportTraceServiceRequest } from '../collector/types/opentelemetry/proto/collector/trace/v1/trace_service';
 import { Resource } from '../collector/types/opentelemetry/proto/resource/v1/resource';
 import { Span } from '../collector/types/opentelemetry/proto/trace/v1/trace';
-import { Expectation, findMatchingSpans, findMatchingSpansInFileDump } from './findMatchingSpans';
+import { Expectation, findMatchingSpans, findMatchingSpansInFileDump, MatchingSpansResult } from './findMatchingSpans';
 
 export function expectMatchingSpan(
   traceDataItems: ExportTraceServiceRequest[],
   resourceExpectations: Expectation<Resource>[],
   spanExpectations: Expectation<Span>[],
 ): Span {
-  const { matchingSpans, lastError } = findMatchingSpans(traceDataItems, resourceExpectations, spanExpectations);
-  return processFindSpanResult(matchingSpans, lastError);
+  const matchResult = findMatchingSpans(traceDataItems, resourceExpectations, spanExpectations);
+  return processFindSpanResult(matchResult);
 }
 
 export function expectMatchingSpanInFileDump(
@@ -21,29 +21,33 @@ export function expectMatchingSpanInFileDump(
   spanExpectations: Expectation<any>[],
   spanAttributeExpectations: Expectation<any>[],
 ): Span {
-  const { matchingSpans, lastError } = findMatchingSpansInFileDump(
+  const matchResult = findMatchingSpansInFileDump(
     spans,
     resourceAttributeExpectations,
     spanExpectations,
     spanAttributeExpectations,
   );
-  return processFindSpanResult(matchingSpans, lastError);
+  return processFindSpanResult(matchResult);
 }
 
-function processFindSpanResult(matchingSpans: Span[], lastError: Error | undefined): Span {
-  if (matchingSpans.length === 1) {
-    return matchingSpans[0];
-  } else if (matchingSpans.length === 0) {
-    if (lastError) {
-      throw new Error(`No matching span found. Most recent failing expectation: ${lastError}`);
+function processFindSpanResult(matchResult: MatchingSpansResult): Span {
+  if (matchResult.matchingSpans) {
+    const matchingSpans = matchResult.matchingSpans;
+    if (matchingSpans.length === 1) {
+      return matchingSpans[0];
+    } else if (matchingSpans.length > 1) {
+      throw new Error(
+        `Expected exactly one matching span, found ${matchingSpans.length}.\nMatches:\n${JSON.stringify(matchingSpans, null, 2)}`,
+      );
     } else {
-      throw new Error('No matching span found.');
+      throw new Error('Unexpected error while processing matching spans.');
     }
-  } else if (matchingSpans.length > 1) {
+  } else if (matchResult.bestCandidate) {
+    const bestCandidate = matchResult.bestCandidate;
     throw new Error(
-      `Expected exactly one matching span, found ${matchingSpans.length}.\nMatches:\n${JSON.stringify(matchingSpans, null, 2)} `,
+      `No matching span has been found. The best candidate passed ${bestCandidate.passedChecks} and failed check ${bestCandidate.passedChecks + 1} with error ${bestCandidate.error}. This is the best candidate:\n${JSON.stringify(bestCandidate.spanLike, null, 2)}`,
     );
   } else {
-    throw new Error('Unexpected error while processing matching spans.');
+    throw new Error('No matching span has been found.');
   }
 }