@datalayer/core 1.2.17 → 1.2.18

package/lib/otel/index.d.ts

@@ -13,6 +13,8 @@
  */
 export type { OtelSpan, OtelLog, OtelMetric, OtelSpanEvent, OtelSpanLink, SignalType, OtelLiveProps, OtelTracesListProps, OtelSpanDetailProps, OtelTimelineProps, OtelLogsListProps, OtelMetricsListProps, OtelSpanTreeProps, OtelSearchBarProps, OtelTimelineRangeSliderProps, OtelQueryRow, OtelQueryResult, } from './types';
 export { toMs, formatDuration, formatTime, serviceColor, kindColor, severityColor, severityVariant, buildSpanTree, flattenSpanTree, } from './utils';
+export { createOtelLiveTracer, traceparentOf, PEER_SERVICE, spanConcerns, spansOfService, useOtelLiveSpans, useOtelLiveTracer, } from './live';
+export type { OtelAttributeValue, OtelAttributes, OtelLiveExport, OtelLiveSpan, OtelLiveTracer, OtelLiveTracerOptions, OtelSpanContext, OtelSpanKindName, OtelStartSpanOptions, } from './live';
 export { resolveOtelAuth, resolveOtelUserUid, buildOtelWebSocketUrl, } from './auth';
 export type { ResolvedOtelAuth } from './auth';
 export { useOtelTraces, useOtelTrace, useOtelLogs, useOtelMetrics, useOtelServices, useOtelStats, useOtelQuery, useOtelSystem, useOtelWebSocket, setOtelOnUnauthorized, } from './hooks';
@@ -29,6 +31,8 @@ export { OtelMetricsList } from './views';
 export { OtelMetricsChart } from './views';
 export type { OtelMetricsChartProps } from './views';
 export { OtelTimeline } from './views';
+export { OtelLiveSpans, DEFAULT_SPAN_FACETS, filterSpansByFacets, unfoldedValue, } from './views';
+export type { OtelLiveSpansProps, OtelSpanFacet } from './views';
 export { OtelTimelineRangeSlider } from './views';
 export { OtelSqlView } from './views';
 export type { OtelSqlViewProps } from './views';

package/lib/otel/index.js

@@ -4,6 +4,8 @@
  */
 // ── Utils ─────────────────────────────────────────────────────────────────────
 export { toMs, formatDuration, formatTime, serviceColor, kindColor, severityColor, severityVariant, buildSpanTree, flattenSpanTree, } from './utils.js';
+// ── In the page ───────────────────────────────────────────────────────────────
+export { createOtelLiveTracer, traceparentOf, PEER_SERVICE, spanConcerns, spansOfService, useOtelLiveSpans, useOtelLiveTracer, } from './live/index.js';
 // ── Auth helpers ──────────────────────────────────────────────────────────────
 export { resolveOtelAuth, resolveOtelUserUid, buildOtelWebSocketUrl, } from './auth.js';
 // ── Hooks ─────────────────────────────────────────────────────────────────────
@@ -20,6 +22,7 @@ export { OtelSearchBar } from './views/index.js';
 export { OtelMetricsList } from './views/index.js';
 export { OtelMetricsChart } from './views/index.js';
 export { OtelTimeline } from './views/index.js';
+export { OtelLiveSpans, DEFAULT_SPAN_FACETS, filterSpansByFacets, unfoldedValue, } from './views/index.js';
 export { OtelTimelineRangeSlider } from './views/index.js';
 export { OtelSqlView } from './views/index.js';
 export { OtelSystemView } from './views/index.js';

package/lib/otel/live/filter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Which spans concern a service: those it did, and those done toward it — a
+ * client span whose `peer.service` names it (the OpenTelemetry attribute for
+ * the remote service a call goes to). One message between two services shows
+ * in both: sent in one, received in the other.
+ *
+ * @module otel/live/filter
+ */
+import type { OtelSpan } from '../types';
+/** The OpenTelemetry attribute naming the service a call goes to. */
+export declare const PEER_SERVICE = "peer.service";
+/** Whether a span concerns a service: done by it, or toward it. */
+export declare function spanConcerns(span: OtelSpan, service: string): boolean;
+/** The spans that concern a service; every span without one. */
+export declare function spansOfService(spans: readonly OtelSpan[], service: string | undefined): OtelSpan[];

package/lib/otel/live/filter.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The OpenTelemetry attribute naming the service a call goes to. */
+export const PEER_SERVICE = 'peer.service';
+/** Whether a span concerns a service: done by it, or toward it. */
+export function spanConcerns(span, service) {
+    return (span.service_name === service || span.attributes?.[PEER_SERVICE] === service);
+}
+/** The spans that concern a service; every span without one. */
+export function spansOfService(spans, service) {
+    return service
+        ? spans.filter(span => spanConcerns(span, service))
+        : [...spans];
+}

