TypeScript

​

HoneyHiveTracer class

The HoneyHiveTracer class is a utility designed to initialize and manage a tracing session with the HoneyHive API, utilizing OpenTelemetry. This class encapsulates initialization of the tracing environment, capturing telemetry, and sending updates related to feedback, metrics, and metadata.

Our tracer uses OpenTelemetry as a base to auto-trace JavaScript code. A full explanation of how this works in JavaScript can be found here.

A general explanation of what OpenTelemetry is can be found here.

​

Attributes

• sessionId (string | undefined): Stores the current session ID. This is undefined until a session is initialized.
• apiKey (string | undefined): API key used for authentication (read-only, sourced from initialization or HH_API_KEY env var).
• project (string | undefined): Project name associated with the session (read-only, sourced from initialization or HH_PROJECT env var).
• serverUrl (string): HoneyHive server URL (read-only, sourced from initialization, HH_API_URL env var, or default).
• sessionName (string): Name for the current session (read-only, sourced from initialization, HH_SESSION_NAME env var, main module filename, or default).
• source (string): Source identifier for the session (read-only, sourced from initialization, HH_SOURCE env var, package name, or default).
• metadata (Record<string, any>): Default metadata associated with the session during initialization (read-only).
• disableBatch (boolean): Whether batch exporting of traces is disabled (read-only, sourced from initialization).
• verbose (boolean): Whether verbose logging is enabled (read-only, sourced from initialization).
• disableHttpTracing (boolean): Whether automatic HTTP tracing is disabled (read-only, sourced from initialization).

​

Example Usage

Here’s a simplified example showing basic initialization and usage:

import { HoneyHiveTracer, enrichSession, enrichSpan, traceFunction } from "honeyhive";

async function initializeTracer() {
    // Initialize a session
    return await HoneyHiveTracer.init({
        apiKey: "your-api-key",
        project: "Project Name",
        sessionName: "Session Name",
        source: "source_identifier"
    });
}


async function tracedMain() {
    // Enrich the session with additional data
    await enrichSession({
        metadata: { key: "value" },
        feedback: { feedback: "Session feedback" },
        metrics: { metric_name: "metric_value" }
    });


    // Trace a function with the traceFunction decorator
    const tracedFunction = traceFunction()(async (arg1: any, arg2: any) => {
        // Your function logic here
        console.log(`Executing tracedFunction with args: ${arg1}, ${arg2}`);
        // Enrich a span within a traced function
        await enrichSpan({
            metadata: { key: "value" }
        });
        return "some result"; // Added return for example
    });

    // Example call to the traced function
    await tracedFunction("hello", 123);

    console.log("tracedMain finished successfully.");

}

async function main() {
    const tracer = await initializeTracer();
    try {
        await tracer.trace(() => tracedMain());
        return true;
    } catch (error) {
        console.error(error);
        return false;
    } finally {
        // Flush traces
        await tracer.flush();
    }
}

​

Methods

​

init

Initializes a HoneyHive tracing session and sets up the OpenTelemetry tracing environment.

Parameters:

• params (Partial<HoneyHiveTracerProperties>, optional): An object containing initialization options.
  • apiKey (string, required if HH_API_KEY env var not set): API key for authenticating with the HoneyHive service.
  • project (string, required if HH_PROJECT env var not set): Name of the project associated with this tracing session.
  • sessionId (string, optional): Pre-existing session ID (must be a valid UUID) to continue tracing an existing session.
  • sessionName (string, optional): Name for this specific session. Defaults will be inferred from the environment.
  • source (string, optional): Source identifier, typically describing the environment or component. Defaults will be inferred from the environment.
  • serverUrl (string, optional): HoneyHive server URL. Defaults to "https://api.honeyhive.ai", can also be set via HH_API_URL env var.
  • metadata (Record<string, any>, optional): Default metadata to associate with the session.
  • verbose (boolean, optional): Enable verbose logging (default: false).
  • disableBatch (boolean, optional): Disable batch exporting of traces (default: false).
  • disableHttpTracing (boolean, optional): Disable automatic tracing for HTTP requests (default: false).

Returns: Promise<HoneyHiveTracer>: A promise that resolves to an instance of HoneyHiveTracer.

​

enrichSession

Instance method to enrich the current session with additional data.

Parameters:

• See the exported enrichSession function for parameters.

Returns: Promise<void>

​

traceFunction

Instance method to create a decorator for tracing functions.

Parameters:

• See the exported traceFunction function for parameters.

