argus-obs-semconv 1.0.0a3__tar.gz

argus_obs_semconv-1.0.0a3/.gitignore

@@ -0,0 +1,30 @@
+.env
+.env.*
+!.env.example
+!.env.*.example
+*.env.local
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+# Configuracion del dead man's switch: lleva credenciales de aviso.
+deadman/deadman.json
+
+# Secretos montados en contenedores. Nunca al repositorio.
+platform/secrets/
+
+# El índice se GENERA desde dist/ con scripts/construir_indice.py.
+# Versionar ruedas es versionar binarios que ya sabemos reproducir.
+platform/indice/simple/
+
+# La coordinacion con otros equipos vive FUERA del repositorio, en
+# ~/Documents/Victor/<equipo>_argus/. Aqui hay incidentes suyos, rutas de su
+# codigo y sus identificadores de backlog: es informacion de ellos y este
+# repositorio es publico. Ver docs/coordinacion.md.
+docs/solicitudes/

argus_obs_semconv-1.0.0a3/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: argus-obs-semconv
+Version: 1.0.0a3
+Summary: Convenciones semanticas de Argus. Para LIBRERIAS: depende solo de la API de OpenTelemetry.
+Project-URL: Homepage, https://github.com/Root1V/argus-obs
+Project-URL: Repository, https://github.com/Root1V/argus-obs
+Project-URL: Issues, https://github.com/Root1V/argus-obs/issues
+Author: Emeric Espiritu
+License: MIT
+Keywords: genai,llm,observability,opentelemetry,semantic-conventions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api<2,>=1.30
+Provides-Extra: dev
+Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# argus-semconv
+
+Convenciones semánticas de Argus para **librerías**.
+
+## Cuándo usar este paquete y cuándo no
+
+| Escribes… | Importa | Por qué |
+|---|---|---|
+| Una **librería** (Axonium, synaptum, un SDK tuyo) | `argus-semconv` | Solo depende de `opentelemetry-api`. No impone SDK ni exportadores a quien te use |
+| Una **aplicación** (servicio, worker, CLI) | `argus-sdk` | Es quien configura e inicializa la telemetría |
+
+## La garantía
+
+Si la aplicación que importa tu librería **no** ha inicializado un SDK de
+OpenTelemetry, toda la instrumentación de este paquete es **no-op con coste
+cero**. Si **sí** lo ha inicializado, se enciende sola usando *su*
+configuración, *su* endpoint y *su* muestreo.
+
+Eso significa que puedes instrumentar tus librerías sin imponer nada a nadie.
+
+```python
+from argus_semconv import genai
+
+# En Axonium, dentro del cliente de inferencia:
+with genai("chat", provider="ollama", request_model=model) as g:
+    resp = await self._call_backend(...)
+    g.usage(input_tokens=resp.prompt_tokens, output_tokens=resp.completion_tokens)
+    g.backend(backend_id=backend.id, ttft_ms=resp.ttft_ms)
+```
+
+## Las constantes están generadas
+
+`attributes.py` se genera desde `libs/semconv-model/argus.yaml`. No lo edites a
+mano: ejecuta `python tools/gen_semconv.py`. Un test de CI verifica que no hay
+deriva entre el modelo y lo commiteado.

argus_obs_semconv-1.0.0a3/README.md