package/lib/otel/live/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OpenTelemetry in the page: a tracer whose spans the OTEL views draw as
+ * they happen, and which of them concern a service. Light: no view, no
+ * client, nothing sent.
+ *
+ * @module otel/live
+ */
+export { createOtelLiveTracer, traceparentOf, type OtelAttributeValue, type OtelAttributes, type OtelLiveExport, type OtelLiveSpan, type OtelLiveTracer, type OtelLiveTracerOptions, type OtelSpanContext, type OtelSpanKindName, type OtelStartSpanOptions, } from './tracer';
+export { PEER_SERVICE, spanConcerns, spansOfService } from './filter';
+export { useOtelLiveSpans, useOtelLiveTracer } from './useOtelLiveSpans';

package/lib/otel/live/index.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OpenTelemetry in the page: a tracer whose spans the OTEL views draw as
+ * they happen, and which of them concern a service. Light: no view, no
+ * client, nothing sent.
+ *
+ * @module otel/live
+ */
+export { createOtelLiveTracer, traceparentOf, } from './tracer.js';
+export { PEER_SERVICE, spanConcerns, spansOfService } from './filter.js';
+export { useOtelLiveSpans, useOtelLiveTracer } from './useOtelLiveSpans.js';

package/lib/otel/live/tracer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A tracer that lives in the page: spans started and ended in the browser,
+ * kept as the OTEL views draw them (`OtelSpan`), as they happen — a span is
+ * there from its start (`in_progress`), its events added as they come, its
+ * end and status when it ends.
+ *
+ * What it records is OpenTelemetry: W3C trace and span ids, a span kind, a
+ * status, attributes of primitive values (structured values as JSON text, as
+ * the GenAI semantic conventions carry arguments and results), events, and an
+ * `exception` event for an error. Nothing is sent anywhere: the record is the
+ * page's, read by `useOtelLiveSpans` and drawn by `OtelLiveSpans`.
+ *
+ * A span started without a parent continues the innermost span still open
+ * of the same service — what one agent of the page is doing — so a tool call
+ * nests under its turn without the caller carrying a context; `parent: null`
+ * starts a trace of its own.
+ *
+ * @module otel/live/tracer
+ */
+import type { OtelSpan, OtelSpanLink } from '../types';
+/** What identifies a span: its trace and itself. */
+export interface OtelSpanContext {
+    trace_id: string;
+    span_id: string;
+}
+/** An attribute's value, as OpenTelemetry allows it. */
+export type OtelAttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+/** Attributes; an `undefined` value is left out. */
+export type OtelAttributes = Record<string, OtelAttributeValue | undefined>;
+/** A span's kind, as the OTEL views name it. */
+export type OtelSpanKindName = 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+export interface OtelStartSpanOptions {
+    /** The service that does it: the tracer's own unless said. */
+    serviceName?: string;
+    kind?: OtelSpanKindName;
+    attributes?: OtelAttributes;
+    /**
+     * The span it is part of. Left out: the innermost span still open of the
+     * same service; `null`: a trace of its own.
+     */
+    parent?: OtelSpanContext | null;
+    /** When it started, in ms since the epoch: now unless said. */
+    startTime?: number;
+    /** The instrumentation scope: the tracer's own unless said. */
+    scopeName?: string;
+    links?: OtelSpanLink[];
+}
+/** A span being recorded. */
+export interface OtelLiveSpan {
+    readonly context: OtelSpanContext;
+    /** Whether it has ended. */
+    readonly ended: boolean;
+    setAttribute(key: string, value: OtelAttributeValue | undefined): void;
+    setAttributes(attributes: OtelAttributes): void;
+    addEvent(name: string, attributes?: OtelAttributes, time?: number): void;
+    setStatus(code: 'OK' | 'ERROR', message?: string): void;
+    /** An `exception` event, and the status `ERROR`. */
+    recordException(error: unknown, time?: number): void;
+    updateName(name: string): void;
+    /** End it; a second end is ignored. */
+    end(time?: number): void;
+}
+/** The record, saved. */
+export interface OtelLiveExport {
+    exportedAt: string;
+    spans: OtelSpan[];
+}
+export interface OtelLiveTracer {
+    /** The service a span is done by unless it says. */
+    readonly serviceName: string;
+    startSpan(name: string, options?: OtelStartSpanOptions): OtelLiveSpan;
+    /** The innermost span still open of a service (the tracer's own unless said). */
+    activeSpan(serviceName?: string): OtelSpanContext | undefined;
+    /** The spans, oldest first: a new array each time one changes. */
+    spans(): readonly OtelSpan[];
+    subscribe(listener: () => void): () => void;
+    /** Forget every span; those still open are recorded no more. */
+    clear(): void;
+    exportSpans(): OtelLiveExport;
+}
+export interface OtelLiveTracerOptions {
+    serviceName?: string;
+    scopeName?: string;
+    /** The clock: `Date.now` unless a test sets it. */
+    now?: () => number;
+    /** The most spans kept: the oldest ended ones go first. Default 2000. */
+    limit?: number;
+    /** Random bytes as hex, for ids: `crypto.getRandomValues` unless a test sets it. */
+    randomHex?: (bytes: number) => string;
+}
+/** A W3C `traceparent` header for a span: `00-<trace>-<span>-01`. */
+export declare function traceparentOf(context: OtelSpanContext): string;
+/** Make a tracer for the page. */
+export declare function createOtelLiveTracer(options?: OtelLiveTracerOptions): OtelLiveTracer;