Returns: A function that takes a function as an argument and returns a traced version of that function.

​

traceModel

Instance method to trace a function specifically for model operations.

Parameters:

• See the exported traceModel function for parameters.

Returns: A traced version of the input function with model-specific tracing.

Example:

// Example using the recommended standalone function:
import { traceModel } from 'honeyhive';

async function generateText(prompt: string): Promise<string> {
    const response = await LLMCompletion({ prompt });
    return response.text;
}

const modelFunction = traceModel(generateText, {
    metadata: { model: "gpt-4" },
    config: { temperature: 0.7 }
});

​

traceTool

Instance method to trace a function specifically for tool operations.

Parameters:

• See the exported traceTool function for parameters.

Returns: A traced version of the input function with tool-specific tracing.

Example:

// Example using the recommended standalone function:
import { traceTool } from 'honeyhive';

async function searchDatabase(query: string): Promise<unknown> {
  const result = await DatabaseSearch(query);
  return result;
}

const toolFunction = traceTool(searchDatabase, {
  metadata: { tool_type: "database_search" }
});

​

traceChain

Instance method to trace a function specifically for chain operations.

Parameters:

• See the exported traceChain function for parameters.

Returns: A traced version of the input function with chain-specific tracing.

Example:

// Example using the recommended standalone function:
import { traceChain, traceTool } from 'honeyhive';

const tracedFirstOp = traceTool(async (input: string) => { /* ... */ return `first-${input}`; }, { eventName: 'first_op' });
const tracedSecondOp = traceTool(async (input: string) => { /* ... */ return `second-${input}`; }, { eventName: 'second_op' });

const processingPipeline = async (input: string): Promise<unknown> => {
  const intermediateResult = await tracedFirstOp(input);
  const finalResult = await tracedSecondOp(intermediateResult);
  return finalResult;
};

const chainFunction = traceChain(processingPipeline, {
  metadata: { chain_name: "processing_pipeline" }
});

​

trace

Executes a given function with its arguments, wrapping the execution within the current HoneyHive session’s trace context using OpenTelemetry association properties. This helps ensure that any spans created within the executed function are correctly linked to the session.

It handles both synchronous and asynchronous functions. If the provided function is asynchronous (returns a Promise), trace will also return a Promise.

Signature: trace<A extends unknown[], F extends (...args: A) => ReturnType<F>>(fn: F, ...args: A): ReturnType<F>

Parameters:

• fn (F): The function to execute and trace.
• …args (A): The arguments to pass to the function fn.

Returns: ReturnType<F>: The result of executing fn(...args), preserving whether it’s a direct value or a Promise.

​

enrichSpan

Instance method to enrich the current span with additional data.

Parameters:

• See the exported enrichSpan function for parameters.

Returns: void

​

flush

Forces a flush of all pending traces.

Returns: Promise<void>

​

Notes

• The tracer automatically instruments several popular AI and machine learning libraries, including OpenAI, Anthropic, Azure OpenAI, Cohere, AWS Bedrock, Google AI Platform, Pinecone, LangChain, and Chroma.
• The enrichSpan method should be called within a traced function to ensure there’s an active span to enrich.
• The inputs parameter in enrichSession is currently not supported and will log a warning if used.

​

Standalone Functions

After initializing the HoneyHiveTracer once using HoneyHiveTracer.init(), the following exported functions are the preferred way to interact with tracing throughout your application. They automatically handle the necessary context association.

​

enrichSession

Enriches the current session with additional data. It automatically attempts to find the sessionId from the current context if not provided.

Parameters:

• params (EnrichSessionParams, optional): An object containing data to enrich the session.
  • sessionId (string, optional): The ID of the session to enrich. If not provided, it attempts to get it from the active context.
  • metadata (Record<string, any>, optional): Additional metadata for the session.
  • feedback (Record<string, any>, optional): Feedback data for the session.
  • metrics (Record<string, any>, optional): Metrics data for the session.
  • config (Record<string, any>, optional): Configuration data for the session.
  • inputs (Record<string, any>, optional): Input data for the session (currently not supported).
  • outputs (Record<string, any>, optional): Output data for the session.
  • userProperties (Record<string, any>, optional): User properties for the session.

Returns: Promise<void>

​

enrichSpan

Enriches the currently active span with additional data. Must be called within the context of a traced function (e.g., inside a function decorated with traceFunction, traceModel, etc.).

Parameters:

