feat(js/tracing): added an option to disable internal root span detection (#3491)

Author: pavelgj

js/core/src/tracing/instrumentation.ts

@@ -16,6 +16,7 @@
 
 import {
   ROOT_CONTEXT,
+  SpanOptions,
   SpanStatusCode,
   trace,
   type Span as ApiSpan,
@@ -95,9 +96,15 @@ export async function runInNewSpan<T>(
     getAsyncContext().getStore<SpanContext>(spanMetadataAlsKey);
   const isInRoot = parentStep?.metadata?.isRoot === true;
   if (!parentStep) opts.metadata.isRoot ||= true;
+
+  const spanOptions: SpanOptions = { links: opts.links };
+  if (!isDisableRootSpanDetection()) {
+    spanOptions.root = opts.metadata.isRoot;
+  }
+
   return await tracer.startActiveSpan(
     opts.metadata.name,
-    { links: opts.links, root: opts.metadata.isRoot },
+    spanOptions,
     async (otSpan) => {
       if (opts.labels) otSpan.setAttributes(opts.labels);
       const spanContext = {
@@ -317,3 +324,22 @@ function decoratePathWithSubtype(metadata: SpanMetadata): string {
   const decoratedStep = `{${pathComponents.at(-1)?.slice(0, -1)}${stepSubtype}}`;
   return root + decoratedStep;
 }
+
+const rootSpanDetectionKey = '__genkit_disableRootSpanDetection';
+
+function isDisableRootSpanDetection(): boolean {
+  return global[rootSpanDetectionKey] === true;
+}
+
+/**
+ * Disables Genkit's custom root span detection and leaves default Otel root span.
+ *
+ * This function attempts to control Genkit's internal OTel instrumentation behaviour,
+ * since internal implementation details are subject to change at any time consider
+ * this function "unstable" and subject to breaking changes as well.
+ *
+ * @hidden
+ */
+export function disableOTelRootSpanDetection() {
+  global[rootSpanDetectionKey] = true;
+}

js/genkit/src/tracing.ts

@@ -25,6 +25,7 @@ export {
   TraceMetadataSchema,
   TraceServerExporter,
   appendSpan,
+  disableOTelRootSpanDetection,
   enableTelemetry,
   flushTracing,
   runInNewSpan,

js/testapps/next/src/genkit/index.ts

@@ -16,6 +16,9 @@
 
 import { gemini15Flash, googleAI } from '@genkit-ai/googleai';
 import { genkit } from 'genkit';
+import { disableOTelRootSpanDetection } from 'genkit/tracing';
+
+disableOTelRootSpanDetection();
 
 export const ai = genkit({
   plugins: [googleAI()],