Custom Logs with the Logger SDK - Helicone OSS LLM Observability

The Logger SDK allows you to log any custom operation to Helicone - database queries, API calls, ML inference, file processing, or any other operation you want to track.

To get started, install the @helicone/helpers package

npm install @helicone/helpers

Set up your Helicone API key in your .env file

Log into Helicone or create an account. Once you have an account, you can generate an API key here.

export HELICONE_API_KEY=<your-helicone-api-key>

Create a new HeliconeManualLogger instance

import { HeliconeManualLogger } from "@helicone/helpers";const heliconeLogger = new HeliconeManualLogger({  apiKey: process.env.HELICONE_API_KEY,  headers: {} // Additional headers sent with the request (optional)});

Log your request

The logRequest method takes three parameters:

Request data: What you're logging (query, operation name, etc.)
Operation function: The actual work being done
Headers: Optional custom properties or session tracking

const result = await heliconeLogger.logRequest(  // 1. What you're logging  {    _type: "data",    name: "user_query",    query: "SELECT * FROM users WHERE active = true",    database: "production"  },  // 2. The actual operation  async (resultRecorder) => {    const queryResult = await database.query(      "SELECT * FROM users WHERE active = true"    );    // Record the results    resultRecorder.appendResults({      _type: "data",      name: "user_query",      status: "success",      data: queryResult.rows,      count: queryResult.rows.length    });    return queryResult;  },  // 3. Optional: session tracking or custom properties  {    "Helicone-Property-Session": "user-123",    "Helicone-Property-Environment": "production"  });

Verify your requests in Helicone

With the above setup, any calls to any data operation will automatically be logged and monitored by Helicone. Review them in your Helicone dashboard.

Understanding the Structure#

All custom logs follow the same pattern with two parts:

Request Data#

What you're about to do. Must include:

_type: "data" - Identifies this as a custom data log
name - A descriptive name for your operation
Any custom fields you want to track (query, endpoint, model, etc.)

Response Data#

What happened. Should include:

_type: "data" - Identifies this as a custom data response
name - Same name as the request
status - Success or error state
Any result data you want to track

More Examples#

API Call#

await heliconeLogger.logRequest(  {    _type: "data",    name: "external_api_call",    endpoint: "https://api.example.com/users",    method: "GET"  },  async (resultRecorder) => {    const response = await fetch("https://api.example.com/users?limit=10");    const data = await response.json();    resultRecorder.appendResults({      _type: "data",      name: "external_api_call",      status: "success",      result: data    });    return data;  });

ML Model Inference#

await heliconeLogger.logRequest(  {    _type: "data",    name: "ml_inference",    model: "custom-classifier-v2",    input_features: { text: "This is a sample text" }  },  async (resultRecorder) => {    const prediction = await customModel.predict({      text: "This is a sample text",      threshold: 0.8    });    resultRecorder.appendResults({      _type: "data",      name: "ml_inference",      status: "success",      result: {        classification: prediction.classification,        confidence: prediction.confidence      }    });    return prediction;  });

For more examples, check out our GitHub examples.

To learn more about the HeliconeManualLogger API, see the API Reference here.