@artinet/sdk
Version:
A TypeScript SDK for building collaborative AI agents.
102 lines (101 loc) • 3 kB
TypeScript
/**
* Copyright 2025 The Artinet Project
* SPDX-License-Identifier: Apache-2.0
*
* @fileoverview OpenTelemetry integration for Artinet SDK.
*
* Lightweight utilities for integrating user-configured OpenTelemetry
* with the SDK's tracing and logging interfaces.
*
* @module @artinet/sdk/otel
*
* @example
* ```typescript
* import { trace } from '@opentelemetry/api';
* import { configure } from '@artinet/sdk';
* import { configureOtel, withSpan } from '@artinet/sdk/otel';
*
* // User initializes their own OpenTelemetry setup
* // ... NodeSDK setup, exporters, etc. ...
*
* // Get tracer and configure SDK
* const tracer = trace.getTracer('my-agent');
* configure({
* tracer,
* logger: configureOtel({ level: 'debug' })
* });
* ```
*/
import { trace, context, SpanKind, SpanStatusCode, Tracer, Span, Context } from "@opentelemetry/api";
import type { ILogger } from "../config/observability.js";
/**
* Options for configuring the OTel-aware logger.
*/
export interface OtelLoggerOptions {
/**
* Base logger to wrap (logs go here AND to spans).
* If not provided, logs only go to spans.
*/
baseLogger?: ILogger;
/**
* Log level.
* @default 'info'
*/
level?: "trace" | "verbose" | "debug" | "info" | "warn" | "error" | "silent";
}
/**
* Create a logger that adds log events to the current span.
*
* This logger optionally wraps a base logger and adds all log messages
* as span events in the current trace context.
*
* @param options - Logger options
* @returns ILogger implementation
*
* @example
* ```typescript
* import { configure } from '@artinet/sdk';
* import { configureOtel } from '@artinet/sdk/otel';
* import { configurePino } from '@artinet/sdk/pino';
* import pino from 'pino';
*
* // Logs go to both Pino AND span events
* configure({
* logger: configureOtel({
* baseLogger: configurePino(pino()),
* level: 'debug'
* })
* });
* ```
*/
export declare function configureOtel(options?: OtelLoggerOptions): ILogger;
/**
* Execute a function within a new span.
*
* @param tracer - User's tracer instance
* @param name - Span name
* @param fn - Function to execute
* @param options - Optional span options
* @returns Result of the function
*
* @example
* ```typescript
* import { trace } from '@opentelemetry/api';
* import { withSpan } from '@artinet/sdk/otel';
*
* const tracer = trace.getTracer('my-agent');
* const result = await withSpan(tracer, 'processTask', async (span) => {
* span.setAttribute('taskId', '123');
* return await doWork();
* });
* ```
*/
export declare function withSpan<T>(tracer: Tracer, name: string, fn: (span: Span) => Promise<T>, options?: {
kind?: SpanKind;
attributes?: Record<string, string | number | boolean>;
}): Promise<T>;
/**
* Re-export OpenTelemetry API types for convenience.
*/
export { trace, context, SpanKind, SpanStatusCode, type Tracer, type Span, type Context, };
export default configureOtel;