Helicone (tracing)

Helicone’s Manual Logger records calls to custom, self-hosted, and provider-backed models. The Respan Helicone instrumentation observes that same manual-logger lifecycle and emits canonical Respan spans without replacing or bypassing Helicone’s own logging.

The integration supports helicone-helpers >=1.2.1,<1.3.0 for Python and @helicone/helpers >=1.8.3 <1.9.0 for TypeScript.

Setup

pip install respan-ai respan-instrumentation-helicone "helicone-helpers~=1.2.1" openai

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export HELICONE_API_KEY="YOUR_HELICONE_API_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

import os
from helicone_helpers import HeliconeManualLogger
from openai import OpenAI
from respan import Respan
from respan_instrumentation_helicone import HeliconeInstrumentor
respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    app_name="helicone-manual-logger",
    instrumentations=[HeliconeInstrumentor()],
)
helicone = HeliconeManualLogger(api_key=os.environ["HELICONE_API_KEY"])
openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
request = {
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in three languages."}],
}
def call_model(recorder):
    response = openai.chat.completions.create(**request)
    recorder.append_results(response.model_dump())
    return response
try:
    response = helicone.log_request(
        request=request,
        operation=call_model,
        provider="openai",
        additional_headers={
            "Helicone-User-Id": "user_123",
            "Helicone-Session-Id": "conversation_456",
            "Helicone-Property-Environment": "production",
        },
    )
    print(response.choices[0].message.content)
finally:
    respan.flush()
    respan.shutdown()

What is traced

The instrumentors patch Helicone’s published Manual Logger methods rather than the underlying provider SDK.

The emitted span type is inferred from the payload:

When Helicone supplies them, Respan retains model and provider identity, request and response content, token usage, tool definitions and calls, streaming timing, HTTP status, and errors. An operation that fails before Helicone reaches its shared logging sink still produces one error span rather than a duplicate success/error pair.

Configuration

Disable content capture

Disable content capture when prompts or responses may contain sensitive data:

from respan_instrumentation_helicone import HeliconeInstrumentor
instrumentor = HeliconeInstrumentor(capture_content=False)

Model, provider, usage, timing, status, errors, and safe correlation fields remain available. Helicone API keys, authorization headers, unknown headers, and structured secret fields are never copied into spans.

Correlation attributes

The instrumentors recognize Helicone’s safe correlation headers:

Respan propagated attributes also stay attached to the manual-log span, including parent workflow context captured when a delayed builder is created.

Avoid duplicate telemetry

Helicone instrumentation is explicit-only. Activate it only in processes that use HeliconeManualLogger.

Do not also activate a provider-specific instrumentor for the same provider call unless two spans for one logical operation are intentional. Likewise, a request routed through Respan Gateway already creates a gateway log; wrapping it in an instrumented Helicone manual log adds a separate manual-log span. See the gateway guide for the simpler gateway-only migration path.