Route LLM provider requests through the Helicone gateway for observability, or log asynchronously when the proxy cannot be in the critical path

Documented steps

1. Create a Helicone account and generate an API key at us.helicone.ai/settings/api-keys. Store it as HELICONE_API_KEY.
2. Choose an integration mode. Helicone currently documents two distinct gateways with different contracts, and mixing their headers is the most common failure: the unified AI Gateway at https://ai-gateway.helicone.ai (OpenAI-compatible, model-name-based routing across 100+ models, observability on by default), or the older Gateway Integration at https://gateway.helicone.ai which requires per-request target headers.
3. For the unified AI Gateway, change only two things in your existing OpenAI SDK client: set base_url / baseURL to https://ai-gateway.helicone.ai and set api_key / apiKey to your HELICONE_API_KEY. No Helicone-specific client library is required.
4. For the legacy Gateway Integration, set base_url to https://gateway.helicone.ai, add the header Helicone-Auth: Bearer <HELICONE_API_KEY>, add Helicone-Target-Url pointing at the real provider endpoint (for example https://api.openai.com/), optionally add Helicone-Target-Provider, and continue passing the provider's own Authorization or api-key header as that provider requires.
5. Send a single test request and confirm a Helicone-Id response header comes back, then verify the request and response appear in the Helicone dashboard.
6. Generate your own UUID per request and pass it as Helicone-Request-Id when you need to correlate Helicone records with your application logs.
7. If you use a fine-tuned or custom model name, set Helicone-Model-Override to the base model so Helicone prices the call correctly.
8. If Helicone cannot sit in the critical request path for latency reasons, switch to async logging instead: call the provider directly and ship events out-of-band. Helicone's documentation points to OpenLLMetry as the SDK for this path.
9. Understand what async logging costs you before choosing it: the proxy-vs-async doc is explicit that async forfeits gateway-only features including caching, rate limiting, retries, and moderations.
10. Roll out one service or environment at a time and diff cost and latency dashboards before and after, so a base-URL or auth misconfiguration surfaces on a small blast radius.
11. Store HELICONE_API_KEY and provider keys separately in secrets management so the Helicone key can be rotated independently.
12. Once the basic path is stable, layer on the observability headers (custom properties, user ids, sessions, caching, rate limits) incrementally rather than all at once.