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