package/lib/otel/live/tracer.js

@@ -0,0 +1,223 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Random bytes as lowercase hex. */
+function cryptoHex(bytes) {
+    const values = new Uint8Array(bytes);
+    if (globalThis.crypto?.getRandomValues) {
+        globalThis.crypto.getRandomValues(values);
+    }
+    else {
+        for (let index = 0; index < bytes; index += 1) {
+            values[index] = Math.floor(Math.random() * 256);
+        }
+    }
+    return Array.from(values, value => value.toString(16).padStart(2, '0')).join('');
+}
+/** A W3C `traceparent` header for a span: `00-<trace>-<span>-01`. */
+export function traceparentOf(context) {
+    return `00-${context.trace_id}-${context.span_id}-01`;
+}
+/** Attributes without their `undefined` values. */
+function defined(attributes) {
+    const kept = {};
+    for (const [key, value] of Object.entries(attributes ?? {})) {
+        if (value !== undefined) {
+            kept[key] = value;
+        }
+    }
+    return kept;
+}
+/** Make a tracer for the page. */
+export function createOtelLiveTracer(options = {}) {
+    const serviceName = options.serviceName ?? 'browser';
+    const scopeName = options.scopeName ?? '@datalayer/core/otel/live';
+    const now = options.now ?? Date.now;
+    const limit = options.limit ?? 2000;
+    const randomHex = options.randomHex ?? cryptoHex;
+    const iso = (ms) => new Date(ms).toISOString();
+    let list = [];
+    /** The spans still open, by service, innermost last. */
+    const open = new Map();
+    const listeners = new Set();
+    let scheduled = false;
+    /** Bumped by `clear`: a span started before it is recorded no more. */
+    let generation = 0;
+    const notify = () => {
+        if (scheduled) {
+            return;
+        }
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            listeners.forEach(listener => listener());
+        });
+    };
+    const trim = () => {
+        let excess = list.length - limit;
+        if (excess <= 0) {
+            return;
+        }
+        list = list.filter(span => {
+            if (excess > 0 && !span.in_progress) {
+                excess -= 1;
+                return false;
+            }
+            return true;
+        });
+    };
+    const closeOpen = (service, spanId) => {
+        const stack = open.get(service);
+        if (!stack) {
+            return;
+        }
+        const kept = stack.filter(id => id !== spanId);
+        if (kept.length) {
+            open.set(service, kept);
+        }
+        else {
+            open.delete(service);
+        }
+    };
+    const tracer = {
+        serviceName,
+        startSpan(name, start = {}) {
+            const service = start.serviceName ?? serviceName;
+            const parent = start.parent === undefined
+                ? tracer.activeSpan(service)
+                : (start.parent ?? undefined);
+            const context = {
+                trace_id: parent?.trace_id ?? randomHex(16),
+                span_id: randomHex(8),
+            };
+            const startedAt = start.startTime ?? now();
+            const born = generation;
+            let current = {
+                trace_id: context.trace_id,
+                span_id: context.span_id,
+                ...(parent ? { parent_span_id: parent.span_id } : {}),
+                span_name: name,
+                service_name: service,
+                kind: start.kind ?? 'INTERNAL',
+                start_time: iso(startedAt),
+                end_time: iso(startedAt),
+                duration_ms: 0,
+                status_code: 'UNSET',
+                otel_scope_name: start.scopeName ?? scopeName,
+                attributes: defined(start.attributes),
+                events: [],
+                ...(start.links?.length ? { links: start.links } : {}),
+                in_progress: true,
+            };
+            list = [...list, current];
+            trim();
+            open.set(service, [...(open.get(service) ?? []), context.span_id]);
+            notify();
+            let ended = false;
+            const change = (next) => {
+                if (born !== generation) {
+                    return;
+                }
+                const updated = { ...current, ...next };
+                list = list.map(span => (span === current ? updated : span));
+                current = updated;
+                notify();
+            };
+            const span = {
+                context,
+                get ended() {
+                    return ended;
+                },
+                setAttribute(key, value) {
+                    span.setAttributes({ [key]: value });
+                },
+                setAttributes(attributes) {
+                    if (ended) {
+                        return;
+                    }
+                    change({
+                        attributes: { ...current.attributes, ...defined(attributes) },
+                    });
+                },
+                addEvent(eventName, attributes, time) {
+                    if (ended) {
+                        return;
+                    }
+                    const event = {
+                        name: eventName,
+                        timestamp: iso(time ?? now()),
+                        attributes: defined(attributes),
+                    };
+                    change({ events: [...(current.events ?? []), event] });
+                },
+                setStatus(code, message) {
+                    if (ended) {
+                        return;
+                    }
+                    change({
+                        status_code: code,
+                        ...(message ? { status_message: message } : {}),
+                    });
+                },
+                recordException(error, time) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    span.addEvent('exception', {
+                        'exception.type': error instanceof Error ? error.name : typeof error,
+                        'exception.message': message,
+                        'exception.stacktrace': error instanceof Error ? error.stack : undefined,
+                    }, time);
+                    span.setStatus('ERROR', message);
+                },
+                updateName(next) {
+                    if (!ended) {
+                        change({ span_name: next });
+                    }
+                },
+                end(time) {
+                    if (ended) {
+                        return;
+                    }
+                    ended = true;
+                    closeOpen(service, context.span_id);
+                    const endedAt = Math.max(time ?? now(), startedAt);
+                    change({
+                        end_time: iso(endedAt),
+                        duration_ms: endedAt - startedAt,
+                        in_progress: false,
+                    });
+                },
+            };
+            return span;
+        },
+        activeSpan(service = serviceName) {
+            const stack = open.get(service);
+            const spanId = stack?.[stack.length - 1];
+            const span = spanId
+                ? list.find(candidate => candidate.span_id === spanId)
+                : undefined;
+            return span
+                ? { trace_id: span.trace_id, span_id: span.span_id }
+                : undefined;
+        },
+        spans() {
+            return list;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        clear() {
+            generation += 1;
+            list = [];
+            open.clear();
+            notify();
+        },
+        exportSpans() {
+            return { exportedAt: iso(now()), spans: [...list] };
+        },
+    };
+    return tracer;
+}