@@ -0,0 +1,35 @@
+# argus-semconv
+
+Convenciones semánticas de Argus para **librerías**.
+
+## Cuándo usar este paquete y cuándo no
+
+| Escribes… | Importa | Por qué |
+|---|---|---|
+| Una **librería** (Axonium, synaptum, un SDK tuyo) | `argus-semconv` | Solo depende de `opentelemetry-api`. No impone SDK ni exportadores a quien te use |
+| Una **aplicación** (servicio, worker, CLI) | `argus-sdk` | Es quien configura e inicializa la telemetría |
+
+## La garantía
+
+Si la aplicación que importa tu librería **no** ha inicializado un SDK de
+OpenTelemetry, toda la instrumentación de este paquete es **no-op con coste
+cero**. Si **sí** lo ha inicializado, se enciende sola usando *su*
+configuración, *su* endpoint y *su* muestreo.
+
+Eso significa que puedes instrumentar tus librerías sin imponer nada a nadie.
+
+```python
+from argus_semconv import genai
+
+# En Axonium, dentro del cliente de inferencia:
+with genai("chat", provider="ollama", request_model=model) as g:
+    resp = await self._call_backend(...)
+    g.usage(input_tokens=resp.prompt_tokens, output_tokens=resp.completion_tokens)
+    g.backend(backend_id=backend.id, ttft_ms=resp.ttft_ms)
+```
+
+## Las constantes están generadas
+
+`attributes.py` se genera desde `libs/semconv-model/argus.yaml`. No lo edites a
+mano: ejecuta `python tools/gen_semconv.py`. Un test de CI verifica que no hay
+deriva entre el modelo y lo commiteado.

argus_obs_semconv-1.0.0a3/generated/go/attributes.go

@@ -0,0 +1,119 @@
+// GENERADO AUTOMATICAMENTE. NO EDITAR A MANO.
+//
+// Fuente: libs/semconv-model/argus.yaml
+// Regenerar: python tools/gen_semconv.py
+
+package semconv
+
+const (
+	SemconvVersion      = "1.0.0"
+	GenAISemconvVersion = "1.39.0"
+)
+
+// identity: Identidad de aplicacion y componente
+const (
+	ServiceNamespace = "service.namespace"
+	ServiceName = "service.name"
+	ServiceVersion = "service.version"
+	ServiceInstanceID = "service.instance.id"
+	DeploymentEnvironmentName = "deployment.environment.name"
+	ArgusComponentRole = "argus.component.role"
+)
+
+// langfuse_bridge: Atributos que Langfuse interpreta de forma especial
+const (
+	LangfuseEnvironment = "langfuse.environment"
+	LangfuseRelease = "langfuse.release"
+	LangfuseObservationType = "langfuse.observation.type"
+	LangfuseTraceName = "langfuse.trace.name"
+	LangfuseTraceTags = "langfuse.trace.tags"
+)
+
+// attribution: Etiquetas de atribucion para FinOps y analisis
+const (
+	ArgusApp = "argus.app"
+	ArgusFeature = "argus.feature"
+	ArgusUseCase = "argus.use_case"
+	ArgusRunID = "argus.run.id"
+	ArgusTenant = "argus.tenant"
+)
+
+// wide_event: Campos del evento ancho canonico
+const (
+	ArgusEvent = "argus.event"
+	ArgusOutcome = "argus.outcome"
+	ArgusDurationMs = "argus.duration_ms"
+	ArgusStepDepth = "argus.step.depth"
+)
+
+// hotpath: Marcas que enrutan al camino caliente de deteccion
+const (
+	ArgusHot = "argus.hot"
+	ArgusSloBreached = "argus.slo.breached"
+	ArgusSloThresholdMs = "argus.slo.threshold_ms"
+	ArgusGuardrail = "argus.guardrail"
+)
+
+// errors: Clasificacion de errores
+const (
+	ErrorType = "error.type"
+	ArgusErrorRetryable = "argus.error.retryable"
+	ArgusErrorRetryPolicy = "argus.error.retry_policy"
+)
+
+// genai: Convenciones GenAI de OpenTelemetry
+const (
+	GenAIOperationName = "gen_ai.operation.name"
+	GenAIProviderName = "gen_ai.provider.name"
+	GenAIRequestModel = "gen_ai.request.model"
+	GenAIResponseModel = "gen_ai.response.model"
+	GenAIResponseID = "gen_ai.response.id"
+	GenAIResponseFinishReasons = "gen_ai.response.finish_reasons"
+	GenAIUsageInputTokens = "gen_ai.usage.input_tokens"
+	GenAIUsageOutputTokens = "gen_ai.usage.output_tokens"
+	GenAIUsageCacheReadInputTokens = "gen_ai.usage.cache_read.input_tokens"
+	GenAIRequestTemperature = "gen_ai.request.temperature"
+	GenAIRequestMaxTokens = "gen_ai.request.max_tokens"
+	GenAIRequestTopP = "gen_ai.request.top_p"
+	GenAIConversationID = "gen_ai.conversation.id"
+	GenAIAgentName = "gen_ai.agent.name"
+	GenAIAgentID = "gen_ai.agent.id"
+	GenAIToolName = "gen_ai.tool.name"
+	GenAIToolType = "gen_ai.tool.type"
+	GenAIToolCallID = "gen_ai.tool.call.id"
+	GenAIInputMessages = "gen_ai.input.messages"
+	GenAIOutputMessages = "gen_ai.output.messages"
+	GenAISystemInstructions = "gen_ai.system_instructions"
+	GenAIToolCallArguments = "gen_ai.tool.call.arguments"
+	GenAIToolCallResult = "gen_ai.tool.call.result"
+	GenAIContentTruncated = "gen_ai.content.truncated"
+)
+
+// inference: Detalles de inferencia local que solo conoce el SDK cliente
+const (
+	ArgusBackendID = "argus.backend.id"
+	ArgusBackendCircuitState = "argus.backend.circuit_state"
+	ArgusBackendFallback = "argus.backend.fallback"
+	ArgusCostUSD = "argus.cost_usd"
+	ArgusTtftMs = "argus.ttft_ms"
+	ArgusFirstTokenMs = "argus.first_token_ms"
+	ArgusTokensPerSecond = "argus.tokens_per_second"
+)
+
+// retrieval: Recuperacion de documentos
+const (
+	ArgusRetrievalStore = "argus.retrieval.store"
+	ArgusRetrievalTopK = "argus.retrieval.top_k"
+	ArgusRetrievalDocCount = "argus.retrieval.doc_count"
+	ArgusRetrievalScoreMin = "argus.retrieval.score_min"
+	ArgusRetrievalScoreMax = "argus.retrieval.score_max"
+)
+
+// Metricas
+const (
+	MetricGenAIClientOperationDuration = "gen_ai.client.operation.duration"
+	MetricGenAIClientTokenUsage = "gen_ai.client.token.usage"
+	MetricGenAIServerTimeToFirstToken = "gen_ai.server.time_to_first_token"
+	MetricArgusStepDuration = "argus.step.duration"
+	MetricArgusCostUSD = "argus.cost.usd"
+)

