@datalayer/core 1.0.2 → 1.0.11

package/README.md

@@ -165,7 +165,7 @@ Available at http://localhost:3000/:
 A complete Next.js application demonstrating platform integration:
 
 ```bash
-cd examples/nextjs-notebook
+cd examples/nextjj
 npm install
 npm run dev
 ```

package/lib/api/constants.d.ts

@@ -2,7 +2,9 @@
  * API base paths for different service domains
  */
 export declare const API_BASE_PATHS: {
+    readonly AI_AGENTS: "/api/ai-agents/v1";
     readonly IAM: "/api/iam/v1";
+    readonly OTEL: "/api/otel/v1";
     readonly RUNTIMES: "/api/runtimes/v1";
     readonly SPACER: "/api/spacer/v1";
 };
@@ -10,8 +12,12 @@ export declare const API_BASE_PATHS: {
  * Default service URLs for the Datalayer platform
  */
 export declare const DEFAULT_SERVICE_URLS: {
+    /** Default URL for AI Agents (durable agent management) service */
+    readonly AI_AGENTS: "https://prod1.datalayer.run";
     /** Default URL for IAM (Identity and Access Management) service */
     readonly IAM: "https://prod1.datalayer.run";
+    /** Default URL for OTEL (OpenTelemetry observability) service */
+    readonly OTEL: "https://prod1.datalayer.run";
     /** Default URL for Runtimes service */
     readonly RUNTIMES: "https://prod1.datalayer.run";
     /** Default URL for Spacer (workspaces and collaboration) service */

package/lib/api/constants.js

@@ -6,7 +6,9 @@
  * API base paths for different service domains
  */
 export const API_BASE_PATHS = {
+    AI_AGENTS: '/api/ai-agents/v1',
     IAM: '/api/iam/v1',
+    OTEL: '/api/otel/v1',
     RUNTIMES: '/api/runtimes/v1',
     SPACER: '/api/spacer/v1',
 };
@@ -14,8 +16,12 @@ export const API_BASE_PATHS = {
  * Default service URLs for the Datalayer platform
  */
 export const DEFAULT_SERVICE_URLS = {
+    /** Default URL for AI Agents (durable agent management) service */
+    AI_AGENTS: 'https://prod1.datalayer.run',
     /** Default URL for IAM (Identity and Access Management) service */
     IAM: 'https://prod1.datalayer.run',
+    /** Default URL for OTEL (OpenTelemetry observability) service */
+    OTEL: 'https://prod1.datalayer.run',
     /** Default URL for Runtimes service */
     RUNTIMES: 'https://prod1.datalayer.run',
     /** Default URL for Spacer (workspaces and collaboration) service */

package/lib/api/index.d.ts

@@ -9,6 +9,7 @@
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi';
 export type { IRequestDatalayerAPIOptions } from './DatalayerApi';
 export * as iam from './iam';
+export * as otel from './otel';
 export * as runtimes from './runtimes';
 export * as spacer from './spacer';
 /**

package/lib/api/index.js

@@ -14,6 +14,7 @@
 export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi';
 // Domain-organized API exports
 export * as iam from './iam';
+export * as otel from './otel';
 export * as runtimes from './runtimes';
 export * as spacer from './spacer';
 /**

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

@@ -0,0 +1,12 @@
+/**
+ * OTEL API exports.
+ *
+ * Provides organized access to OpenTelemetry observability functionality.
+ *
+ * @module api/otel
+ */
+export * as traces from './traces';
+export * as metrics from './metrics';
+export * as logs from './logs';
+export * as services from './services';
+export * as query from './query';

package/lib/api/otel/index.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * OTEL API exports.
+ *
+ * Provides organized access to OpenTelemetry observability functionality.
+ *
+ * @module api/otel
+ */
+export * as traces from './traces';
+export * as metrics from './metrics';
+export * as logs from './logs';
+export * as services from './services';
+export * as query from './query';

package/lib/api/otel/logs.d.ts

@@ -0,0 +1,19 @@
+import type { ListLogsResponse } from './types';
+/**
+ * Query log records.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.severity - Filter by severity (INFO, WARN, ERROR, etc.)
+ * @param options.traceId - Filter by trace ID
+ * @param options.limit - Maximum number of log records
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of log records
+ */
+export declare const queryLogs: (token: string, options?: {
+    serviceName?: string;
+    severity?: string;
+    traceId?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<ListLogsResponse>;

package/lib/api/otel/logs.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Logs API functions for the Datalayer OTEL service.
+ *
+ * @module api/otel/logs
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+import { validateToken } from '../utils/validation';
+/**
+ * Query log records.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.severity - Filter by severity (INFO, WARN, ERROR, etc.)
+ * @param options.traceId - Filter by trace ID
+ * @param options.limit - Maximum number of log records
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of log records
+ */
+export const queryLogs = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    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);
+    if (options.limit)
+        params.set('limit', String(options.limit));
+    const queryString = params.toString();
+    const url = `${baseUrl}${API_BASE_PATHS.OTEL}/logs${queryString ? `?${queryString}` : ''}`;
+    return requestDatalayerAPI({
+        url,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/otel/metrics.d.ts

@@ -0,0 +1,31 @@
+import type { ListMetricsResponse } from './types';
+/**
+ * List available metric names.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of results
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of metrics
+ */
+export declare const listMetrics: (token: string, options?: {
+    serviceName?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<ListMetricsResponse>;
+/**
+ * Query metric data points with filters.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.metricName - Filter by metric name
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of data points
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to metric data points
+ */
+export declare const queryMetrics: (token: string, options?: {
+    metricName?: string;
+    serviceName?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<ListMetricsResponse>;

package/lib/api/otel/metrics.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Metrics API functions for the Datalayer OTEL service.
+ *
+ * @module api/otel/metrics
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+import { validateToken } from '../utils/validation';
+/**
+ * List available metric names.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of results
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of metrics
+ */
+export const listMetrics = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (options.limit)
+        params.set('limit', String(options.limit));
+    if (options.serviceName)
+        params.set('service_name', options.serviceName);
+    const queryString = params.toString();
+    const url = `${baseUrl}${API_BASE_PATHS.OTEL}/metrics${queryString ? `?${queryString}` : ''}`;
+    return requestDatalayerAPI({
+        url,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Query metric data points with filters.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.metricName - Filter by metric name
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of data points
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to metric data points
+ */
+export const queryMetrics = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (options.metricName)
+        params.set('name', options.metricName);
+    if (options.serviceName)
+        params.set('service_name', options.serviceName);
+    if (options.limit)
+        params.set('limit', String(options.limit));
+    const queryString = params.toString();
+    const url = `${baseUrl}${API_BASE_PATHS.OTEL}/metrics/query${queryString ? `?${queryString}` : ''}`;
+    return requestDatalayerAPI({
+        url,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/otel/query.d.ts

@@ -0,0 +1,16 @@
+import type { QueryResponse } from './types';
+/**
+ * Execute an ad-hoc SQL query via the SQL Engine engine.
+ *
+ * @param token - Authentication token
+ * @param sql - SQL query string
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to query results
+ *
+ * @example
+ * ```ts
+ * const result = await executeSql(token, 'SELECT * FROM spans LIMIT 10');
+ * console.log(result.data);
+ * ```
+ */
+export declare const executeSql: (token: string, sql: string, baseUrl?: string) => Promise<QueryResponse>;

package/lib/api/otel/query.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * SQL query API functions for the Datalayer OTEL service.
+ *
+ * Executes ad-hoc SQL queries via the SQL Engine engine.
+ *
+ * @module api/otel/query
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+import { validateToken } from '../utils/validation';
+/**
+ * Execute an ad-hoc SQL query via the SQL Engine engine.
+ *
+ * @param token - Authentication token
+ * @param sql - SQL query string
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to query results
+ *
+ * @example
+ * ```ts
+ * const result = await executeSql(token, 'SELECT * FROM spans LIMIT 10');
+ * console.log(result.data);
+ * ```
+ */
+export const executeSql = async (token, sql, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/query`,
+        method: 'POST',
+        body: { sql },
+        token,
+    });
+};

package/lib/api/otel/services.d.ts

@@ -0,0 +1,39 @@
+import type { ListServicesResponse, OtelStats, PingResponse, VersionResponse, FlushResponse } from './types';
+/**
+ * List all observed service names.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of service names
+ */
+export declare const listServices: (token: string, baseUrl?: string) => Promise<ListServicesResponse>;
+/**
+ * Check service health (no auth required).
+ *
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to ping response
+ */
+export declare const ping: (baseUrl?: string) => Promise<PingResponse>;
+/**
+ * Get service version.
+ *
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to version info
+ */
+export declare const version: (baseUrl?: string) => Promise<VersionResponse>;
+/**
+ * Get storage statistics.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to storage statistics
+ */
+export declare const getStats: (token: string, baseUrl?: string) => Promise<OtelStats>;
+/**
+ * Force-flush all buffered telemetry data.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to flush result
+ */
+export declare const flush: (token: string, baseUrl?: string) => Promise<FlushResponse>;

package/lib/api/otel/services.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Services API functions for the Datalayer OTEL service.
+ *
+ * @module api/otel/services
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+import { validateToken } from '../utils/validation';
+/**
+ * List all observed service names.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of service names
+ */
+export const listServices = async (token, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/traces/services/list`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Check service health (no auth required).
+ *
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to ping response
+ */
+export const ping = async (baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/ping`,
+        method: 'GET',
+    });
+};
+/**
+ * Get service version.
+ *
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to version info
+ */
+export const version = async (baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/version`,
+        method: 'GET',
+    });
+};
+/**
+ * Get storage statistics.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to storage statistics
+ */
+export const getStats = async (token, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/stats`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Force-flush all buffered telemetry data.
+ *
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to flush result
+ */
+export const flush = async (token, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/flush`,
+        method: 'POST',
+        token,
+    });
+};

package/lib/api/otel/traces.d.ts

@@ -0,0 +1,24 @@
+import type { ListTracesResponse, GetTraceResponse } from './types';
+/**
+ * List recent traces.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of traces (default: 20)
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of trace spans
+ */
+export declare const listTraces: (token: string, options?: {
+    serviceName?: string;
+    limit?: number;
+}, baseUrl?: string) => Promise<ListTracesResponse>;
+/**
+ * Get all spans for a specific trace.
+ *
+ * @param token - Authentication token
+ * @param traceId - The trace ID to retrieve
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to the trace's spans
+ */
+export declare const getTrace: (token: string, traceId: string, baseUrl?: string) => Promise<GetTraceResponse>;

package/lib/api/otel/traces.js

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Traces API functions for the Datalayer OTEL service.
+ *
+ * @module api/otel/traces
+ */
+import { requestDatalayerAPI } from '../DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants';
+import { validateToken } from '../utils/validation';
+/**
+ * List recent traces.
+ *
+ * @param token - Authentication token
+ * @param options - Query options
+ * @param options.serviceName - Filter by service name
+ * @param options.limit - Maximum number of traces (default: 20)
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to a list of trace spans
+ */
+export const listTraces = async (token, options = {}, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (options.limit)
+        params.set('limit', String(options.limit));
+    if (options.serviceName)
+        params.set('service_name', options.serviceName);
+    const queryString = params.toString();
+    const url = `${baseUrl}${API_BASE_PATHS.OTEL}/traces${queryString ? `?${queryString}` : ''}`;
+    return requestDatalayerAPI({
+        url,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get all spans for a specific trace.
+ *
+ * @param token - Authentication token
+ * @param traceId - The trace ID to retrieve
+ * @param baseUrl - Base URL for the OTEL service
+ * @returns Promise resolving to the trace's spans
+ */
+export const getTrace = async (token, traceId, baseUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.OTEL}/traces/${traceId}`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/otel/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * TypeScript DTOs for the OTEL API.
+ *
+ * @module api/otel/types
+ */
+/** A single span in a trace. */
+export interface OtelSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    span_name: string;
+    service_name: string;
+    kind: string;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    status_code?: string;
+    status_message?: string;
+    otel_scope_name?: string;
+    attributes?: Record<string, unknown>;
+    events?: OtelSpanEvent[];
+    links?: OtelSpanLink[];
+}
+/** An event attached to a span. */
+export interface OtelSpanEvent {
+    name: string;
+    timestamp: string;
+    attributes?: Record<string, unknown>;
+}
+/** A link between spans. */
+export interface OtelSpanLink {
+    trace_id: string;
+    span_id: string;
+    attributes?: Record<string, unknown>;
+}
+/** Response from list traces endpoint. */
+export interface ListTracesResponse {
+    data: OtelSpan[];
+    total?: number;
+}
+/** Response from get single trace endpoint. */
+export interface GetTraceResponse {
+    data: OtelSpan[];
+    trace_id: string;
+}
+/** A metric data point. */
+export interface OtelMetric {
+    metric_name: string;
+    service_name: string;
+    value: number;
+    unit?: string;
+    timestamp: string;
+    attributes?: Record<string, unknown>;
+    metric_type?: string;
+}
+/** Response from list/query metrics endpoint. */
+export interface ListMetricsResponse {
+    data: OtelMetric[];
+    total?: number;
+}
+/** A log record. */
+export interface OtelLog {
+    timestamp: string;
+    severity_text: string;
+    severity_number?: number;
+    body: string;
+    service_name: string;
+    trace_id?: string;
+    span_id?: string;
+    attributes?: Record<string, unknown>;
+}
+/** Response from query logs endpoint. */
+export interface ListLogsResponse {
+    data: OtelLog[];
+    total?: number;
+}
+/** Storage statistics. */
+export interface OtelStats {
+    spans_count?: number;
+    metrics_count?: number;
+    logs_count?: number;
+    spans_files?: number;
+    metrics_files?: number;
+    logs_files?: number;
+    data_dir?: string;
+    [key: string]: unknown;
+}
+/** Response from SQL query endpoint. */
+export interface QueryResponse {
+    data: Record<string, unknown>[];
+    columns?: string[];
+    row_count?: number;
+}
+/** Ping/health response. */
+export interface PingResponse {
+    status: string;
+    [key: string]: unknown;
+}
+/** Version response. */
+export interface VersionResponse {
+    version: string;
+    [key: string]: unknown;
+}
+/** Flush response. */
+export interface FlushResponse {
+    flushed: boolean;
+    [key: string]: unknown;
+}
+/** List services response. */
+export interface ListServicesResponse {
+    services: string[];
+}

package/lib/api/otel/types.js

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