feat(telemetry): widen usage attrs, add metrics histograms, opt-in content events

src/celeste/client.py

@@ -213,16 +213,14 @@ async def _predict(
         Returns:
             Output of the parameterized type.
         """
-        with telemetry.tracer.start_as_current_span(
-            telemetry.span_name(self.modality, self.model),
-            attributes=telemetry.request_attributes(
-                model=self.model,
-                provider=self.provider,
-                protocol=self.protocol,
-                modality=self.modality,
-            ),
-        ) as span:
+        with telemetry.gen_ai_span(
+            model=self.model,
+            provider=self.provider,
+            protocol=self.protocol,
+            modality=self.modality,
+        ) as (span, request_attrs):
             inputs, parameters = self._validate_artifacts(inputs, **parameters)
+            telemetry.add_input_event(span, inputs)
             request_body = self._build_request(
                 inputs, extra_body=extra_body, **parameters
             )
@@ -249,7 +247,7 @@ async def _predict(
                 tool_calls=tool_calls,
                 **kwargs,
             )
-            span.set_attributes(telemetry.output_attributes(output))
+            telemetry.record_output(span, output, request_attrs)
             return output
 
     def _parse_tool_calls(self, response_data: dict[str, Any]) -> list[ToolCall]:
@@ -297,18 +295,17 @@ def _stream(
         request_body = self._build_request(
             inputs, extra_body=extra_body, streaming=True, **parameters
         )
+        request_attrs = telemetry.request_attributes(
+            model=self.model,
+            provider=self.provider,
+            protocol=self.protocol,
+            modality=self.modality,
+        )
         span = telemetry.tracer.start_span(
             telemetry.span_name(self.modality, self.model),
-            attributes={
-                **telemetry.request_attributes(
-                    model=self.model,
-                    provider=self.provider,
-                    protocol=self.protocol,
-                    modality=self.modality,
-                ),
-                "gen_ai.request.stream": True,
-            },
+            attributes={**request_attrs, "gen_ai.request.stream": True},
         )
+        telemetry.add_input_event(span, inputs)
         sse_iterator = self._make_stream_request(
             request_body,
             endpoint=endpoint,
@@ -326,7 +323,7 @@ def _stream(
             },
             **parameters,
         )
-        return telemetry.trace_stream(stream, span)  # type: ignore[return-value]
+        return telemetry.trace_stream(stream, span, metric_attributes=request_attrs)  # type: ignore[return-value]
 
     @classmethod
     @abstractmethod

src/celeste/modalities/text/io.py

@@ -50,6 +50,7 @@ class TextUsage(Usage):
     input_tokens: int | None = None
     output_tokens: int | None = None
     reasoning_tokens: int | None = None
+    cached_tokens: int | None = None
 
 
 class TextOutput(Output[TextContent]):

src/celeste/protocols/chatcompletions/client.py

@@ -117,10 +117,12 @@ def map_usage_fields(usage_data: dict[str, Any]) -> dict[str, int | float | None
 
         Shared by client and streaming across all capabilities.
         """
+        prompt_tokens_details = usage_data.get("prompt_tokens_details") or {}
         return {
             UsageField.INPUT_TOKENS: usage_data.get("prompt_tokens"),
             UsageField.OUTPUT_TOKENS: usage_data.get("completion_tokens"),
             UsageField.TOTAL_TOKENS: usage_data.get("total_tokens"),
+            UsageField.CACHED_TOKENS: prompt_tokens_details.get("cached_tokens"),
         }
 
     def _parse_usage(

src/celeste/providers/google/generate_content/client.py

@@ -110,6 +110,7 @@ def map_usage_fields(usage_data: dict[str, Any]) -> dict[str, int | float | None
             UsageField.OUTPUT_TOKENS: usage_data.get("candidatesTokenCount"),
             UsageField.TOTAL_TOKENS: usage_data.get("totalTokenCount"),
             UsageField.REASONING_TOKENS: usage_data.get("thoughtsTokenCount"),
+            UsageField.CACHED_TOKENS: usage_data.get("cachedContentTokenCount"),
         }
 
     def _parse_usage(