paid-python 1.0.0a4__tar.gz → 1.0.2__tar.gz

{paid_python-1.0.0a4 → paid_python-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: paid-python
-Version: 1.0.0a4
+Version: 1.0.2
 Summary: 
 Requires-Python: >=3.9,<3.14
 Classifier: Intended Audience :: Developers
@@ -20,6 +20,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: httpx (>=0.21.2)
 Requires-Dist: mutagen (>=1.47.0)
+Requires-Dist: openinference-instrumentation-anthropic (>=0.1.20)
 Requires-Dist: openinference-instrumentation-bedrock (>=0.1.0)
 Requires-Dist: openinference-instrumentation-google-genai (>=0.1.8)
 Requires-Dist: openinference-instrumentation-instructor (>=0.1.0)
@@ -28,11 +29,9 @@ Requires-Dist: openinference-instrumentation-openai (>=0.1.40)
 Requires-Dist: openinference-instrumentation-openai-agents (>=1.0.0)
 Requires-Dist: opentelemetry-api (>=1.23.0)
 Requires-Dist: opentelemetry-exporter-otlp-proto-http (>=1.23.0)
-Requires-Dist: opentelemetry-instrumentation-anthropic (>=0.47.0)
 Requires-Dist: opentelemetry-sdk (>=1.23.0)
 Requires-Dist: pydantic (>=1.9.2)
 Requires-Dist: pydantic-core (>=2.18.2,<3.0.0)
-Requires-Dist: python-dotenv (>=0.15.0)
 Requires-Dist: typing_extensions (>=4.0.0)
 Description-Content-Type: text/markdown
 
@@ -281,83 +280,78 @@ image_generate()
 
 You can attach custom metadata to your traces by passing a `metadata` dictionary to the `paid_tracing()` decorator or context manager. This metadata will be stored with the trace and can be used to filter and query traces later.
 
-<Tabs>
-  <Tab title="Python - Decorator">
-    ```python
-    from paid.tracing import paid_tracing, signal, initialize_tracing
-    from paid.tracing.wrappers import PaidOpenAI
-    from openai import OpenAI
+<details>
+<summary><strong>Python - Decorator</strong></summary>
 
-    initialize_tracing()
+```python
+from paid.tracing import paid_tracing, signal, initialize_tracing
+from paid.tracing.wrappers import PaidOpenAI
+from openai import OpenAI
 
-    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+initialize_tracing()
 
-    @paid_tracing(
-        "customer_123",
-        external_product_id="product_123",
-        metadata={
-            "campaign_id": "campaign_456",
-            "environment": "production",
-            "user_tier": "enterprise"
-        }
+openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+@paid_tracing(
+    "customer_123",
+    external_product_id="product_123",
+    metadata={
+        "campaign_id": "campaign_456",
+        "environment": "production",
+        "user_tier": "enterprise"
+    }
+)
+def process_event(event):
+    """Process event with custom metadata"""
+    response = openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": event.content}]
+    )
+
+    signal("event_processed", enable_cost_tracing=True)
+    return response
+
+process_event(incoming_event)
+```
+
+</details>
+
+<details>
+<summary><strong>Python - Context Manager</strong></summary>
+
+```python
+from paid.tracing import paid_tracing, signal, initialize_tracing
+from paid.tracing.wrappers import PaidOpenAI
+from openai import OpenAI
+
+initialize_tracing()
+
+openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+def process_event(event):
+    """Process event with custom metadata"""
+    response = openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": event.content}]
     )
-    def process_event(event):
-        """Process event with custom metadata"""
-        response = openai_client.chat.completions.create(
-            model="gpt-4",
-            messages=[{"role": "user", "content": event.content}]
-        )
 
-        signal("event_processed", enable_cost_tracing=True)
-        return response
+    signal("event_processed", enable_cost_tracing=True)
+    return response
 
+# Pass metadata to context manager
+with paid_tracing(
+    "customer_123",
+    external_product_id="product_123",
+    metadata={
+        "campaign_id": "campaign_456",
+        "environment": "production",
+        "user_tier": "enterprise"
+    }
+):
     process_event(incoming_event)
