progress-observability 1.5.0__tar.gz → 1.5.3__tar.gz

{progress_observability-1.5.0 → progress_observability-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: progress-observability
-Version: 1.5.0
+Version: 1.5.3
 Summary: Progress Observability instrumentation for Python agents
 Project-URL: Homepage, https://github.com/telerik/agentclarity
 Project-URL: Repository, https://github.com/telerik/agentclarity
@@ -10,7 +10,8 @@ License: MIT
 License-File: LICENSE
 License-File: notices.txt
 Requires-Python: <4.0.0,>=3.10.0
-Requires-Dist: httpx>=0.23.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: requests==2.34.2
 Requires-Dist: traceloop-sdk==0.62.3
 Description-Content-Type: text/markdown
 
@@ -50,7 +51,7 @@ Common options (for `Observability.instrument`):
 - `app_name` - Application name for telemetry
 - `endpoint` - OpenTelemetry collector endpoint
 - `api_key` - Authentication key
-- `debug` - Enable debug logging
+- `debug` - Show sanitized OTLP trace-delivery failures on standard error (default: `False`)
 - `instruments` / `block_instruments` - Control what gets traced via `ObservabilityInstruments`
 - `trace_content` - when set to `False` will stop sending LLM prompt/responses as part of the telemetry data
 - `additional_tags` - custom tags (see below)
@@ -61,8 +62,10 @@ Environment overrides (optional):
 - `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
 - `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
 - `OBSERVABILITY_TRACE_CONTENT` when set to `false` will stop sending LLM prompt/responses as part of the telemetry data
+- `OBSERVABILITY_DEBUG` enables sanitized trace-delivery errors when set to `1`, `true`, or `yes`
 
 Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
+Invalid endpoints and missing or empty API keys raise during initialization. Delivery failures do not terminate the application and remain silent unless debug logging is enabled. Debug messages never include API keys, authorization headers, or telemetry payloads.
 
 ## Custom Tags
 

{progress_observability-1.5.0 → progress_observability-1.5.3}/README.md

@@ -34,7 +34,7 @@ Common options (for `Observability.instrument`):
 - `app_name` - Application name for telemetry
 - `endpoint` - OpenTelemetry collector endpoint
 - `api_key` - Authentication key
-- `debug` - Enable debug logging
+- `debug` - Show sanitized OTLP trace-delivery failures on standard error (default: `False`)
 - `instruments` / `block_instruments` - Control what gets traced via `ObservabilityInstruments`
 - `trace_content` - when set to `False` will stop sending LLM prompt/responses as part of the telemetry data
 - `additional_tags` - custom tags (see below)
@@ -45,8 +45,10 @@ Environment overrides (optional):
 - `OBSERVABILITY_ENDPOINT` sets a custom endpoint for collecting data (e.g. "https://collector.observability.progress.com:443")
 - `OBSERVABILITY_API_KEY` sets the authentication key to use when sending data
 - `OBSERVABILITY_TRACE_CONTENT` when set to `false` will stop sending LLM prompt/responses as part of the telemetry data
+- `OBSERVABILITY_DEBUG` enables sanitized trace-delivery errors when set to `1`, `true`, or `yes`
 
 Auth headers are added automatically for HTTP(S) endpoints when api_key is provided.
+Invalid endpoints and missing or empty API keys raise during initialization. Delivery failures do not terminate the application and remain silent unless debug logging is enabled. Debug messages never include API keys, authorization headers, or telemetry payloads.
 
 ## Custom Tags
 

{progress_observability-1.5.0 → progress_observability-1.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "progress-observability"
-version = "1.5.0"
+version = "1.5.3"
 description = "Progress Observability instrumentation for Python agents"
 readme = "README.md"
 license = { text = "MIT" }
@@ -12,7 +12,8 @@ license-files = ["LICENSE", "notices.txt"]
 requires-python = ">=3.10.0,<4.0.0"
 dependencies = [
     "traceloop-sdk==0.62.3",
-    "httpx>=0.23.0",
+    "httpx==0.28.1",
+    "requests==2.34.2",
 ]
 [project.urls]
 Homepage = "https://github.com/telerik/agentclarity"

{progress_observability-1.5.0 → progress_observability-1.5.3}/src/progress/observability/genkit_span_processor.py

@@ -37,6 +37,20 @@ def _normalize_role(role: Any) -> str:
     return role if isinstance(role, str) else "unknown"
 
 
+def _merge_consecutive_text_parts(parts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    # Streaming responses (e.g. Genkit's generate_stream) record the final message content
+    # as a sequence of raw text deltas rather than one coalesced string. Merge adjacent
+    # text parts so consumers see the reassembled text instead of fragmented chunks.
+    merged: list[dict[str, Any]] = []
+    for part in parts:
+        previous = merged[-1] if merged else None
+        if part.get("type") == "text" and previous is not None and previous.get("type") == "text":
+            previous["content"] = f"{previous.get('content', '')}{part.get('content', '')}"
+            continue
+        merged.append(dict(part))
+    return merged
+
+
 def _normalize_parts(content: Any) -> list[dict[str, Any]]:
     if not isinstance(content, list):
         return [{"type": "text", "content": content}] if isinstance(content, str) else []
@@ -65,7 +79,7 @@ def _normalize_parts(content: Any) -> list[dict[str, Any]]:
             parts.append(part)
         else:
             parts.append({"type": item.get("type", "unknown"), **item})
-    return parts
+    return _merge_consecutive_text_parts(parts)
 
 
 def _normalize_messages(value: Any) -> list[dict[str, Any]]:
@@ -81,6 +95,9 @@ def _normalize_messages(value: Any) -> list[dict[str, Any]]:
 class GenkitSpanProcessor:
     """Post-process native Genkit action spans before export."""
 
+    def __init__(self, trace_content: bool = True) -> None:
+        self._trace_content = trace_content
+
     def on_end(self, span: Any) -> None:
         attributes = get_writable_attributes(span)
         if not attributes or "genkit:type" not in attributes:
@@ -92,8 +109,44 @@ class GenkitSpanProcessor:
             return
         if subtype == "tool":
             attributes.setdefault("traceloop.span.kind", "tool")
+            attributes.setdefault("gen_ai.operation.name", "execute_tool")
+            tool_name = attributes.get("genkit:name")
+            if isinstance(tool_name, str) and tool_name:
+                attributes.setdefault("gen_ai.tool.name", tool_name)
+            if self._trace_content:
+                tool_input = attributes.get("genkit:input")
+                if isinstance(tool_input, str):
+                    attributes.setdefault("gen_ai.tool.call.arguments", tool_input)
+                tool_output = attributes.get("genkit:output")
+                if isinstance(tool_output, str):
+                    attributes.setdefault("gen_ai.tool.call.result", tool_output)
             return
         if subtype != "model":
+            # The root span of ai.generate()/ai.generate_stream() calls made outside of an
+            # explicit flow isn't tagged with a subtype (it's registered as a "util"
+            # action), so it falls through every branch above and is left without a span
+            # kind or provider. Since genkit:input carries the requested model name, derive
+            # both from it the same way the model span does. Genkit's built-in generate
+            # action always reports subtype "util" (or omits it for nested turns); guard
+            # on that so a user-defined action merely named "generate" with a different
+            # subtype (e.g. "prompt") isn't misclassified.
+            if attributes.get("genkit:name") == "generate" and subtype in (None, "util"):
+                attributes.setdefault("traceloop.span.kind", "agent")
+                input_data = _parse_json(attributes.get("genkit:input"))
+                model_name = input_data.get("model") if input_data else None
+                if isinstance(model_name, str) and model_name:
+                    separator = model_name.find("/")
+                    if separator >= 0:
+                        plugin = model_name[:separator].lower()
+                        model = model_name[separator + 1 :]
+                        if "gen_ai.provider.name" not in attributes and plugin:
+                            attributes["gen_ai.provider.name"] = _PROVIDERS.get(
+                                plugin, plugin[:1].upper() + plugin[1:]
+                            )
+                    else:
+                        model = model_name
+                    attributes.setdefault("gen_ai.request.model", model)
+                    attributes.setdefault("gen_ai.response.model", model)
             return
 
         name = attributes.get("genkit:name")
@@ -111,24 +164,26 @@ class GenkitSpanProcessor:
         attributes.setdefault("gen_ai.request.model", model)
         attributes.setdefault("gen_ai.response.model", model)
 
-        input_data = _parse_json(attributes.get("genkit:input"))
-        if input_data and "gen_ai.input.messages" not in attributes:
-            messages = _normalize_messages(input_data.get("messages"))
-            if messages:
-                attributes["gen_ai.input.messages"] = json.dumps(messages)
+        if self._trace_content:
+            input_data = _parse_json(attributes.get("genkit:input"))
+            if input_data and "gen_ai.input.messages" not in attributes:
+                messages = _normalize_messages(input_data.get("messages"))
+                if messages:
+                    attributes["gen_ai.input.messages"] = json.dumps(messages)
 
         output_data = _parse_json(attributes.get("genkit:output"))
         if not output_data:
             return
-        output_message = output_data.get("message")
-        if output_message is None and isinstance(output_data.get("candidates"), list):
-            candidates = output_data["candidates"]
-            if candidates and isinstance(candidates[0], dict):
-                output_message = candidates[0].get("message")
-        if isinstance(output_message, dict) and "gen_ai.output.messages" not in attributes:
-            messages = _normalize_messages([output_message])
-            if messages:
-                attributes["gen_ai.output.messages"] = json.dumps(messages)
+        if self._trace_content:
+            output_message = output_data.get("message")
+            if output_message is None and isinstance(output_data.get("candidates"), list):
+                candidates = output_data["candidates"]
+                if candidates and isinstance(candidates[0], dict):
+                    output_message = candidates[0].get("message")
+            if isinstance(output_message, dict) and "gen_ai.output.messages" not in attributes:
+                messages = _normalize_messages([output_message])
+                if messages:
+                    attributes["gen_ai.output.messages"] = json.dumps(messages)
 
         usage = output_data.get("usage")
         if isinstance(usage, dict):

{progress_observability-1.5.0 → progress_observability-1.5.3}/src/progress/observability/sdk.py

@@ -19,6 +19,7 @@ Quick Start:
 
 """
 
+import re
 import sys
 import os
 from contextlib import redirect_stdout, redirect_stderr
@@ -63,6 +64,88 @@ class Observability:
     _tags_processor = None  # TagsSpanProcessor instance for tag propagation
     SDK = Traceloop
 
+    _EXPORTER_LOGGER_NAME = "opentelemetry.exporter.otlp.proto.http.trace_exporter"
+    _EXPORTER_HANDLER_MARKER = "_progress_observability_handler"
+    _EXPORTER_FILTER_MARKER = "_progress_observability_filter"
+
+    @staticmethod
+    def _sanitize_exporter_message(message: str) -> str:
+        """Map exporter failures to useful messages without exposing request data."""
+        normalized = message.lower()
+
+        status_match = re.search(r"\b(401|403)\b", normalized)
+        if status_match:
+            status_messages = {
+                "401": "HTTP 401 Unauthorized.",
+                "403": "HTTP 403 Forbidden.",
+            }
+            return status_messages[status_match.group(1)]
+        if "timed out" in normalized or "timeout" in normalized:
+            return "request timed out."
+        if any(
+            term in normalized for term in ("name resolution", "resolve host", "dns")
+        ):
+            return "collector host could not be resolved."
+        if any(
+            term in normalized
+            for term in (
+                "connection refused",
+                "unreachable",
+                "failed to establish a new connection",
+            )
+        ):
+            return "collector is unreachable."
+        return "failed to export traces."
+
+    @classmethod
+    def _configure_exporter_logging(cls, debug_enabled: bool) -> None:
+        exporter_logger = logging.getLogger(cls._EXPORTER_LOGGER_NAME)
+
+        for handler in list(exporter_logger.handlers):
+            if getattr(handler, cls._EXPORTER_HANDLER_MARKER, False):
+                exporter_logger.removeHandler(handler)
+                handler.close()
+        for logger_filter in list(exporter_logger.filters):
+            if getattr(logger_filter, cls._EXPORTER_FILTER_MARKER, False):
+                exporter_logger.removeFilter(logger_filter)
+
+        exporter_logger.propagate = False
+        exporter_logger.disabled = not debug_enabled
+
+        if not debug_enabled:
+            return
+
+        class SanitizingFilter(logging.Filter):
+            _progress_observability_filter = True
+
+            def filter(self, record: logging.LogRecord) -> bool:
+                record.msg = cls._sanitize_exporter_message(record.getMessage())
+                record.args = ()
+                record.exc_info = None
+                record.exc_text = None
+                record.stack_info = None
+                return True
+
+        exporter_logger.setLevel(logging.ERROR)
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setLevel(logging.ERROR)
+        handler.setFormatter(
+            logging.Formatter(
+                "[Observability] Failed to export traces: %(message)s"
+            )
+        )
+        setattr(handler, cls._EXPORTER_HANDLER_MARKER, True)
+        exporter_logger.addFilter(SanitizingFilter())
+        exporter_logger.addHandler(handler)
+
+    @staticmethod
+    def _report_configuration_failure(debug_enabled: bool, message: str) -> None:
+        if debug_enabled:
+            print(
+                f"[Observability] Configuration error: {message}",
+                file=sys.stderr,
+            )
+
     @staticmethod
     def _validate_endpoint(endpoint: Optional[str]) -> str:
         """
@@ -131,7 +214,7 @@ class Observability:
         return endpoint
 
     @staticmethod
-    def _validate_api_key(api_key: Optional[str]) -> None:
+    def _validate_api_key(api_key: Optional[str]) -> str:
         """Validate the API key is provided via parameter or environment variable.
         Args:
             api_key: The API key parameter value to validate
@@ -258,17 +341,49 @@ class Observability:
         # Always allow re-initialization to support different instrument configurations
         # The underlying traceloop SDK will handle duplicate initialization safely
 
-        # Validate and resolve endpoint and API key before processing
-        endpoint = cls._validate_endpoint(endpoint)
-        api_key = cls._validate_api_key(api_key)
-
-        app_name = init_environment(app_name, trace_content)
-
         # Ensure debug logs are visible when explicitly requested.
         # Honor both the debug parameter and the OBSERVABILITY_DEBUG env var.
         # Only raise the progress.observability logger - not the root logger,
         # which would make every third-party library verbose.
-        debug_enabled = debug or os.getenv("OBSERVABILITY_DEBUG", "").lower() in ("1", "true", "yes")
+        debug_enabled = debug or os.getenv("OBSERVABILITY_DEBUG", "").lower() in (
+            "1",
+            "true",
+            "yes",
+        )
+        cls._configure_exporter_logging(debug_enabled)
+
+        endpoint_error: Optional[Exception] = None
+        api_key_error: Optional[Exception] = None
+
+        try:
+            endpoint = cls._validate_endpoint(endpoint)
+        except EndpointValidationError as exc:
+            endpoint_error = exc
+            cls._report_configuration_failure(
+                debug_enabled,
+                "endpoint is invalid. Use a valid http/https URL with host and port.",
+            )
+
+        try:
+            api_key = cls._validate_api_key(api_key)
+        except (TypeError, ValueError) as exc:
+            api_key_error = exc
+            cls._report_configuration_failure(
+                debug_enabled,
+                "API key is missing or empty.",
+            )
+
+        if endpoint_error and api_key_error:
+            raise ValueError(
+                "Invalid configuration: endpoint is invalid and API key is missing or empty."
+            ) from api_key_error
+        if endpoint_error:
+            raise endpoint_error
+        if api_key_error:
+            raise api_key_error
+
+        app_name = init_environment(app_name, trace_content)
+
         if debug_enabled:
             pkg_logger = logging.getLogger("progress.observability")
             pkg_logger.setLevel(logging.DEBUG)
@@ -280,9 +395,13 @@ class Observability:
                 handler.addFilter(lambda record: record.levelno == logging.DEBUG)
                 pkg_logger.addHandler(handler)
 
+        # Resolve the effective trace_content setting (init_environment() already
+        # applied env var precedence and may have set TRACELOOP_TRACE_CONTENT).
+        trace_content_enabled = os.getenv("TRACELOOP_TRACE_CONTENT", "true").lower() == "true"
+
         # Create processors with debug mode
         genai_message_processor = GenAIMessageProcessor(debug=debug_enabled)
-        genkit_span_processor = GenkitSpanProcessor()
+        genkit_span_processor = GenkitSpanProcessor(trace_content=trace_content_enabled)
         model_fix_processor = ModelFixProcessor(debug=debug_enabled)
         cls._model_fix_processor = model_fix_processor
 
@@ -376,6 +495,8 @@ class Observability:
             After shutdown, subsequent calls to instrument() will reinitialize
             the instrumentation.
         """
+        cls._configure_exporter_logging(False)
+
         if not cls._initialized:
             return True
 

{progress_observability-1.5.0 → progress_observability-1.5.3}/uv.lock

@@ -1544,16 +1544,18 @@ wheels = [
 
 [[package]]
 name = "progress-observability"
-version = "1.5.0"
+version = "1.5.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
+    { name = "requests" },
     { name = "traceloop-sdk" },
 ]
 
 [package.metadata]
 requires-dist = [
-    { name = "httpx", specifier = ">=0.23.0" },
+    { name = "httpx", specifier = "==0.28.1" },
+    { name = "requests", specifier = "==2.34.2" },
     { name = "traceloop-sdk", specifier = "==0.62.3" },
 ]