/helicone-observability

Route LLM API calls through Helicone for cost tracking, latency monitoring, and per-user attribution across all products.

Architecture

App → Helicone Gateway (proxy) → LLM Provider (Anthropic, OpenAI, etc.) ↓ Helicone Dashboard (cost, latency, properties)

Helicone is a transparent proxy. One URL + header change per provider. No SDK lock-in.

Multi-Product Strategy

Helicone has ONE dashboard per account. Segmentation is via custom properties, not separate projects.

Mandatory properties for every LLM call:

Header Purpose Example

Helicone-Property-Product

Which product/repo moneta , adminifi , vox

Helicone-Property-Environment

Deploy stage production , staging , development

Helicone-Property-Feature

What triggered the call chat , upload , classification

Helicone-User-Id

Per-user cost attribution User ID from auth

Optional properties (add as needed):

Header Purpose

Helicone-Session-Id

Group multi-turn conversations

Helicone-Session-Path

Hierarchical session path

Helicone-Property-Model

Override for model routing analysis

Helicone-Property-TaxYear

Domain-specific segmentation

Integration: Vercel AI SDK + Anthropic

Install

No extra packages needed. Helicone works via baseURL

• headers on @ai-sdk/anthropic .

Provider Setup

// lib/ai-provider.ts import { createAnthropic } from "@ai-sdk/anthropic";

// Helicone-proxied Anthropic provider export const anthropic = createAnthropic({ baseURL: "https://anthropic.helicone.ai/v1", headers: { "Helicone-Auth": Bearer ${process.env.HELICONE_API_KEY}, // Static properties set once at provider level "Helicone-Property-Product": "your-product-name", "Helicone-Property-Environment": process.env.NODE_ENV ?? "development", }, });

Per-Request Properties

Dynamic properties (userId, feature, session) go in the headers option of streamText /generateText :

import { streamText } from "ai"; import { anthropic } from "@/lib/ai-provider";

const result = streamText({ model: anthropic("claude-sonnet-4-6"), system: "...", messages, headers: { "Helicone-User-Id": userId, "Helicone-Property-Feature": "chat", "Helicone-Session-Id": conversationId, "Helicone-Session-Path": "/chat", }, });

Other Providers

// OpenAI import { createOpenAI } from "@ai-sdk/openai"; const openai = createOpenAI({ baseURL: "https://oai.helicone.ai/v1", headers: { "Helicone-Auth": Bearer ${process.env.HELICONE_API_KEY}, "Helicone-Property-Product": "your-product-name", }, });

// Google Gemini import { createGoogleGenerativeAI } from "@ai-sdk/google"; const google = createGoogleGenerativeAI({ baseURL: "https://gateway.helicone.ai/v1beta", headers: { "Helicone-Auth": Bearer ${process.env.HELICONE_API_KEY}, "Helicone-Target-URL": "https://generativelanguage.googleapis.com", "Helicone-Property-Product": "your-product-name", }, });

Caching

Enable for deterministic prompts (system prompt caching, repeated queries):

const anthropic = createAnthropic({ baseURL: "https://anthropic.helicone.ai/v1", headers: { "Helicone-Auth": Bearer ${process.env.HELICONE_API_KEY}, "Helicone-Cache-Enabled": "true", // Default 7 days. Max 365 days. "Cache-Control": "max-age=604800", }, });

Per-user cache isolation:

headers: { "Helicone-Cache-Seed": userId, // Separate cache per user }

Environment Variables

.env.example / .env.local

HELICONE_API_KEY=sk-helicone-...

API key location: ~/.secrets (line: export HELICONE_API_KEY=... )

Generate new keys: https://helicone.ai → Developer → API Keys

Pricing Awareness

Tier Requests/mo Retention Cost

Free 10,000 1 month $0

Growth Unlimited 3 months $20/seat/mo

Self-host Unlimited Unlimited Infra cost

Free tier is sufficient for beta/early launch of most indie products.

Audit Checklist

When adding Helicone to a project, verify:

• HELICONE_API_KEY in .env.local and deployment env vars

• Provider baseURL points to Helicone gateway

• Helicone-Auth header on every provider

• Helicone-Property-Product set (identifies this product in shared dashboard)

• Helicone-Property-Environment set (prevents dev/prod mixing)

• Helicone-User-Id passed on every user-facing request

• Helicone-Property-Feature distinguishes call types

• Requests visible in Helicone dashboard after deploy

• Cost per user queryable in dashboard

Dashboard Queries

Filter the Helicone dashboard by:

• Product: Property: Product = moneta → see only Moneta costs

• User: User Id = user_123 → per-user cost breakdown

• Feature: Property: Feature = chat → chat vs upload vs classification costs

• Environment: Property: Environment = production → exclude dev noise

Anti-Patterns

• Setting only Helicone-Auth without custom properties (everything is unsegmented noise)

• Using Helicone-Property-* in client-side code (leaks API key)

• Forgetting Helicone-Property-Product (can't distinguish products in shared account)

• Enabling cache for non-deterministic chat completions (stale responses)

• Hardcoding API keys instead of using env vars

References

• Vercel AI SDK integration

• Custom properties

• User metrics

• Caching

• AI SDK observability docs