-    ```
-
-  </Tab>
-
-  <Tab title="Python - Context Manager">
-    ```python
-    from paid.tracing import paid_tracing, signal, initialize_tracing
-    from paid.tracing.wrappers import PaidOpenAI
-    from openai import OpenAI
-
-    initialize_tracing()
-
-    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
-
-    def process_event(event):
-        """Process event with custom metadata"""
-        response = openai_client.chat.completions.create(
-            model="gpt-4",
-            messages=[{"role": "user", "content": event.content}]
-        )
-
-        signal("event_processed", enable_cost_tracing=True)
-        return response
-
-    # Pass metadata to context manager
-    with paid_tracing(
-        "customer_123",
-        external_product_id="product_123",
-        metadata={
-            "campaign_id": "campaign_456",
-            "environment": "production",
-            "user_tier": "enterprise"
-        }
-    ):
-        process_event(incoming_event)
-    ```
-
-  </Tab>
-
-  <Tab title="Node.js">
-    ```typescript
-    // Metadata support is not yet available in the Node.js SDK.
-    // Please use Python for passing custom metadata to traces.
-    ```
-  </Tab>
-</Tabs>
+```
+
+</details>
 
 #### Querying Traces by Metadata
 

{paid_python-1.0.0a4 → paid_python-1.0.2}/README.md

@@ -243,83 +243,78 @@ image_generate()
 
 You can attach custom metadata to your traces by passing a `metadata` dictionary to the `paid_tracing()` decorator or context manager. This metadata will be stored with the trace and can be used to filter and query traces later.
 
-<Tabs>
-  <Tab title="Python - Decorator">
-    ```python
-    from paid.tracing import paid_tracing, signal, initialize_tracing
-    from paid.tracing.wrappers import PaidOpenAI
-    from openai import OpenAI
-
-    initialize_tracing()
-
-    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
-
-    @paid_tracing(
-        "customer_123",
-        external_product_id="product_123",
-        metadata={
-            "campaign_id": "campaign_456",
-            "environment": "production",
-            "user_tier": "enterprise"
-        }
+<details>
+<summary><strong>Python - Decorator</strong></summary>
+
+```python
+from paid.tracing import paid_tracing, signal, initialize_tracing
+from paid.tracing.wrappers import PaidOpenAI
+from openai import OpenAI
+
+initialize_tracing()
+
+openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+@paid_tracing(
+    "customer_123",
+    external_product_id="product_123",
+    metadata={
+        "campaign_id": "campaign_456",
+        "environment": "production",
+        "user_tier": "enterprise"
+    }
+)
+def process_event(event):
+    """Process event with custom metadata"""
+    response = openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": event.content}]
     )
-    def process_event(event):
-        """Process event with custom metadata"""
-        response = openai_client.chat.completions.create(
-            model="gpt-4",
-            messages=[{"role": "user", "content": event.content}]
-        )
 
-        signal("event_processed", enable_cost_tracing=True)
-        return response
+    signal("event_processed", enable_cost_tracing=True)
+    return response
+
+process_event(incoming_event)
+```
+
+</details>
+
+<details>
+<summary><strong>Python - Context Manager</strong></summary>
 
+```python
+from paid.tracing import paid_tracing, signal, initialize_tracing
+from paid.tracing.wrappers import PaidOpenAI
+from openai import OpenAI
+
+initialize_tracing()
+
+openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
+
+def process_event(event):
+    """Process event with custom metadata"""
+    response = openai_client.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": event.content}]
+    )
+
+    signal("event_processed", enable_cost_tracing=True)
+    return response
+
+# Pass metadata to context manager
+with paid_tracing(
+    "customer_123",
+    external_product_id="product_123",
+    metadata={
+        "campaign_id": "campaign_456",
+        "environment": "production",
+        "user_tier": "enterprise"
+    }
+):
     process_event(incoming_event)
