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.

npm install @helicone/helpers

pip install helicone-helpers

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

import { HeliconeManualLogger } from "@helicone/helpers";

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

from helicone_helpers import HeliconeManualLogger

helicone_logger = HeliconeManualLogger(
  api_key=os.getenv("HELICONE_API_KEY"),
  headers={} # Additional headers sent with the request (optional)
)

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"
  }
);

def database_operation(result_recorder):
  # The actual operation
  query_result = database.execute(
    "SELECT * FROM users WHERE active = true"
  )

  # Record the results
  result_recorder.append_results({
    "_type": "data",
    "name": "user_query",
    "status": "success",
    "data": query_result.fetchall(),
    "count": len(query_result.fetchall())
  })
  return query_result

result = helicone_logger.log_request(
  # 1. What you're logging
  request={
    "_type": "data",
    "name": "user_query",
    "query": "SELECT * FROM users WHERE active = true",
    "database": "production"
  },
  # 2. The actual operation
  operation=database_operation,
  # 3. Optional: session tracking or custom properties
  additional_headers={
    "Helicone-Property-Session": "user-123",
    "Helicone-Property-Environment": "production"
  }
)

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;
  }
);

def api_call_operation(result_recorder):
  response = requests.get("https://api.example.com/users", params={"limit": 10})
  data = response.json()

  result_recorder.append_results({
    "_type": "data",
    "name": "external_api_call",
    "status": "success",
    "result": data
  })
  return data

api_result = helicone_logger.log_request(
  request={
    "_type": "data",
    "name": "external_api_call",
    "endpoint": "https://api.example.com/users",
    "method": "GET"
  },
  operation=api_call_operation
)

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;
  }
);

def ml_inference_operation(result_recorder):
  prediction = custom_model.predict({
    "text": "This is a sample text",
    "threshold": 0.8
  })

  result_recorder.append_results({
    "_type": "data",
    "name": "ml_inference",
    "status": "success",
    "result": {
      "classification": prediction["classification"],
      "confidence": prediction["confidence"]
    }
  })
  return prediction

prediction = helicone_logger.log_request(
  request={
    "_type": "data",
    "name": "ml_inference",
    "model": "custom-classifier-v2",
    "input_features": {"text": "This is a sample text"}
  },
  operation=ml_inference_operation
)

For more examples, check out our GitHub examples.

​Understanding the Structure

​Request Data

​Response Data

​More Examples

​API Call

​ML Model Inference

​Related Guides