@axarai/axar/dist/common/telemetry.d.ts

TypeScript-based agent framework for building agentic applications powered by LLMs

import { Context } from '@opentelemetry/api';
import { ZodSchema } from 'zod';
/**
 * Type definition for valid attribute values in telemetry spans
 */
type AttributeValue = string | ZodSchema | string[] | Object | undefined | null;
/**
 * Telemetry class that provides a wrapper around OpenTelemetry functionality
 * for tracking and monitoring application behavior.
 *
 * @template T - The type of object being monitored. Must extend Object.
 */
export declare class Telemetry<T extends Object> {
    private readonly object;
    private readonly tracer;
    private span?;
    /**
     * Creates a new Telemetry instance
     * @param object - The object to monitor. Used to generate span names based on the constructor name.
     */
    constructor(object: T);
    /**
     * Starts a new span with the given method name
     * @param method - The method name to use for the span
     * @throws Error if span creation fails
     */
    private startSpan;
    /**
     * Ends the current span if it exists and cleans up resources
     */
    private endSpan;
    /**
     * Adds an attribute to the current span if telemetry is enabled
     * @param key - The attribute key to be added to the span
     * @param value - The attribute value. Can be:
     *   - string: Added directly as an attribute
     *   - ZodSchema: Converted to JSON schema before adding
     *   - string[]: Stringified before adding
     *   - Object: Stringified with indentation before adding
     *   - undefined/null: Ignored
     * @example
     * ```typescript
     * telemetry.addAttribute('userId', '12345');
     * telemetry.addAttribute('requestBody', userSchema);
     * telemetry.addAttribute('tags', ['important', 'urgent']);
     * ```
     */
    addAttribute(key: string, value: AttributeValue): void;
    /**
     * Executes an operation within a new span, providing automatic error handling
     * and context management.
     *
     * @param method - The method name for the span. Must not be empty.
     * @param operation - The async operation to execute within the span
     * @returns The result of the operation
     * @throws Any error from the operation, after recording it in the span
     *
     * @example
     * ```typescript
     * const result = await telemetry.withSpan('processUser', async () => {
     *   const user = await processUserData();
     *   return user;
     * });
     * ```
     */
    withSpan<R>(method: string, operation: () => Promise<R>): Promise<R>;
    /**
     * Gets the current context with the active span
     * @returns The current context with the active span if one exists,
     *          otherwise returns the active context
     */
    getContext(): Context;
    isRecording(): boolean;
}
export {};