-    ```
-
-  </Tab>
-
-  <Tab title="Python - Context Manager">
-    ```python
-    from paid.tracing import paid_tracing, signal, initialize_tracing
-    from paid.tracing.wrappers import PaidOpenAI
-    from openai import OpenAI
-
-    initialize_tracing()
-
-    openai_client = PaidOpenAI(OpenAI(api_key="<OPENAI_API_KEY>"))
-
-    def process_event(event):
-        """Process event with custom metadata"""
-        response = openai_client.chat.completions.create(
-            model="gpt-4",
-            messages=[{"role": "user", "content": event.content}]
-        )
-
-        signal("event_processed", enable_cost_tracing=True)
-        return response
-
-    # Pass metadata to context manager
-    with paid_tracing(
-        "customer_123",
-        external_product_id="product_123",
-        metadata={
-            "campaign_id": "campaign_456",
-            "environment": "production",
-            "user_tier": "enterprise"
-        }
-    ):
-        process_event(incoming_event)
-    ```
-
-  </Tab>
-
-  <Tab title="Node.js">
-    ```typescript
-    // Metadata support is not yet available in the Node.js SDK.
-    // Please use Python for passing custom metadata to traces.
-    ```
-  </Tab>
-</Tabs>
+```
+
+</details>
 
 #### Querying Traces by Metadata
 

{paid_python-1.0.0a4 → paid_python-1.0.2}/pyproject.toml

@@ -3,7 +3,7 @@ name = "paid-python"
 
 [tool.poetry]
 name = "paid-python"
-version = "1.0.0-alpha4"
+version = "1.0.2"
 description = ""
 readme = "README.md"
 authors = []
@@ -37,6 +37,7 @@ Repository = 'https://github.com/paid-ai/paid-python'
 python = ">=3.9,<3.14"
 httpx = ">=0.21.2"
 mutagen = ">=1.47.0"
+openinference-instrumentation-anthropic = ">=0.1.20"
 openinference-instrumentation-bedrock = ">=0.1.0"
 openinference-instrumentation-google-genai = ">=0.1.8"
 openinference-instrumentation-instructor = ">=0.1.0"
@@ -45,11 +46,9 @@ openinference-instrumentation-openai = ">=0.1.40"
 openinference-instrumentation-openai-agents = ">=1.0.0"
 opentelemetry-api = ">=1.23.0"
 opentelemetry-exporter-otlp-proto-http = ">=1.23.0"
-opentelemetry-instrumentation-anthropic = ">=0.47.0"
 opentelemetry-sdk = ">=1.23.0"
 pydantic = ">= 1.9.2"
 pydantic-core = "^2.18.2"
-python-dotenv = ">=0.15.0"
 typing_extensions = ">= 4.0.0"
 
 [tool.poetry.group.dev.dependencies]

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/core/client_wrapper.py

@@ -20,10 +20,10 @@ class BaseClientWrapper:
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "paid-python/1.0.0-alpha4",
+            "User-Agent": "paid-python/1.0.2",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "paid-python",
-            "X-Fern-SDK-Version": "1.0.0-alpha4",
+            "X-Fern-SDK-Version": "1.0.2",
         }
         headers["Authorization"] = f"Bearer {self._get_token()}"
         return headers

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/logger.py

@@ -5,10 +5,7 @@ This file exports `logger` object for unified logging across the Paid SDK.
 import logging
 import os
 
-import dotenv
-
 # Configure logging
-_ = dotenv.load_dotenv()
 logger = logging.getLogger(__name__)
 
 # Set default log level to ERROR, allow override via PAID_LOG_LEVEL environment variable

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/tracing/autoinstrumentation.py

@@ -15,7 +15,7 @@ from paid.logger import logger
 
 # Safe imports for instrumentation libraries
 try:
-    from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
+    from openinference.instrumentation.anthropic import AnthropicInstrumentor
 
     ANTHROPIC_AVAILABLE = True
 except Exception:
@@ -118,9 +118,15 @@ def paid_autoinstrument(libraries: Optional[List[str]] = None) -> None:
         logger.info("Tracing not initialized, initializing automatically")
         initialize_tracing()
 
+    logger.debug(
+        "[paid:autoinstrument] tracer_provider type=%s, requested libraries=%s",
+        type(tracing.paid_tracer_provider).__name__, libraries,
+    )
+
     # Default to all supported libraries if none specified
     if libraries is None:
         libraries = ["anthropic", "openai", "openai-agents", "bedrock", "langchain", "google-genai", "instructor"]