package/lib/otel/live/useOtelLiveSpans.d.ts

@@ -0,0 +1,6 @@
+import type { OtelSpan } from '../types';
+import { type OtelLiveTracer } from './tracer';
+/** A tracer's spans, kept current; none without a tracer. */
+export declare function useOtelLiveSpans(tracer: OtelLiveTracer | null | undefined): readonly OtelSpan[];
+/** A tracer made once for a component (or the one given). */
+export declare function useOtelLiveTracer(given?: OtelLiveTracer | null, serviceName?: string): OtelLiveTracer;

package/lib/otel/live/useOtelLiveSpans.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A live tracer's spans, kept current in a component.
+ *
+ * @module otel/live/useOtelLiveSpans
+ */
+import { useState, useSyncExternalStore } from 'react';
+import { createOtelLiveTracer } from './tracer.js';
+const NO_SPANS = [];
+const NO_SUBSCRIPTION = () => () => undefined;
+/** A tracer's spans, kept current; none without a tracer. */
+export function useOtelLiveSpans(tracer) {
+    return useSyncExternalStore(tracer ? tracer.subscribe : NO_SUBSCRIPTION, () => (tracer ? tracer.spans() : NO_SPANS), () => (tracer ? tracer.spans() : NO_SPANS));
+}
+/** A tracer made once for a component (or the one given). */
+export function useOtelLiveTracer(given, serviceName) {
+    const [own] = useState(() => given ?? createOtelLiveTracer({ serviceName }));
+    return given ?? own;
+}

package/lib/otel/types.d.ts

@@ -3,6 +3,7 @@
  *
  * @module otel/types
  */
