Field conventions
Fields are how spend becomes attributable. Every event carries key–value pairs from your project's registered vocabulary — you declare the keys once on the Fields page (up to 20 per project), and they become the columns of the events table and the filter/group-by pickers in the explorer.
Registration is what keeps your dashboards trustworthy: an unregistered key on
an incoming event is stripped and reported (in the API's ignored array,
surfaced by the SDKs as an ignored-fields warning). The event still lands —
no data loss, no rejected batches over vocabulary — but a typo'd key can never
create a phantom column.
Suggested conventions#
There are no built-in fields — the vocabulary is entirely yours. (Don't
register model or provider: they're top-level keys on the
event itself, and the explorer can already filter and group
by them without any registration.) These two names are just conventions,
but they keep the cost story coherent and set up what comes later:
| Field | What it holds | Why it matters |
|---|---|---|
customer | Who the cost is attributable to — an ID or stable slug | The unit-economics field: "what does customer X cost us?" Future revenue integration will join on it. |
feature | The product surface that made the call — chat, summarize, search | Splits spend by what users actually use. |
One convention that is not a field: environments. Keep production and
staging as separate projects, each with its own API key — dev and test
noise never touches your real numbers, instead of being something you have
to remember to filter out.
Picking good values#
- Prefer stable IDs over display names for
customer— renames and typos fragment your history (acmeandAcme Corpare two different customers to a group-by). - Keep values canonical. Filtering is exact-match:
prodandproductionwon't find each other. - Keys can be up to 64 characters — letters, numbers,
.,_, and-only (the display name is where spaces belong). Values can be up to 256 characters and may be strings, numbers, or booleans.
Changing your vocabulary#
- Adding a field starts recording it on new events immediately. Any member of the project can manage fields.
- Removing a field only unregisters it: new events stop recording it, and historic values stay in the data but are hidden from tables and pickers. Re-register the same key and the history shows up again.
- Renames aren't supported. Removing
custand addingcustomercreates a new key — old events keep their values under the old one.