+        logger.debug("[paid:autoinstrument] No libraries specified, defaulting to all: %s", libraries)
 
     for library in libraries:
         if library in _initialized_instrumentors:
@@ -157,6 +163,8 @@ def _instrument_anthropic() -> None:
         logger.warning("Anthropic library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting anthropic with AnthropicInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     # Instrument Anthropic with Paid's tracer provider
     AnthropicInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
 
@@ -172,6 +180,8 @@ def _instrument_openai() -> None:
         logger.warning("OpenAI library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting openai with OpenAIInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     # Instrument OpenAI with Paid's tracer provider
     OpenAIInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
 
@@ -187,6 +197,8 @@ def _instrument_openai_agents() -> None:
         logger.warning("OpenAI Agents library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting openai-agents with OpenAIAgentsInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     # Instrument OpenAI Agents with Paid's tracer provider
     OpenAIAgentsInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
 
@@ -202,6 +214,8 @@ def _instrument_bedrock() -> None:
         logger.warning("Bedrock instrumentation library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting bedrock with BedrockInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     # Instrument Bedrock with Paid's tracer provider
     BedrockInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
 
@@ -217,6 +231,8 @@ def _instrument_langchain() -> None:
         logger.warning("LangChain instrumentation library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting langchain with LangChainInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     # Instrument LangChain with Paid's tracer provider
     LangChainInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
 
@@ -232,6 +248,8 @@ def _instrument_google_genai() -> None:
         logger.warning("Google GenAI instrumentation library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting google-genai with GoogleGenAIInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     GoogleGenAIInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
     _initialized_instrumentors.append("google-genai")
     logger.info("Google GenAI auto-instrumentation enabled")
@@ -245,6 +263,8 @@ def _instrument_instructor() -> None:
         logger.warning("Instructor library not available, skipping instrumentation")
         return
 
+    logger.debug("[paid:autoinstrument] Instrumenting instructor with InstructorInstrumentor, provider=%s",
+                 type(tracing.paid_tracer_provider).__name__)
     InstructorInstrumentor().instrument(tracer_provider=tracing.paid_tracer_provider)
     _initialized_instrumentors.append("instructor")
     logger.info("Instructor auto-instrumentation enabled")

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/tracing/context_data.py

@@ -52,6 +52,7 @@ class ContextData:
         reset_token = cls._context[key].set(value)
         reset_tokens = cls._get_or_create_reset_tokens()
         reset_tokens[key] = reset_token
+        logger.debug("[paid:ctx] set_context_key: %s (type=%s)", key, type(value).__name__)
 
     @classmethod
     def unset_context_key(cls, key: str) -> None:
@@ -59,6 +60,7 @@ class ContextData:
         if key not in cls._context:
             logger.warning(f"Invalid context key: {key}")
             return
+        logger.debug("[paid:ctx] unset_context_key: %s", key)
         reset_tokens = cls._reset_tokens.get()
         if reset_tokens:
             _ = cls._context[key].set(None)
@@ -69,6 +71,7 @@ class ContextData:
     def reset_context(cls) -> None:
         reset_tokens = cls._reset_tokens.get()
         if reset_tokens:
+            logger.debug("[paid:ctx] reset_context: resetting keys=%s", list(reset_tokens.keys()))
             for key, reset_token in reset_tokens.items():
                 cls._context[key].reset(reset_token)
             reset_tokens.clear()

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/tracing/context_manager.py

@@ -80,7 +80,14 @@ class paid_tracing:
         self.span: Optional[Span] = None
         self.span_ctx: Optional[Any] = None  # Context manager for the span
 
+        logger.debug(
+            "[paid:ctx] paid_tracing.__init__: customer_id=%s, product_id=%s, tracing_token=%s, store_prompt=%s",
+            external_customer_id, external_product_id,
+            "present" if tracing_token else "none", store_prompt,
+        )
+
         if not get_token():
+            logger.debug("[paid:ctx] paid_tracing.__init__: token not set, auto-initializing tracing")
             initialize_tracing(None, self.collector_endpoint)
 
     def _setup_context(self) -> Optional[Context]:
@@ -106,6 +113,12 @@ class paid_tracing:
                 trace_flags=TraceFlags(TraceFlags.SAMPLED),
             )
             ctx = trace.set_span_in_context(NonRecordingSpan(span_context))
+            token_source = "explicit" if self.tracing_token else "context-inherited"
+            logger.debug("[paid:distributed] _setup_context: trace_id=%s (source=%s)",
+                         format(override_trace_id, '032x') if isinstance(override_trace_id, int) else str(override_trace_id),
+                         token_source)
+        else:
+            logger.debug("[paid:distributed] _setup_context: no override trace_id, using auto-generated")
 
         return ctx
 
@@ -130,9 +143,11 @@ class paid_tracing:
     def _enter_ctx(self):
         ctx = self._setup_context()
         tracer = get_paid_tracer()
-        logger.info(f"Creating span for external_customer_id: {self.external_customer_id}")
+        logger.debug("[paid:ctx] _enter_ctx: creating parent_span for customer_id=%s", self.external_customer_id)
         self.span_ctx = tracer.start_as_current_span("parent_span", context=ctx)
         self.span = self.span_ctx.__enter__()
+        logger.debug("[paid:ctx] _enter_ctx: span created, trace_id=%s",
+                     format(self.span.get_span_context().trace_id, '032x') if isinstance(self.span.get_span_context().trace_id, int) else str(self.span.get_span_context().trace_id))
         return self
 
     def _exit_ctx(self, exc_type, exc_val, exc_tb):
@@ -141,9 +156,10 @@ class paid_tracing:
             if self.span and self.span_ctx:
                 if exc_type is not None:
                     self.span.set_status(Status(StatusCode.ERROR, str(exc_val)))
+                    logger.debug("[paid:ctx] _exit_ctx: span ended with ERROR: %s", exc_val)
                 else:
                     self.span.set_status(Status(StatusCode.OK))
-                    logger.info("Context block executed successfully")
+                    logger.debug("[paid:ctx] _exit_ctx: span ended with OK")
 
                 self.span_ctx.__exit__(exc_type, exc_val, exc_tb)
                 self.span_ctx = None
@@ -157,6 +173,7 @@ class paid_tracing:
     # Decorator functionality
     def __call__(self, func: Callable[..., Any]) -> Callable[..., Any]:
         """Use as a decorator."""
+        logger.debug("[paid:ctx] __call__: wrapping fn=%s (async=%s)", getattr(func, '__name__', repr(func)), asyncio.iscoroutinefunction(func))
         if asyncio.iscoroutinefunction(func):
 
             @functools.wraps(func)

{paid_python-1.0.0a4 → paid_python-1.0.2}/src/paid/tracing/tracing.py

@@ -6,21 +6,20 @@ import signal
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable, Dict, Optional, Tuple, TypeVar, Union
 
-import dotenv
 from . import distributed_tracing
 from .context_data import ContextData
 from opentelemetry import trace
 from opentelemetry.context import Context
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanLimits, SpanProcessor, TracerProvider
 from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
 from opentelemetry.trace import NonRecordingSpan, NoOpTracerProvider, SpanContext, Status, StatusCode, TraceFlags
 from opentelemetry.util.types import Attributes
 
 from paid.logger import logger
 
-_ = dotenv.load_dotenv()
 DEFAULT_COLLECTOR_ENDPOINT = (
     os.environ.get("PAID_OTEL_COLLECTOR_ENDPOINT") or "https://collector.agentpaid.io:4318/v1/traces"
 )
@@ -208,7 +207,7 @@ class PaidSpanProcessor(SpanProcessor):
             # Langchain instrumentation creates spans, that are created by other instrumentations (ex. OpenAI, Anthropic).
             # Not all spans need filtering (ex. ChatGoogleGenerativeAI), so first test actual telemetry before adding filters.
             # TODO: maybe consider a dropping sampler for such spans instead of raising an exception?
-            logger.debug(f"Dropping Langchain span: {span.name}")
+            logger.debug("[paid:span] Dropping duplicate LangChain span: %s", span.name)
             raise Exception(f"Dropping Langchain span: {span.name}")
 
         # Prefix the span name
@@ -224,10 +223,29 @@ class PaidSpanProcessor(SpanProcessor):
         if agent_id:
             span.set_attribute("external_agent_id", agent_id)
 
+        logger.debug(
+            "[paid:span] on_start: name=%s, customer_id=%s, agent_id=%s",
+            span.name, customer_id, agent_id,
+        )
+
         metadata = ContextData.get_context_key("user_metadata")
         if metadata:
             metadata_attributes: dict[str, Any] = {}
 
+            # OTEL attributes only accept: bool, str, bytes, int, float
+            _OTEL_SAFE_TYPES = (bool, str, bytes, int, float)
+
+            def _sanitize_value(v: Any) -> Any:
+                """Convert non-OTEL-safe values to str."""
+                if isinstance(v, _OTEL_SAFE_TYPES):
+                    return v
+                if isinstance(v, (list, tuple)):
+                    return [
+                        el if isinstance(el, _OTEL_SAFE_TYPES) else str(el)
+                        for el in v
+                    ]
+                return str(v)
+
             def flatten_dict(d: dict[str, Any], parent_key: str = "") -> None:
                 """Recursively flatten nested dictionaries into dot-notation keys."""
                 for k, v in d.items():
@@ -235,13 +253,14 @@ class PaidSpanProcessor(SpanProcessor):
                     if isinstance(v, dict):
                         flatten_dict(v, new_key)
                     else:
-                        metadata_attributes[new_key] = v
+                        metadata_attributes[new_key] = _sanitize_value(v)
 
             flatten_dict(metadata)
 
             # Add all flattened metadata attributes to the span
             for key, value in metadata_attributes.items():
                 span.set_attribute(f"metadata.{key}", value)
+            logger.debug("[paid:span] on_start: attached metadata keys=%s", list(metadata_attributes.keys()))
 
     def on_end(self, span: ReadableSpan) -> None:
         if span.name and not span.name.startswith(self.SPAN_NAME_PREFIX):
@@ -251,6 +270,7 @@ class PaidSpanProcessor(SpanProcessor):
         """Filter out prompt and response contents unless explicitly asked to store"""
         store_prompt = ContextData.get_context_key("store_prompt")
         if store_prompt:
+            logger.debug("[paid:span] on_end: name=%s, store_prompt=True, keeping all attributes", span.name)
             return
 
         original_attributes = span.attributes
@@ -262,6 +282,12 @@ class PaidSpanProcessor(SpanProcessor):
                 for k, v in original_attributes.items()
                 if not any(substr in k for substr in self.PROMPT_ATTRIBUTES_SUBSTRINGS)
             }
+            filtered_count = len(original_attributes) - len(filtered_attrs)
+            if filtered_count > 0:
+                logger.debug(
+                    "[paid:span] on_end: name=%s, filtered %d prompt attribute(s)",
+                    span.name, filtered_count,
+                )
             # This works because the exporter reads attributes during serialization
             object.__setattr__(span, "_attributes", filtered_attrs)
 
@@ -303,6 +329,7 @@ class PydanticSpanProcessor(SpanProcessor):
         settings = _PydanticSettingsRegistry.get(scope_name)
         if settings is None or settings.track_usage:
             # No filtering needed - keep usage/cost data
+            logger.debug("[paid:span] PydanticSpanProcessor on_end: scope=%s, track_usage=True, keeping usage data", scope_name)
             return
 
         original_attributes = span.attributes
@@ -314,6 +341,11 @@ class PydanticSpanProcessor(SpanProcessor):
             for k, v in original_attributes.items()
             if not any(substr in k for substr in self.USAGE_ATTRIBUTES_SUBSTRINGS)
         }
+        filtered_count = len(original_attributes) - len(filtered_attrs)
+        logger.debug(
+            "[paid:span] PydanticSpanProcessor on_end: scope=%s, filtered %d usage/cost attribute(s)",
+            scope_name, filtered_count,
+        )
         # This works because the exporter reads attributes during serialization
         object.__setattr__(span, "_attributes", filtered_attrs)
 
@@ -355,6 +387,7 @@ def setup_graceful_termination(paid_tracer_provider: TracerProvider):
         # signal handlers
         for sig in (signal.SIGINT, signal.SIGTERM):
             signal.signal(sig, create_chained_signal_handler(sig))
+        logger.debug("[paid:init] Registered atexit and signal handlers (SIGINT, SIGTERM)")
     except Exception as e:
         logger.warning(
             f"Could not set up termination handlers: {e}"
@@ -385,6 +418,9 @@ def initialize_tracing(
     if not collector_endpoint:
         collector_endpoint = DEFAULT_COLLECTOR_ENDPOINT
 
+    logger.debug("[paid:init] initialize_tracing called, endpoint=%s, api_key=%s",
+                 collector_endpoint, "provided" if api_key else "not provided (will check env)")
+
     try:
         # Check if tracing is disabled via environment variable
         paid_enabled = os.environ.get("PAID_ENABLED", "true").lower()
@@ -403,27 +439,51 @@ def initialize_tracing(
                 logger.error("API key must be provided via PAID_API_KEY environment variable")
                 # don't throw - tracing should not break the app
                 return
+            logger.debug("[paid:init] API key resolved from PAID_API_KEY environment variable")
+        else:
+            logger.debug("[paid:init] API key provided via parameter")
 
         set_token(api_key)
 
         resource = Resource(attributes={"api.key": api_key})
         # Create isolated tracer provider for Paid - don't use or modify global provider
-        paid_tracer_provider = TracerProvider(resource=resource)
+        # Pass explicit sampler and span_limits to avoid inheriting from OTEL env vars
+        # (OTEL_TRACES_SAMPLER=always_off or OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=1
+        #  set by the client app would silently break this)
+        paid_tracer_provider = TracerProvider(
+            resource=resource,
+            sampler=ALWAYS_ON,
+            span_limits=SpanLimits(
+                max_span_attributes=128,
+                max_event_attributes=128,
+                max_link_attributes=128,
+                max_events=128,
+                max_links=128,
+            ),
+        )
+        # Override OTEL_SDK_DISABLED - the client may set it to disable their own OTEL
+        paid_tracer_provider._disabled = False
+        logger.debug("[paid:init] TracerProvider created (sampler=ALWAYS_ON, OTEL_SDK_DISABLED overridden)")
 
         # Add span processor to prefix span names and add customer/agent ID attributes
         paid_tracer_provider.add_span_processor(PaidSpanProcessor())
+        logger.debug("[paid:init] Added PaidSpanProcessor")
 
         # Add Pydantic span processor - it self-filters by scope using the settings registry
         paid_tracer_provider.add_span_processor(PydanticSpanProcessor())
+        logger.debug("[paid:init] Added PydanticSpanProcessor")
 
         # Legacy support: if processor_settings.pydantic is provided, register it for the default scope
         if processor_settings and processor_settings.pydantic:
             _PydanticSettingsRegistry.register(PYDANTIC_SCOPE_NAME, processor_settings.pydantic)
+            logger.debug("[paid:init] Registered legacy PydanticProcessorSettings for scope=%s", PYDANTIC_SCOPE_NAME)
 
-        # Set up OTLP exporter
+        # Set up OTLP exporter with explicit settings to avoid inheriting from
+        # client OTEL env vars (e.g. OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TIMEOUT)
         otlp_exporter = OTLPSpanExporter(
             endpoint=collector_endpoint,
-            headers={},  # No additional headers needed for OTLP
+            headers={"_paid": "1"},  # Non-empty to prevent env var OTEL_EXPORTER_OTLP_HEADERS leak (empty dict is falsy)
+            timeout=10,  # Explicit timeout to prevent env var OTEL_EXPORTER_OTLP_TIMEOUT override
         )
 
         # Use SimpleSpanProcessor for immediate span export.
@@ -431,6 +491,7 @@ def initialize_tracing(
         # Airflow terminates processes before the batch is sent, losing traces.
         span_processor = SimpleSpanProcessor(otlp_exporter)
         paid_tracer_provider.add_span_processor(span_processor)
+        logger.debug("[paid:init] Added SimpleSpanProcessor with OTLPSpanExporter -> %s", collector_endpoint)
 
         setup_graceful_termination(paid_tracer_provider)  # doesn't throw
 
@@ -454,6 +515,7 @@ def get_paid_tracer() -> trace.Tracer:
         Tracing is automatically initialized when using @paid_tracing decorator or context manager.
     """
     global paid_tracer_provider
+    logger.debug("[paid:init] get_paid_tracer: provider_type=%s", type(paid_tracer_provider).__name__)
     return paid_tracer_provider.get_tracer("paid.python")
 
 
@@ -553,15 +615,22 @@ def trace_sync_(
             trace_flags=TraceFlags(TraceFlags.SAMPLED),
         )
         ctx = trace.set_span_in_context(NonRecordingSpan(span_context))
+        logger.debug("[paid:distributed] trace_sync_ using override trace_id=%s",
+                     format(override_trace_id, '032x') if isinstance(override_trace_id, int) else str(override_trace_id))
+    else:
+        logger.debug("[paid:distributed] trace_sync_ no override trace_id, using auto-generated")
 
     try:
         tracer = get_paid_tracer()
-        logger.info(f"Creating span for external_customer_id: {external_customer_id}")
+        logger.debug("[paid:span] trace_sync_ creating parent_span for customer_id=%s, agent_id=%s, fn=%s",
+                      external_customer_id, external_agent_id, getattr(fn, '__name__', repr(fn)))
         with tracer.start_as_current_span("parent_span", context=ctx) as span:
+            logger.debug("[paid:span] trace_sync_ span created, trace_id=%s",
+                         format(span.get_span_context().trace_id, '032x') if isinstance(span.get_span_context().trace_id, int) else str(span.get_span_context().trace_id))
             try:
                 result = fn(*args, **kwargs)
                 span.set_status(Status(StatusCode.OK))
-                logger.info(f"Function {fn.__name__} executed successfully")
+                logger.debug("[paid:span] trace_sync_ fn=%s completed successfully", getattr(fn, '__name__', repr(fn)))
                 return result
             except Exception as error:
                 span.set_status(Status(StatusCode.ERROR, str(error)))
@@ -624,18 +693,25 @@ async def trace_async_(
             trace_flags=TraceFlags(TraceFlags.SAMPLED),
         )
         ctx = trace.set_span_in_context(NonRecordingSpan(span_context))
+        logger.debug("[paid:distributed] trace_async_ using override trace_id=%s",
+                     format(override_trace_id, '032x') if isinstance(override_trace_id, int) else str(override_trace_id))
+    else:
+        logger.debug("[paid:distributed] trace_async_ no override trace_id, using auto-generated")
 
     try:
         tracer = get_paid_tracer()
-        logger.info(f"Creating span for external_customer_id: {external_customer_id}")
+        logger.debug("[paid:span] trace_async_ creating parent_span for customer_id=%s, agent_id=%s, fn=%s",
+                      external_customer_id, external_agent_id, getattr(fn, '__name__', repr(fn)))
         with tracer.start_as_current_span("parent_span", context=ctx) as span:
+            logger.debug("[paid:span] trace_async_ span created, trace_id=%s",
+                         format(span.get_span_context().trace_id, '032x') if isinstance(span.get_span_context().trace_id, int) else str(span.get_span_context().trace_id))
             try:
                 if asyncio.iscoroutinefunction(fn):
                     result = await fn(*args, **kwargs)
                 else:
                     result = fn(*args, **kwargs)
                 span.set_status(Status(StatusCode.OK))
-                logger.info(f"Async function {fn.__name__} executed successfully")
+                logger.debug("[paid:span] trace_async_ fn=%s completed successfully", getattr(fn, '__name__', repr(fn)))
                 return result
             except Exception as error:
                 span.set_status(Status(StatusCode.ERROR, str(error)))