frugal-sdk-python 0.1.0__tar.gz → 0.2.0__tar.gz

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frugal-sdk-python
-Version: 0.1.0
+Version: 0.2.0
 Summary: Instrumentation for Cost-to-Code attribution.
 Project-URL: Homepage, https://frugal.co
 Author: Frugal AI Inc.
@@ -140,6 +140,50 @@ profile prefixes (`us.`, `eu.`, `jp.`, `apac.`, `au.`, `global.`) are
 preserved in `gen_ai.request.model`. Async clients (`aiobotocore` /
 `aioboto3`) are detected automatically. See [`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrap_bedrock) for the full Bedrock walkthrough.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model gateway, a CLI shell-out, or an internal helper that returns raw usage — mark the call site yourself and feed in the usage you have. You get the same metrics and the same caller attribution as the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+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:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`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>"`). 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`.
+
+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.
+
 ## Streaming
 
 Streaming works with no extra setup. The wrapper returns a drop-in replacement that passes events through and emits metrics when the stream finishes.
@@ -180,6 +224,57 @@ FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
 - If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never raise our own exceptions into your code.
 - Wrapping is idempotent — calling `wrap_openai(client)` twice on the same client is safe.
 
+## Debugging
+
+The SDK is silent by design — when misconfigured it degrades to a no-op. To see *why* it is doing nothing (missing env var, instrument-build failure, cardinality-cap hit, a metric export that keeps failing), register a debug callback:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    # level: "info" | "warn" | "error"
+    # message: human-readable string
+    # context: optional dict of structured detail, e.g. {"stage": "setup_failed"}
+    getattr(my_logger, level if level != "warn" else "warning")(
+        "[frugal-metrics] %s", message, extra=context or {}
+    )
+
+set_debug_callback(on_debug)
+```
+
+This is a **structural-diagnostics hook, not a per-call trace**. It only fires for structural or persistent problems — missing/invalid configuration, setup failures, cardinality-cap hits, and *consecutive* export failures (one de-duped `error`, re-armed on the next success). Ordinary transient per-call API errors are never emitted — those are your own API errors and already visible to you.
+
+Notes:
+
+- **A throwing callback is swallowed.** If your callback raises, the exception never escapes into the SDK or your code.
+- **Issues are replayed.** Configuration runs lazily and may happen before you register, so init/config diagnostics emitted beforehand are held in a small bounded buffer and replayed in order the moment you call `set_debug_callback`. Register once at startup to catch them all.
+- The callback is global and thread-safe. Pass `None` to clear it.
+
+## Flushing & graceful shutdown
+
+Metrics export on a periodic interval (default 60s). A short-lived process — a CLI, a job, a serverless invocation, a test run — can exit before the next export, silently dropping its final window of metrics. Use `flush` / `shutdown` to avoid that:
+
+```python
+from frugal_metrics import flush, shutdown
+
+flush()     # force an immediate export; SDK keeps recording afterwards
+shutdown()  # flush + tear down the provider (rebuilt lazily on next wrap)
+```
+
+Both are **safe no-ops when the SDK was never initialized** and never raise.
+
+For processes that exit on their own, opt in to automatic flush-on-exit:
+
+```python
+from frugal_metrics import enable_auto_shutdown
+
+enable_auto_shutdown()  # flush + shutdown via atexit, plus SIGTERM / SIGINT
+```
+
+`enable_auto_shutdown` always registers an `atexit` hook and, when `handle_signals=True` (the default), installs SIGTERM/SIGINT handlers that flush+shutdown and then **chain to whatever handler was previously installed** (so your own handler still runs). Off the main thread, signal registration is unavailable and it falls back to atexit-only. It is **idempotent** — repeat calls register nothing extra.
+
+It is **opt-in** because installing signal handlers is intrusive. If you run your own signal handling, do **not** call `enable_auto_shutdown(handle_signals=True)`; prefer calling `shutdown()` from inside your own handler instead.
+
 ## Verifying the setup
 
 Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/README.md

@@ -111,6 +111,50 @@ profile prefixes (`us.`, `eu.`, `jp.`, `apac.`, `au.`, `global.`) are
 preserved in `gen_ai.request.model`. Async clients (`aiobotocore` /
 `aioboto3`) are detected automatically. See [`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrap_bedrock) for the full Bedrock walkthrough.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model gateway, a CLI shell-out, or an internal helper that returns raw usage — mark the call site yourself and feed in the usage you have. You get the same metrics and the same caller attribution as the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+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:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`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>"`). 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`.
+
+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.
+
 ## Streaming
 
 Streaming works with no extra setup. The wrapper returns a drop-in replacement that passes events through and emits metrics when the stream finishes.
@@ -151,6 +195,57 @@ FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
 - If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never raise our own exceptions into your code.
 - Wrapping is idempotent — calling `wrap_openai(client)` twice on the same client is safe.
 
+## Debugging
+
+The SDK is silent by design — when misconfigured it degrades to a no-op. To see *why* it is doing nothing (missing env var, instrument-build failure, cardinality-cap hit, a metric export that keeps failing), register a debug callback:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    # level: "info" | "warn" | "error"
+    # message: human-readable string
+    # context: optional dict of structured detail, e.g. {"stage": "setup_failed"}
+    getattr(my_logger, level if level != "warn" else "warning")(
+        "[frugal-metrics] %s", message, extra=context or {}
+    )
+
+set_debug_callback(on_debug)
+```
+
+This is a **structural-diagnostics hook, not a per-call trace**. It only fires for structural or persistent problems — missing/invalid configuration, setup failures, cardinality-cap hits, and *consecutive* export failures (one de-duped `error`, re-armed on the next success). Ordinary transient per-call API errors are never emitted — those are your own API errors and already visible to you.
+
+Notes:
+
+- **A throwing callback is swallowed.** If your callback raises, the exception never escapes into the SDK or your code.
+- **Issues are replayed.** Configuration runs lazily and may happen before you register, so init/config diagnostics emitted beforehand are held in a small bounded buffer and replayed in order the moment you call `set_debug_callback`. Register once at startup to catch them all.
+- The callback is global and thread-safe. Pass `None` to clear it.
+
+## Flushing & graceful shutdown
+
+Metrics export on a periodic interval (default 60s). A short-lived process — a CLI, a job, a serverless invocation, a test run — can exit before the next export, silently dropping its final window of metrics. Use `flush` / `shutdown` to avoid that:
+
+```python
+from frugal_metrics import flush, shutdown
+
+flush()     # force an immediate export; SDK keeps recording afterwards
+shutdown()  # flush + tear down the provider (rebuilt lazily on next wrap)
+```
+
+Both are **safe no-ops when the SDK was never initialized** and never raise.
+
+For processes that exit on their own, opt in to automatic flush-on-exit:
+
+```python
+from frugal_metrics import enable_auto_shutdown
+
+enable_auto_shutdown()  # flush + shutdown via atexit, plus SIGTERM / SIGINT
+```
+
+`enable_auto_shutdown` always registers an `atexit` hook and, when `handle_signals=True` (the default), installs SIGTERM/SIGINT handlers that flush+shutdown and then **chain to whatever handler was previously installed** (so your own handler still runs). Off the main thread, signal registration is unavailable and it falls back to atexit-only. It is **idempotent** — repeat calls register nothing extra.
+
+It is **opt-in** because installing signal handlers is intrusive. If you run your own signal handling, do **not** call `enable_auto_shutdown(handle_signals=True)`; prefer calling `shutdown()` from inside your own handler instead.
+
 ## Verifying the setup
 
 Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/docs/metrics-reference.md

