@datalayer/core 1.0.2 → 1.0.11

package/lib/otel/client/OtelClient.js

@@ -0,0 +1,232 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OtelClient – Typed HTTP client for the Datalayer OTEL service.
+ *
+ * Reads the OTEL service URL from the Datalayer core configuration by default,
+ * so callers don't need to pass `baseUrl` unless they want to override it.
+ *
+ * @example
+ * ```ts
+ * import { createOtelClient } from '@datalayer/core/otel';
+ *
+ * const client = createOtelClient({ token: myJwt });
+ * const { data: spans } = await client.fetchTraces({ limit: 50 });
+ * ```
+ */
+import { coreStore } from '../../state/substates/CoreState';
+// ── Fetch helper ────────────────────────────────────────────────────────────
+async function otelFetch(url, token, options) {
+    const headers = {
+        Accept: 'application/json',
+        'Cache-Control': 'no-store, no-cache, must-revalidate',
+    };
+    if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+    }
+    if (options?.body) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const resp = await fetch(url, {
+        method: options?.method ?? 'GET',
+        headers,
+        body: options?.body != null ? JSON.stringify(options.body) : undefined,
+    });
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => '');
+        throw new Error(`OTEL API error ${resp.status}: ${text}`);
+    }
+    return resp.json();
+}
+function parseMetricValue(raw) {
+    const candidates = [raw.value, raw.value_double, raw.value_int];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+        if (typeof candidate === 'string') {
+            const parsed = Number(candidate);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+    }
+    return 0;
+}
+function parseMetricTimestamp(raw) {
+    const candidate = raw.timestamp ??
+        raw.Timestamp ??
+        raw.timestamp_unix_nano ??
+        raw.start_time_unix_nano;
+    if (typeof candidate === 'string' && candidate.trim().length > 0) {
+        return candidate;
+    }
+    const numeric = Number(candidate);
+    if (!Number.isFinite(numeric)) {
+        return '';
+    }
+    if (numeric > 1e15) {
+        return new Date(numeric / 1e6).toISOString();
+    }
+    if (numeric > 1e12) {
+        return new Date(numeric / 1e3).toISOString();
+    }
+    return new Date(numeric).toISOString();
+}
+function normalizeMetric(raw) {
+    return {
+        metric_name: String(raw.metric_name ?? raw.MetricName ?? raw.name ?? raw.Name ?? ''),
+        service_name: String(raw.service_name ?? raw.ServiceName ?? ''),
+        value: parseMetricValue(raw),
+        unit: raw.metric_unit != null
+            ? String(raw.metric_unit)
+            : raw.MetricUnit != null
+                ? String(raw.MetricUnit)
+                : raw.unit != null
+                    ? String(raw.unit)
+                    : raw.Unit != null
+                        ? String(raw.Unit)
+                        : undefined,
+        timestamp: parseMetricTimestamp(raw),
+        metric_type: raw.metric_type != null
+            ? String(raw.metric_type)
+            : raw.MetricType != null
+                ? String(raw.MetricType)
+                : undefined,
+        attributes: typeof raw.attributes === 'object' && raw.attributes !== null
+            ? raw.attributes
+            : undefined,
+    };
+}
+// ── OtelClient class ─────────────────────────────────────────────────────────
+/**
+ * Typed HTTP client for all OTEL service endpoints.
+ *
+ * Construct via `createOtelClient()` or `new OtelClient(options)`.
+ */
+export class OtelClient {
+    baseUrl;
+    token;
+    constructor(options = {}) {
+        this.baseUrl =
+            options.baseUrl ?? coreStore.getState().configuration.otelRunUrl;
+        this.token = options.token;
+    }
+    // ── Traces ────────────────────────────────────────────────────────────────
+    /** List recent spans / traces. */
+    async fetchTraces(options = {}) {
+        const params = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.serviceName)
+            params.set('service_name', options.serviceName);
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/traces/?${params}`, this.token);
+        const rows = (Array.isArray(resp) ? resp : resp.data) ?? [];
+        return { data: rows, count: rows.length };
+    }
+    /** Fetch all spans for a single trace by `traceId`. */
+    async fetchTrace(traceId) {
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/traces/${traceId}`, this.token);
+        const rows = (Array.isArray(resp) ? resp : resp.data) ?? [];
+        return { data: rows };
+    }
+    // ── Logs ──────────────────────────────────────────────────────────────────
+    /** List recent log records. */
+    async fetchLogs(options = {}) {
+        const params = new URLSearchParams({ limit: String(options.limit ?? 100) });
+        if (options.serviceName)
+            params.set('service_name', options.serviceName);
+        if (options.severity)
+            params.set('severity', options.severity);
+        if (options.traceId)
+            params.set('trace_id', options.traceId);
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/logs/?${params}`, this.token);
+        const rows = (Array.isArray(resp) ? resp : resp.data) ?? [];
+        return { data: rows, count: rows.length };
+    }
+    // ── Metrics ───────────────────────────────────────────────────────────────
+    /** List recent metric data points. */
+    async fetchMetrics(options = {}) {
+        const params = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.serviceName)
+            params.set('service_name', options.serviceName);
+        if (options.metricName)
+            params.set('metric_name', options.metricName);
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/metrics/?${params}`, this.token);
+        const rows = (Array.isArray(resp) ? resp : resp.data) ?? [];
+        const normalized = Array.isArray(rows)
+            ? rows.map(row => normalizeMetric(row))
+            : [];
+        return { data: normalized, count: normalized.length };
+    }
+    /** Sum all values for one metric name, with optional service filter. */
+    async fetchMetricTotal(metricName, options = {}) {
+        const { serviceName, limit = 500, fallbackWithoutService = true } = options;
+        const filtered = await this.fetchMetrics({
+            metricName,
+            serviceName,
+            limit,
+        });
+        const filteredTotal = filtered.data.reduce((sum, row) => sum + Number(row.value || 0), 0);
+        if (filteredTotal > 0 || !serviceName || !fallbackWithoutService) {
+            return filteredTotal;
+        }
+        const unfiltered = await this.fetchMetrics({ metricName, limit });
+        return unfiltered.data.reduce((sum, row) => sum + Number(row.value || 0), 0);
+    }
+    // ── Services ──────────────────────────────────────────────────────────────
+    /** List known service names observed in traces. */
+    async fetchServices() {
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/traces/services/list`, this.token);
+        if (Array.isArray(resp))
+            return resp;
+        const byServices = resp.services;
+        if (Array.isArray(byServices))
+            return byServices;
+        const byData = resp.data;
+        if (Array.isArray(byData)) {
+            return byData.map((r) => String(r.service_name ?? r.name ?? ''));
+        }
+        return [];
+    }
+    // ── Stats ─────────────────────────────────────────────────────────────────
+    /** Fetch storage / ingestion statistics. */
+    async fetchStats() {
+        return otelFetch(`${this.baseUrl}/api/otel/v1/stats/`, this.token);
+    }
+    // ── SQL query ─────────────────────────────────────────────────────────────
+    /**
+     * Execute an ad-hoc DataFusion SQL query against the OTEL service.
+     *
+     * Available tables: `spans`, `logs`, `metrics`.
+     */
+    async executeQuery(sql) {
+        return otelFetch(`${this.baseUrl}/api/otel/v1/query/`, this.token, { method: 'POST', body: { sql } });
+    }
+    // ── System ────────────────────────────────────────────────────────────────
+    /**
+     * Fetch system statistics (platform_admin only).
+     *
+     * Returns process memory/CPU, disk usage, and per-table row counts.
+     */
+    async fetchSystem() {
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/system/`, this.token);
+        return (resp.data ?? resp);
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a new `OtelClient`.
+ *
+ * The `baseUrl` defaults to `configuration.otelRunUrl` from the Datalayer core
+ * configuration store, so only pass it when you want to override the default.
+ *
+ * @example
+ * ```ts
+ * const client = createOtelClient({ token: jwt });
+ * const services = await client.fetchServices();
+ * ```
+ */
+export function createOtelClient(options = {}) {
+    return new OtelClient(options);
+}

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

