@oneuptime/common 12.0.24 → 12.0.26

package/Types/SecurityEvent/ThreatIntelConstants.ts

@@ -0,0 +1,118 @@
+import OcsfSeverity from "./OcsfSeverity";
+
+/*
+ * The contract between the threat-intel engine and everything that watches
+ * its output — the sibling of DetectionFindingConstants for IOC matches.
+ * The matcher stamps every Threat Intel finding row with these attribute
+ * keys, the ingest-time enricher stamps matched events with the threat.*
+ * keys, and the dashboard's "create a monitor from this feed" flow builds
+ * its filters from the same constants — one source, so a renamed attribute
+ * cannot silently orphan every monitor and Sigma rule built on it.
+ */
+
+// Telemetry service the matcher's findings are attributed to.
+export const THREAT_INTEL_SERVICE_NAME: string = "OneUptime Threat Intel";
+
+/*
+ * productName stamped on finding rows, so IOC findings are filterable
+ * apart from Sigma findings ("OneUptime Detections").
+ */
+export const THREAT_INTEL_PRODUCT_NAME: string = "OneUptime Threat Intel";
+
+/*
+ * Flattened attributes carried by every Threat Intel finding row
+ * (oneuptime.threat.*, mirroring the Sigma engine's oneuptime.detection.*).
+ */
+export const THREAT_FEED_ID_ATTRIBUTE: string = "oneuptime.threat.feed_id";
+export const THREAT_FEED_NAME_ATTRIBUTE: string = "oneuptime.threat.feed_name";
+export const THREAT_INDICATOR_ID_ATTRIBUTE: string =
+  "oneuptime.threat.indicator_id";
+export const THREAT_INDICATOR_TYPE_ATTRIBUTE: string =
+  "oneuptime.threat.indicator_type";
+export const THREAT_INDICATOR_VALUE_ATTRIBUTE: string =
+  "oneuptime.threat.indicator_value";
+export const THREAT_CONFIDENCE_ATTRIBUTE: string =
+  "oneuptime.threat.confidence";
+export const THREAT_MATCH_COUNT_ATTRIBUTE: string =
+  "oneuptime.threat.match_count";
+
+/*
+ * Enrichment attributes stamped onto the MATCHED EVENT itself at ingest
+ * (short threat.* keys, as Sigma rules and monitors will filter on them):
+ * threat.matched is always the literal string "true" on a stamped event.
+ */
+export const ENRICHMENT_MATCHED_ATTRIBUTE: string = "threat.matched";
+export const ENRICHMENT_INDICATOR_ID_ATTRIBUTE: string = "threat.indicator_id";
+export const ENRICHMENT_INDICATOR_TYPE_ATTRIBUTE: string =
+  "threat.indicator_type";
+export const ENRICHMENT_INDICATOR_VALUE_ATTRIBUTE: string =
+  "threat.indicator_value";
+export const ENRICHMENT_FEED_ATTRIBUTE: string = "threat.feed";
+export const ENRICHMENT_FEED_ID_ATTRIBUTE: string = "threat.feed_id";
+export const ENRICHMENT_CONFIDENCE_ATTRIBUTE: string = "threat.confidence";
+export const ENRICHMENT_MATCH_COUNT_ATTRIBUTE: string = "threat.match_count";
+export const ENRICHMENT_MATCHED_VALUE: string = "true";
+
+/*
+ * Normalized indicator types the STIX pattern parser emits. Values are
+ * stored on ThreatIntelIndicator.indicatorType and stamped into the
+ * threat.indicator_type attributes, so they are part of the public
+ * contract — rename only with a data migration.
+ */
+export enum ThreatIntelIndicatorType {
+  Ipv4Address = "ipv4-addr",
+  Ipv6Address = "ipv6-addr",
+  DomainName = "domain-name",
+  Url = "url",
+  EmailAddress = "email-addr",
+  FileHashSha256 = "file-hash-sha256",
+  FileHashSha1 = "file-hash-sha1",
+  FileHashMd5 = "file-hash-md5",
+}
+
+/*
+ * STIX confidence (0-100, 0 meaning "not specified") -> OCSF severity for
+ * finding rows and for alert-severity name matching. Unknown confidence
+ * reads as Medium: an indicator a feed did not score is still an
+ * indicator somebody curated.
+ */
+export function ocsfSeverityForConfidence(confidence: number): OcsfSeverity {
+  if (!Number.isFinite(confidence) || confidence <= 0) {
+    return OcsfSeverity.Medium;
+  }
+
+  if (confidence >= 90) {
+    return OcsfSeverity.Critical;
+  }
+
+  if (confidence >= 70) {
+    return OcsfSeverity.High;
+  }
+
+  if (confidence >= 40) {
+    return OcsfSeverity.Medium;
+  }
+
+  return OcsfSeverity.Low;
+}
+
+/*
+ * Save-time bounds for ThreatIntelFeed.minimumConfidence — one home for
+ * the server validator and the dashboard form, so the two ranges cannot
+ * drift apart. 0 disables the filter (and unscored indicators always
+ * pass it — see ThreatIntelFeedPoller).
+ */
+export const THREAT_INTEL_MINIMUM_CONFIDENCE_MIN: number = 0;
+export const THREAT_INTEL_MINIMUM_CONFIDENCE_MAX: number = 100;
+
+/*
+ * Indicators whose STIX object carries no valid_until stay active this
+ * long after valid_from. STIX says "valid until revoked"; unbounded
+ * validity would grow the IOC table forever, so a year is the ceiling.
+ * The window is ANCHORED at the object's own valid_from — re-polling does
+ * not extend it (an unchanged object is never re-fetched past the
+ * added_after cursor, and an updated one keeps its valid_from); only a
+ * producer update that moves valid_from or sets valid_until changes the
+ * expiry, and objects already past the window are skipped at ingest.
+ */
+export const THREAT_INTEL_DEFAULT_VALID_DAYS: number = 365;