@@ -45,7 +45,7 @@ calls, token usage) are 100% — never sampled.
 
 | Attribute                  | Example                                    |
 | -------------------------- | ------------------------------------------ |
-| `gen_ai.system`            | `openai` \| `anthropic` \| `aws.bedrock` \| `vertex_ai` |
+| `gen_ai.system`            | `openai` \| `anthropic` \| `aws.bedrock` \| `vertex_ai` \| `custom` |
 | `gen_ai.operation.name`    | `chat` \| `text_completion` \| `embeddings` |
 | `gen_ai.request.model`     | `gpt-4o` / `claude-3-5-sonnet-latest` / …   |
 | `gen_ai.response.model`    | Provider-returned model id (often identical)|
@@ -110,6 +110,7 @@ attribute describing where our own code failed. Non-exhaustive list:
 | Claude on AWS Bedrock (via Anthropic SDK)               | `wrap_anthropic(AnthropicBedrock())` | `aws.bedrock`    |
 | AWS Bedrock — any model, AWS SDKs directly              | `wrap_bedrock`                       | `aws.bedrock`    |
 | Claude on Google Vertex                                 | `wrap_anthropic(AnthropicVertex())`  | `vertex_ai`      |
+| Custom / manual call sites                              | `track_ai_call` / `start_ai_call`    | `custom` (override via `system=`) |
 
 `wrap_bedrock` covers all four `bedrock-runtime` operations (`InvokeModel`,
 `InvokeModelWithResponseStream`, `Converse`, `ConverseStream`) on every model

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/docs/quickstart.md

