> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript

> Reference documentation for the HoneyHiveTracer class

## 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](https://opentelemetry.io/docs/zero-code/js/).

A general explanation of what OpenTelemetry is can be found [here](https://opentelemetry.io/docs/what-is-opentelemetry/).

### 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:

```typescript theme={null}
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.

<Note> It is **recommended** to use the exported [`enrichSession`](#enrichsession-2) function instead for better context handling. </Note>

**Parameters**:

* See the exported [`enrichSession`](#enrichsession-2) function for parameters.

**Returns**:
`Promise<void>`

#### `traceFunction`

Instance method to create a decorator for tracing functions.

<Note> It is **recommended** to use the exported [`traceFunction`](#tracefunction-2) function instead for better context handling. </Note>

**Parameters**:

* See the exported [`traceFunction`](#tracefunction-2) 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.

<Note> It is **recommended** to use the exported [`traceModel`](#tracemodel-2) function instead for better context handling. </Note>

**Parameters**:

* See the exported [`traceModel`](#tracemodel-2) function for parameters.

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

**Example**:

```typescript theme={null}
// 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.

<Note> It is **recommended** to use the exported [`traceTool`](#tracetool-2) function instead for better context handling. </Note>

**Parameters**:

* See the exported [`traceTool`](#tracetool-2) function for parameters.

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

**Example**:

```typescript theme={null}
// 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.

<Note> It is **recommended** to use the exported [`traceChain`](#tracechain-2) function instead for better context handling. </Note>

**Parameters**:

* See the exported [`traceChain`](#tracechain-2) function for parameters.

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

**Example**:

```typescript theme={null}
// 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.

<Note> While this method works, using the specific [`traceFunction`](#tracefunction-2), [`traceModel`](#tracemodel-2), [`traceTool`](#tracetool-2), or [`traceChain`](#tracechain-2) decorators/wrappers often provides more structured tracing with automatic event type tagging. </Note>

**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.

<Note> This method is **deprecated**. It is **strongly recommended** to use the exported [`enrichSpan`](#enrichspan-2) function instead. </Note>

**Parameters**:

* See the exported [`enrichSpan`](#enrichspan-2) 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**:

```typescript theme={null}
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**:

```typescript theme={null}
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**:

```typescript theme={null}
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**:

```typescript theme={null}
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.