How do I choose a key label that is reliably present on a source’s events?

Tares sets key_value on each event from the label you mark primary: true, and uses the connector’s default key when no label is primary. To pick a key that is reliably present, open the source’s Fields tab, or call the fields endpoint, and compare each label’s coverage among sampled events and its top values.

How it works

A label is a named axis on an event. You declare it on the source in one of two ways:

• const: a fixed value applied to every event from the source.
• field: a value read per event from a field in the connector’s normalized event.

The label marked primary: true is the key, and Tares stores its value on each event as key_value. If no label is marked primary, Tares uses the connector’s default key. An entity is a (label, value) pair, such as (service, checkout), so the key you choose decides how events group into entities. Because labels are indexed, selecting events by a label is a lookup, not a text scan.

A const label is present on every event from its source by definition. A field label depends on the events actually carrying that field. The Fields tab shows you which it is. For each label and field it reports:

• Coverage: how many of the sampled events actually carry it.
• Top values: the most common values it takes.

High coverage means the label is reliably present. Top values show whether it names the things you want to group by. The concepts page defines these terms in full, see Concepts. The key also feeds triggers: a trigger’s optional key_field names the label that identifies the entity across its sources, and by default it is the primary label of the first source. The wider workflow is in AI SRE.

Set it up

1. Declare the labels you are considering on the source. Mark the one you prefer as primary for now.

labels:
  - { name: service, field: service, primary: true }
  - { name: env, const: prod }

2. Let the source ingest some events, so there is a sample to measure.
3. Open the source’s Fields tab in the console. You can also read the same report from the API:

GET /api/sources/<name>/fields

4. Read the coverage of each label and field. Prefer a label that nearly every sampled event carries. If your candidate has low coverage, look at another field in the list, or declare a const label when the whole source belongs to one value.
5. Read the top values of the candidate. They should look like the entities you want to follow, such as service names or repo names, and not like one-off identifiers.
6. Set primary: true on the label you chose, and remove it from the others. key_value is then set from that label.
7. Open Explore and pick an entity. It lists each label’s distinct values with event counts, so you can confirm the key groups events the way you expect.

What you get

• A key chosen from measured coverage on sampled events, not from a guess about what the connector emits.
• A key_value on events that matches the entity you read, trigger on and hand to agents.
• Top values that show you the real entities a source carries before you commit to a key.
• A clear fallback: with no primary label, the connector’s default key applies.
• Entities you can read as a correlated, time-ordered timeline across sources, because the label is indexed.

When something else fits

• If a connector’s default key already names the entity you care about, you can leave every label without primary: true and skip the choice.
• If every event in a source belongs to one thing, a const label is present on all events and needs no coverage check.
• If a trigger spans several sources and you want a different grouping label than the first source’s primary one, set the trigger’s key_field.

Related