TypeScript

​

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” or HH_API_URL env var.
  • verbose (boolean, optional): Enable detailed error messages. Defaults to false.

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

Example:

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” or HH_API_URL env var.
  • verbose (boolean, optional): Enable detailed error messages. Defaults to false.

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

Example:

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” or HH_API_URL env var.
  • verbose (boolean, optional): Enable detailed error messages. Defaults to false.

Returns: Promise<void>

Example:

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.