frugal-sdk-python 0.4.0__tar.gz → 0.6.0__tar.gz

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: frugal-sdk-python
-Version: 0.4.0
+Version: 0.6.0
 Summary: Instrumentation for Cost-to-Code attribution.
 Project-URL: Homepage, https://frugal.co
 Author: Frugal AI Inc.
@@ -62,7 +62,7 @@ All configuration is via environment variables. No `init()` call, no configurati
 
 ### Required
 
-Set both or the wrapper silently returns the client unmodified:
+Console mode (`FRUGAL_METRICS_EXPORTER=console`) needs only `FRUGAL_PROJECT_ID`; every other mode needs both. If a required variable is unset, the wrapper silently returns the client unmodified:
 
 | Variable            | Purpose                                                    |
 | ------------------- | ---------------------------------------------------------- |
@@ -71,21 +71,27 @@ Set both or the wrapper silently returns the client unmodified:
 
 ### Optional
 
+The export endpoint and authentication come only from `FRUGAL_`-prefixed variables, so the SDK never crosses wires with the host's own OTel pipeline: the generic `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are never read. (The OTel exporter library still reads its own generic TLS, compression, timeout and temporality variables.)
+
 | Variable                                 | Purpose                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------- |
 | `FRUGAL_CUSTOMER_ID`                     | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `FRUGAL_REPO_ROOT`                       | Absolute path to the source root; the strip prefix for `caller_file`. Defaults to the process working directory. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_API_KEY`. Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
-| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. |
+| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics` (also when set but empty). |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Precedence: this variable wins; otherwise the header built from `FRUGAL_API_KEY` (`FRUGAL_METRICS_API_KEY` first), which is sent verbatim. Values set here are percent-decoded (`Bearer%20tok` → `Bearer tok`). A value with no `key=value` pair is treated as missing auth (the API key is not used instead); a blank (whitespace-only) value is treated as unset. |
+| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. Deduped, and only the first **10** entries are honored (hard cap, not configurable); the rest are dropped at startup with one debug warning. |
 | `FRUGAL_CUSTOM_PROVIDERS`                | Comma-separated allowlist of provider names beyond the built-in registry (e.g. `together_ai,fireworks`) that should pass through verbatim on `gen_ai.system` / `gen_ai.provider.name` instead of being coerced to `custom`. Capped at 10 (extras are coerced) to keep label cardinality bounded. |
-| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; a value outside the first 20 entries (hard cap, not configurable) is coerced to `other`. |
+| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`. The vocabulary is the first **20** comma-separated entries by raw position (hard cap, not configurable); empty entries are ignored and duplicates collapsed. `other` is reserved (the coercion sentinel) and is ignored with one warning. A value outside the allowlist is coerced to `other` with a bounded once-per-value warning; when the variable is unset, every value is `other`. One warning fires only when non-empty entries past the 20th are actually dropped (a trailing comma does not warn). |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console` (print metrics to stdout; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored). Case-insensitive; any other value warns once and uses `otlp`. |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`, for apps that already use those names. An empty value falls through to the bare name. |
 | `FRUGAL_PATH_BLOCK_LIST`                 | Comma-separated repo-relative paths to skip for caller attribution (see below).          |
-| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds. Default `60000`.                                         |
-| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute. Default `500`. Set to `0` to disable. |
-| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. |
+| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds, `1`-`2147483647`. Default `60000`; a value outside the range warns once and uses the default.                                      |
+| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute; past it `frugal.caller_file` / `frugal.caller_function` become `<overflow>`. Default `500`. Set to `0` to disable. |
+| `FRUGAL_MAX_MODELS`                      | Cardinality cap — max distinct model strings to attribute; past it `gen_ai.request.model` / `gen_ai.response.model` become `<overflow>`. One registry shared by both labels, so a request alias and its dated response snapshot each take a slot. Default `100`. Set to `0` to disable. |
+| `FRUGAL_MAX_SERIES_PER_INSTRUMENT`       | OpenTelemetry's per-instrument limit on distinct attribute **combinations**, raised from the SDK default. Default `50000`. Set to `0` for effectively unlimited (a 1,000,000 ceiling). Applied **only when the installed `opentelemetry-sdk` accepts a per-instrument cardinality limit** — current releases (through 1.42) do not implement one, so nothing is capped and setting this variable emits one `warn` telling you it has no effect. |
+| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls that run the lightweight prompt analyzer: a decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. Default `0.1`. Set to `0` to disable, `1` for every call. |
 | `FRUGAL_DUPLICATE_REQUEST_DETECTION`     | Duplicate-request detection (the `frugal.gen_ai.duplicate_requests` metric) is **on by default** and hashes each chat request in-process (the hash never leaves the SDK). Set to `0`/`false`/`no`/`off` to disable — no hashing, no filter memory, no metric. |
-| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `604800` (7 days). |
+| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `86400` (1 day). |
 | `FRUGAL_DUPLICATE_CAPACITY`              | Expected distinct request signatures per window (sizes the in-memory filter). Default `10000`, max `1000000`. Raise it if the SDK warns the filter is saturated. |
 | `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate of the duplicate filter. Default `0.01`, clamped to `[1e-6, 0.5]`. |
 | `FRUGAL_DUPLICATE_GENERATIONS`           | Rotation granularity of the duplicate filter's time window. Default `2`, max `16`.        |
