ENG-2239: Respect suppressed option telemetry (#20)

* ENG-2239: respect suppressed option telemetry

* docs: use Photon Project identity

* test: translate Developer telemetry fixture

Author: gtxy27

docs/guides/option-runtime.mdx

@@ -35,12 +35,16 @@ Calling it before `setupOtel()` is a configuration error.
 ```ts
 const logger = option.createLogger("@photon-ai/developer-logs");
 
-await option.withSpan("project.generate", { "project.id": projectId }, async () => {
-  logger.emit({
-    body: "starting project generation",
-    eventName: "developer.message",
-  });
-});
+await option.withSpan(
+  "project.generate",
+  { "photon.project.id": projectId },
+  async () => {
+    logger.emit({
+      body: "starting project generation",
+      eventName: "developer.message",
+    });
+  }
+);
 ```
 
 Success leaves the Span status `UNSET`. If the callback throws, the runtime

docs/reference/api.mdx

@@ -119,6 +119,11 @@ interface OptionOtelHandle {
     inject(headers: Headers, captured?: Context): void;
     run<T>(captured: Context, fn: () => T): T;
   };
+  withActiveSpan<T>(
+    name: string,
+    options: SpanOptions & { parentContext?: Context },
+    fn: (span: Span) => Promise<T> | T,
+  ): Promise<T>;
   withSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
   withSpan<T>(
     name: string,
@@ -129,6 +134,11 @@ interface OptionOtelHandle {
 }
 ```
 
+`withActiveSpan()` is the instrumentation-level form. It accepts standard
+OpenTelemetry `SpanOptions`, an optional explicit parent Context, and exposes
+the active Span to the callback. A suppressed parent produces no recording
+Span and does not make `hasActiveSpan()` true; the business callback still runs.
+
 The propagation helper uses the fixed internal
 `photon-developer-traceparent` header and never changes the standard
 `traceparent`.

src/option-runtime.ts

@@ -5,8 +5,10 @@ import {
   defaultTextMapGetter,
   defaultTextMapSetter,
   diag,
+  INVALID_SPAN_CONTEXT,
   ROOT_CONTEXT,
   type Span,
+  type SpanOptions,
   SpanStatusCode,
   trace,
 } from "@opentelemetry/api";
@@ -52,7 +54,7 @@ export interface OptionOtelHandle {
   ): {
     emit: (record: Omit<LogRecord, "context">) => void;
   };
-  /** True only for a local Span created by this runtime, not a remote parent. */
+  /** True only for a recording local Span, not a remote or suppressed parent. */
   hasActiveSpan(): boolean;
   readonly propagation: {
     /** Capture the current context so delayed iterators can re-enter it. */
@@ -65,6 +67,12 @@ export interface OptionOtelHandle {
     run: <T>(captured: Context, fn: () => T) => T;
   };
   shutdown(): Promise<void>;
+  /** Run a callback with a Span active only in this runtime's private Context. */
+  withActiveSpan<T>(
+    name: string,
+    options: SpanOptions & { parentContext?: Context },
+    fn: (span: Span) => Promise<T> | T
+  ): Promise<T>;
   withSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
   withSpan<T>(
     name: string,
@@ -186,30 +194,28 @@ export const createOptionOtelRuntime = (
     run: (captured, fn) => contextManager.with(captured, fn),
   };
 
-  const withSpan = <T>(
-    name: string,
-    attributesOrFn: Attributes | (() => Promise<T> | T),
-    maybeFn?: () => Promise<T> | T
-  ): Promise<T> => {
-    const fn = typeof attributesOrFn === "function" ? attributesOrFn : maybeFn;
-    if (!fn) {
-      throw new Error("withSpan: function argument is required");
-    }
-    const attributes =
-      typeof attributesOrFn === "function" ? undefined : attributesOrFn;
-    const parent = contextManager.active();
+  const withActiveSpan: OptionOtelHandle["withActiveSpan"] = async (
+    name,
+    options,
+    fn
+  ) => {
+    const { parentContext, ...spanOptions } = options;
+    const parent = parentContext ?? contextManager.active();
     let span: Span;
     try {
-      span = tracer.startSpan(name, { attributes }, parent);
+      span = tracer.startSpan(name, spanOptions, parent);
     } catch (error) {
       reportDiagnostic("failed to start Span", error);
-      return Promise.resolve().then(fn);
+      return await fn(trace.wrapSpanContext(INVALID_SPAN_CONTEXT));
     }
 
-    const active = trace.setSpan(parent, span).setValue(localSpanKey, span);
-    return contextManager.with(active, async () => {
+    const spanContext = trace.setSpan(parent, span);
+    const active = span.isRecording()
+      ? spanContext.setValue(localSpanKey, span)
+      : spanContext;
+    return await contextManager.with(active, async () => {
       try {
-        return await fn();
+        return await fn(span);
       } catch (error) {
         try {
           span.recordException(error instanceof Error ? error : String(error));
@@ -232,6 +238,20 @@ export const createOptionOtelRuntime = (
     });
   };
 
+  const withSpan = <T>(
+    name: string,
+    attributesOrFn: Attributes | (() => Promise<T> | T),
+    maybeFn?: () => Promise<T> | T
+  ): Promise<T> => {
+    const fn = typeof attributesOrFn === "function" ? attributesOrFn : maybeFn;
+    if (!fn) {
+      throw new Error("withSpan: function argument is required");
+    }
+    const attributes =
+      typeof attributesOrFn === "function" ? undefined : attributesOrFn;
+    return withActiveSpan(name, { attributes }, () => fn());
+  };
+
   return {
     createLogger(name, version) {
       const logger: Logger = loggerProvider.getLogger(name, version);
@@ -260,6 +280,7 @@ export const createOptionOtelRuntime = (
       }
       return shutdownPromise;
     },
+    withActiveSpan,
     withSpan: withSpan as OptionOtelHandle["withSpan"],
   };
 };

tests/option-runtime.test.ts

@@ -1,5 +1,11 @@
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import {
+  ROOT_CONTEXT,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+} from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
+import { suppressTracing } from "@opentelemetry/core";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import {
   InMemoryLogRecordExporter,
@@ -155,22 +161,66 @@ describe("option runtime", () => {
     await runtime.shutdown();
   });
 
+  it("supports a private active SERVER root with full Span options", async () => {
+    const { runtime, spanExporter } = createRuntime();
+    let callbackSpanId = "";
+
+    await runtime.withActiveSpan(
+      "developer.http",
+      {
+        attributes: { "photon.api_key.id": "pho_sk_test" },
+        kind: SpanKind.SERVER,
+        parentContext: ROOT_CONTEXT,
+      },
+      (span) => {
+        callbackSpanId = span.spanContext().spanId;
+        expect(runtime.hasActiveSpan()).toBe(true);
+      }
+    );
+
+    const [server] = spanExporter.getFinishedSpans();
+    expect(server?.kind).toBe(SpanKind.SERVER);
+    expect(server?.parentSpanContext).toBeUndefined();
+    expect(server?.attributes["photon.api_key.id"]).toBe("pho_sk_test");
+    expect(callbackSpanId).toBe(server?.spanContext().spanId);
+    await runtime.shutdown();
+  });
+
+  it("does not activate or export spans when tracing is suppressed", async () => {
+    const { runtime, spanExporter } = createRuntime();
+    let callbackRan = false;
+    const headers = new Headers();
+
+    await runtime.propagation.run(suppressTracing(ROOT_CONTEXT), () =>
+      runtime.withSpan("suppressed", () => {
+        callbackRan = true;
+        expect(runtime.hasActiveSpan()).toBe(false);
+        runtime.propagation.inject(headers);
+      })
+    );
+
+    expect(callbackRan).toBe(true);
+    expect(headers.has(TRACEPARENT_HEADER)).toBe(false);
+    expect(spanExporter.getFinishedSpans()).toEqual([]);
+    await runtime.shutdown();
+  });
+
   it("associates logs with the active local span and inherited Resource", async () => {
     const { logExporter, runtime } = createRuntime("projects-service");
     const logger = runtime.createLogger("@photon-ai/developer-logs");
 
     await runtime.withSpan("project.generate", () => {
       logger.emit({
-        attributes: { "project.id": "proj_123" },
-        body: "开始生成项目",
+        attributes: { "photon.project.id": "pho_prj_123" },
+        body: "Starting project generation",
         eventName: "developer.message",
         severityNumber: SeverityNumber.INFO,
         severityText: "INFO",
       });
     });
 
     const [record] = logExporter.getFinishedLogRecords();
-    expect(record?.body).toBe("开始生成项目");
+    expect(record?.body).toBe("Starting project generation");
     expect(record?.instrumentationScope.name).toBe("@photon-ai/developer-logs");
     expect(record?.spanContext?.traceId).toMatch(TRACE_ID_PATTERN);
     expect(record?.spanContext?.spanId).toMatch(SPAN_ID_PATTERN);