Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

4.7 KB
Raw Blame
import {
  type Context,
  context,
  type Span as OtelSpan,
  propagation,
  ROOT_CONTEXT,
  SpanKind,
  trace,
} from '@opentelemetry/api';
import type { Resource } from '@opentelemetry/resources';
import type { Attributes, TelemetryInitConfig } from './config';
import { INSTRUMENTATION_SCOPE_NAME } from './constants';
import { suppressUserId } from './privacy';
import type { TelemetryTracingProvider } from './provider';
import type { SamplingClass, TraceSampling } from './sampling';
import { type Span, SpanImpl, type TraceContext } from './span';

export interface SpanOptions {
  /**
   * The class whose sampling decision keeps this span when it starts outside
   * an exported trace. Without one it is always kept.
   */
  sampling?: SamplingClass;
  /** `client` for an outbound request. Defaults to `internal`. */
  kind?: 'internal' | 'client';
  /** Start time as Unix time in milliseconds, for a phase that already began. */
  startTime?: number;
  attributes?: Attributes;
}

interface StartOptions extends SpanOptions {
  /** A phase of its parent: always in its parent's trace, dropped with it. */
  phase?: boolean;
}

export class Tracing {
  #provider: TelemetryTracingProvider | undefined;
  #sampling: TraceSampling | undefined;
  #propagationEnabled = false;
  #enablement: Promise<void> | undefined;

  init(
    config: TelemetryInitConfig<string>,
    resource: Resource,
    getUserId: () => string | undefined,
    sampling: TraceSampling
  ): void {
    this.#sampling = sampling;
    this.#propagationEnabled = false;
    this.#enablement = this.#enablePropagation(config, sampling);
    this.#provider = config.tracingProvider?.(resource, getUserId, sampling);
  }

  captureContext(): TraceContext {
    const parent = context.active();
    return { run: (operation) => context.with(parent, operation) };
  }

  remoteContext(traceparent: string): TraceContext {
    const parent = propagation.extract(ROOT_CONTEXT, { traceparent });
    return { run: (operation) => context.with(parent, operation) };
  }

  span(name: string, options: SpanOptions = {}): Span {
    return this.#startSpan(name, context.active(), options);
  }

  /** Starts a detached root span tree with user enrichment suppressed. */
  anonymousSpan(name: string): Span {
    return this.#startSpan(name, suppressUserId(ROOT_CONTEXT), {});
  }

  /** Export a timestamped measurement without retaining a long-lived span. */
  recordSample(
    name: string,
    attributes: Attributes,
    timestamp: number,
    sampling?: SamplingClass
  ): void {
    const { otelSpan } = this.#startOtelSpan(name, ROOT_CONTEXT, {
      sampling,
      attributes,
      startTime: timestamp,
    });
    // Historical samples must win over live onStart enrichment.
    otelSpan.setAttributes(attributes);
    otelSpan.end(timestamp);
  }

  async flush(): Promise<void> {
    await this.#enablement;
    await this.#provider?.forceFlush();
  }

  async shutdown(): Promise<void> {
    await this.#provider?.shutdown();
    this.#provider = undefined;
  }

  #startOtelSpan(
    name: string,
    parent: Context,
    options: StartOptions
  ): { otelSpan: OtelSpan; parent: Context } {
    const started = this.#sampling?.start(
      parent,
      options.phase ?? false,
      options.sampling
    );
    const startParent = started?.context ?? parent;
    const otelSpan = trace.getTracer(INSTRUMENTATION_SCOPE_NAME).startSpan(
      name,
      {
        kind: options.kind === 'client' ? SpanKind.CLIENT : undefined,
        attributes: options.attributes,
        startTime: options.startTime,
      },
      startParent
    );
    if (started)
      this.#sampling?.started(otelSpan, started.record, otelSpan.spanContext());
    return { otelSpan, parent: startParent };
  }

  #startSpan(name: string, parent: Context, options: StartOptions): Span {
    const { otelSpan, parent: startParent } = this.#startOtelSpan(
      name,
      parent,
      options
    );
    const sampling = this.#sampling;
    return new SpanImpl(
      otelSpan,
      trace.setSpan(startParent, otelSpan),
      (childName, childParent) =>
        this.#startSpan(childName, childParent, { phase: true }),
      () => this.#propagationEnabled,
      () =>
        trace.setSpanContext(
          startParent,
          sampling?.spanContext(otelSpan) ?? otelSpan.spanContext()
        )
    );
  }

  async #enablePropagation(
    config: TelemetryInitConfig<string>,
    sampling: TraceSampling
  ): Promise<void> {
    try {
      const [enabled] = await Promise.all([config.enabled(), config.startup]);
      // Spans started before enablement propagate once they are placed.
      await sampling.decided;
      this.#propagationEnabled = enabled;
    } catch {
      this.#propagationEnabled = false;
    }
  }
}