@@ -198,6 +198,65 @@ client = wrap_anthropic(AnthropicVertex(region="us-central1", project_id="my-pro
 > integrations are not yet instrumented. The block-list approach below
 > usually covers framework wrappers in the meantime.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model
+gateway, a CLI shell-out, or an internal helper that returns raw usage — mark
+the call site yourself and feed in the usage you have. You get the same metrics
+(tagged `gen_ai.system = custom` by default) and the same caller attribution as
+the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+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:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`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>"`). 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`.
+
+The same env-var configuration, safety guarantees, and exported metrics apply.
+
 ## Attributing the right caller
 
 By default we walk the stack and pick the first frame that is:
@@ -272,6 +331,46 @@ The token-side metrics (`gen_ai.client.token.usage`, `frugal.gen_ai.calls`,
 `frugal.gen_ai.cache_*`, `frugal.gen_ai.output_cap_utilization`) are 100% —
 never sampled.
 
+## See why nothing is exporting (debug callback)
+
+The SDK is silent by design, so when it no-ops you get no feedback. Register a
+debug callback once at startup to surface structural diagnostics (missing config,
+setup failures, cardinality-cap hits, persistent export failures) through your own
+logger:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    print(f"[frugal-metrics] {level}: {message}", context or {})
+
+set_debug_callback(on_debug)
+```
+
+It is a structural-diagnostics hook, not a per-call trace. A throwing callback is
+swallowed, and issues emitted before you register are replayed on registration —
+so register early. Pass `None` to clear it.
+
+## Flush on shutdown
+
+Export runs on an interval, so a short-lived process can exit before the final
+batch ships. Flush (or shut down) before exit:
+
+```python
+from frugal_metrics import flush, shutdown, enable_auto_shutdown
+
+flush()     # immediate export, keep recording
+shutdown()  # flush + tear down (safe even if never initialized)
+
+enable_auto_shutdown()  # or: opt in to auto flush+shutdown on exit/SIGTERM/SIGINT
+```
+
+`flush` / `shutdown` are safe no-ops when the SDK was never initialized.
+`enable_auto_shutdown` registers an `atexit` hook and (by default) chained
+SIGTERM/SIGINT handlers, and is idempotent; if you manage your own signal
+handlers, call it with `handle_signals=False` (or just call `shutdown()` from
+your handler).
+
 ## Verifying the setup
 
 Point the library at a local collector (or set the endpoint empty to print

frugal_sdk_python-0.2.0/src/frugal_metrics/__init__.py

@@ -0,0 +1,27 @@
+"""frugal-metrics: call-site instrumentation for AI API calls."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from frugal_metrics.debug import set_debug_callback
+from frugal_metrics.shutdown import enable_auto_shutdown, flush, shutdown
+from frugal_metrics.track import AICallSpan, start_ai_call, track_ai_call
+from frugal_metrics.wrappers.openai import wrap_openai
+from frugal_metrics.wrappers.anthropic import wrap_anthropic
+from frugal_metrics.wrappers.bedrock import wrap_bedrock
+
+__all__ = [
+    "wrap_openai",
+    "wrap_anthropic",
+    "wrap_bedrock",
+    "track_ai_call",
+    "start_ai_call",
+    "AICallSpan",
+    "set_debug_callback",
+    "flush",
+    "shutdown",
+    "enable_auto_shutdown",
+]
+try:
+    __version__ = version("frugal-sdk-python")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/src/frugal_metrics/config.py

@@ -35,6 +35,8 @@ import os
 import threading
 from dataclasses import dataclass, field
 
+from frugal_metrics.debug import emit_log
+
 logger = logging.getLogger("frugal_metrics")
 
 _ENV_API_KEY = "FRUGAL_API_KEY"
@@ -92,6 +94,7 @@ def _warn_once(message: str) -> None:
             return
         _warned_once = True
     logger.warning("frugal-metrics disabled: %s", message)
+    emit_log("warn", f"disabled: {message}")
 
 
 def load_config() -> Config | None:
@@ -207,6 +210,10 @@ def _parse_int(raw: str | None, *, default: int) -> int:
             raw,
             default,
         )
+        emit_log(
+            "warn",
+            f"could not parse int env var value {raw!r}; using default {default}",
+        )
         return default
 
 
@@ -221,6 +228,10 @@ def _parse_float(raw: str | None, *, default: float) -> float:
             raw,
             default,
         )
+        emit_log(
+            "warn",
+            f"could not parse float env var value {raw!r}; using default {default}",
+        )
         return default
 
 

frugal_sdk_python-0.2.0/src/frugal_metrics/debug.py

@@ -0,0 +1,109 @@
+"""Debug / log callback.
+
+Lets a customer observe the SDK's own structural diagnostics — missing/invalid
+configuration, instrument-build failures, cardinality-cap hits, persistent
+export failures — via a single registered callback. This is NOT a per-call
+trace: only structural/persistent problems are emitted, never ordinary transient
+per-call API errors (those are the customer's own API errors).
+
+Safe by construction: a throwing customer callback can never escape (every
+invocation is wrapped in try/except), and emissions made before a callback is
+registered are held in a small bounded buffer and replayed on registration.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any, Callable
+
+logger = logging.getLogger("frugal_metrics")
+
+# level is one of "info" | "warn" | "error".
+DebugCallback = Callable[[str, str, "dict[str, Any] | None"], None]
+
+# Cap the replay buffer so an app that never registers a callback can't grow
+# memory unbounded. Oldest entries are dropped when full.
+_MAX_BUFFER = 50
+
+_lock = threading.Lock()
+_callback: DebugCallback | None = None
+_buffer: list[tuple[str, str, "dict[str, Any] | None"]] = []
+_once_keys: set[str] = set()
+
+
+def _invoke(
+    cb: DebugCallback,
+    level: str,
+    message: str,
+    context: dict[str, Any] | None,
+) -> None:
+    try:
+        cb(level, message, context)
+    except Exception:  # noqa: BLE001
+        # A throwing customer callback must never escape into SDK / customer code.
+        logger.debug("frugal-metrics: debug callback raised", exc_info=True)
+
+
+def set_debug_callback(cb: DebugCallback | None) -> None:
+    """Register (or clear, with ``None``) the debug callback.
+
+    On registration of a non-None callback, the bounded replay buffer of
+    diagnostics emitted before registration is replayed through the callback in
+    order, then cleared.
+    """
+    global _callback
+    with _lock:
+        _callback = cb
+        if cb is None:
+            return
+        pending = _buffer[:]
+        _buffer.clear()
+    for level, message, context in pending:
+        _invoke(cb, level, message, context)
+
+
+def emit_log(level: str, message: str, context: dict[str, Any] | None = None) -> None:
+    """Emit a structural diagnostic.
+
+    Invokes the registered callback (inside a try/except so a throwing callback
+    never escapes); if none is registered yet, the entry is held in the bounded
+    replay buffer.
+    """
+    with _lock:
+        cb = _callback
+        if cb is None:
+            _buffer.append((level, message, context))
+            if len(_buffer) > _MAX_BUFFER:
+                _buffer.pop(0)
+            return
+    _invoke(cb, level, message, context)
+
+
+def emit_log_once(
+    key: str,
+    level: str,
+    message: str,
+    context: dict[str, Any] | None = None,
+) -> None:
+    """Emit a diagnostic at most once per ``key``.
+
+    The de-dupe set persists for the process lifetime — use this for steady-state
+    conditions that would otherwise spam (cardinality-cap hits, repeated setup
+    failures). For the consecutive export-failure signal, which needs to re-arm,
+    use the explicit reset in the export-health wrapper instead.
+    """
+    with _lock:
+        if key in _once_keys:
+            return
+        _once_keys.add(key)
+    emit_log(level, message, context)
+
+
+def reset_debug_for_tests() -> None:
+    """Test-only hook — clear callback, replay buffer, and once-keys."""
+    global _callback
+    with _lock:
+        _callback = None
+        _buffer.clear()
+        _once_keys.clear()

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/src/frugal_metrics/instrument.py

@@ -21,6 +21,7 @@ from frugal_metrics.caller import (
     resolve_caller,
 )
 from frugal_metrics.config import Config
+from frugal_metrics.debug import emit_log_once
 from frugal_metrics.otel import Instruments, get_instruments
 from frugal_metrics.prompt_analyzer import (
     RequestPayload,
@@ -84,6 +85,13 @@ def start_call(
     resolver = caller_resolver or default_caller_resolver(config, ctx)
     caller = resolver()
     if consume_cap_hit_event():
+        emit_log_once(
+            "cardinality_cap",
+            "warn",
+            "call-site cardinality cap hit; further distinct (file, function) call "
+            "sites are attributed to an overflow bucket. Raise FRUGAL_MAX_CALL_SITES "
+            "if this is unexpected.",
+        )
         try:
             cap_attrs: dict[str, Any] = {
                 semconv.FRUGAL_PROJECT_ID: config.project_id,

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.2.0}/src/frugal_metrics/otel.py

@@ -19,6 +19,7 @@ from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.metrics.export import (
     ConsoleMetricExporter,
     MetricExporter,
+    MetricExportResult,
     PeriodicExportingMetricReader,
 )
 from opentelemetry.sdk.metrics.view import (
@@ -28,6 +29,7 @@ from opentelemetry.sdk.metrics.view import (
 from opentelemetry.sdk.resources import Resource
 
 from frugal_metrics import semconv
+from frugal_metrics.debug import emit_log
 
 if TYPE_CHECKING:
     from opentelemetry.metrics import Counter, Histogram, Meter
@@ -145,7 +147,11 @@ def get_instruments(config: "Config") -> Instruments:
     with _lock:
         if _instruments is not None:
             return _instruments
-        _instruments = _build_instruments(config)
+        try:
+            _instruments = _build_instruments(config)
+        except Exception as exc:  # noqa: BLE001
+            emit_log("error", f"failed to initialize metrics: {exc}")
+            raise
         return _instruments
 
 
@@ -285,15 +291,89 @@ def _build_exporter(config: "Config") -> MetricExporter:
         logger.info(
             "frugal-metrics: no OTLP endpoint configured; falling back to console exporter"
         )
-        return ConsoleMetricExporter()
+        return wrap_exporter_for_health(ConsoleMetricExporter())
 
     headers = _parse_headers(config.otlp_headers)
-    return OTLPMetricExporter(
-        endpoint=config.otlp_endpoint,
-        headers=headers or None,
+    return wrap_exporter_for_health(
+        OTLPMetricExporter(
+            endpoint=config.otlp_endpoint,
+            headers=headers or None,
+        )
     )
 
 
+class _HealthCheckingExporter(MetricExporter):
+    """Wrap an exporter so persistent export failures surface as a single
+    de-duped ``error`` debug callback.
+
+    The periodic reader retries silently forever; without this, a wrong
+    endpoint / bad token / down backend is invisible to the customer. We emit on
+    the FIRST failure after a success (0->1 edge) and re-arm on the next success,
+    so a flapping backend produces one alert per failure run, not one per export
+    tick. Every other attribute delegates to the inner exporter.
+    """
+
+    def __init__(self, inner: MetricExporter) -> None:
+        # Do NOT call super().__init__ — we delegate everything to the inner
+        # exporter, including the preferred temporality/aggregation it was built
+        # with. Accessing those goes through __getattr__.
+        self._inner = inner
+        self._consecutive_failures = 0
+
+    def export(  # type: ignore[override]
+        self,
+        metrics_data: Any,
+        timeout_millis: float = 10_000,
+        **kwargs: Any,
+    ) -> MetricExportResult:
+        result = self._inner.export(
+            metrics_data, timeout_millis=timeout_millis, **kwargs
+        )
+        if result == MetricExportResult.SUCCESS:
+            self._consecutive_failures = 0
+        else:
+            self._consecutive_failures += 1
+            if self._consecutive_failures == 1:
+                emit_log("error", "metric export failing")
+        return result
+
+    def force_flush(self, timeout_millis: float = 10_000) -> bool:
+        return self._inner.force_flush(timeout_millis=timeout_millis)
+
+    def shutdown(self, timeout_millis: float = 30_000, **kwargs: Any) -> None:
+        self._inner.shutdown(timeout_millis=timeout_millis, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate preferred_temporality / preferred_aggregation and any other
+        # attribute the SDK reads off the exporter to the inner instance.
+        return getattr(self._inner, name)
+
+
+def wrap_exporter_for_health(exporter: MetricExporter) -> MetricExporter:
+    """Wrap an exporter so persistent export failures emit one de-duped error."""
+    return _HealthCheckingExporter(exporter)
+
+
+def flush_metrics() -> None:
+    """Force an immediate export of buffered metrics. No-op when uninitialized."""
+    if _instruments is None:
+        return
+    _instruments.meter_provider.force_flush()
+
+
+def shutdown_metrics() -> None:
+    """Shut down the provider (flushes + stops readers) and drop the cache so a
+    later wrap call lazily rebuilds. No-op when uninitialized.
+    """
+    global _instruments
+    with _lock:
+        if _instruments is None:
+            return
+        provider = _instruments.meter_provider
+        _instruments = None
+    provider.shutdown()
+
+
 def _parse_headers(raw: str | None) -> dict[str, str]:
     """Parse OTEL-style header strings: key1=value1,key2=value2."""
     if not raw: