What do Helicone-Property-* headers do to a logged request, and why set them?

## The problem properties solve A logging tool that records every LLM call gives you a firehose: thousands of rows, each with a model, a prompt, a latency and a cost. The question you actually have is never "what did request 84719 cost" — it is "which feature is burning the budget", "is staging traffic polluting my production numbers", "which tenant is responsible for the p99". Answering those requires the log row to carry the dimension you want to slice by, and only your application knows it. Custom properties are the channel for that knowledge. ## The mechanism Any request header whose name begins with `Helicone-Property-` is treated as a custom property. The remainder of the header name is the property name; the header value is the property value. ``` Helicone-Property-Environment: production Helicone-Property-Feature: ticket-summary Helicone-Property-AppVersion: 2026.8.3 ``` Helicone stores those with the request and exposes them as columns you can filter and group by. There is no schema to register in advance and no configuration step: the first request carrying a new property name creates the dimension. Because they are ordinary request headers, they compose naturally with how clients are constructed. Stable values — environment, service name, release version — belong in the client's default headers so every call carries them without thought. Call-specific values — which feature or workflow made this particular call — are set per request. ## Designing the vocabulary The mechanism is trivial; using it well is the skill. **Low cardinality.** A property is useful in proportion to how many requests share each value. `Feature: summarizer` with ten thousand rows behind it is a useful group. A property whose value is unique per request produces ten thousand groups of one and is unusable for aggregation, while bloating the dimension. Reserve identity for `Helicone-User-Id` and per-run grouping for the session headers, which exist precisely so you are not tempted to abuse a property for them. **Enumerable and stable.** If you cannot list the possible values of a property on a whiteboard, it is probably the wrong property. Free-form values drift — `prod`, `production` and `Production` become three groups that should have been one — so normalise them in one place rather than at every call site. **No secrets and no PII.** A property value is stored in the trace record and visible to anyone with dashboard access. API keys, tokens, email addresses and raw user content do not belong there. **Not retroactive.** Properties describe the request that carried them. Traffic logged before you introduced a property simply has no value for it, so comparisons across the rollout boundary are misleading. Add the dimension ahead of the investigation you expect to need it for. ## What you get back Once the vocabulary exists, the dashboards answer real questions without further work: - **Cost attribution.** Spend grouped by feature or tenant, which is the input to any chargeback or pricing conversation. - **Environment hygiene.** Filtering staging and evaluation traffic out of production numbers — worth doing on day one, since eval runs can dwarf real traffic. - **Change tracking.** Grouping by app or prompt version to see whether a release moved latency, token consumption or cost. - **Triage.** Narrowing an incident to the subset of traffic that shares a property value, instead of scrolling a global log. ## Mode independence Properties are fields on the log record, not an interception feature, so they work the same whether the request went through the proxy or was reported by async logging. In proxy mode they ride as request headers; in async logging they are part of the payload you send. That is what keeps a mixed fleet coherent: services on either integration land in the same project and can be sliced by the same dimensions, as long as they agree on the names. ## The usual mistakes Teams that get little value out of properties almost always made one of three mistakes: they let every service invent its own names, so nothing aggregates across the fleet; they put something unbounded in a value, so the dimension is meaningless; or they added the header only after an incident, and discovered the historical data they wanted does not exist. All three are avoidable by setting a small, agreed vocabulary in a shared client wrapper before you need it.