• params (EnrichSpanParams, optional): An object containing data to enrich the span.
  • config (any, optional): Configuration data for the span.
  • metadata (any, optional): Additional metadata for the span.
  • metrics (any, optional): Metrics data for the span.
  • feedback (any, optional): Feedback data for the span.
  • inputs (any, optional): Input data for the span.
  • outputs (any, optional): Output data for the span.
  • error (any, optional): Error data for the span.
  • eventName (string, optional): A specific name to associate with this enrichment event within the span.

Returns: void

​

traceFunction

Creates a higher-order function (decorator) to wrap and trace another function. Captures inputs, outputs, errors, and associates the execution with the current HoneyHive session context.

Parameters:

• options (TraceFunctionOptions, optional): Configuration options for the trace.
  • eventType (string, optional): Type of event (‘tool’, ‘model’, or ‘chain’). Sets the honeyhive_event_type attribute.
  • config (any, optional): Configuration data to attach to the span (honeyhive_config).
  • metadata (any, optional): Additional metadata to attach to the span (honeyhive_metadata).
  • eventName (string, optional): Custom name for the trace span. Defaults to the function name or a generic event name.

Returns: A function that takes the target function (func) as input and returns a new, traced version of func.

Example Usage:

import { traceFunction, enrichSpan } from 'honeyhive';

const myTracedFunction = traceFunction({ eventName: 'custom_operation' })(
  async (input: string) => {
    // Function logic...
    const result = `Processed: ${input}`;
    enrichSpan({ outputs: { finalResult: result } });
    return result;
  }
);

await myTracedFunction("hello");

​

traceModel

A convenience wrapper around traceFunction that automatically sets the eventType to “model”.

Parameters:

• func (Function): The model-related function to trace.
• options (Omit<TraceFunctionOptions, 'eventType'>, optional): Configuration options (excluding eventType).
  • config (any, optional): Configuration data for the span.
  • metadata (any, optional): Additional metadata for the span.
  • eventName (string, optional): Custom name for the trace span.

Returns: The traced version of the input func.

Example Usage:

import { traceModel } from 'honeyhive';

async function callLLM(prompt: string): Promise<string> {
  // ... call LLM API ...
  return "LLM response";
}

const tracedLLMCall = traceModel(callLLM, {
  metadata: { model_name: 'claude-3' },
  config: { temperature: 0.5 }
});

await tracedLLMCall("Generate a poem.");

​

traceTool

A convenience wrapper around traceFunction that automatically sets the eventType to “tool”.

Parameters:

• func (Function): The tool-related function to trace.
• options (Omit<TraceFunctionOptions, 'eventType'>, optional): Configuration options (excluding eventType).
  • config (any, optional): Configuration data for the span.
  • metadata (any, optional): Additional metadata for the span.
  • eventName (string, optional): Custom name for the trace span.

Returns: The traced version of the input func.

Example Usage:

import { traceTool } from 'honeyhive';

async function searchAPI(query: string): Promise<any[]> {
  // ... call search API ...
  return [{ result: 1 }];
}

const tracedSearch = traceTool(searchAPI, {
  metadata: { api_version: 'v2' }
});

await tracedSearch("honeyhive sdk");

​

traceChain

A convenience wrapper around traceFunction that automatically sets the eventType to “chain”. Typically used to wrap functions that orchestrate multiple model or tool calls.

Parameters:

• func (Function): The chain-related function to trace.
• options (Omit<TraceFunctionOptions, 'eventType'>, optional): Configuration options (excluding eventType).
  • config (any, optional): Configuration data for the span.
  • metadata (any, optional): Additional metadata for the span.
  • eventName (string, optional): Custom name for the trace span.

Returns: The traced version of the input func.

Example Usage:

import { traceChain, traceModel, traceTool } from 'honeyhive';

const tracedLLMCall = traceModel(async (prompt: string) => "LLM says: " + prompt, { eventName: 'llm_call' });

const tracedSearch = traceTool(async (query: string) => ["Search result for: " + query], { eventName: 'search_tool' });

const main_flow = traceChain(async (input: string) => {
  const llm_res = await tracedLLMCall(input);
  const search_res = await tracedSearch(llm_res);
  return search_res;
}, { eventName: 'main_processing_chain' });

await main_flow("What is HoneyHive?");

​

Notes

• The enrichSession and enrichSpan functions should be used within the context of a traced function to ensure the correct session and span are enriched.
• The traceFunction, traceModel, traceTool, and traceChain functions are designed to be used within the context of a traced function to ensure the correct event type is set.
• The trace function is a convenience function that can be used to trace any function, but it does not automatically associate the trace with the current session.