> ## 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 HoneyHive Logger

<Note>
  `@honeyhive/logger` targets HoneyHive v1 and is being deprecated in favor of [`@honeyhive/api-client`](https://www.npmjs.com/package/@honeyhive/api-client). New TypeScript projects on v2 should use the API client; existing logger users should follow the [migration guide](/v2/sdk-reference/typescript-logger-to-api-sdk-migration).
</Note>

## Overview

The HoneyHive Logger is a lightweight, stateless SDK designed to track and monitor AI applications by wrapping HoneyHive's `/events` endpoints. With no external dependencies, it's particularly well-suited for serverless execution and regulated environments with strict security requirements.

## Installation

`npm install @honeyhive/logger`

## API Reference

The logger provides three main functions for interacting with HoneyHive's event tracking system:

### `start(options)`

Starts a new session with HoneyHive. This function initializes a tracking session and returns a session ID that can be used to correlate subsequent events.

**Parameters**:

* **options** (`Object`): Configuration options for starting a session.
  * **apiKey** (`string`, required if not set via env): Your HoneyHive API key. Can be set via `HH_API_KEY` env var.
  * **project** (`string`, required if not set via env): The project name. Can be set via `HH_PROJECT` env var.
  * **sessionName** (`string`, optional): Tag to filter sessions (e.g., "v1", "au1i249c"). Defaults to project name.
  * **source** (`string`, optional): Environment identifier. Defaults to "dev" or `HH_SOURCE` env var.
  * **config** (`Object`, optional): Configuration details like experiment versions, model names, etc.
  * **inputs** (`Object`, optional): Input parameters for the session.
  * **metadata** (`Object`, optional): Additional metadata for the session.
  * **userProperties** (`Object`, optional): User-defined properties for the session.
  * **sessionId** (`string`, optional): A valid UUIDv4 for correlation. Generated if not provided.
  * **serverUrl** (`string`, optional): HoneyHive API server URL. Defaults to "[https://api.honeyhive.ai](https://api.honeyhive.ai)" or `HH_API_URL` env var.
  * **verbose** (`boolean`, optional): Enable detailed error messages. Defaults to false.

**Returns**:
`Promise<string>`: The session ID (UUIDv4)

**Example**:

```typescript theme={null}
const {start} = require('@honeyhive/logger');

const sessionId = await start({
    apiKey: "your-api-key",
    project: "your-project",
    sessionName: "v1",
    source: "prod",
    config: {
        model: "gpt-4",
        temperature: 0.7
    }
});
```

### `log(options)`

Logs an event to HoneyHive. This function records individual events within a session, such as model inferences, tool executions, or chain operations.

**Parameters**:

* **options** (`Object`): Configuration options for logging an event.
  * **apiKey** (`string`, required if not set via env): Your HoneyHive API key. Can be set via `HH_API_KEY` env var.
  * **project** (`string`, required if not set via env): The project name. Can be set via `HH_PROJECT` env var.
  * **sessionId** (`string`, required): The session ID to log the event under.
  * **eventName** (`string`, required): Name of the event being logged.
  * **eventType** (`string`, optional): Type of event - "model", "tool", or "chain". Defaults to "tool".
  * **config** (`Object`, optional): Configuration details for the event.
  * **inputs** (`Object`, optional): Input parameters for the event.
  * **outputs** (`Object`, optional): Output data from the event.
  * **metadata** (`Object`, optional): Additional metadata for the event.
  * **durationMs** (`number`, optional): Duration of the event in milliseconds. Defaults to 10.
  * **serverUrl** (`string`, optional): HoneyHive API server URL. Defaults to "[https://api.honeyhive.ai](https://api.honeyhive.ai)" or `HH_API_URL` env var.
  * **verbose** (`boolean`, optional): Enable detailed error messages. Defaults to false.

**Returns**:
`Promise<string>`: The event ID (UUIDv4)

**Example**:

```typescript theme={null}
const {log} = require('@honeyhive/logger');

const eventId = await log({
    sessionId: "your-session-id",
    eventName: "model_inference",
    eventType: "model",
    config: {
        model: "gpt-4",
        temperature: 0.7
    },
    inputs: {
        prompt: "Hello world"
    },
    outputs: {
        response: "Hi there!"
    }
});
```

### `update(options)`

Updates an existing event or session with additional data. This function allows you to enrich events or sessions with feedback, metrics, or other information after they've been created.

**Parameters**:

* **options** (`Object`): Configuration options for updating an event or session.
  * **apiKey** (`string`, required if not set via env): Your HoneyHive API key. Can be set via `HH_API_KEY` env var.
  * **eventId** (`string`, required): The ID to update (can be either a session\_id or event\_id).
  * **metadata** (`Object`, optional): Additional metadata to add.
  * **feedback** (`Object`, optional): User feedback data.
  * **metrics** (`Object`, optional): Computed metrics data.
  * **config** (`Object`, optional): Updated configuration data.
  * **outputs** (`Object`, optional): Additional output data.
  * **userProperties** (`Object`, optional): Updated user-defined properties.
  * **durationMs** (`number`, optional): Duration in milliseconds.
  * **serverUrl** (`string`, optional): HoneyHive API server URL. Defaults to "[https://api.honeyhive.ai](https://api.honeyhive.ai)" or `HH_API_URL` env var.
  * **verbose** (`boolean`, optional): Enable detailed error messages. Defaults to false.

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

**Example**:

```typescript theme={null}
const {update} = require('@honeyhive/logger');

// Update a session
await update({
    eventId: sessionId,
    metadata: {
        status: "completed"
    }
});

// Update an event
await update({
    eventId: eventId,
    feedback: {
        rating: 5,
        comment: "Great response!"
    },
    metrics: {
        latency: 100,
        tokens: 50
    }
});
```

## Error Handling

The logger implements robust error handling with exponential backoff and jitter for retrying failed requests. It handles various types of errors including:

* Network connectivity issues
* API authentication errors
* Invalid parameters
* Server-side errors

When `verbose` mode is enabled, detailed error information is thrown as exceptions. In non-verbose mode, errors are logged to the console and functions return `null` or void.

### Retryable Errors

The following errors are automatically retried with backoff:

* Network errors
* Server errors (HTTP 500-599)
* Rate limiting responses (HTTP 429)
* Request timeouts (HTTP 408)

### Configuration

The retry mechanism can be configured with the following defaults:

* Maximum retries: 3
* Base delay: 1.0 seconds
* Maximum delay: 5.0 seconds
* Request timeout: 5.0 seconds

## Environment Variables

The logger supports configuration through environment variables:

* `HH_API_KEY`: Your HoneyHive API key
* `HH_PROJECT`: Your project name
* `HH_SOURCE`: Environment identifier
* `HH_API_URL`: HoneyHive API server URL

These environment variables can be used instead of passing the corresponding options in function calls.