@@ -0,0 +1,2 @@
+export { OtelClient, createOtelClient } from './OtelClient';
+export type { OtelClientOptions, FetchTracesOptions, FetchLogsOptions, FetchMetricsOptions, FetchMetricTotalOptions, OtelSystemData, OtelSystemProcess, OtelSystemDisk, OtelSystemTable, } from './OtelClient';

package/lib/otel/client/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export { OtelClient, createOtelClient } from './OtelClient';

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

@@ -0,0 +1,186 @@
+import type { OtelSpan, OtelLog, OtelMetric, OtelQueryRow } from '../types';
+/**
+ * Register a callback invoked whenever an OTEL API call receives a
+ * **401 Unauthorized** response.  Typically used to clear auth state
+ * (i.e. log the user out) when the token has expired.
+ *
+ * Pass `null` to unregister.
+ *
+ * @example
+ * ```ts
+ * import { setOtelOnUnauthorized } from '@datalayer/core/lib/otel';
+ * setOtelOnUnauthorized(() => authStore.getState().clearAuth());
+ * ```
+ */
+export declare function setOtelOnUnauthorized(cb: (() => void) | null): void;
+/** Fetch a list of traces / spans from the OTEL service. */
+export declare function useOtelTraces(options: {
+    token?: string;
+    baseUrl?: string;
+    serviceName?: string;
+    limit?: number;
+    autoRefreshMs?: number;
+}): {
+    traces: OtelSpan[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/** Fetch all spans for a single trace. */
+export declare function useOtelTrace(options: {
+    traceId: string | null;
+    token?: string;
+    baseUrl?: string;
+}): {
+    spans: OtelSpan[];
+    loading: boolean;
+    error: string | null;
+};
+/** Fetch log records from the OTEL service. */
+export declare function useOtelLogs(options: {
+    token?: string;
+    baseUrl?: string;
+    serviceName?: string;
+    severity?: string;
+    traceId?: string;
+    limit?: number;
+    autoRefreshMs?: number;
+}): {
+    logs: OtelLog[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/** Fetch metrics from the OTEL service. */
+export declare function useOtelMetrics(options: {
+    token?: string;
+    baseUrl?: string;
+    serviceName?: string;
+    metricName?: string;
+    limit?: number;
+    autoRefreshMs?: number;
+}): {
+    metrics: OtelMetric[];
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+/** Fetch list of observed service names. */
+export declare function useOtelServices(options: {
+    token?: string;
+    baseUrl?: string;
+}): {
+    services: string[];
+    loading: boolean;
+};
+/** Fetch storage stats from the OTEL service. */
+export declare function useOtelStats(options: {
+    token?: string;
+    baseUrl?: string;
+}): {
+    stats: Record<string, unknown>;
+    loading: boolean;
+};
+export interface OtelSystemProcess {
+    memory_rss_bytes: number;
+    memory_vms_bytes: number;
+    cpu_percent: number;
+    num_threads: number;
+    error?: string;
+}
+export interface OtelSystemDisk {
+    data_dir: string;
+    used_bytes: number;
+    free_bytes: number;
+    total_bytes: number;
+    used_percent: number;
+    error?: string;
+}
+export interface OtelSystemTable {
+    row_count: number;
+    distinct_users: number;
+    disk_bytes: number;
+    error?: string;
+}
+export interface OtelSystemData {
+    process: OtelSystemProcess;
+    disk: OtelSystemDisk;
+    tables: Record<string, OtelSystemTable>;
+    total_distinct_users: number;
+}
+/** Fetch system statistics from /api/otel/v1/system/ (platform_admin). */
+export declare function useOtelSystem(options: {
+    token?: string;
+    baseUrl?: string;
+}): {
+    data: OtelSystemData | null;
+    loading: boolean;
+    error: string | null;
+    refresh: () => void;
+};
+/**
+ * Execute an ad-hoc DataFusion SQL query against the OTEL service.
+ *
+ * Usage:
+ * ```tsx
+ * const { execute, rows, loading, error } = useOtelQuery({ baseUrl, token });
+ * await execute('SELECT trace_id FROM spans LIMIT 10');
+ * ```
+ */
+export declare function useOtelQuery(options: {
+    token?: string;
+    baseUrl?: string;
+}): {
+    rows: OtelQueryRow[];
+    loading: boolean;
+    error: string | null;
+    execute: (sql: string) => Promise<void>;
+    clear: () => void;
+};
+/** WebSocket message shape sent by the OTEL service. */
+export interface OtelWsMessage {
+    signal: 'traces' | 'logs' | 'metrics';
+    data: Record<string, unknown>[];
+    count: number;
+}
+/** Callbacks for WebSocket lifecycle events. */
+export interface OtelWsCallbacks {
+    /** Called when new traces are flushed. */
+    onTraces?: (spans: OtelSpan[]) => void;
+    /** Called when new logs are flushed. */
+    onLogs?: (logs: OtelLog[]) => void;
+    /** Called when new metrics are flushed. */
+    onMetrics?: (metrics: OtelMetric[]) => void;
+    /** Called on any message (raw). */
+    onMessage?: (msg: OtelWsMessage) => void;
+    /** Called when connection opens. */
+    onOpen?: () => void;
+    /** Called when connection closes. */
+    onClose?: (event: CloseEvent) => void;
+    /** Called on error. */
+    onError?: (event: Event) => void;
+}
+/**
+ * Connect to the OTEL service WebSocket for live telemetry streaming.
+ *
+ * The server pushes JSON messages whenever new data is flushed to storage.
+ * Authentication is via the `token` query parameter (JWT or API key).
+ *
+ * @returns `{ connected, error, close }` – reactive connection state.
+ */
+export declare function useOtelWebSocket(options: {
+    /** OTEL service base URL (e.g. `http://localhost:7800`). */
+    baseUrl?: string;
+    /** JWT token or API key for authentication. */
+    token?: string;
+    /** Whether to automatically reconnect on disconnect. Default true. */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms. Default 3000. */
+    reconnectDelayMs?: number;
+    /** Callbacks for signal events. */
+    callbacks?: OtelWsCallbacks;
+}): {
+    connected: boolean;
+    error: string | null;
+    close: () => void;
+};