Skip to main content

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.

The honeyhive-logger package is a lightweight API wrapper with start(), log(), and update() functions. The v1 honeyhive package adds OpenTelemetry tracing, automatic context propagation, decorators, instrumentors, and evaluation support. Use this guide when moving Python code from honeyhive-logger to honeyhive>=1.0.0.
The logger package is useful when you need a dependency-free client. Migrate to the v1 SDK when you want automatic spans, nested trace trees, framework integrations, or evaluate().
Use this HoneyHive migration guide: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/logger-to-v1.md

Explore my codebase to find where HoneyHive logging is used. Ask me any questions needed to understand the project context, runtime, and migration constraints. Then present a concise migration plan for my confirmation. After I confirm the plan, implement the migration changes.

​
API mapping

Logger APIv1 SDK replacementNotes
start(...)HoneyHiveTracer.init(...), tracer.create_session(...), or tracer.with_session(...)Initialize once, then create scoped sessions when needed
log(...)@trace, enrich_span_context(...), or tracer.enrich_span(...)Prefer decorators for function-level tracing
update(event_id=...)tracer.enrich_span(event_id=...)Updates a specific existing event
update(event_id=session_id, ...)tracer.enrich_session(session_id=...)Updates a session
duration_msCaptured by spans automaticallyUse metrics only if you need custom duration fields

​
1. Replace the package

pip uninstall honeyhive-logger -y
pip install "honeyhive>=1.0.0"
Set credentials: 
export HH_API_KEY="your-project-scoped-api-key"
export HH_SOURCE="production"

​
2. Migrate session creation

Logger code usually starts a session and passes session_id to every event. In v1, initialize a tracer once and use session helpers to scope work. 
import os
from honeyhive_logger import start

session_id = start(
    api_key=os.environ["HH_API_KEY"],
    project="support-bot",
    session_name="support-chat",
    source="production",
    inputs={"message": "How do I reset my password?"},
    metadata={"tenant_id": "acme"},
    user_properties={"user_id": "user-123"},
)
For single-operation scripts, with_session() keeps session setup close to the work: 
with tracer.with_session(
    session_name="support-chat",
    inputs={"message": message},
    user_properties={"user_id": user_id},
):
    response = answer(message)
    tracer.enrich_session(outputs={"response": response})

​
3. Replace log() with @trace

Use @trace when the event maps to a Python function. 
from honeyhive_logger import log

def answer(message: str, session_id: str) -> str:
    response = call_model(message)
    log(
        session_id=session_id,
        event_name="model_inference",
        event_type="model",
        config={"model": "gpt-4o-mini"},
        inputs={"prompt": message},
        outputs={"response": response},
        metadata={"route": "password-reset"},
    )
    return response
The decorator captures function inputs and outputs automatically. Use tracer.enrich_span(...) inside the function for extra metadata, metrics, feedback, config, or a custom output shape.

​
4. Replace log() with manual spans when decorators do not fit

Use enrich_span_context() for loops, conditional blocks, or code that is not cleanly wrapped by a function. 
event_id = log(
    session_id=session_id,
    event_name="retrieve_documents",
    event_type="tool",
    inputs={"query": query},
    outputs={"documents": docs},
)
Use tracer.start_span() only when you need raw OpenTelemetry control: 
with tracer.start_span("retrieve_documents") as span:
    span.set_attribute("query", query)
    docs = retrieve_documents(query)
    span.set_attribute("document_count", len(docs))

​
5. Replace update() for events

When you need to update a known event ID, pass it to tracer.enrich_span().
Use event_id when you want to update an existing event in HoneyHive. If you are updating the current active span, omit event_id.
from honeyhive_logger import update

update(
    event_id=event_id,
    feedback={"rating": 5},
    metrics={"quality_score": 0.94},
    outputs={"response": response},
)
If the event is the current active span, omit event_id: 
tracer.enrich_span(
    feedback={"rating": 5},
    metrics={"quality_score": 0.94},
)

​
6. Replace update() for sessions

Logger uses update(event_id=session_id, ...) for session updates. In v1, use session enrichment. 
update(
    event_id=session_id,
    outputs={"answer": answer_text},
    feedback={"thumbs_up": True},
    user_properties={"plan": "enterprise"},
)
If you created the session with create_session() in the active request, you can omit session_id: 
tracer.enrich_session(outputs={"answer": answer_text})

​
7. Add automatic provider instrumentation

After migrating logger calls, you can add automatic model or framework spans. 
pip install "honeyhive[openinference-openai]"

from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(
    api_key="your-api-key",
)
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)
See Integrations for provider-specific setup.

​
Complete before and after

from honeyhive_logger import start, log, update

def handle_chat(message: str, user_id: str) -> str:
    session_id = start(
        session_name="support-chat",
        inputs={"message": message},
        user_properties={"user_id": user_id},
    )

    response = call_model(message)
    event_id = log(
        session_id=session_id,
        event_name="model_inference",
        event_type="model",
        inputs={"prompt": message},
        outputs={"response": response},
    )

    update(event_id=event_id, metrics={"quality_score": score(response)})
    update(event_id=session_id, outputs={"response": response})
    return response

​
Migration checklist

  • Replace honeyhive-logger with honeyhive>=1.0.0
  • Initialize one HoneyHiveTracer at startup
  • Replace start() with create_session() or with_session()
  • Replace function-level log() calls with @trace
  • Replace block-level log() calls with enrich_span_context()
  • Replace event update() calls with tracer.enrich_span(event_id=...)
  • Replace session update() calls with tracer.enrich_session(...)
  • Add provider instrumentors where automatic tracing is useful
  • Confirm traces show nested spans and session outputs in HoneyHive

Custom Spans

Learn decorator and manual span patterns.

Tracer Initialization

Place tracer initialization correctly for your runtime.

Enriching Traces

Add metadata, metrics, feedback, and outputs.

OpenAI Integration

Add automatic model call tracing.