@@ -103,8 +109,9 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | `frugal.gen_ai.cache_read_tokens`       | histogram | Prompt cache hits                                            | —                                      |
 | `frugal.gen_ai.cache_write_tokens`      | histogram | Prompt cache writes                                          | —                                      |
 | `frugal.gen_ai.reasoning_tokens`        | histogram | OpenAI reasoning tokens (o-series), Anthropic thinking tokens| —                                      |
+| `frugal.gen_ai.agent.turns`             | histogram | Model-response turns per successful `invoke_agent` call (manual only) | —                              |
 | `frugal.gen_ai.errors`                  | counter   | Errors by exception type                                     | `frugal.error.type`                    |
-| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality cap, bugs)     | `frugal.internal_error.stage`          |
+| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality caps, bugs)    | `frugal.internal_error.stage`, `frugal.internal_error.type`, `frugal.instrument` |
 | `frugal.gen_ai.output_cap_utilization`  | histogram | `output_tokens / max_tokens` ratio when `max_tokens` is set  | `frugal.structured_output_mode`        |
 | `frugal.gen_ai.history_depth`           | histogram | `messages.length` — every chat call (100%, not sampled)      | —                                      |
 | `frugal.gen_ai.duplicate_requests`      | counter   | Repeat-request detection — every chat call (100%, not sampled; disable via `FRUGAL_DUPLICATE_REQUEST_DETECTION`) | `frugal.dup_state` |
