add Tracer Span.addLinks, for dynamically linking spans (#4465)

Author: tim-smart

.changeset/eight-hats-turn.md

@@ -0,0 +1,6 @@
+---
+"@effect/opentelemetry": minor
+"effect": minor
+---
+
+add Tracer Span.addLinks, for dynamically linking spans

packages/effect/src/Effect.ts

@@ -12962,6 +12962,17 @@ export const linkSpans: {
   ): Effect<A, E, R>
 } = effect.linkSpans
 
+/**
+ * Add span links to the current span.
+ *
+ * @since 3.14.0
+ * @category Tracing
+ */
+export const linkSpanCurrent: {
+  (span: Tracer.AnySpan, attributes?: Readonly<Record<string, unknown>> | undefined): Effect<void>
+  (links: ReadonlyArray<Tracer.SpanLink>): Effect<void>
+} = effect.linkSpanCurrent
+
 /**
  * Create a new span for tracing.
  *

packages/effect/src/Tracer.ts

@@ -121,6 +121,7 @@ export interface Span {
   end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void
   attribute(key: string, value: unknown): void
   event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void
+  addLinks(links: ReadonlyArray<SpanLink>): void
 }
 
 /**

packages/effect/src/internal/core-effect.ts

@@ -1950,6 +1950,21 @@ export const annotateCurrentSpan: {
   ))
 }
 
+/* @internal */
+export const linkSpanCurrent: {
+  (span: Tracer.AnySpan, attributes?: Readonly<Record<string, unknown>> | undefined): Effect.Effect<void>
+  (links: ReadonlyArray<Tracer.SpanLink>): Effect.Effect<void>
+} = function(): Effect.Effect<void> {
+  const args = arguments
+  const links: ReadonlyArray<Tracer.SpanLink> = Array.isArray(args[0])
+    ? args[0]
+    : [{ _tag: "SpanLink", span: args[0], attributes: args[1] ?? {} }]
+  return ignore(core.flatMap(
+    currentSpan,
+    (span) => core.sync(() => span.addLinks(links))
+  ))
+}
+
 /* @internal */
 export const annotateSpans = dual<
   {

packages/effect/src/internal/core.ts

@@ -3147,7 +3147,8 @@ const NoopSpanProto: Omit<Tracer.Span, "parent" | "name" | "context"> = {
   kind: "internal",
   attribute() {},
   event() {},
-  end() {}
+  end() {},
+  addLinks() {}
 }
 
 /** @internal */

packages/effect/src/internal/tracer.ts

@@ -44,12 +44,13 @@ export class NativeSpan implements Tracer.Span {
   status: Tracer.SpanStatus
   attributes: Map<string, unknown>
   events: Array<[name: string, startTime: bigint, attributes: Record<string, unknown>]> = []
+  links: Array<Tracer.SpanLink>
 
   constructor(
     readonly name: string,
     readonly parent: Option.Option<Tracer.AnySpan>,
     readonly context: Context.Context<never>,
-    readonly links: ReadonlyArray<Tracer.SpanLink>,
+    links: Iterable<Tracer.SpanLink>,
     readonly startTime: bigint,
     readonly kind: Tracer.SpanKind
   ) {
@@ -60,6 +61,7 @@ export class NativeSpan implements Tracer.Span {
     this.attributes = new Map()
     this.traceId = parent._tag === "Some" ? parent.value.traceId : randomHexString(32)
     this.spanId = randomHexString(16)
+    this.links = Array.from(links)
   }
 
   end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
@@ -78,6 +80,11 @@ export class NativeSpan implements Tracer.Span {
   event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
     this.events.push([name, startTime, attributes ?? {}])
   }
+
+  addLinks(links: ReadonlyArray<Tracer.SpanLink>): void {
+    // eslint-disable-next-line no-restricted-syntax
+    this.links.push(...links)
+  }
 }
 
 /** @internal */

packages/opentelemetry/package.json

@@ -47,13 +47,13 @@
     "coverage": "vitest --coverage"
   },
   "peerDependencies": {
-    "@opentelemetry/api": "^1.6",
-    "@opentelemetry/resources": "^1.22",
-    "@opentelemetry/sdk-metrics": "^1.22",
-    "@opentelemetry/sdk-trace-base": "^1.22",
-    "@opentelemetry/sdk-trace-node": "^1.22",
-    "@opentelemetry/sdk-trace-web": "^1.22",
-    "@opentelemetry/semantic-conventions": "^1.24.1",
+    "@opentelemetry/api": "^1.9",
+    "@opentelemetry/resources": "^1.25",
+    "@opentelemetry/sdk-metrics": "^1.25",
+    "@opentelemetry/sdk-trace-base": "^1.25",
+    "@opentelemetry/sdk-trace-node": "^1.25",
+    "@opentelemetry/sdk-trace-web": "^1.25",
+    "@opentelemetry/semantic-conventions": "^1.25",
     "effect": "workspace:^"
   },
   "peerDependenciesMeta": {

packages/opentelemetry/src/internal/tracer.ts

@@ -39,7 +39,7 @@ export class OtelSpan implements EffectTracer.Span {
     readonly name: string,
     readonly parent: Option.Option<EffectTracer.AnySpan>,
     readonly context: Context.Context<never>,
-    readonly links: ReadonlyArray<EffectTracer.SpanLink>,
+    readonly links: Array<EffectTracer.SpanLink>,
     startTime: bigint,
     readonly kind: EffectTracer.SpanKind
   ) {
@@ -76,6 +76,15 @@ export class OtelSpan implements EffectTracer.Span {
     this.attributes.set(key, value)
   }
 
+  addLinks(links: ReadonlyArray<EffectTracer.SpanLink>): void {
+    // eslint-disable-next-line no-restricted-syntax
+    this.links.push(...links)
+    this.span.addLinks(links.map((link) => ({
+      context: makeSpanContext(link.span),
+      attributes: recordToAttributes(link.attributes)
+    })))
+  }
+
   end(endTime: bigint, exit: Exit<unknown, unknown>) {
     const hrTime = nanosToHrTime(endTime)
     this.status = {
@@ -141,7 +150,7 @@ export const make = Effect.map(Tracer, (tracer) =>
         name,
         parent,
         context,
-        links,
+        links.slice(),
         startTime,
         kind
       )