Feature request: Tracer hook/callback API for span creation interception

[schickling]

Summary

I'd like to request an API to intercept span creation events without having to monkey-patch the tracer. Currently, to track span metadata (like building a span path/tree), the only option is to patch tracer.span() directly, which feels hacky and fragile.

Use Case

In our UI framework, we wrap user effects with Effect.withSpan('ui.effect', { root: true }) and want to log the "deepest" span path when the effect completes. For example:

[handleClick → fetchData → processResult] Trace URL: https://...

Since Effect.ensuring() runs after inner spans have closed, we can't access the span hierarchy at that point. Our current workaround patches the tracer to track the deepest span path in a root span attribute as spans are created.

Current Workaround

const ensureTracerPatched = (tracer: Tracer.Tracer) => {
  const originalSpan = tracer.span
  tracer.span = function (name, parent, context, links, startTime, kind, options) {
    const span = originalSpan.apply(this, arguments)
    // Track span path in root span attribute...
    return span
  }
}

Proposed Solutions

Any of these would help:

1. Tracer hook/callback: An official API to register callbacks for span lifecycle events (create, end)
2. In-memory span tree: A way to query the current span hierarchy from within an effect
3. Span creation interceptor: A composable way to wrap span creation similar to how layers work

Environment

• Effect version: 3.x
• Platform: Browser (Electron renderer)

Happy to provide more context or help with implementation if needed!

[higherorderfunctor]

I'd add to this request a way to do it effectfully. As an example, to log every span, I'm manually extracting all the logger info from the span context on top of having to monkey patch the end function on every span.

Logging Tracer

 export const LoggingTracer = Effect.tracerWith((tracer) =>
  Effect.gen(function* () {
    const runtime = yield* Effect.runtime();

    const log = (
      message: string,
      span: Tracer.Span,
      options?: { cause?: Cause.Cause<any> | undefined },
    ) => {
      const fiber = Option.getOrThrow(Fiber.getCurrentFiber());
      const minimumLogLevel = fiber.getFiberRef(FiberRef.currentMinimumLogLevel);
      if (LogLevel.lessThan(LogLevel.Info, minimumLogLevel)) {
        return;
      }
      const date = Runtime.runSync(runtime)(DateTime.now.pipe(Effect.map(DateTime.toDate)));
      const loggers = fiber.getFiberRef(FiberRef.currentLoggers);
      const spans = fiber.getFiberRef(FiberRef.currentLogSpan);
      const spanAnnotations = HashMap.fromIterable(
        Record.toEntries(getSpanInfo(span) as Record<string, unknown>),
      );
      const refs = fiber.getFiberRefs();

      HashSet.forEach(loggers, (logger) => {
        logger.log({
          annotations: spanAnnotations,
          cause: options?.cause ?? Cause.empty,
          context: refs,
          date,
          fiberId: fiber.id(),
          logLevel: options?.cause ? LogLevel.Error : LogLevel.Info,
          message,
          spans,
        });
      });
    };

    return Tracer.make({
      context: (f) => f(),
      span: (name, parent, context, links, startTime, kind) => {
        const span = tracer.span(name, parent, context, links, startTime, kind);
        log('Span started', span);
        const end = span.end.bind(span);
        span.end = (endTime, exit) => {
          if (Exit.isFailure(exit)) {
            log('Span failure', span, { cause: Option.getOrUndefined(Exit.causeOption(exit)) });
          }
          end(endTime, exit);
          log('Span ended', span);
        };
        return span;
      },
    });
  }),
)

export const layer = LoggingTracer.pipe(
  Effect.map(Layer.setTracer),
  Layer.unwrapEffect,
);

[clayroach]

@schickling I'm working on an OpenTelemetry instrumentation library for Effect and this use case is interesting. I think there's a solution at the SpanProcessor layer—the span tree already exists in OTel, it's just not exposed to application code. I'm going to prototype something and also happy to contribute it back to the Effect project if you're good with the approach.

Before I prototype something, a couple quick clarifications:

1. When you say "deepest path"—is that the maximum depth reached during the entire trace (e.g., the path to the span that was nested furthest), or the path at some specific moment?

2. Is this primarily for dev/debugging UX, or production logging? Just trying to understand if memory overhead for tracking the tree is a concern.

I think the Span Tree idea is where I'm going to start but as it would require some fixed memory per trace, I want to be conservative and/or keep a fixed memory approach.