+import type { ReactNode } from 'react';
 /** A single span in a trace. */
 export interface OtelSpan {
     trace_id: string;
@@ -20,6 +21,12 @@ export interface OtelSpan {
     attributes?: Record<string, unknown>;
     events?: OtelSpanEvent[];
     links?: OtelSpanLink[];
+    /**
+     * The span has started and not ended yet: a live, in-page span
+     * (`createOtelLiveTracer`). Its `end_time` is its `start_time` and its
+     * `duration_ms` 0 until it ends.
+     */
+    in_progress?: boolean;
     /** Nested children (computed client-side from parent_span_id). */
     children?: OtelSpan[];
     /** Depth in a span tree (computed client-side). */
@@ -96,6 +103,16 @@ export interface OtelTracesListProps {
     loading?: boolean;
     selectedSpanId?: string | null;
     onSelectSpan?: (span: OtelSpan) => void;
+    /** What is said while there is no span. */
+    emptyText?: string;
+    /** Narrower columns, for a panel beside other content. */
+    compact?: boolean;
+    /** Every span with children starts unfolded: a live record, read as it grows. */
+    defaultExpanded?: boolean;
+    /** A mark drawn before a span's name (an icon, an emoji). */
+    renderSpanMark?: (span: OtelSpan) => ReactNode;
+    /** A line that says what a span carried, drawn after its name. */
+    describeSpan?: (span: OtelSpan) => string | undefined;
 }
 /** Props for the span detail panel. */
 export interface OtelSpanDetailProps {

package/lib/otel/views/OtelLiveSpans.d.ts

@@ -0,0 +1,52 @@
+/**
+ * OtelLiveSpans – the spans of a page's own tracer (`createOtelLiveTracer`),
+ * drawn as they happen: the traces list (each trace a tree, unfolded), and
+ * the selected span's detail (its attributes, events, trace tree, raw data).
+ *
+ * One service's own (`service`): what it did, and the calls made toward it
+ * (`peer.service`). Filters by facets (the service, the span kind, or any
+ * value a span carries); *Pause* holds the rows still while the record goes
+ * on, *Clear* empties it, *Export* saves the spans as JSON.
+ *
+ * @module otel/views/OtelLiveSpans
+ */
+import React from 'react';
+import type { OtelSpan } from '../types';
+import type { OtelLiveTracer } from '../live/tracer';
+/** A filter menu: the values a span has for it, each to keep or not. */
+export interface OtelSpanFacet {
+    label: string;
+    /** The span's value for it; `undefined` when it has none. */
+    value: (span: OtelSpan) => string | undefined;
+    /** A value, in words. */
+    name?: (value: string) => string;
+}
+/** The facets unless said: the service and the span kind. */
+export declare const DEFAULT_SPAN_FACETS: readonly OtelSpanFacet[];
+export interface OtelLiveSpansProps {
+    /** The tracer whose spans are drawn, kept current. */
+    tracer?: OtelLiveTracer | null;
+    /** Or the spans, as given. */
+    spans?: readonly OtelSpan[];
+    /** One service's own: done by it, or toward it. */
+    service?: string;
+    facets?: readonly OtelSpanFacet[];
+    /** Narrower columns, the detail under the list. */
+    compact?: boolean;
+    /** How tall the list grows before it scrolls. */
+    maxHeight?: number | string;
+    /** Where the selected span's detail goes. Default `below`. */
+    detailPlacement?: 'below' | 'side';
+    /** What is said while there is no span. */
+    emptyText?: string;
+    /** The file the spans are exported as, without `.json`. */
+    exportName?: string;
+    /** The toolbar's name. */
+    label?: string;
+    renderSpanMark?: (span: OtelSpan) => React.ReactNode;
+    describeSpan?: (span: OtelSpan) => string | undefined;
+}
+/** The spans each facet keeps: an empty selection keeps every value. */
+export declare function filterSpansByFacets(spans: readonly OtelSpan[], facets: readonly OtelSpanFacet[], selected: readonly ReadonlySet<string>[]): OtelSpan[];
+export declare const OtelLiveSpans: React.FC<OtelLiveSpansProps>;
+export default OtelLiveSpans;

package/lib/otel/views/OtelLiveSpans.js

@@ -0,0 +1,139 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OtelLiveSpans – the spans of a page's own tracer (`createOtelLiveTracer`),
+ * drawn as they happen: the traces list (each trace a tree, unfolded), and
+ * the selected span's detail (its attributes, events, trace tree, raw data).
+ *
+ * One service's own (`service`): what it did, and the calls made toward it
+ * (`peer.service`). Filters by facets (the service, the span kind, or any
+ * value a span carries); *Pause* holds the rows still while the record goes
+ * on, *Clear* empties it, *Export* saves the spans as JSON.
+ *
+ * @module otel/views/OtelLiveSpans
+ */
+import { useMemo, useState } from 'react';
+import { ActionList, ActionMenu, Box, Button, Text } from '@primer/react';
+import { DownloadIcon, PauseIcon, PlayIcon, TrashIcon, } from '@primer/octicons-react';
+import { toMs } from '../utils.js';
+import { spansOfService } from '../live/filter.js';
+import { useOtelLiveSpans } from '../live/useOtelLiveSpans.js';
+import { OtelTracesList } from './OtelTracesList.js';
+import { OtelSpanDetail } from './OtelSpanDetail.js';
+/** The facets unless said: the service and the span kind. */
+export const DEFAULT_SPAN_FACETS = [
+    { label: 'Service', value: span => span.service_name },
+    { label: 'Kind', value: span => span.kind },
+];
+/** The spans each facet keeps: an empty selection keeps every value. */
+export function filterSpansByFacets(spans, facets, selected) {
+    return spans.filter(span => facets.every((facet, index) => {
+        const values = selected[index];
+        if (!values?.size)
+            return true;
+        const value = facet.value(span);
+        return value !== undefined && values.has(value);
+    }));
+}
+function toggle(set, value) {
+    const next = new Set(set);
+    if (next.has(value)) {
+        next.delete(value);
+    }
+    else {
+        next.add(value);
+    }
+    return next;
+}
+function FacetMenu({ facet, options, selected, onChange, }) {
+    const name = facet.name ?? ((value) => value);
+    return (_jsxs(ActionMenu, { children: [_jsxs(ActionMenu.Button, { size: "small", "data-otel-facet": facet.label.toLowerCase(), children: [facet.label, selected.size ? ` · ${selected.size}` : ''] }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsxs(ActionList, { selectionVariant: "multiple", "aria-label": facet.label, children: [_jsx(ActionList.Item, { selected: !selected.size, onSelect: () => onChange(new Set()), children: "All" }), _jsx(ActionList.Divider, {}), options.map(option => (_jsx(ActionList.Item, { selected: selected.has(option), onSelect: () => onChange(toggle(selected, option)), children: name(option) }, option)))] }) })] }));
+}
+/** Save the spans as a JSON file. */
+function download(name, record) {
+    const blob = new Blob([JSON.stringify(record, null, 2)], {
+        type: 'application/json',
+    });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `${name}.json`;
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+export const OtelLiveSpans = ({ tracer, spans: given, service, facets = DEFAULT_SPAN_FACETS, compact = false, maxHeight = 420, detailPlacement = 'below', emptyText = 'Nothing recorded yet.', exportName = 'otel-spans', label = 'Spans', renderSpanMark, describeSpan, }) => {
+    const live = useOtelLiveSpans(given ? null : tracer);
+    const everything = given ?? live;
+    const [clearedAt, setClearedAt] = useState(0);
+    const [held, setHeld] = useState(null);
+    const [selected, setSelected] = useState(() => facets.map(() => new Set()));
+    const [selectedSpanId, setSelectedSpanId] = useState(null);
+    const recorded = useMemo(() => {
+        const own = spansOfService(everything, service);
+        return clearedAt
+            ? own.filter(span => toMs(span.start_time) >= clearedAt)
+            : own;
+    }, [everything, service, clearedAt]);
+    const shown = held ?? recorded;
+    const waiting = held ? recorded.length - held.length : 0;
+    const options = useMemo(() => facets.map(facet => [
+        ...new Set(recorded
+            .map(span => facet.value(span))
+            .filter((value) => value !== undefined)),
+    ].sort()), [facets, recorded]);
+    const rows = useMemo(() => filterSpansByFacets(shown, facets, selected), [shown, facets, selected]);
+    // The selected span as it is now: a live span changes as it goes.
+    const selectedSpan = useMemo(() => selectedSpanId
+        ? (everything.find(span => span.span_id === selectedSpanId) ?? null)
+        : null, [everything, selectedSpanId]);
+    const traceSpans = useMemo(() => selectedSpan
+        ? everything.filter(span => span.trace_id === selectedSpan.trace_id)
+        : [], [everything, selectedSpan]);
+    const side = detailPlacement === 'side' && !compact;
+    return (_jsxs(Box, { "data-otel-live-spans": "", sx: {
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            minWidth: 0,
+        }, children: [_jsxs(Box, { role: "toolbar", "aria-label": label, sx: {
+                    display: 'flex',
+                    flexWrap: 'wrap',
+                    gap: 2,
+                    alignItems: 'center',
+                    p: 2,
+                    borderBottom: '1px solid',
+                    borderColor: 'border.default',
+                }, children: [facets.map((facet, index) => (_jsx(FacetMenu, { facet: facet, options: options[index] ?? [], selected: selected[index] ?? new Set(), onChange: next => setSelected(prev => facets.map((_, at) => at === index ? next : (prev[at] ?? new Set()))) }, facet.label))), _jsx(Box, { sx: { flex: 1 } }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, "data-otel-span-count": "", children: [rows.length === shown.length
+                                ? `${rows.length} ${rows.length === 1 ? 'span' : 'spans'}`
+                                : `${rows.length} of ${shown.length}`, waiting > 0 ? ` · ${waiting} new` : ''] }), _jsx(Button, { size: "small", leadingVisual: held ? PlayIcon : PauseIcon, "aria-pressed": held !== null, onClick: () => setHeld(held ? null : recorded), "data-otel-pause": "", children: held ? 'Resume' : 'Pause' }), _jsx(Button, { size: "small", leadingVisual: TrashIcon, onClick: () => {
+                            setHeld(null);
+                            setSelectedSpanId(null);
+                            // One service's view of a shared record clears only itself.
+                            if (tracer && !given && !service) {
+                                tracer.clear();
+                            }
+                            else {
+                                setClearedAt(Date.now());
+                            }
+                        }, "data-otel-clear": "", children: "Clear" }), _jsx(Button, { size: "small", leadingVisual: DownloadIcon, disabled: !recorded.length, onClick: () => download(exportName, {
+                            exportedAt: new Date().toISOString(),
+                            spans: [...recorded],
+                        }), "data-otel-export": "", children: "Export" })] }), _jsxs(Box, { sx: {
+                    display: side ? 'grid' : 'block',
+                    gridTemplateColumns: side
+                        ? 'minmax(0, 3fr) minmax(0, 2fr)'
+                        : undefined,
+                }, children: [_jsx(Box, { sx: { maxHeight, overflowY: 'auto', minWidth: 0 }, children: _jsx(OtelTracesList, { spans: rows, selectedSpanId: selectedSpanId, onSelectSpan: span => setSelectedSpanId(span.span_id), emptyText: emptyText, compact: compact, defaultExpanded: true, renderSpanMark: renderSpanMark, describeSpan: describeSpan }) }), selectedSpan && (_jsx(Box, { "data-otel-live-detail": "", sx: {
+                            maxHeight,
+                            overflowY: 'auto',
+                            minWidth: 0,
+                            borderTop: side ? 'none' : '1px solid',
+                            borderColor: 'border.default',
+                        }, children: _jsx(OtelSpanDetail, { span: selectedSpan, traceSpans: traceSpans, onClose: () => setSelectedSpanId(null) }) }))] })] }));
+};
+export default OtelLiveSpans;

package/lib/otel/views/OtelSpanDetail.d.ts

@@ -8,4 +8,10 @@
  */
 import React from 'react';
 import type { OtelSpanDetailProps } from '../types';
+/**
+ * A value as the detail unfolds it: JSON text of an object or an array (the
+ * GenAI conventions carry a tool call's arguments and result so) is the value
+ * it says; anything else is itself.
+ */
+export declare function unfoldedValue(value: unknown): unknown;
 export declare const OtelSpanDetail: React.FC<OtelSpanDetailProps>;

package/lib/otel/views/OtelSpanDetail.js

@@ -11,7 +11,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *
  * @module otel/OtelSpanDetail
  */
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { Box, Text, IconButton, UnderlineNav, CounterLabel, Label, } from '@primer/react';
 import { XIcon, ChevronDownIcon, ChevronRightIcon, } from '@primer/octicons-react';
 import { formatDuration, buildSpanTree } from '../utils.js';
@@ -61,8 +61,28 @@ const CollapsibleSection = ({ title, data, defaultOpen = false }) => {
                     overflowX: 'auto',
                 }, children: Object.entries(data).map(([key, val]) => (_jsx(AttributeRow, { attrKey: key, value: val, depth: 0 }, key))) }))] }));
 };
