@graphorin/observability 0.6.0 → 0.7.0

package/src/exporters/otlp-http.ts

@@ -0,0 +1,178 @@
+import pkg from '../../package.json' with { type: 'json' };
+/**
+ * `OTLPHttpExporter` - reference implementation that POSTs span
+ * records to an OpenTelemetry HTTP endpoint.
+ *
+ * The exporter is deliberately minimal: production hardening (retry
+ * logic, batching policy tuning, gzip compression, bearer-token auth
+ * rotation) is left to operators. The wire format follows the OTLP
+ * `traces` resource shape and is compatible with collectors that accept
+ * the `application/json` content type.
+ *
+ * Operators wanting the upstream OpenTelemetry SDK exporter
+ * (`@opentelemetry/exporter-trace-otlp-http`) can adapt
+ * {@link toOtlpEnvelope} into their own wrapper - the helper is
+ * exported so the OTel adapter does not need to duplicate the wire
+ * shape.
+ *
+ * @packageDocumentation
+ */
+
+import type { SpanAttributes, SpanAttributeValue, SpanType } from '@graphorin/core';
+
+import type { SpanRecord, SpanRecordEvent, TraceExporter } from './types.js';
+
+/**
+ * Configuration shape for {@link createOTLPHttpExporter}.
+ *
+ * @stable
+ */
+export interface OTLPHttpExporterOptions {
+  /** Identifier reported via `exporter.id`. Defaults to `'otlp-http'`. */
+  readonly id?: string;
+  /** OTLP collector URL (e.g. `http://localhost:4318/v1/traces`). */
+  readonly url: string;
+  /** Optional headers (auth, tenant id, …). Avoid passing secrets in plain. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Service name embedded in the OTLP `Resource`. */
+  readonly serviceName?: string;
+  /** Optional `fetch` override - useful for testing without the network. */
+  readonly fetchImpl?: typeof fetch;
+  /** Optional timeout (ms). Defaults to 10000. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Build a minimal OTLP-over-HTTP trace exporter. Call
+ * `withValidation(exporter)` before passing the result to
+ * `createTracer({ exporters })`.
+ *
+ * The implementation issues one `POST` per finished span - no
+ * batching. Operators wanting batching should wrap this exporter
+ * with their own queue or use a sidecar collector.
+ *
+ * @stable
+ */
+export function createOTLPHttpExporter(opts: OTLPHttpExporterOptions): TraceExporter {
+  const id = opts.id ?? 'otlp-http';
+  const url = opts.url;
+  const headers = opts.headers ?? {};
+  const serviceName = opts.serviceName ?? 'graphorin';
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  let closed = false;
+
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError(
+      'createOTLPHttpExporter: no fetch implementation available. Provide ' +
+        '`fetchImpl` explicitly or run on a Node.js version with global fetch ' +
+        '(>= 18).',
+    );
+  }
+
+  return {
+    id,
+    async export(record: SpanRecord): Promise<void> {
+      if (closed) return;
+      const body = toOtlpEnvelope(record, serviceName);
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetchImpl(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...headers },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+        if (!res.ok) {
+          throw new Error(`OTLP exporter received HTTP ${res.status} ${res.statusText}`);
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+    async flush(): Promise<void> {
+      // No internal queue; each export() awaits the POST already.
+    },
+    async shutdown(): Promise<void> {
+      closed = true;
+    },
+  };
+}
+
+/**
+ * @internal - exposed for unit tests
+ */
+export function toOtlpEnvelope(record: SpanRecord, serviceName: string): unknown {
+  const otelStatus = record.status === 'ok' ? 1 : record.status === 'error' ? 2 : 0;
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: serviceName } },
+            { key: 'graphorin.framework.version', value: { stringValue: pkg.version } },
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: '@graphorin/observability', version: pkg.version },
+            spans: [
+              {
+                traceId: record.traceId,
+                spanId: record.id,
+                ...(record.parentId === undefined ? {} : { parentSpanId: record.parentId }),
+                name: record.name,
+                kind: spanKindFor(record.type),
+                startTimeUnixNano: String(record.startUnixNano),
+                endTimeUnixNano: String(record.endUnixNano),
+                attributes: toOtlpAttributes(record.attributes),
+                events: record.events.map(toOtlpEvent),
+                status: {
+                  code: otelStatus,
+                  ...(record.statusMessage === undefined ? {} : { message: record.statusMessage }),
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function spanKindFor(type: SpanType): number {
+  // OTel SpanKind enum: 0 unspecified, 1 internal, 2 server, 3 client, 4 producer, 5 consumer.
+  if (type === 'provider.generate' || type === 'provider.stream' || type === 'mcp.call') return 3;
+  if (type === 'tool.execute' || type === 'memory.embed') return 1;
+  return 1;
+}
+
+function toOtlpAttributes(attrs: SpanAttributes): unknown[] {
+  return Object.entries(attrs).map(([k, v]) => ({ key: k, value: toOtlpAttributeValue(v) }));
+}
+
+function toOtlpEvent(event: SpanRecordEvent): unknown {
+  return {
+    timeUnixNano: String(event.timeUnixNano),
+    name: event.name,
+    attributes: toOtlpAttributes(event.attributes),
+  };
+}
+
+function toOtlpAttributeValue(v: SpanAttributeValue): unknown {
+  if (typeof v === 'string') return { stringValue: v };
+  if (typeof v === 'number') {
+    return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+  }
+  if (typeof v === 'boolean') return { boolValue: v };
+  if (v === null) return { stringValue: '' };
+  if (Array.isArray(v)) {
+    return {
+      arrayValue: {
+        values: v.map((item) => toOtlpAttributeValue(item as SpanAttributeValue)),
+      },
+    };
+  }
+  return { stringValue: String(v) };
+}

package/src/exporters/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared types for the exporter surface.
+ *
+ * @packageDocumentation
+ */
+
+import type { SpanAttributes, SpanAttributeValue, SpanStatus, SpanType } from '@graphorin/core';
+
+/**
+ * Discriminator marker - every exporter that has been wrapped via
+ * `withValidation(...)` is branded with this symbol so the tracer can
+ * fail-fast at startup when a raw exporter is registered.
+ *
+ * @stable
+ */
+export const VALIDATED_EXPORTER_BRAND: unique symbol = Symbol.for(
+  'graphorin.observability.exporter.validated',
+);
+
+/**
+ * Sanitized, JSON-serialisable representation of a finished span. The
+ * exporters never see the live OTel span; the tracer materialises this
+ * record once the span ends and runs it through the validator.
+ *
+ * @stable
+ */
+export interface SpanRecord<T extends SpanType = SpanType> {
+  readonly type: T;
+  readonly id: string;
+  readonly traceId: string;
+  readonly parentId?: string;
+  readonly name: string;
+  readonly startUnixNano: number;
+  readonly endUnixNano: number;
+  readonly status: SpanStatus;
+  readonly statusMessage?: string;
+  readonly attributes: SpanAttributes;
+  readonly events: ReadonlyArray<SpanRecordEvent>;
+  /** Optional per-attribute sensitivity map - see `setAttribute({ sensitivity })`. */
+  readonly sensitivityByAttribute?: Readonly<Record<string, SpanAttributeValue>>;
+  /** Set when the validator dropped the span entirely (replay marker). */
+  readonly droppedReason?: string;
+}
+
+/**
+ * Single span event carried alongside the span record.
+ *
+ * @stable
+ */
+export interface SpanRecordEvent {
+  readonly name: string;
+  readonly timeUnixNano: number;
+  readonly attributes: SpanAttributes;
+  /**
+   * W-094: per-attribute sensitivity map recorded by
+   * `addEvent(name, attrs, { sensitivity, sensitivityByAttribute })`.
+   * Consumed by the validation exporter; absent ⇒ every attribute is
+   * untagged (default-deny below the export floor).
+   */
+  readonly sensitivityByAttribute?: Readonly<Record<string, 'public' | 'internal' | 'secret'>>;
+}
+
+/**
+ * A trace exporter contract. Exporters consume a stream of finished
+ * spans and forward them to a sink (console, file, OTLP wire, …).
+ *
+ * @stable
+ */
+export interface TraceExporter {
+  readonly id: string;
+  /** Forward a finished span record. Implementations should be cheap. */
+  export(record: SpanRecord): Promise<void>;
+  /** Flush any buffered spans. Called on `tracer.shutdown()`. */
+  flush(): Promise<void>;
+  /** Close any underlying resources. Idempotent. */
+  shutdown(): Promise<void>;
+  /**
+   * Branded-marker stub. Set by `withValidation(...)` to signal that the
+   * exporter has been wrapped. Direct exporters omit the brand and the
+   * tracer fails fast at startup.
+   *
+   * @internal
+   */
+  readonly [VALIDATED_EXPORTER_BRAND]?: true;
+}

package/src/exporters/with-validation.ts

@@ -0,0 +1,176 @@
+/**
+ * `withValidation(exporter, opts)` - the **mandatory wrapper** applied
+ * to every exporter. Forwards each span record through a
+ * `RedactionValidator` first; drops + counts when a value exceeds the
+ * configured tier floor or matches a secret / PII pattern.
+ *
+ * @packageDocumentation
+ */
+
+import type { Sensitivity, SpanAttributes, SpanAttributeValue } from '@graphorin/core';
+import type {
+  RedactionCounters,
+  RedactionValidatorInstance,
+  RedactionValidatorOptions,
+} from '../redaction/types.js';
+import { createRedactionValidator } from '../redaction/validator.js';
+
+import { type SpanRecord, type TraceExporter, VALIDATED_EXPORTER_BRAND } from './types.js';
+
+const DEFAULT_ATTR_SENSITIVITY: Sensitivity = 'internal';
+
+/**
+ * Options for {@link withValidation}.
+ *
+ * @stable
+ */
+export interface WithValidationOptions extends RedactionValidatorOptions {
+  /**
+   * Optional pre-built validator. When supplied, the rest of the
+   * options on this object are ignored and the supplied validator is
+   * reused - useful for sharing one validator across multiple exporters.
+   */
+  readonly validator?: RedactionValidatorInstance;
+}
+
+/**
+ * Wrap an exporter so every span flows through a {@link RedactionValidator}
+ * before reaching the sink. Exporters that are not wrapped are rejected
+ * by the tracer at startup.
+ *
+ * @stable
+ */
+export function withValidation<E extends TraceExporter>(
+  exporter: E,
+  opts: WithValidationOptions = {},
+): TraceExporter {
+  const validator = opts.validator ?? createRedactionValidator(opts);
+  const wrapped: TraceExporter = {
+    id: `${exporter.id}+validated`,
+    [VALIDATED_EXPORTER_BRAND]: true,
+    async export(record: SpanRecord): Promise<void> {
+      // RP-18: the validator strips offending attributes (counting each drop)
+      // and always returns an exportable record - a single untagged or
+      // over-tier attribute no longer makes the whole span vanish from every
+      // exporter.
+      await exporter.export(sanitizeRecord(record, validator));
+    },
+    flush: () => exporter.flush(),
+    shutdown: () => exporter.shutdown(),
+  };
+  return wrapped;
+}
+
+/**
+ * @internal
+ */
+export function sanitizeRecord(
+  record: SpanRecord,
+  validator: RedactionValidatorInstance,
+): SpanRecord {
+  const sensitivities = record.sensitivityByAttribute ?? {};
+  // RP-18: attribute-granular sanitization. Offending attributes are stripped
+  // (and counted by the validator); the span itself always survives so
+  // framework spans carrying untagged attributes still reach every exporter.
+  const sanitizedAttrs = sanitizeAttributes(
+    record.attributes,
+    sensitivities,
+    validator,
+    record.type,
+  );
+  const sanitizedEvents = sanitizeEvents(record.events, validator, record.type);
+  return {
+    ...record,
+    attributes: sanitizedAttrs,
+    events: sanitizedEvents,
+  };
+}
+
+/**
+ * @internal
+ */
+export function sanitizeAttributes(
+  attrs: SpanAttributes,
+  sensitivities: Readonly<Record<string, SpanAttributeValue>>,
+  validator: RedactionValidatorInstance,
+  spanType?: string,
+  origin?: string,
+): SpanAttributes {
+  const out: Record<string, SpanAttributeValue> = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    const tier = readTier(sensitivities[key]);
+    const result = validator.validate({
+      value,
+      tier,
+      context: {
+        attribute: key,
+        ...(spanType !== undefined ? { spanType } : {}),
+        // W-094: lets onViolation / droppedByReason tell an EVENT
+        // attribute from a span attribute.
+        ...(origin !== undefined ? { origin } : {}),
+      },
+    });
+    if (result === null) {
+      // RP-18: this single attribute exceeded the floor (or matched a secret
+      // pattern). Strip it - the validator has already counted the drop - and
+      // keep the rest of the span rather than discarding the whole record.
+      continue;
+    }
+    out[key] = result.value as SpanAttributeValue;
+  }
+  return Object.freeze(out) as SpanAttributes;
+}
+
+/**
+ * @internal
+ */
+export function sanitizeEvents(
+  events: SpanRecord['events'],
+  validator: RedactionValidatorInstance,
+  spanType?: string,
+): SpanRecord['events'] {
+  const out: SpanRecord['events'][number][] = [];
+  for (const event of events) {
+    // W-094: honour the per-event sensitivity map recorded by
+    // `addEvent(..., opts)` (pre-fix an empty map was passed here, so
+    // EVERY event attribute - including `exception.type` - was dropped
+    // under the default 'public' floor). Untagged attributes still
+    // default-deny; the `event:<name>` origin distinguishes event drops
+    // from span-attribute drops in onViolation.
+    const sanitizedAttrs = sanitizeAttributes(
+      event.attributes,
+      event.sensitivityByAttribute ?? {},
+      validator,
+      spanType,
+      `event:${event.name}`,
+    );
+    out.push({ name: event.name, timeUnixNano: event.timeUnixNano, attributes: sanitizedAttrs });
+  }
+  return out;
+}
+
+function readTier(value: SpanAttributeValue | undefined): Sensitivity {
+  if (value === 'public' || value === 'internal' || value === 'secret') return value;
+  return DEFAULT_ATTR_SENSITIVITY;
+}
+
+/**
+ * Quickly check whether an exporter is the result of a previous
+ * {@link withValidation} call. The tracer uses this to fail fast at
+ * startup.
+ *
+ * @stable
+ */
+export function isValidatedExporter(exporter: TraceExporter): boolean {
+  return exporter[VALIDATED_EXPORTER_BRAND] === true;
+}
+
+/**
+ * Pull the counters out of any exporter wrapped by {@link withValidation}.
+ * Returns `null` for exporters that were never wrapped.
+ *
+ * @stable
+ */
+export function tryGetValidatorCounters(validator: RedactionValidatorInstance): RedactionCounters {
+  return validator.counters();
+}

package/src/gen-ai/emit.ts

@@ -0,0 +1,157 @@
+/**
+ * Emission helpers that attach OpenTelemetry GenAI semantic-convention
+ * attributes / events to an existing span.
+ *
+ * The helpers are deliberately additive - they NEVER remove or rename
+ * existing attributes. The new `gen_ai.*` family sits on top of the
+ * Graphorin-prefixed family. Sensitivity defaults follow the catalogue
+ * documented alongside the canonical mapping table:
+ *
+ * - `gen_ai.system` / `gen_ai.request.model` / `gen_ai.response.model` /
+ *   `gen_ai.response.id` / `gen_ai.usage.{input,output}_tokens` /
+ *   `gen_ai.response.finish_reasons` / `gen_ai.tool.{name,type,call.id,description}` /
+ *   `gen_ai.agent.{id,name}` / `gen_ai.session.id` /
+ *   `gen_ai.operation.name` → `'public'`
+ * - `gen_ai.request.messages` / per-message events / `gen_ai.response.content`
+ *   → `'internal'` (default-deny non-public per DEC-141)
+ * - `gen_ai.tool.output` → inherits per-tool `Tool.sensitivity`
+ *
+ * @packageDocumentation
+ */
+
+import type { AISpan, SpanAttributes, SpanAttributeValue, SpanType } from '@graphorin/core';
+
+import type { GraphorinSpan } from '../tracer/span.js';
+import { asGraphorinSpan } from '../tracer/tracer.js';
+
+import { operationNameFor } from './operation-mapping.js';
+import type { GenAIAttributes, GenAIMessage, GenAIMessageRole } from './types.js';
+
+const PUBLIC_KEY_PREFIXES = [
+  'gen_ai.system',
+  'gen_ai.request.model',
+  'gen_ai.response.model',
+  'gen_ai.response.id',
+  'gen_ai.response.finish_reasons',
+  'gen_ai.usage.input_tokens',
+  'gen_ai.usage.output_tokens',
+  'gen_ai.tool.name',
+  'gen_ai.tool.type',
+  'gen_ai.tool.call.id',
+  'gen_ai.tool.description',
+  'gen_ai.agent.id',
+  'gen_ai.agent.name',
+  'gen_ai.session.id',
+  'gen_ai.operation.name',
+] as const;
+
+/**
+ * Attach the canonical `gen_ai.*` attribute set to a span. The helper
+ * is additive on the existing Graphorin-prefixed attributes and applies
+ * the per-attribute sensitivity defaults catalogue.
+ *
+ * @stable
+ */
+export function emitGenAIAttributes<T extends SpanType>(
+  span: AISpan<T>,
+  attrs: GenAIAttributes,
+): void {
+  const gs = asGraphorinSpan(span);
+  const operation = attrs.operation ?? operationNameFor(span.type);
+  if (operation !== undefined) setPublic(gs, span, 'gen_ai.operation.name', operation);
+
+  if (attrs.system !== undefined) setPublic(gs, span, 'gen_ai.system', attrs.system);
+  if (attrs.requestModel !== undefined)
+    setPublic(gs, span, 'gen_ai.request.model', attrs.requestModel);
+  if (attrs.responseModel !== undefined)
+    setPublic(gs, span, 'gen_ai.response.model', attrs.responseModel);
+  if (attrs.responseId !== undefined) setPublic(gs, span, 'gen_ai.response.id', attrs.responseId);
+  if (attrs.inputTokens !== undefined)
+    setPublic(gs, span, 'gen_ai.usage.input_tokens', attrs.inputTokens);
+  if (attrs.outputTokens !== undefined)
+    setPublic(gs, span, 'gen_ai.usage.output_tokens', attrs.outputTokens);
+  if (attrs.finishReasons !== undefined)
+    setPublic(gs, span, 'gen_ai.response.finish_reasons', [...attrs.finishReasons]);
+  if (attrs.agentId !== undefined) setPublic(gs, span, 'gen_ai.agent.id', attrs.agentId);
+  if (attrs.agentName !== undefined) setPublic(gs, span, 'gen_ai.agent.name', attrs.agentName);
+  if (attrs.sessionId !== undefined) setPublic(gs, span, 'gen_ai.session.id', attrs.sessionId);
+  if (attrs.toolName !== undefined) setPublic(gs, span, 'gen_ai.tool.name', attrs.toolName);
+  if (attrs.toolType !== undefined) setPublic(gs, span, 'gen_ai.tool.type', attrs.toolType);
+  if (attrs.toolCallId !== undefined) setPublic(gs, span, 'gen_ai.tool.call.id', attrs.toolCallId);
+  if (attrs.toolDescription !== undefined)
+    setPublic(gs, span, 'gen_ai.tool.description', attrs.toolDescription);
+}
+
+/**
+ * Emit per-message OpenTelemetry GenAI span events. The helper records
+ * one event per message - the per-message-event emission shape per the
+ * OTel semconv discipline (size-bounded individually; safer than the
+ * aggregate-attribute shape on large prompts).
+ *
+ * @stable
+ */
+export function emitGenAIMessageEvents<T extends SpanType>(
+  span: AISpan<T>,
+  messages: ReadonlyArray<GenAIMessage>,
+  opts: { readonly system?: string } = {},
+): void {
+  for (const message of messages) {
+    // W-094: structural metadata (role, provider name, message name,
+    // tool-call id) is 'public' so a message event survives the default
+    // export floor as a marker; the CONTENT (and tool-call payloads)
+    // stays 'internal' - exported only when the operator opted the
+    // floor up, with the PII patterns applying there.
+    span.addEvent(eventNameFor(message.role), buildEventAttrs(message, opts.system), {
+      sensitivity: 'internal',
+      sensitivityByAttribute: {
+        'gen_ai.message.role': 'public',
+        'gen_ai.system': 'public',
+        'gen_ai.message.name': 'public',
+        'gen_ai.tool.call.id': 'public',
+      },
+    });
+  }
+}
+
+function eventNameFor(role: GenAIMessageRole): string {
+  switch (role) {
+    case 'system':
+      return 'gen_ai.system.message';
+    case 'user':
+      return 'gen_ai.user.message';
+    case 'assistant':
+      return 'gen_ai.assistant.message';
+    case 'tool':
+      return 'gen_ai.tool.message';
+  }
+}
+
+function buildEventAttrs(message: GenAIMessage, system?: string): SpanAttributes {
+  const out: Record<string, SpanAttributeValue> = {
+    'gen_ai.message.role': message.role,
+    content: message.content,
+  };
+  if (system !== undefined) out['gen_ai.system'] = system;
+  if (message.name !== undefined) out['gen_ai.message.name'] = message.name;
+  if (message.toolCallId !== undefined) out['gen_ai.tool.call.id'] = message.toolCallId;
+  if (message.toolCalls !== undefined && message.toolCalls.length > 0) {
+    out['gen_ai.tool.calls'] = JSON.stringify(message.toolCalls);
+  }
+  return Object.freeze(out) as SpanAttributes;
+}
+
+function setPublic(
+  gs: GraphorinSpan | null,
+  span: AISpan,
+  key: string,
+  value: SpanAttributeValue,
+): void {
+  if (
+    gs !== null &&
+    PUBLIC_KEY_PREFIXES.some((prefix) => key === prefix || key.startsWith(`${prefix}.`))
+  ) {
+    gs.setAttribute(key, value, { sensitivity: 'public' });
+    return;
+  }
+  span.setAttributes({ [key]: value });
+}

package/src/gen-ai/index.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenTelemetry GenAI semantic-conventions conformance helpers.
+ *
+ * @packageDocumentation
+ */
+
+export { emitGenAIAttributes, emitGenAIMessageEvents } from './emit.js';
+export {
+  OPERATION_NAME_TABLE,
+  operationNameFor,
+} from './operation-mapping.js';
+export {
+  _resetGenAISystemWarningsForTesting,
+  deriveGenAISystem,
+  PROVIDER_CLASS_TO_GEN_AI_SYSTEM,
+  setGenAISystemWarnSink,
+} from './system-derivation.js';
+export type {
+  GenAIAttributes,
+  GenAIMessage,
+  GenAIMessageRole,
+  GenAIOperationName,
+  GenAISystem,
+  GenAIToolType,
+  SpanTypeToOperationName,
+} from './types.js';