package/Types/SerializableObjectDictionary.ts

@@ -12,6 +12,8 @@ import IncludesNone from "./BaseDatabase/IncludesNone";
 import StartsWith from "./BaseDatabase/StartsWith";
 import EndsWith from "./BaseDatabase/EndsWith";
 import NotContains from "./BaseDatabase/NotContains";
+import Wildcard from "./BaseDatabase/Wildcard";
+import NotWildcard from "./BaseDatabase/NotWildcard";
 import IsNull from "./BaseDatabase/IsNull";
 import LessThan from "./BaseDatabase/LessThan";
 import LessThanOrEqual from "./BaseDatabase/LessThanOrEqual";
@@ -165,6 +167,12 @@ const SerializableObjectDictionary: Dictionary<any> = {
   get [ObjectType.NotContains](): any {
     return NotContains;
   },
+  get [ObjectType.Wildcard](): any {
+    return Wildcard;
+  },
+  get [ObjectType.NotWildcard](): any {
+    return NotWildcard;
+  },
   get [ObjectType.NotNull](): any {
     return NotNull;
   },

package/Types/Telemetry/LlmConventions.ts

@@ -16,6 +16,65 @@
  * lookup helpers return the first key that is present.
  */
 
+/**
+ * The prefix OTLP ingest stamps onto every RESOURCE attribute before the
+ * attributes map reaches any extractor.
+ *
+ * This is not cosmetic and it is the difference between a feature that works
+ * and one that silently reports nothing. All three ingest services flatten
+ * resource attributes through
+ * `TelemetryUtil.getAttributes({ items, prefixKeysWithString: "resource" })`
+ * — OtelTracesIngestService, OtelMetricsIngestService and
+ * OtelLogsIngestService alike. So an operator who sets
+ * `OTEL_RESOURCE_ATTRIBUTES=team.id=platform` does NOT produce an attribute
+ * called `team.id`; they produce one called `resource.team.id`.
+ *
+ * OtelTracesIngestService already learned this the hard way for session
+ * replay (see its `sessionIdAttributeKeys`, which lists both spellings and
+ * whose comment notes that reading only the bare key "would look correct in a
+ * unit test and fail in production"). Identity is the same trap, one tier
+ * worse: identity is precisely the kind of value a fleet stamps ONCE on the
+ * resource rather than on every span, and Cursor documents `cursor.user.id` /
+ * `cursor.team.id` as resource attributes outright.
+ */
+export const RESOURCE_ATTRIBUTE_KEY_PREFIX: string = "resource.";
+
+/**
+ * Widen a key list so it matches both the span-attribute spelling and the
+ * resource-attribute spelling of every key in it.
+ *
+ * The bare block comes FIRST in its entirety, then the resource-prefixed
+ * block, because a span attribute is strictly more specific than a resource
+ * attribute: the resource describes the whole process, the span describes one
+ * call. Preserving each block's internal order keeps the documented
+ * preference ordering intact within each tier.
+ *
+ * Pure and exported so the widening is one tested function rather than a
+ * hand-maintained second copy of every list that drifts the first time
+ * somebody adds a key.
+ */
+export function withResourcePrefixedKeys(keys: Array<string>): Array<string> {
+  return [
+    ...keys,
+    ...keys.map((key: string) => {
+      return `${RESOURCE_ATTRIBUTE_KEY_PREFIX}${key}`;
+    }),
+  ];
+}
+
+/*
+ * Note what is deliberately NOT widened: every list below that carries a
+ * per-CALL value — system, operation, models, tokens, cost, conversation id,
+ * tool name, request parameters, prompts and completions. Those describe one
+ * LLM request and have no business being set on a resource, which describes
+ * the whole process; a resource-scoped `gen_ai.request.model` would be a
+ * misconfiguration, not a convention to support. Widening them would double
+ * the number of map lookups on the hottest ingest path to chase a spelling
+ * nobody emits. Only the IDENTITY lists — user id, user email, team, and the
+ * end-user EXCLUSION list — are widened, because identity is exactly the
+ * value an operator sets once via OTEL_RESOURCE_ATTRIBUTES.
+ */
+
 // Provider / system, e.g. "openai", "anthropic", "aws.bedrock".
 export const LlmSystemAttributeKeys: Array<string> = [
   "gen_ai.system",
@@ -96,6 +155,202 @@ export const LlmAgentNameAttributeKeys: Array<string> = [
   "agent.name",
 ];
 
+/*
+ * ---------------------------------------------------------------------------
+ * WHO ran this call — the EMPLOYEE, never the employee's own customer.
+ * ---------------------------------------------------------------------------
+ *
+ * The LLM feature was born trace-only and had no concept of a human being, so
+ * "which of our engineers burned $4k on Opus last month" was unanswerable. The
+ * three lists below make the human actor a first-class span dimension, so
+ * spend can be grouped by person and by cost centre.
+ *
+ * THE CORRECTNESS RULE, and it is not a stylistic one: an LLM span can carry
+ * TWO different humans. The employee who made the call, and the DOWNSTREAM
+ * CUSTOMER on whose behalf the call was made (OpenAI's `user` request
+ * parameter, which instrumentations echo back as gen_ai.user / llm.user, and
+ * LiteLLM's end-user id). Those two are not interchangeable. Mapping a
+ * downstream customer into the employee columns produces internal chargeback
+ * that is not merely imprecise but WRONG — a support bot serving 40k
+ * customers would manufacture 40k phantom "employees", and the engineer who
+ * actually owns that spend would appear to have spent nothing.
+ *
+ * So the customer-identity keys are enumerated separately in
+ * LlmEndUserAttributeKeys below and are deliberately NOT read into any
+ * column. The exclusion is pinned by a test; if someone later wants
+ * downstream-customer analytics it must land in its OWN column, never by
+ * appending a key to the lists below.
+ */
+
+/*
+ * The employee / internal actor id.
+ *
+ * Provenance, preferred first:
+ *   - user.id      OTel general semantic conventions; THE canonical key for
+ *                  the human actor and the one to standardize on.
+ *   - enduser.id   Also still an ACTIVE semconv attribute — the 1.25
+ *                  deprecation removed enduser.role and enduser.scope only,
+ *                  so this remains a legitimate, widely-emitted spelling.
+ *   - litellm.metadata.user_api_key_user_id  /  metadata.user_api_key_user_id
+ *                  LiteLLM proxy: the internal user who OWNS the virtual key
+ *                  the request authenticated with. Note the sibling key
+ *                  user_api_key_end_user_id is the CUSTOMER and is excluded.
+ *
+ *                  BOTH spellings are required, and the bare one is the one
+ *                  that actually fires for most deployments. LiteLLM's
+ *                  default `otel` callback (v1) stamps its metadata with a
+ *                  bare "metadata." prefix — see METRIC_METADATA_KEYS and the
+ *                  `common_attrs[f"metadata.{key}"]` assignment in
+ *                  litellm/integrations/opentelemetry.py. The "litellm."
+ *                  namespace only appears under OpenTelemetry v2, which is
+ *                  OFF by default (LITELLM_OTEL_V2, `enabled: default=False`).
+ *                  Recognizing only the v2 spelling meant a stock LiteLLM
+ *                  proxy — the exact "one virtual key per employee" setup our
+ *                  docs recommend as the cleanest chargeback architecture —
+ *                  produced ZERO attribution, silently, with every gateway
+ *                  dollar landing in Unattributed and no error to explain it.
+ *   - traceloop.association.properties.user_id   OpenLLMetry.
+ *   - langfuse.user.id                           Langfuse.
+ *   - user.account_uuid / user.account_id        Claude Code (and Codex for
+ *                  the latter) stamp the signed-in account onto every span.
+ *   - cursor.user.id   Cursor's OTel export; an opaque team-scoped integer,
+ *                  which is why it sorts last — it needs the Cursor admin API
+ *                  to resolve to a person, unlike the keys above.
+ *
+ * The `Base` list is the SPAN-attribute spelling only. Consumers must import
+ * LlmUserIdAttributeKeys, which adds the resource-attribute tier — see
+ * withResourcePrefixedKeys. The base list is exported solely so tests and
+ * docs can cross-check the two tiers against each other.
+ */
+export const LlmUserIdBaseAttributeKeys: Array<string> = [
+  "user.id",
+  "enduser.id",
+  // LiteLLM OTel v2 spelling, then the v1 default. Both are needed — see above.
+  "litellm.metadata.user_api_key_user_id",
+  "metadata.user_api_key_user_id",
+  "traceloop.association.properties.user_id",
+  "langfuse.user.id",
+  "user.account_uuid",
+  "user.account_id",
+  "cursor.user.id",
+];
+
+export const LlmUserIdAttributeKeys: Array<string> = withResourcePrefixedKeys(
+  LlmUserIdBaseAttributeKeys,
+);
+
+/*
+ * The employee's email address — in practice the only identity value a
+ * manager can read without a lookup table, which is why it gets its own
+ * column rather than being folded into the id.
+ *
+ * user.email is the OTel general-semconv key and is emitted NATIVELY by
+ * Claude Code, Gemini CLI and OpenAI Codex, so for the coding-agent fleet
+ * this list is usually the one that hits.
+ *
+ * The two LiteLLM spellings matter more than their position suggests: the
+ * proxy carries the key owner's email in its metadata (user_api_key_user_email
+ * is in METRIC_METADATA_KEYS), so a gateway issuing one virtual key per
+ * employee yields a real, human-readable email with no lookup table and no
+ * per-application instrumentation. That is the cleanest chargeback setup
+ * available today, and it is what our AI-gateway guide recommends. As with
+ * the id list, the bare "metadata." spelling is the DEFAULT one and the
+ * "litellm." namespace only appears under the opt-in OpenTelemetry v2 mode.
+ *
+ * Because this column holds real PII, TraceScrubRuleService scrubs it under
+ * the Attributes scope exactly as it scrubs the attribute it was derived from
+ * — see the identity-column pass in scrubSpan. A denormalized column that
+ * skipped the scrub pass would make a customer's email-redaction rule
+ * silently ineffective on the very column most likely to hold an email.
+ */
+export const LlmUserEmailBaseAttributeKeys: Array<string> = [
+  "user.email",
+  // LiteLLM OTel v2 spelling, then the v1 default. Both are needed — see above.
+  "litellm.metadata.user_api_key_user_email",
+  "metadata.user_api_key_user_email",
+  "traceloop.association.properties.user_email",
+  "enduser.email",
+];
+
+export const LlmUserEmailAttributeKeys: Array<string> =
+  withResourcePrefixedKeys(LlmUserEmailBaseAttributeKeys);
+
+/*
+ * The team / cost centre the spend charges to.
+ *
+ * The first four are not emitted by any instrumentation on their own: they
+ * are what an organization sets via OTEL_RESOURCE_ATTRIBUTES on the agent
+ * process (OTEL_RESOURCE_ATTRIBUTES=team.id=platform,cost_center=RD-114), and
+ * are conventionally the ONLY way a coding-agent CLI learns which budget it
+ * belongs to. The remaining entries are the gateway/vendor spellings that
+ * arrive without any operator configuration.
+ *
+ * That first sentence is exactly why the resource tier is not optional here:
+ * OTEL_RESOURCE_ATTRIBUTES sets a RESOURCE attribute, which ingest delivers
+ * as `resource.team.id`. A list of bare keys alone would mean the one
+ * mechanism the docs present as THE way to attribute spend to a cost centre
+ * never matches a single row.
+ */
+export const LlmTeamBaseAttributeKeys: Array<string> = [
+  "team.id",
+  "team",
+  "cost_center",
+  "department",
+  // LiteLLM OTel v2 spellings, then the v1 default. See the id list above.
+  "litellm.metadata.user_api_key_team_id",
+  "litellm.team.id",
+  "metadata.user_api_key_team_id",
+  "cursor.team.id",
+];
+
+export const LlmTeamAttributeKeys: Array<string> = withResourcePrefixedKeys(
+  LlmTeamBaseAttributeKeys,
+);
+
+/*
+ * DELIBERATELY EXCLUDED — the DOWNSTREAM CUSTOMER, not the employee.
+ *
+ * Exported so the exclusion is a documented, testable decision rather than an
+ * omission somebody "fixes" later:
+ *
+ *   - gen_ai.user / llm.user
+ *       Both carry the OpenAI `user` REQUEST PARAMETER, which the API
+ *       documents as the caller's own end user, sent for abuse monitoring. On
+ *       a SaaS product's spans this is the SaaS product's customer.
+ *   - litellm.metadata.user_api_key_end_user_id  /
+ *     metadata.user_api_key_end_user_id  /  litellm.end_user.id
+ *       LiteLLM's explicit end-user id, distinct from the key-owner id above
+ *       (which IS the employee and IS recognized). All three spellings are
+ *       listed for the same reason the employee lists carry two: the bare
+ *       "metadata." form is what the DEFAULT v1 otel callback emits, while
+ *       "litellm.end_user.id" is the dedicated attribute the opt-in v2 mode
+ *       defines in litellm/integrations/otel/model/semconv.py. Excluding only
+ *       the v2 metadata spelling would leave the two spellings a real
+ *       deployment actually produces free to be mistaken for an employee.
+ *
+ * None of these is denormalized into a column by this change. They remain
+ * available in the raw attributes map for anyone who queries them directly.
+ *
+ * This list is resource-widened too, and for the OPPOSITE reason to the
+ * lists above. Here the widening does not make anything match — it makes the
+ * EXCLUSION hold. The exclusion is enforced as a set relation ("no end-user
+ * key appears in an employee list"), so if this list stopped at the bare
+ * spellings while the employee lists carried both tiers, a future
+ * `resource.gen_ai.user` could be appended to an employee list and every
+ * exclusion test would still pass. Both tiers here, both tiers there.
+ */
+export const LlmEndUserBaseAttributeKeys: Array<string> = [
+  "gen_ai.user",
+  "llm.user",
+  "litellm.metadata.user_api_key_end_user_id",
+  "metadata.user_api_key_end_user_id",
+  "litellm.end_user.id",
+];
+
+export const LlmEndUserAttributeKeys: Array<string> = withResourcePrefixedKeys(
+  LlmEndUserBaseAttributeKeys,
+);
+
 export const LlmToolNameAttributeKeys: Array<string> = [
   "gen_ai.tool.name",
   "tool.name",

package/Types/Telemetry/LlmMetricConventions.ts

@@ -1,3 +1,5 @@
+import { withResourcePrefixedKeys } from "./LlmConventions";
+
 /*
  * Single source of truth for the OpenTelemetry GenAI **metric** names and
  * attribute keys OneUptime recognizes — the metric-side sibling of
@@ -30,6 +32,51 @@ export const LlmTokenUsageMetricNames: Array<string> = [
   "gen_ai.client.token.count",
   "llm.token.usage",
   "llm.usage.tokens",
+  /*
+   * Coding-agent CLIs. Every one of these ships OpenTelemetry natively and
+   * every one namespaces its metrics under its own vendor prefix rather than
+   * gen_ai.*, so before this list knew their names an entire fleet of agents
+   * could be exporting straight into OneUptime and still report zero tokens
+   * and zero spend. That is the failure mode these three entries fix.
+   */
+  // Anthropic Claude Code CLI.
+  "claude_code.token.usage",
+  // Cursor Enterprise OTel export.
+  "cursor.token.usage",
+  // OpenAI Codex CLI.
+  "codex.turn.token_usage",
+  /*
+   * DELIBERATELY ABSENT: "gemini_cli.token.usage".
+   *
+   * Gemini CLI emits BOTH its vendor metric and the semantic-convention
+   * `gen_ai.client.token.usage` for the SAME tokens (see the metric table in
+   * Docs/Content/en/telemetry/gemini-cli-and-copilot.md, which lists the two
+   * side by side). LlmMetricQuery.buildTokenQuery issues ONE query with
+   * `name: new Includes(LlmTokenUsageMetricNames)` and groups only by the
+   * token-TYPE attribute keys — never by metric name — so both emissions come
+   * back as separate rows and reduceTokenRows adds them together. Listing
+   * both names would make a Gemini-CLI-only project report exactly 2x its
+   * real token count on the AI / LLM Usage view, with no error and no gap in
+   * the chart to give it away.
+   *
+   * Nothing is lost by the omission: the semconv name that stays in this list
+   * is emitted by Gemini CLI itself, so its tokens are still counted — once.
+   *
+   * AUDIT of the three names above, against the vendor docs in
+   * Docs/Content/en/telemetry/, because this hazard applies to any emitter
+   * that publishes two token metrics:
+   *   - claude_code.token.usage   Claude Code's metric table is entirely
+   *       claude_code.* — no gen_ai.* metric. Its gen_ai.* keys are on SPANS,
+   *       which are a different stream and are summed separately.
+   *   - cursor.token.usage        Cursor publishes exactly three metrics, all
+   *       cursor.*, and emits no gen_ai.* telemetry at all.
+   *   - codex.turn.token_usage    Codex's metrics are codex.*; its gen_ai.*
+   *       usage attributes are on SPANS, not metrics.
+   * None of the three overlaps a semconv metric, so all three stay.
+   *
+   * Before re-adding ANY vendor token metric, check whether the same process
+   * also emits gen_ai.client.token.usage. If it does, leave it out.
+   */
 ];
 
 /*
@@ -47,6 +94,42 @@ export const LlmCostMetricNames: Array<string> = [
   // LiteLLM proxy.
   "litellm_spend_metric",
   "litellm.cost.total",
+  // Anthropic Claude Code CLI — unit USD.
+  "claude_code.cost.usage",
+  /*
+   * Cursor Enterprise OTel export — unit USD, and documented as a
+   * best-effort estimate rather than a billed figure. It is still worth
+   * summing: an estimate that is visible beats a true cost nobody can see.
+   */
+  "cursor.cost.usage",
+];
+
+/**
+ * The multiplier that turns a micro-USD figure into USD. Exported so the
+ * scale lives in exactly one place that a test can pin, rather than as a
+ * literal 0.000001 sprinkled through the query layer where a typo'd zero
+ * would be invisible in review and off by a factor of ten in production.
+ */
+export const MICRO_USD_TO_USD: number = 0.000001;
+
+/*
+ * Cost metric names denominated in MILLIONTHS of a USD.
+ *
+ * This list exists separately from LlmCostMetricNames for one reason, and it
+ * is worth being blunt about it: the OpenAI Codex CLI reports spend in
+ * micro-USD. If "codex.turn.cost_microusd" were appended to the USD list, the
+ * shared Sum aggregate would add its raw values to genuinely-USD values and a
+ * $3 Codex turn would land in a cost budget as $3,000,000 — instantly
+ * breaching every threshold a customer has configured. There is no way to
+ * recover the unit after the sum, so the two units must never share a query.
+ *
+ * Callers query this separately and combine via
+ * LlmMetricQuery.combineCostTotals, which applies MICRO_USD_TO_USD in the one
+ * tested place.
+ */
+export const LlmMicroUsdCostMetricNames: Array<string> = [
+  // OpenAI Codex CLI — unit is millionths of a USD, NOT dollars.
+  "codex.turn.cost_microusd",
 ];
 
 /*
@@ -57,6 +140,22 @@ export const LlmCostMetricNames: Array<string> = [
 export const LlmTokenTypeAttributeKeys: Array<string> = [
   "gen_ai.token.type",
   "llm.token.type",
+  /*
+   * Claude Code spells it bare: `type`.
+   *
+   * A one-word key like this looks alarmingly generic, and the risk is worth
+   * spelling out because it is bounded rather than absent: these keys are
+   * consulted ONLY for rows that already matched one of the LLM metric NAMES
+   * above. A `type` attribute on some unrelated business metric is never
+   * reached by this code path, because that metric's name never enters the
+   * query. The key is also last-but-two in preference order, so any emitter
+   * carrying a namespaced spelling as well wins over it.
+   */
+  "type",
+  // Cursor Enterprise OTel export.
+  "cursor.token.type",
+  // OpenAI Codex CLI.
+  "token_type",
 ];
 
 /*
@@ -68,18 +167,124 @@ export const LlmInputTokenTypeValues: Array<string> = ["input", "prompt"];
 /*
  * Attribute values that mean "tokens produced by the model".
  *
- * Note what is deliberately absent: cache_read / cache_creation. Those are
- * real token counts, but they are neither input nor output in the sense the
- * span columns (llmInputTokens / llmOutputTokens) use, and folding them in
- * would silently inflate the metric-sourced totals relative to the
- * span-sourced ones they stand in for.
+ * Note what is deliberately absent, and why each exclusion is its own
+ * decision rather than an oversight. The coding-agent CLIs emit a richer
+ * token vocabulary than the semconv does:
+ *
+ *   Claude Code  input | output | cacheRead | cacheCreation   (camelCase!)
+ *   Cursor       input | output | cache_read | cache_creation
+ *   Codex        total | input | cached_input | cache_write_input |
+ *                output | reasoning_output
+ *
+ * The plain input/output values are covered by the two lists here and need
+ * nothing added. The rest are excluded on purpose:
+ *
+ *   - cache_read / cacheRead / cached_input, and
+ *     cache_creation / cacheCreation / cache_write_input
+ *       Real token counts, but neither input nor output in the sense the span
+ *       columns (llmInputTokens / llmOutputTokens) use. Folding them in would
+ *       silently inflate the metric-sourced totals against the span-sourced
+ *       ones they stand in for. Cache-aware accounting deserves its own
+ *       columns; until it has them, these are dropped rather than guessed at.
+ *   - total
+ *       A SUPERSET of its siblings. Codex emits it ALONGSIDE the per-kind
+ *       datapoints, so counting it would add every token a second time.
+ *   - reasoning_output
+ *       A SUBSET of `output` — the reasoning share of the same tokens, which
+ *       Codex also reports under `output`. Counting it would double-count the
+ *       reasoning portion of every turn.
+ *
+ * Both classes are pinned by explicit getLlmTokenDirection tests, so a future
+ * "why is this not handled?" reads as a decision, not a gap.
  */
 export const LlmOutputTokenTypeValues: Array<string> = ["output", "completion"];
 