+/**
+ * A value as the detail unfolds it: JSON text of an object or an array (the
+ * GenAI conventions carry a tool call's arguments and result so) is the value
+ * it says; anything else is itself.
+ */
+export function unfoldedValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    const text = value.trim();
+    if (!/^[[{]/.test(text))
+        return value;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : value;
+    }
+    catch {
+        return value;
+    }
+}
 /** Recursive attribute row – supports nested objects and arrays. */
-const AttributeRow = ({ attrKey, value, depth }) => {
+const AttributeRow = ({ attrKey, value: given, depth }) => {
+    const value = useMemo(() => unfoldedValue(given), [given]);
     const [open, setOpen] = useState(depth < 1);
     const isObject = typeof value === 'object' && value !== null && !Array.isArray(value);
     const isArray = Array.isArray(value);

package/lib/otel/views/OtelTracesList.js

@@ -19,6 +19,8 @@ import { Blankslate } from '@primer/react/experimental';
 import { TelescopeIcon, ChevronRightIcon, ChevronDownIcon, } from '@primer/octicons-react';
 import { formatDuration, formatTime, buildSpanTree } from '../utils.js';
 const GRID_COLS = '140px 1fr 160px 90px';
+/** Narrower: for a panel beside other content. */
+const COMPACT_GRID_COLS = '96px minmax(0, 1fr) 96px 64px';
 // ── Helpers ─────────────────────────────────────────────────────────
 /** Extract gen_ai token counts from span attributes. */
 function getTokenUsage(span) {
@@ -35,9 +37,13 @@ function getTokenUsage(span) {
         return null;
     return { input, output };
 }
-export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }) => {
-    // Set of expanded span_ids (show their children)
-    const [expanded, setExpanded] = useState(new Set());
+export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, emptyText, compact = false, defaultExpanded = false, renderSpanMark, describeSpan, }) => {
+    // The span_ids unfolded (or, when every span starts unfolded, folded).
+    const [toggled, setToggled] = useState(new Set());
+    const expanded = useMemo(() => ({
+        has: (spanId) => defaultExpanded ? !toggled.has(spanId) : toggled.has(spanId),
+    }), [toggled, defaultExpanded]);
+    const gridCols = compact ? COMPACT_GRID_COLS : GRID_COLS;
     // Build the span tree from flat input
     const roots = useMemo(() => buildSpanTree(spans), [spans]);
     // Flatten visible rows based on which nodes are expanded
@@ -58,7 +64,7 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
         return rows;
     }, [roots, expanded]);
     const toggleExpand = useCallback((spanId) => {
-        setExpanded(prev => {
+        setToggled(prev => {
             const next = new Set(prev);
             if (next.has(spanId)) {
                 next.delete(spanId);
@@ -73,11 +79,11 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
         return (_jsx(Box, { sx: { display: 'flex', justifyContent: 'center', p: 5 }, children: _jsx(Spinner, { size: "medium" }) }));
     }
     if (spans.length === 0) {
-        return (_jsxs(Blankslate, { children: [_jsx(Blankslate.Visual, { children: _jsx(TelescopeIcon, { size: 24 }) }), _jsx(Blankslate.Heading, { children: "No traces found" }), _jsx(Blankslate.Description, { children: "Send some telemetry data first." })] }));
+        return (_jsxs(Blankslate, { children: [_jsx(Blankslate.Visual, { children: _jsx(TelescopeIcon, { size: 24 }) }), _jsx(Blankslate.Heading, { children: "No traces found" }), _jsx(Blankslate.Description, { children: emptyText ?? 'Send some telemetry data first.' })] }));
     }
     return (_jsxs(Box, { sx: { width: '100%', flex: 1, minHeight: 0, overflow: 'auto' }, children: [_jsx(Box, { sx: {
                     display: 'grid',
-                    gridTemplateColumns: GRID_COLS,
+                    gridTemplateColumns: gridCols,
                     gap: 2,
                     px: 3,
                     position: 'sticky',
@@ -97,15 +103,16 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
                     }, children: h }, h))) }), visibleRows.map(({ span, depth, hasChildren }, idx) => {
                 const isSelected = selectedSpanId === span.span_id;
                 const isExpanded = expanded.has(span.span_id);
-                const indent = depth * 20;
-                return (_jsxs(Box, { onClick: () => {
+                const indent = depth * (compact ? 12 : 20);
+                const description = describeSpan?.(span);
+                return (_jsxs(Box, { "data-otel-span": span.span_id, "data-otel-span-name": span.span_name, onClick: () => {
                         if (hasChildren) {
                             toggleExpand(span.span_id);
                         }
                         onSelectSpan?.(span);
                     }, sx: {
                         display: 'grid',
-                        gridTemplateColumns: GRID_COLS,
+                        gridTemplateColumns: gridCols,
                         gap: 2,
                         px: 3,
                         py: '5px',
@@ -121,7 +128,7 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
                             bg: isSelected ? 'accent.subtle' : 'canvas.subtle',
                         },
                     }, children: [_jsx(Text, { sx: {
-                                fontSize: 1,
+                                fontSize: compact ? 0 : 1,
                                 fontFamily: 'mono',
                                 color: 'fg.muted',
                                 whiteSpace: 'nowrap',
@@ -148,12 +155,14 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
                                         justifyContent: 'center',
                                         color: 'fg.subtle',
                                         fontSize: 0,
-                                    }, children: "\u2500" })) : null, _jsx(Text, { sx: {
+                                    }, children: "\u2500" })) : null, renderSpanMark?.(span), _jsx(Text, { sx: {
                                         fontSize: 1,
                                         overflow: 'hidden',
                                         textOverflow: 'ellipsis',
                                         whiteSpace: 'nowrap',
-                                    }, title: span.span_name, children: span.span_name }), span.status_code === 'ERROR' && (_jsx(Label, { variant: "danger", size: "small", children: "ERROR" })), (() => {
+                                        flexShrink: description ? 0 : 1,
+                                        maxWidth: description ? '60%' : undefined,
+                                    }, title: span.span_name, children: span.span_name }), span.in_progress && (_jsx(Label, { variant: "attention", size: "small", children: "running" })), span.status_code === 'ERROR' && (_jsx(Label, { variant: "danger", size: "small", children: "ERROR" })), (() => {
                                     const usage = getTokenUsage(span);
                                     if (!usage)
                                         return null;
@@ -179,7 +188,14 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
                                                     alignItems: 'center',
                                                     gap: '1px',
                                                 }, children: [_jsx(Text, { sx: { fontSize: '9px', color: 'fg.subtle' }, children: "\u2199" }), _jsx(Text, { children: usage.output })] }))] }));
-                                })(), span.otel_scope_name && (_jsx(Label, { size: "small", variant: "secondary", sx: { flexShrink: 0, fontSize: '10px' }, children: span.otel_scope_name }))] }), _jsx(Text, { sx: {
+                                })(), description && (_jsx(Text, { sx: {
+                                        fontSize: 1,
+                                        color: 'fg.muted',
+                                        overflow: 'hidden',
+                                        textOverflow: 'ellipsis',
+                                        whiteSpace: 'nowrap',
+                                        minWidth: 0,
+                                    }, title: description, "data-otel-span-description": "", children: description })), span.otel_scope_name && !compact && (_jsx(Label, { size: "small", variant: "secondary", sx: { flexShrink: 0, fontSize: '10px' }, children: span.otel_scope_name }))] }), _jsx(Text, { sx: {
                                 fontSize: 1,
                                 color: 'fg.muted',
                                 overflow: 'hidden',
@@ -194,6 +210,6 @@ export const OtelTracesList = ({ spans, loading, selectedSpanId, onSelectSpan, }
                                 color: span.duration_ms != null && span.duration_ms > 1000
                                     ? 'danger.fg'
                                     : 'fg.default',
-                            }, children: formatDuration(span.duration_ms) })] }, `${span.trace_id}-${span.span_id}-${idx}`));
+                            }, children: span.in_progress ? '…' : formatDuration(span.duration_ms) })] }, `${span.trace_id}-${span.span_id}-${idx}`));
             })] }));
 };