@@ -121,15 +128,17 @@ The analyzer-sampled metrics fire on a fraction of calls
 Every metric carries this base attribute set (except
 `frugal.gen_ai.internal_errors`, which is emitted from failure paths where
 these attributes may not exist yet and carries only `frugal.project_id`, the
-stage/type, and `frugal.customer_id` / `frugal.custom_label` when set):
+stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
+`frugal.customer_id` / `frugal.custom_label` when set; `frugal.custom_label`
+never on the setup_failed / emission stages):
 
 - `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
 - `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
 - `gen_ai.system` + `gen_ai.provider.name` — the provider, dual-emitted under both the legacy and current OTel attribute (`openai`, `anthropic`, `aws.bedrock`, `vertex_ai`/`gcp.vertex_ai`, …, or `custom`). Set via the `system` kwarg; an unrecognized value is coerced to `custom` with a one-time warning. See [`docs/metrics-reference.md`](docs/metrics-reference.md#attributes).
-- `gen_ai.request.model`, `gen_ai.response.model` — the model used
+- `gen_ai.request.model`, `gen_ai.response.model` — the model used; both draw on one shared registry and become `<overflow>` past `FRUGAL_MAX_MODELS` distinct model strings
 - `gen_ai.operation.name` — `chat`, `text_completion`, `embeddings`, `generate_content`, `execute_tool`, `create_agent`, `invoke_agent`, or `other` (the sentinel an unrecognized operation coerces to)
 - `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise
-- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other`
+- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other` (with a once-per-value warning). `custom_label=None` means no label; a non-string value is coerced to `other`
 
 The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
 
@@ -169,6 +178,39 @@ with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
     )
 ```
 
+For an enclosing agent invocation, set `operation="invoke_agent"` and report
+the number of model-response steps performed inside it:
+
+```python
+with track_ai_call(
+    system="anthropic",
+    operation="invoke_agent",
+    request_model="claude-sonnet-4-20250514",
+) as span:
+    result = my_agent_framework_call(prompt)
+    span.set_usage(
+        input_tokens=result.usage.input_tokens,
+        output_tokens=result.usage.output_tokens,
+        agent_turns=result.turn_count,
+    )
+```
+
+- Provider wrappers still measure individual model calls and never set
+  `agent_turns`.
+- Agent frameworks such as the Claude Agent SDK, OpenAI Agents SDK, and
+  LangGraph do not have dedicated wrappers yet; track them manually as shown.
+- `frugal.gen_ai.history_depth` is the request message count
+  (`messages.length`), not a turn count.
+- Missing, non-integer, non-positive, or otherwise invalid `agent_turns`
+  values are silently dropped. They never raise or affect customer execution.
+- Turn data is emitted only on success, like token usage.
+- **Avoid double-counting tokens.** Only report aggregate `input_tokens` /
+  `output_tokens` on the `invoke_agent` call when the agent's inner
+  model-client calls are **not** already wrapped by a supported provider
+  wrapper. If they are wrapped, those wrappers already emit token usage per
+  inner call — report `agent_turns` only on the `invoke_agent` call in that
+  case, or the same tokens are double-counted.
+
 The `with` block times the call and emits metrics on exit — or an error metric if the block raises (the exception always propagates). Works the same around an `await` in async code. Call `span.set_usage(...)` once the response is back; if you never call it, you still get a call-count and latency point.
 
 For calls that span function boundaries — where a single `with` block won't fit — use the manual handle:
@@ -191,9 +233,9 @@ except BaseException as exc:
 
 `success()` and `error()` finalize the call exactly once and are idempotent — extra calls are ignored.
 
-**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call except the `frugal.gen_ai.internal_errors` setup_failed / emission points; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
 
-**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `response_model`.
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `agent_turns`, `response_model`.
 
 The same env-var configuration, safety guarantees, and exported metrics apply. See [`docs/quickstart.md`](docs/quickstart.md#custom-call-sites) for the full custom call-site walkthrough.
 
@@ -290,14 +332,27 @@ It is **opt-in** because installing signal handlers is intrusive. If you run you
 
 ## Verifying the setup
 
-Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them. Console mode needs only `FRUGAL_PROJECT_ID`; the API key,
+endpoint and header variables are ignored. An empty
+endpoint does not select the console exporter: it falls through to the default
+Frugal endpoint.
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+python my_script.py
+```
+
+Or point the library at a local OTLP/HTTP collector to see what it exports:
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=test-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 python my_script.py
 ```
 
-You should see JSON metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
+The collector should receive metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.6.0}/README.md

@@ -33,7 +33,7 @@ All configuration is via environment variables. No `init()` call, no configurati
 
 ### Required
 
-Set both or the wrapper silently returns the client unmodified:
+Console mode (`FRUGAL_METRICS_EXPORTER=console`) needs only `FRUGAL_PROJECT_ID`; every other mode needs both. If a required variable is unset, the wrapper silently returns the client unmodified:
 
 | Variable            | Purpose                                                    |
 | ------------------- | ---------------------------------------------------------- |
@@ -42,21 +42,27 @@ Set both or the wrapper silently returns the client unmodified:
 
 ### Optional
 
+The export endpoint and authentication come only from `FRUGAL_`-prefixed variables, so the SDK never crosses wires with the host's own OTel pipeline: the generic `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are never read. (The OTel exporter library still reads its own generic TLS, compression, timeout and temporality variables.)
+
 | Variable                                 | Purpose                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------- |
 | `FRUGAL_CUSTOMER_ID`                     | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `FRUGAL_REPO_ROOT`                       | Absolute path to the source root; the strip prefix for `caller_file`. Defaults to the process working directory. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. |
-| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_API_KEY`. Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
-| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. |
+| `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics` (also when set but empty). |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Precedence: this variable wins; otherwise the header built from `FRUGAL_API_KEY` (`FRUGAL_METRICS_API_KEY` first), which is sent verbatim. Values set here are percent-decoded (`Bearer%20tok` → `Bearer tok`). A value with no `key=value` pair is treated as missing auth (the API key is not used instead); a blank (whitespace-only) value is treated as unset. |
+| `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. Deduped, and only the first **10** entries are honored (hard cap, not configurable); the rest are dropped at startup with one debug warning. |
 | `FRUGAL_CUSTOM_PROVIDERS`                | Comma-separated allowlist of provider names beyond the built-in registry (e.g. `together_ai,fireworks`) that should pass through verbatim on `gen_ai.system` / `gen_ai.provider.name` instead of being coerced to `custom`. Capped at 10 (extras are coerced) to keep label cardinality bounded. |
-| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; a value outside the first 20 entries (hard cap, not configurable) is coerced to `other`. |
+| `FRUGAL_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`. The vocabulary is the first **20** comma-separated entries by raw position (hard cap, not configurable); empty entries are ignored and duplicates collapsed. `other` is reserved (the coercion sentinel) and is ignored with one warning. A value outside the allowlist is coerced to `other` with a bounded once-per-value warning; when the variable is unset, every value is `other`. One warning fires only when non-empty entries past the 20th are actually dropped (a trailing comma does not warn). |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console` (print metrics to stdout; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored). Case-insensitive; any other value warns once and uses `otlp`. |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`, for apps that already use those names. An empty value falls through to the bare name. |
 | `FRUGAL_PATH_BLOCK_LIST`                 | Comma-separated repo-relative paths to skip for caller attribution (see below).          |
-| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds. Default `60000`.                                         |
-| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute. Default `500`. Set to `0` to disable. |
-| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. |
+| `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds, `1`-`2147483647`. Default `60000`; a value outside the range warns once and uses the default.                                      |
+| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute; past it `frugal.caller_file` / `frugal.caller_function` become `<overflow>`. Default `500`. Set to `0` to disable. |
+| `FRUGAL_MAX_MODELS`                      | Cardinality cap — max distinct model strings to attribute; past it `gen_ai.request.model` / `gen_ai.response.model` become `<overflow>`. One registry shared by both labels, so a request alias and its dated response snapshot each take a slot. Default `100`. Set to `0` to disable. |
+| `FRUGAL_MAX_SERIES_PER_INSTRUMENT`       | OpenTelemetry's per-instrument limit on distinct attribute **combinations**, raised from the SDK default. Default `50000`. Set to `0` for effectively unlimited (a 1,000,000 ceiling). Applied **only when the installed `opentelemetry-sdk` accepts a per-instrument cardinality limit** — current releases (through 1.42) do not implement one, so nothing is capped and setting this variable emits one `warn` telling you it has no effect. |
+| `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls that run the lightweight prompt analyzer: a decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. Default `0.1`. Set to `0` to disable, `1` for every call. |
 | `FRUGAL_DUPLICATE_REQUEST_DETECTION`     | Duplicate-request detection (the `frugal.gen_ai.duplicate_requests` metric) is **on by default** and hashes each chat request in-process (the hash never leaves the SDK). Set to `0`/`false`/`no`/`off` to disable — no hashing, no filter memory, no metric. |
-| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `604800` (7 days). |
+| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `86400` (1 day). |
 | `FRUGAL_DUPLICATE_CAPACITY`              | Expected distinct request signatures per window (sizes the in-memory filter). Default `10000`, max `1000000`. Raise it if the SDK warns the filter is saturated. |
 | `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate of the duplicate filter. Default `0.01`, clamped to `[1e-6, 0.5]`. |
 | `FRUGAL_DUPLICATE_GENERATIONS`           | Rotation granularity of the duplicate filter's time window. Default `2`, max `16`.        |
@@ -74,8 +80,9 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | `frugal.gen_ai.cache_read_tokens`       | histogram | Prompt cache hits                                            | —                                      |
 | `frugal.gen_ai.cache_write_tokens`      | histogram | Prompt cache writes                                          | —                                      |
 | `frugal.gen_ai.reasoning_tokens`        | histogram | OpenAI reasoning tokens (o-series), Anthropic thinking tokens| —                                      |
+| `frugal.gen_ai.agent.turns`             | histogram | Model-response turns per successful `invoke_agent` call (manual only) | —                              |
 | `frugal.gen_ai.errors`                  | counter   | Errors by exception type                                     | `frugal.error.type`                    |
-| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality cap, bugs)     | `frugal.internal_error.stage`          |
+| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality caps, bugs)    | `frugal.internal_error.stage`, `frugal.internal_error.type`, `frugal.instrument` |
 | `frugal.gen_ai.output_cap_utilization`  | histogram | `output_tokens / max_tokens` ratio when `max_tokens` is set  | `frugal.structured_output_mode`        |
 | `frugal.gen_ai.history_depth`           | histogram | `messages.length` — every chat call (100%, not sampled)      | —                                      |
 | `frugal.gen_ai.duplicate_requests`      | counter   | Repeat-request detection — every chat call (100%, not sampled; disable via `FRUGAL_DUPLICATE_REQUEST_DETECTION`) | `frugal.dup_state` |
@@ -92,15 +99,17 @@ The analyzer-sampled metrics fire on a fraction of calls
 Every metric carries this base attribute set (except
 `frugal.gen_ai.internal_errors`, which is emitted from failure paths where
 these attributes may not exist yet and carries only `frugal.project_id`, the
-stage/type, and `frugal.customer_id` / `frugal.custom_label` when set):
+stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
+`frugal.customer_id` / `frugal.custom_label` when set; `frugal.custom_label`
+never on the setup_failed / emission stages):
 
 - `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
 - `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
 - `gen_ai.system` + `gen_ai.provider.name` — the provider, dual-emitted under both the legacy and current OTel attribute (`openai`, `anthropic`, `aws.bedrock`, `vertex_ai`/`gcp.vertex_ai`, …, or `custom`). Set via the `system` kwarg; an unrecognized value is coerced to `custom` with a one-time warning. See [`docs/metrics-reference.md`](docs/metrics-reference.md#attributes).
-- `gen_ai.request.model`, `gen_ai.response.model` — the model used
+- `gen_ai.request.model`, `gen_ai.response.model` — the model used; both draw on one shared registry and become `<overflow>` past `FRUGAL_MAX_MODELS` distinct model strings
 - `gen_ai.operation.name` — `chat`, `text_completion`, `embeddings`, `generate_content`, `execute_tool`, `create_agent`, `invoke_agent`, or `other` (the sentinel an unrecognized operation coerces to)
 - `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise
-- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other`
+- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other` (with a once-per-value warning). `custom_label=None` means no label; a non-string value is coerced to `other`
 
 The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
 
@@ -140,6 +149,39 @@ with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
     )
 ```
 
+For an enclosing agent invocation, set `operation="invoke_agent"` and report
+the number of model-response steps performed inside it:
+
+```python
+with track_ai_call(
+    system="anthropic",
+    operation="invoke_agent",
+    request_model="claude-sonnet-4-20250514",
+) as span:
+    result = my_agent_framework_call(prompt)
+    span.set_usage(
+        input_tokens=result.usage.input_tokens,
+        output_tokens=result.usage.output_tokens,
+        agent_turns=result.turn_count,
+    )
+```
+
+- Provider wrappers still measure individual model calls and never set
+  `agent_turns`.
+- Agent frameworks such as the Claude Agent SDK, OpenAI Agents SDK, and
+  LangGraph do not have dedicated wrappers yet; track them manually as shown.
+- `frugal.gen_ai.history_depth` is the request message count
+  (`messages.length`), not a turn count.
+- Missing, non-integer, non-positive, or otherwise invalid `agent_turns`
+  values are silently dropped. They never raise or affect customer execution.
+- Turn data is emitted only on success, like token usage.
+- **Avoid double-counting tokens.** Only report aggregate `input_tokens` /
+  `output_tokens` on the `invoke_agent` call when the agent's inner
+  model-client calls are **not** already wrapped by a supported provider
+  wrapper. If they are wrapped, those wrappers already emit token usage per
+  inner call — report `agent_turns` only on the `invoke_agent` call in that
+  case, or the same tokens are double-counted.
+
 The `with` block times the call and emits metrics on exit — or an error metric if the block raises (the exception always propagates). Works the same around an `await` in async code. Call `span.set_usage(...)` once the response is back; if you never call it, you still get a call-count and latency point.
 
 For calls that span function boundaries — where a single `with` block won't fit — use the manual handle:
@@ -162,9 +204,9 @@ except BaseException as exc:
 
 `success()` and `error()` finalize the call exactly once and are idempotent — extra calls are ignored.
 
-**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call except the `frugal.gen_ai.internal_errors` setup_failed / emission points; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
 
-**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `response_model`.
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `agent_turns`, `response_model`.
 
 The same env-var configuration, safety guarantees, and exported metrics apply. See [`docs/quickstart.md`](docs/quickstart.md#custom-call-sites) for the full custom call-site walkthrough.
 
@@ -261,14 +303,27 @@ It is **opt-in** because installing signal handlers is intrusive. If you run you
 
 ## Verifying the setup
 
-Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them. Console mode needs only `FRUGAL_PROJECT_ID`; the API key,
+endpoint and header variables are ignored. An empty
+endpoint does not select the console exporter: it falls through to the default
+Frugal endpoint.
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+python my_script.py
+```
+
+Or point the library at a local OTLP/HTTP collector to see what it exports:
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=test-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 python my_script.py
 ```
 
-You should see JSON metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
+The collector should receive metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.6.0}/docs/metrics-reference.md

@@ -20,6 +20,7 @@ metric may carry the extra attributes shown in the rightmost column.
 | `frugal.gen_ai.cache_read_tokens`     | histogram | `{token}`   | when provider reports cache reads                     | —                                              |
 | `frugal.gen_ai.cache_write_tokens`    | histogram | `{token}`   | when provider reports cache writes                    | —                                              |
 | `frugal.gen_ai.reasoning_tokens`      | histogram | `{token}`   | OpenAI o-series reasoning models                      | —                                              |
+| `frugal.gen_ai.agent.turns`           | histogram | `{turn}`    | successful `invoke_agent` calls with a valid `agent_turns` count (manual tracking only) | —                    |
 | `frugal.gen_ai.errors`                | counter   | `{error}`   | when the wrapped call raises                          | `frugal.error.type`                            |
 | `frugal.gen_ai.internal_errors`       | counter   | `{error}`   | frugal-metrics internal failures (cardinality cap, instrumentation bugs) | `frugal.internal_error.stage`     |
 | `frugal.gen_ai.output_cap_utilization`| histogram | `1`         | when request had `max_tokens` (ratio 0..1)            | `frugal.structured_output_mode`                |
@@ -34,6 +35,37 @@ metric may carry the extra attributes shown in the rightmost column.
 `gen_ai.client.token.usage` is split across input and output via the
 `gen_ai.token.type` attribute (`input` | `output`).
 
+### Agent turns
+
+Manual `track_ai_call` and `start_ai_call` instrumentation accepts the
+`agent_turns` usage kwarg through `AICallSpan.set_usage` and
+`AICallSpan.success`. A sample is emitted only when the call succeeds, the
+normalized `gen_ai.operation.name` is exactly `invoke_agent`, and the value is
+a positive integer. Booleans, missing values, non-integers, zero, and negative
+values are silently ignored; validation never affects customer execution.
+Provider wrappers never set this field, so agent frameworks remain
+manual-tracking call sites in this release. `frugal.gen_ai.history_depth`
+continues to mean request message count, not agent turns. The histogram uses
+explicit bucket boundaries
+`(1, 2, 3, 4, 5, 6, 8, 10, 12, 15, 20, 25, 30, 40, 50, 75, 100)` (mirroring
+`gen_ai.client.operation.duration`'s view) so `histogram_quantile()` resolves
+meaningful spread across realistic agent-run turn counts instead of
+collapsing into OTel's duration-tuned default buckets.
+
+Only report aggregate token usage on the `invoke_agent` call itself when the
+agent's inner model-client calls are **not** already wrapped by a supported
+provider wrapper; if they are wrapped, report `agent_turns` only on the
+`invoke_agent` call, since the inner wrappers already emit token usage and
+combining both would double-count tokens.
+
+To derive average turns per reporting agent invocation in MetricsQL, use:
+
+```promql
+increase(frugal.gen_ai.agent.turns_sum[...])
+/
+increase(frugal.gen_ai.agent.turns_count[...])
+```
+
 The analyzer-sampled metrics are gated by `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`
 (default `0.1`). Sampling is deterministic per `(caller_file, caller_function,
 minute)` — within a minute a given call site is either fully sampled or fully
@@ -88,8 +120,8 @@ Controls:
   `false`/`0`/`no`/`off`, no filter is allocated, no signature is hashed, and the
   metric is not emitted. Any other value keeps detection enabled and emits a
   one-time `warn` diagnostic naming the unrecognized value.
-- `FRUGAL_DUPLICATE_WINDOW_SECONDS` (default `3600`, clamped to `604800` — 7
-  days) — retention window. Because the filter rotates in `generations` slots,
+- `FRUGAL_DUPLICATE_WINDOW_SECONDS` (default `3600`, clamped to `86400` — 1
+  day) — retention window. Because the filter rotates in `generations` slots,
   a signature is remembered for **at least**
   `window × (generations−1)/generations` and **at most** `window` seconds
   (30–60 min at defaults) — treat the counterfactual cache TTL as that range,
@@ -101,6 +133,15 @@ Controls:
 - `FRUGAL_DUPLICATE_GENERATIONS` (default `2`, clamped to `16`) — rotating-Bloom
   generation count.
 
+Exporter selection: `FRUGAL_METRICS_EXPORTER` (`otlp` default, or `console` to
+print every metric to stdout via the OpenTelemetry console exporter; console
+mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables
+are ignored, and any other value warns once and uses `otlp`). An empty endpoint variable falls through to the next source and
+never selects console.
+
+`FRUGAL_METRIC_EXPORT_INTERVAL_MS` accepts `1` to `2147483647` (default `60000`);
+a value outside that range warns once and uses the default.
+
 Out-of-range or non-finite values for any of these fall back to the default (or
 clamp to the bound) with a one-time named `warn` through the debug callback.
 
@@ -159,18 +200,18 @@ Reading `duplicate_requests` correctly:
 
 | Attribute                 | Value                                                      |
 | ------------------------- | ---------------------------------------------------------- |
-| `frugal.customer_id`      | From `FRUGAL_CUSTOMER_ID`                                  |
-| `frugal.project_id`       | From `FRUGAL_PROJECT_ID`                                    |
+| `frugal.customer_id`      | From `FRUGAL_CUSTOMER_ID` — present only when set           |
+| `frugal.project_id`       | From `FRUGAL_METRICS_PROJECT_ID`, else `FRUGAL_PROJECT_ID`  |
 | `frugal.component`        | From each entry in `FRUGAL_COMPONENTS` — present only on the per-component series, absent on the base project series |
 | `frugal.caller_file`      | Source file repo-relative to `FRUGAL_REPO_ROOT`             |
 | `frugal.caller_function`  | Function/method name at the call site                       |
-| `frugal.error.type`       | Exception class name (error-path metrics only)              |
-| `frugal.batched`          | `true` when the metric came from a provider batch-API path, `false` otherwise. Present on every metric. Batch submissions (OpenAI `batches.create`, Anthropic `messages.batches.create`) emit `frugal.gen_ai.calls` with `batched="true"` — one point per request for Anthropic (the requests array is in hand, grouped by model), one per submission for OpenAI (per-request counts are not reported at submission time, so OpenAI batched call volume is a floor, never an overcount). Iterating Anthropic `messages.batches.results()` additionally emits per-entry `gen_ai.client.token.usage` (+ cache metrics) with `batched="true"`, attributed to the call site that submitted the batch when the submission happened in the same process (bounded in-process memory; falls back to the results call site). OpenAI batch token usage lives in the output file read through the generic files API and is not intercepted. The manual track API accepts a `batched` flag for hand-instrumented batch paths. An app on an SDK predating batch support reads `false` on genuinely batched traffic — the label reflects what the deployed SDK can see. |
+| `frugal.error.type`       | Exception class name (error-path metrics only); stripped from `frugal.gen_ai.history_depth` and `frugal.gen_ai.duplicate_requests` so success and error points stay additive |
+| `frugal.batched`          | `true` when the metric came from a provider batch-API path, `false` otherwise. Present on every metric of the call except the `frugal.gen_ai.internal_errors` points. Batch submissions (OpenAI `batches.create`, Anthropic `messages.batches.create`) emit `frugal.gen_ai.calls` with `batched="true"` — one point per request for Anthropic (the requests array is in hand, grouped by model), one per submission for OpenAI (per-request counts are not reported at submission time, so OpenAI batched call volume is a floor, never an overcount). Iterating Anthropic `messages.batches.results()` additionally emits per-entry `gen_ai.client.token.usage` (+ cache metrics) with `batched="true"`, attributed to the call site that submitted the batch when the submission happened in the same process (bounded in-process memory; falls back to the results call site). OpenAI batch token usage lives in the output file read through the generic files API and is not intercepted. The manual track API accepts a `batched` flag for hand-instrumented batch paths. An app on an SDK predating batch support reads `false` on genuinely batched traffic — the label reflects what the deployed SDK can see. |
 | `frugal.structured_output_mode` | `none` \| `json_object` \| `json_schema` \| `tools`. Derived from request params by precedence: non-empty `tools` → `tools`; else `response_format.type` `json_object` / `json_schema` → the matching value; else `none`. On `frugal.gen_ai.output_cap_utilization` (when `max_tokens` set), and on `frugal.gen_ai.calls` for every call with a request payload (omitted when there is no payload). |
 | `frugal.block`            | `system` \| `user` \| `tools` \| `schema`. Only on `frugal.gen_ai.cache_prefix_stable`. |
 | `frugal.stable`           | `true` when the block hash matches the previous call at this site. Only on `frugal.gen_ai.cache_prefix_stable`. |
 | `frugal.history_bucket`   | Bounded bucket of `messages.length`: `0` \| `1-2` \| `3-5` \| `6-10` \| `11-20` \| `21-50` \| `51+`. On `frugal.gen_ai.calls` and `gen_ai.client.token.usage`, and only for chat calls (payload has a `messages` array); omitted otherwise. 100% (not analyzer-sampled). |
-| `frugal.custom_label`    | Custom label (e.g. a business unit) passed as `custom_label=` to `track_ai_call` / `start_ai_call` — never set by the provider wrappers. When passed, it rides EVERY metric of that call (success and error paths alike). The value is trimmed of surrounding whitespace (matching the Node SDK), then must match one of the first 20 entries of `FRUGAL_CUSTOM_LABEL` (hard cap, not configurable) or it is coerced to `other`. Omitted when not passed. |
+| `frugal.custom_label`    | Custom label (e.g. a business unit) passed as `custom_label=` to `track_ai_call` / `start_ai_call` — never set by the provider wrappers. When passed, it rides every metric of that call (success and error paths alike), except the `frugal.gen_ai.internal_errors` `setup_failed`/`emission` points, which carry only project, customer and error type. The value is trimmed of surrounding whitespace (matching the Node SDK), then must match the closed vocabulary from the first 20 comma-separated entries of `FRUGAL_CUSTOM_LABEL` by raw position (hard cap, not configurable; empties ignored, duplicates collapsed) or it is coerced to `other` with a bounded once-per-value warning. `other` is reserved as the coercion sentinel: an `other` entry in the env var is ignored with a warning. With the variable unset, every value is `other`. A non-string value is coerced to `other` with a type warning; `None` means no label. A truncation warning fires only when non-empty entries past the 20th are dropped. Omitted when not passed. |
 | `frugal.dup_state`        | `first_seen` \| `repeat_seen` — whether this request's canonical signature was already seen within the duplicate-detection window. Only on `frugal.gen_ai.duplicate_requests`. |
 
 ### Sentinel values for `frugal.caller_file` / `frugal.caller_function`
@@ -182,6 +223,11 @@ Reading `duplicate_requests` correctly:
 | `<lambda>`     | Call originated from a `lambda` expression. This is Python's native `co_name` for lambdas. Only appears in `frugal.caller_function`. |
 | `<overflow>`   | Cardinality cap (`FRUGAL_MAX_CALL_SITES`) exceeded. See below. |
 
+> `<overflow>` is the shared overflow sentinel, not a caller-only value: it also
+> appears on `gen_ai.request.model` / `gen_ai.response.model` once
+> `FRUGAL_MAX_MODELS` distinct model strings have been observed. See
+> [Model cap behavior](#model-cap-behavior).
+
 ### Cardinality cap behavior
 
 Once `FRUGAL_MAX_CALL_SITES` distinct `(file, function)` pairs have been
@@ -196,6 +242,23 @@ The first time the cap is hit per process, the library emits a single
 `frugal.gen_ai.internal_errors{stage=cardinality_cap_hit}` point so you can
 see the transition in your dashboard.
 
+### Model cap behavior
+
+Model ids are free-form provider strings, so `FRUGAL_MAX_MODELS` (default `100`,
+`0` disables) bounds them the same way. The first N distinct model strings a
+process observes keep their real names; every later one is reported as
+`<overflow>` on whichever of `gen_ai.request.model` / `gen_ai.response.model`
+carries it. The registry is process-wide and **shared by both labels** — a model
+first seen in a response is free to use as a request model, and vice versa — so
+a model already in the registry is never re-charged. The default is generous
+because one logical model normally occupies **two** slots: providers answer a
+request alias (`claude-sonnet-4-5`) with a dated response snapshot
+(`claude-sonnet-4-5-20250929`). The SDK's own sentinels — `<unknown>` and
+`<overflow>` — pass through without consuming a slot. The first time the cap is
+hit per process the library emits a single
+`frugal.gen_ai.internal_errors{stage=model_cap_hit}` point plus one `warn`
+through the debug callback.
+
 ### Internal-error stages
 
 `frugal.gen_ai.internal_errors` carries a `frugal.internal_error.stage`
@@ -203,18 +266,23 @@ attribute describing where our own code failed. Non-exhaustive list:
 
 | Stage                   | When it fires                                                          |
 | ----------------------- | ---------------------------------------------------------------------- |
-| `setup_failed`          | Our wrapper setup (OTel init, caller resolution) threw; original call continued normally |
+| `setup_failed`          | Our wrapper setup (OTel init, caller resolution) threw; original call continued normally. Emitted by the provider wrappers and the manual track API (`track_ai_call` / `start_ai_call`); carries `frugal.project_id`, `frugal.customer_id` (when set) and `frugal.internal_error.type` |
 | `stream_proxy_failed`   | Constructing the stream wrapper threw; original response returned unwrapped |
-| `emission`              | Emitting a success/error metric threw                                  |
+| `emission`              | Emitting a success/error metric threw. Emitted by the provider wrappers and the manual track API; carries the same project/customer identity and `frugal.internal_error.type` as `setup_failed` |
+| `call_shape`            | Deriving history_depth / history_bucket / structured_output_mode from the request payload threw; carries `frugal.internal_error.type`; core metrics still emitted |
 | `duplicate_detection`   | The duplicate-request path (signature, filter, or emission) threw — including the one-time filter allocation failure; carries `frugal.internal_error.type` with the exception class |
 | `cardinality_cap_hit`   | `FRUGAL_MAX_CALL_SITES` was just reached (once per process)            |
+| `model_cap_hit`         | `FRUGAL_MAX_MODELS` was just reached (once per process); further distinct models are reported as `<overflow>` |
+| `otel_cardinality_overflow` | OpenTelemetry merged an instrument's attribute sets into its `otel.metric.overflow` series (once per instrument name); carries `frugal.instrument` with the affected instrument |
 
 Unlike every other metric, `frugal.gen_ai.internal_errors` does **not** carry
 the full base attribute set — it is emitted from failure paths where the
 caller/provider/model attributes may not exist yet. Its points carry only
 `frugal.project_id`, `frugal.internal_error.stage` (plus
-`frugal.internal_error.type` where noted), and — when set —
-`frugal.customer_id` and `frugal.custom_label`.
+`frugal.internal_error.type` where noted, and `frugal.instrument` on the
+`otel_cardinality_overflow` stage), and — when set — `frugal.customer_id` and
+`frugal.custom_label` (`setup_failed` and `emission` never carry the custom
+label).
 
 ## Provider coverage