argus_obs_semconv-1.0.0a3/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "argus-obs-semconv"
+version = "1.0.0a3"
+description = "Convenciones semanticas de Argus. Para LIBRERIAS: depende solo de la API de OpenTelemetry."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Emeric Espiritu" }]
+keywords = ["observability", "opentelemetry", "semantic-conventions", "genai", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+
+# ATENCION: esta lista de dependencias es un contrato, no un detalle.
+#
+# Este paquete lo importan LIBRERIAS (Axonium, synaptum, ...), no aplicaciones.
+# Una libreria que depende del SDK impone en silencio su version del SDK y sus
+# opiniones sobre exportadores a TODO el que dependa de ella. Con quince o mas
+# aplicaciones importando Axonium, eso es un infierno de dependencias.
+#
+# Por eso: SOLO la API, y con rango abierto dentro de la mayor. NUNCA una
+# version exacta, NUNCA el SDK, NUNCA un exportador.
+dependencies = [
+    "opentelemetry-api>=1.30,<2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "opentelemetry-sdk>=1.30,<2", "pyyaml>=6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus_semconv"]
+
+# Quien encuentre esto en PyPI tiene derecho a saber de donde sale y donde
+# reportar. Un paquete sin origen publico es la misma opacidad de cadena de
+# suministro que nos objeto un equipo consumidor (D-075).
+[project.urls]
+Homepage = "https://github.com/Root1V/argus-obs"
+Repository = "https://github.com/Root1V/argus-obs"
+Issues = "https://github.com/Root1V/argus-obs/issues"

argus_obs_semconv-1.0.0a3/src/argus_semconv/__init__.py

@@ -0,0 +1,62 @@
+"""Convenciones semanticas de Argus, para LIBRERIAS.
+
+Este paquete depende SOLO de `opentelemetry-api`. Nunca del SDK, nunca de un
+exportador. Esa restriccion es el contrato:
+
+- Si la aplicacion que te importa no inicializo un SDK, todo esto es no-op con
+  coste cero, y tu libreria funciona exactamente igual que sin instrumentar.
+- Si lo inicializo, tu instrumentacion se enciende sola usando SU
+  configuracion, SU endpoint y SU muestreo.
+
+Una libreria que dependiera del SDK impondria en silencio su version y sus
+opiniones sobre exportadores a todo el que dependa de ella.
+
+Las aplicaciones no usan este paquete directamente: usan `argus-sdk`, que lo
+re-exporta ademas de configurar la telemetria.
+"""
+
+from __future__ import annotations
+
+from . import attributes
+from ._content import capture_enabled, mask
+from .genai import GenAISpan, agent, documents, genai, retrieval, tool
+from .guardrails import AgentRun, Budget, GuardrailBreach, current_run
+from .steps import Step, instrument, step
+
+# La version del PAQUETE, distinta de la de las convenciones: el paquete puede
+# publicarse varias veces sin que cambien las convenciones.
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("argus-obs-semconv")
+except Exception:  # noqa: BLE001
+    __version__ = "0.0.0.dev0"
+
+#: Version del MODELO de convenciones (libs/semconv-model/argus.yaml).
+SEMCONV_VERSION = attributes.SEMCONV_VERSION
+
+__all__ = [
+    # Convenciones generadas
+    "attributes",
+    # GenAI
+    "genai",
+    "retrieval",
+    "tool",
+    "agent",
+    "documents",
+    "GenAISpan",
+    # Guardarrailes de agentes
+    "Budget",
+    "GuardrailBreach",
+    "AgentRun",
+    "current_run",
+    # Unidades de trabajo
+    "step",
+    "instrument",
+    "Step",
+    # Contenido
+    "capture_enabled",
+    "mask",
+    "SEMCONV_VERSION",
+    "__version__",
+]

argus_obs_semconv-1.0.0a3/src/argus_semconv/_content.py

@@ -0,0 +1,108 @@
+"""Captura y enmascarado de contenido de prompts.
+
+Dos decisiones que conviene entender antes de tocar este fichero.
+
+1. El contenido va en ATRIBUTOS de span, no en eventos.
+
+   La guia canonica de las semconv GenAI dice que el contenido debe ir en
+   eventos de span, para poder descartarlo en el Collector sin tocar codigo.
+   El razonamiento es bueno. Pero Langfuse lee `gen_ai.input.messages` y
+   `gen_ai.output.messages` de los ATRIBUTOS del span. Si seguimos la guia al
+   pie de la letra, Langfuse ingiere el span y lo muestra sin input ni output,
+   que es justo lo que lo hace util.
+
+   Resolucion: emitir en atributos, y borrarlos en la rama del Collector que
+   va a ClickHouse (donde son decenas de KB sin ninguna consulta que los use).
+
+2. Enmascarar aqui es la PRIMERA capa, no la unica.
+
+   El Collector tiene un `redaction` processor como red de seguridad. Esa
+   segunda capa es la que importa de verdad: significa que un fallo de
+   instrumentacion en una app no se convierte en una fuga en el almacen.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Callable
+from typing import Any, Final
+
+_TRUE: Final = frozenset({"1", "true", "yes", "on"})
+
+# Umbral por defecto. Un prompt entero puede ser de decenas de KB; un atributo
+# de span no es sitio para eso.
+_DEFAULT_MAX_BYTES: Final = 8192
+
+_PATTERNS: Final[tuple[tuple[re.Pattern[str], str], ...]] = (
+    (re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b"), "[EMAIL]"),
+    (re.compile(r"\b(?:\d[ -]*?){13,19}\b"), "[CARD]"),
+    # Telefono: EXIGE separadores o prefijo internacional. Una tirada suelta de
+    # diez digitos es casi siempre un identificador, un timestamp o un contador,
+    # no un telefono. Redactarla destruye datos utiles y no protege nada.
+    # Mismo criterio que el `redaction` processor del Collector: las dos capas
+    # tienen que coincidir o los datos salen distintos segun por donde pasen.
+    (re.compile(r"\+\d{1,3}[-.\s]\d{2,4}[-.\s]\d{2,4}[-.\s]?\d{0,4}"), "[PHONE]"),
+    (re.compile(r"\b\d{3}[-.\s]\d{3}[-.\s]\d{4}\b"), "[PHONE]"),
+    (re.compile(r"\b\d{8}[A-HJ-NP-TV-Z]\b"), "[DNI]"),
+    (re.compile(r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b"), "[IBAN]"),
+    (re.compile(r"(?i)\b(?:sk|pk)-[A-Za-z0-9_\-]{16,}"), "[KEY]"),
+    (re.compile(r"(?i)\bBearer\s+[A-Za-z0-9_\-.]{16,}"), "[TOKEN]"),
+)
+
+
+def capture_enabled() -> bool:
+    """Si se captura el contenido de prompts y respuestas.
+
+    Por defecto NO. Se activa en desarrollo y de forma selectiva por aplicacion
+    en produccion, donde la evaluacion aporta.
+    """
+    val = os.getenv("ARGUS_CAPTURE_CONTENT", "")
+    if val:
+        return val.strip().lower() in _TRUE
+    # Compatibilidad con la variable estandar de OpenTelemetry.
+    return os.getenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "").strip().lower() in _TRUE
+
+
+def max_bytes() -> int:
+    try:
+        return max(0, int(os.getenv("ARGUS_CONTENT_MAX_BYTES", str(_DEFAULT_MAX_BYTES))))
+    except ValueError:
+        return _DEFAULT_MAX_BYTES
+
+
+def mask(text: str) -> str:
+    """Redacta PII conocida. Primera capa; el Collector es la segunda."""
+    for pattern, replacement in _PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def serialize(
+    payload: Any,
+    *,
+    masker: Callable[[str], str] | None = None,
+    limit: int | None = None,
+) -> tuple[str, bool]:
+    """Serializa a JSON, enmascara y trunca.
+
+    Devuelve `(texto, truncado)`. Nunca lanza: si el payload no es
+    serializable cae a `repr`, porque perder telemetria es aceptable y tumbar
+    la aplicacion del usuario no lo es.
+    """
+    try:
+        raw = json.dumps(payload, ensure_ascii=False, default=str)
+    except (TypeError, ValueError):
+        raw = repr(payload)
+
+    raw = (masker or mask)(raw)
+
+    cap = max_bytes() if limit is None else limit
+    if cap and len(raw.encode("utf-8")) > cap:
+        # Cortamos por bytes y descartamos el ultimo caracter posiblemente
+        # partido a mitad de secuencia UTF-8.
+        raw = raw.encode("utf-8")[:cap].decode("utf-8", errors="ignore")
+        return raw, True
+
+    return raw, False

argus_obs_semconv-1.0.0a3/src/argus_semconv/_metrics_api.py

@@ -0,0 +1,124 @@
+"""Instrumentos de metricas GenAI, emitidos desde la API de OpenTelemetry.
+
+Por que vive aqui y no en el SDK de aplicacion: si las metricas hubiera que
+emitirlas a mano, nadie las emitiria. Las convenciones dicen que
+`gen_ai.client.operation.duration` y `gen_ai.client.token.usage` van desde el
+dia uno, y eso solo se cumple si salen SOLAS del mismo context manager que ya
+se usa para las trazas.
+
+La API de metricas de OpenTelemetry tiene la misma propiedad que la de trazas:
+sin SDK configurado devuelve instrumentos no operativos con coste cero. Asi que
+una libreria puede emitir metricas sin imponer nada a quien la importe, igual
+que con los spans.
+
+Los BUCKETS no se fijan aqui —eso es configuracion del SDK— sino en las vistas
+de `argus-obs-sdk`, que los aplica por nombre de instrumento cuando esta
+presente.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry import metrics
+
+from . import attributes as A
+
+_meter = metrics.get_meter("argus-semconv", A.SEMCONV_VERSION)
+
+# Creados una vez al importar. Sin SDK son no-ops.
+_duracion = _meter.create_histogram(
+    A.M_GEN_AI_CLIENT_OPERATION_DURATION,
+    unit=A.M_GEN_AI_CLIENT_OPERATION_DURATION_UNIT,
+    description="Duracion de la operacion GenAI",
+)
+_tokens = _meter.create_histogram(
+    A.M_GEN_AI_CLIENT_TOKEN_USAGE,
+    unit=A.M_GEN_AI_CLIENT_TOKEN_USAGE_UNIT,
+    description="Tokens consumidos, con el tipo como dimension",
+)
+_ttft = _meter.create_histogram(
+    A.M_GEN_AI_SERVER_TIME_TO_FIRST_TOKEN,
+    unit=A.M_GEN_AI_SERVER_TIME_TO_FIRST_TOKEN_UNIT,
+    description="Tiempo hasta el primer token",
+)
+_coste = _meter.create_counter(
+    A.M_ARGUS_COST_USD,
+    unit=A.M_ARGUS_COST_USD_UNIT,
+    description="Coste atribuido",
+)
+
+
+def _base(operation: str, provider: str, model: str | None) -> dict[str, Any]:
+    attrs: dict[str, Any] = {
+        A.GEN_AI_OPERATION_NAME: operation,
+        A.GEN_AI_PROVIDER_NAME: provider,
+    }
+    if model:
+        attrs[A.GEN_AI_REQUEST_MODEL] = model
+    return attrs
+
+
+def record_duration(
+    *, operation: str, provider: str, model: str | None,
+    seconds: float, error_type: str | None = None,
+) -> None:
+    attrs = _base(operation, provider, model)
+    if error_type:
+        attrs[A.ERROR_TYPE] = error_type
+    try:
+        _duracion.record(seconds, attrs)
+    except Exception:  # noqa: BLE001 - la telemetria nunca tumba la app
+        pass
+
+
+def record_tokens(
+    *, operation: str, provider: str, model: str | None,
+    input_tokens: int | None = None, output_tokens: int | None = None,
+) -> None:
+    """`gen_ai.token.type` va como DIMENSION, no como dos instrumentos.
+
+    Es lo que dice la especificacion y lo que permite agregar por modelo sin
+    unir series a mano.
+    """
+    attrs = _base(operation, provider, model)
+    try:
+        if input_tokens:
+            _tokens.record(input_tokens, {**attrs, "gen_ai.token.type": "input"})
+        if output_tokens:
+            _tokens.record(output_tokens, {**attrs, "gen_ai.token.type": "output"})
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def record_ttft(*, provider: str, model: str | None, seconds: float, backend_id: str | None = None) -> None:
+    attrs = _base("chat", provider, model)
+    attrs.pop(A.GEN_AI_OPERATION_NAME, None)
+    if backend_id:
+        attrs[A.ARGUS_BACKEND_ID] = backend_id
+    try:
+        _ttft.record(seconds, attrs)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def record_cost(
+    *, cost_usd: float, model: str | None,
+    app: str | None = None, feature: str | None = None, use_case: str | None = None,
+) -> None:
+    """Dimensiones pensadas para poder ATRIBUIR el coste.
+
+    Sin app, funcionalidad y caso de uso, el coste llega como un numero opaco a
+    fin de mes y no se puede optimizar nada.
+    """
+    attrs = {
+        A.ARGUS_APP: app or "unknown",
+        A.ARGUS_FEATURE: feature or "unknown",
+        A.ARGUS_USE_CASE: use_case or "unknown",
+    }
+    if model:
+        attrs[A.GEN_AI_REQUEST_MODEL] = model
+    try:
+        _coste.add(cost_usd, attrs)
+    except Exception:  # noqa: BLE001
+        pass