package/lib/otel/views/index.d.ts

@@ -14,6 +14,9 @@ export { OtelSearchBar } from './OtelSearchBar';
 export { OtelSpanDetail } from './OtelSpanDetail';
 export { OtelSpanTree } from './OtelSpanTree';
 export { OtelTimeline } from './OtelTimeline';
+export { OtelLiveSpans, DEFAULT_SPAN_FACETS, filterSpansByFacets, } from './OtelLiveSpans';
+export type { OtelLiveSpansProps, OtelSpanFacet } from './OtelLiveSpans';
+export { unfoldedValue } from './OtelSpanDetail';
 export { OtelTimelineRangeSlider } from './OtelTimelineRangeSlider';
 export { OtelSqlView } from './OtelSqlView';
 export type { OtelSqlViewProps } from './OtelSqlView';

package/lib/otel/views/index.js

@@ -16,6 +16,8 @@ export { OtelSearchBar } from './OtelSearchBar.js';
 export { OtelSpanDetail } from './OtelSpanDetail.js';
 export { OtelSpanTree } from './OtelSpanTree.js';
 export { OtelTimeline } from './OtelTimeline.js';
+export { OtelLiveSpans, DEFAULT_SPAN_FACETS, filterSpansByFacets, } from './OtelLiveSpans.js';
+export { unfoldedValue } from './OtelSpanDetail.js';
 export { OtelTimelineRangeSlider } from './OtelTimelineRangeSlider.js';
 export { OtelSqlView } from './OtelSqlView.js';
 export { OtelSystemView } from './OtelSystemView.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/core",
-    "version": "1.2.17",
+    "version": "1.2.18",
     "type": "module",
     "workspaces": [
         ".",