+/*
+ * Attribute keys naming WHO the metric datapoint belongs to, for grouping
+ * metric-sourced spend by employee — the metric-side counterpart of
+ * LlmUserIdAttributeKeys in Common/Types/Telemetry/LlmConventions.ts.
+ *
+ * Email leads here rather than id (the span list is the other way round)
+ * because the coding-agent CLIs that dominate the metric-only population emit
+ * user.email natively, and it is the one value a manager reads without a
+ * lookup table. cursor.user.id sorts last for the same reason it does on the
+ * span side: it is an opaque team-scoped integer.
+ *
+ * Both lists below are resource-widened for the same reason the span lists
+ * are: OtelMetricsIngestService flattens resource attributes with the
+ * "resource" prefix exactly as the traces service does, so a fleet that
+ * stamps identity once on the resource — which is the normal thing to do, and
+ * the only thing OTEL_RESOURCE_ATTRIBUTES can do — arrives here as
+ * `resource.user.email` / `resource.team.id`. The bare tier still leads, so
+ * METRIC_USER_ATTRIBUTE_KEY / METRIC_TEAM_ATTRIBUTE_KEY (element zero, used
+ * for scoped filtering in LlmMetricQuery) are unchanged.
+ */
+export const LlmMetricUserBaseAttributeKeys: Array<string> = [
+  "user.email",
+  "user.id",
+  "user.account_uuid",
+  "user.account_id",
+  "cursor.user.id",
+];
+
+export const LlmMetricUserAttributeKeys: Array<string> =
+  withResourcePrefixedKeys(LlmMetricUserBaseAttributeKeys);
+
+/*
+ * Attribute keys naming the team / cost centre a metric datapoint charges to.
+ * The first four are conventionally set by the operator via
+ * OTEL_RESOURCE_ATTRIBUTES rather than emitted by any instrumentation — which
+ * is precisely why the resource tier has to be here too; see above.
+ */
+export const LlmMetricTeamBaseAttributeKeys: Array<string> = [
+  "team.id",
+  "team",
+  "cost_center",
+  "department",
+  "cursor.team.id",
+];
+
+export const LlmMetricTeamAttributeKeys: Array<string> =
+  withResourcePrefixedKeys(LlmMetricTeamBaseAttributeKeys);
+
+/*
+ * Attribute keys naming WHICH MODEL a metric datapoint was produced by.
+ *
+ * This exists because the vendor cost/token counters DO carry the model on
+ * the datapoint even though they carry no provider and no service id:
+ * claude_code.cost.usage and claude_code.token.usage stamp a bare `model`,
+ * and cursor.cost.usage stamps `cursor.model.name`. Without this list the
+ * Model breakdown is empty for an entire fleet of coding agents whose spend
+ * is perfectly well attributed to a model — the same failure the user list
+ * above fixes for people.
+ *
+ * `model` is bare and looks alarmingly generic, and the bound is the same one
+ * that makes the bare `type` token key safe: these keys are only ever read
+ * off rows that already matched one of the LLM metric NAMES above, so a
+ * `model` attribute on some unrelated business metric is never reached. It
+ * also sorts after the semantic-convention spelling, so an emitter carrying
+ * both wins with the namespaced one.
+ *
+ * Resource-widened for the same reason the identity lists are: a fleet that
+ * pins one model per deployment sets it once via OTEL_RESOURCE_ATTRIBUTES,
+ * and OtelMetricsIngestService flattens that to `resource.model`.
+ */
+export const LlmMetricModelBaseAttributeKeys: Array<string> = [
+  "gen_ai.request.model",
+  // Anthropic Claude Code CLI — bare, on both its cost and token counters.
+  "model",
+  // Cursor Enterprise OTel export.
+  "cursor.model.name",
+];
+
+export const LlmMetricModelAttributeKeys: Array<string> =
+  withResourcePrefixedKeys(LlmMetricModelBaseAttributeKeys);
+
 /**
  * Which side of the exchange a `gen_ai.token.type` value denotes, or null
- * when the value is one we deliberately do not count (cache_read,
- * cache_creation) or do not recognize at all.
+ * when the value is one we deliberately do not count (the cache kinds,
+ * `total`, `reasoning_output` — see LlmOutputTokenTypeValues for why each is
+ * excluded) or do not recognize at all.
  *
  * Comparison is case-insensitive and whitespace-trimmed: the value reaches us
  * as a free-form OTLP string attribute, and emitters are inconsistent about