ioa-observe-sdk 1.0.24__tar.gz → 1.0.26__tar.gz

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ioa-observe-sdk
-Version: 1.0.24
+Version: 1.0.26
 Summary: IOA Observability SDK
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -76,6 +76,37 @@ Alternatively, to download the SDK from git, you could also use the following co
 uv add "git+https://github.com/agntcy/observe"
 ```
 
+### Quick Start
+
+After installation, import and initialize the SDK:
+
+```python
+import os
+from ioa_observe.sdk import Observe
+from ioa_observe.sdk.decorators import agent
+from ioa_observe.sdk.tracing import session_start
+
+# Initialize Observe
+Observe.init(
+    app_name="your_app_name",
+    api_endpoint=os.getenv("OTLP_HTTP_ENDPOINT", "http://localhost:4318")
+)
+
+# Use decorators to instrument your agents
+@agent(name="my_agent", description="Example agent")
+def my_agent_function(state):
+    # Your agent logic here
+    return {"result": "success"}
+
+# Start a session for tracking
+with session_start() as session_id:
+    result = my_agent_function({"input": "data"})
+```
+
+**Note:** The package name for installation is `ioa_observe_sdk`, but imports use `ioa_observe` (underscore, not hyphen).
+
+For comprehensive integration examples with LangGraph, LlamaIndex, and other frameworks, see the [Getting Started Guide](GETTING-STARTED.md).
+
 ## Schema
 
 The AGNTCY observability schema is an extension of the OTel LLM Semantic Conventions for Generative AI systems.

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/README.md

@@ -27,6 +27,37 @@ Alternatively, to download the SDK from git, you could also use the following co
 uv add "git+https://github.com/agntcy/observe"
 ```
 
+### Quick Start
+
+After installation, import and initialize the SDK:
+
+```python
+import os
+from ioa_observe.sdk import Observe
+from ioa_observe.sdk.decorators import agent
+from ioa_observe.sdk.tracing import session_start
+
+# Initialize Observe
+Observe.init(
+    app_name="your_app_name",
+    api_endpoint=os.getenv("OTLP_HTTP_ENDPOINT", "http://localhost:4318")
+)
+
+# Use decorators to instrument your agents
+@agent(name="my_agent", description="Example agent")
+def my_agent_function(state):
+    # Your agent logic here
+    return {"result": "success"}
+
+# Start a session for tracking
+with session_start() as session_id:
+    result = my_agent_function({"input": "data"})
+```
+
+**Note:** The package name for installation is `ioa_observe_sdk`, but imports use `ioa_observe` (underscore, not hyphen).
+
+For comprehensive integration examples with LangGraph, LlamaIndex, and other frameworks, see the [Getting Started Guide](GETTING-STARTED.md).
+
 ## Schema
 
 The AGNTCY observability schema is an extension of the OTel LLM Semantic Conventions for Generative AI systems.

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/connectors/slim.py

@@ -3,7 +3,6 @@
 
 import inspect
 import string
-import time
 from functools import wraps
 from json import JSONEncoder
 from typing import Optional
@@ -82,23 +81,23 @@ def process_slim_msg(name: Optional[str] = None):
                     span, ctx, ctx_token = _setup_span(entity_name)
                     _handle_span_input(span, args, kwargs, cls=JSONEncoder)
 
-                    start_time = time.time()
+                    # start_time = time.time()
 
                     try:
                         async for item in _ahandle_generator(
                             span, ctx_token, fn(*args, **kwargs)
                         ):
                             # Measure throughput and processing time per item
-                            item_process_time = time.time() - start_time
-                            TracerWrapper().processing_time.record(
-                                item_process_time, {"agent": entity_name}
-                            )
+                            # item_process_time = time.time() - start_time
+                            # TracerWrapper().processing_time.record(
+                            #     item_process_time, {"agent": entity_name}
+                            # )
                             TracerWrapper().throughput_counter.add(
                                 1, {"agent": entity_name}
                             )
 
                             # Reset timer for next item
-                            start_time = time.time()
+                            # start_time = time.time()
                             # Count each yielded item as a published message
                             TracerWrapper().messages_received_counter.add(
                                 1, {"agent": entity_name}
@@ -122,16 +121,16 @@ def process_slim_msg(name: Optional[str] = None):
 
                     # span, ctx, ctx_token = _setup_span(entity_name)
                     # _handle_span_input(span, args, kwargs, cls=JSONEncoder)
-                    start_time = time.time()
+                    # start_time = time.time()
 
                     try:
                         res = await fn(*args, **kwargs)
 
                         # Measure processing time
-                        process_time = time.time() - start_time
-                        TracerWrapper().processing_time.record(
-                            process_time, {"agent": entity_name}
-                        )
+                        # process_time = time.time() - start_time
+                        # TracerWrapper().processing_time.record(
+                        #     process_time, {"agent": entity_name}
+                        # )
                         TracerWrapper().throughput_counter.add(
                             1, {"agent": entity_name}
                         )
@@ -172,16 +171,16 @@ def process_slim_msg(name: Optional[str] = None):
                 # span, ctx, ctx_token = _setup_span(entity_name)
                 # _handle_span_input(span, args, kwargs, cls=JSONEncoder)
 
-                start_time = time.time()
+                # start_time = time.time()
 
                 try:
                     res = fn(*args, **kwargs)
 
                     # Measure processing time
-                    process_time = time.time() - start_time
-                    TracerWrapper().processing_time.record(
-                        process_time, {"agent": entity_name}
-                    )
+                    # process_time = time.time() - start_time
+                    # TracerWrapper().processing_time.record(
+                    #     process_time, {"agent": entity_name}
+                    # )
                     TracerWrapper().throughput_counter.add(1, {"agent": entity_name})
                     # span will be ended in the generator
                     # if isinstance(res, types.GeneratorType):

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/decorators/base.py

@@ -312,18 +312,18 @@ def _cleanup_span(span, ctx_token):
     """End the span process and detach the context token"""
 
     # Calculate agent chain completion time before ending span
-    span_kind = span.attributes.get(OBSERVE_SPAN_KIND)
-    if span_kind == ObserveSpanKindValues.AGENT.value:
-        start_time = span.attributes.get("agent_chain_start_time")
-        if start_time is not None:
-            import time
-
-            completion_time = time.time() - start_time
-
-            # Emit the metric
-            TracerWrapper().agent_chain_completion_time_histogram.record(
-                completion_time, attributes=span.attributes
-            )
+    # span_kind = span.attributes.get(OBSERVE_SPAN_KIND)
+    # if span_kind == ObserveSpanKindValues.AGENT.value:
+    #     start_time = span.attributes.get("agent_chain_start_time")
+    #     if start_time is not None:
+    #         import time
+    #
+    #         # completion_time = time.time() - start_time
+    #
+    #         # Emit the metric
+    #         # TracerWrapper().agent_chain_completion_time_histogram.record(
+    #         #     completion_time, attributes=span.attributes
+    #         # )
     span.end()
     context_api.detach(ctx_token)
 

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/instrumentations/a2a.py

@@ -5,6 +5,7 @@ from typing import Collection
 import functools
 import threading
 
+from opentelemetry.context import get_value
 from opentelemetry import baggage
 from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
@@ -47,8 +48,10 @@ class A2AInstrumentor(BaseInstrumentor):
                 session_id = None
                 if traceparent:
                     session_id = kv_store.get(f"execution.{traceparent}")
-                    if session_id:
-                        kv_store.set(f"execution.{traceparent}", session_id)
+                    if not session_id:
+                        session_id = get_value("session.id")
+                        if session_id:
+                            kv_store.set(f"execution.{traceparent}", session_id)
 
                 # Ensure metadata dict exists
                 try:
@@ -101,8 +104,10 @@ class A2AInstrumentor(BaseInstrumentor):
                     session_id = None
                     if traceparent:
                         session_id = kv_store.get(f"execution.{traceparent}")
-                        if session_id:
-                            kv_store.set(f"execution.{traceparent}", session_id)
+                        if not session_id:
+                            session_id = get_value("session.id")
+                            if session_id:
+                                kv_store.set(f"execution.{traceparent}", session_id)
 
                     # Ensure metadata dict exists
                     try:

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/instrumentations/mcp.py

@@ -10,6 +10,7 @@ import traceback
 import re
 from http import HTTPStatus
 
+from opentelemetry.context import get_value
 from opentelemetry import context, propagate
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.instrumentation.utils import unwrap
@@ -212,8 +213,10 @@ class McpInstrumentor(BaseInstrumentor):
                 session_id = None
                 if traceparent:
                     session_id = kv_store.get(f"execution.{traceparent}")
-                    if session_id:
-                        kv_store.set(f"execution.{traceparent}", session_id)
+                    if not session_id:
+                        session_id = get_value("session.id")
+                        if session_id:
+                            kv_store.set(f"execution.{traceparent}", session_id)
 
                         meta = meta or {}
                         if isinstance(meta, dict):

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/instrumentations/nats.py

@@ -7,6 +7,7 @@ import json
 import base64
 import threading
 
+from opentelemetry.context import get_value
 from opentelemetry import baggage, context
 from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
@@ -53,8 +54,10 @@ class NATSInstrumentor(BaseInstrumentor):
             if traceparent:
                 with _kv_lock:
                     session_id = kv_store.get(f"execution.{traceparent}")
-                    if session_id:
-                        kv_store.set(f"execution.{traceparent}", session_id)
+                    if not session_id:
+                        session_id = get_value("session.id")
+                        if session_id:
+                            kv_store.set(f"execution.{traceparent}", session_id)
 
             headers = {
                 "session_id": session_id if session_id else None,
@@ -104,8 +107,10 @@ class NATSInstrumentor(BaseInstrumentor):
             if traceparent:
                 with _kv_lock:
                     session_id = kv_store.get(f"execution.{traceparent}")
-                    if session_id:
-                        kv_store.set(f"execution.{traceparent}", session_id)
+                    if not session_id:
+                        session_id = get_value("session.id")
+                        if session_id:
+                            kv_store.set(f"execution.{traceparent}", session_id)
 
             headers = {
                 "session_id": session_id if session_id else None,

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/instrumentations/slim.py

@@ -7,6 +7,7 @@ import json
 import base64
 import threading
 
+from opentelemetry.context import get_value
 from opentelemetry import baggage, context
 from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
@@ -15,6 +16,7 @@ from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapProp
 from ioa_observe.sdk import TracerWrapper
 from ioa_observe.sdk.client import kv_store
 from ioa_observe.sdk.tracing import set_session_id, get_current_traceparent
+from ioa_observe.sdk.tracing.context_manager import get_tracer
 
 _instruments = ("slim-bindings >= 0.4.0",)
 _global_tracer = None
@@ -79,8 +81,10 @@ class SLIMInstrumentor(BaseInstrumentor):
                 if traceparent:
                     with _kv_lock:
                         session_id = kv_store.get(f"execution.{traceparent}")
-                        if session_id:
-                            kv_store.set(f"execution.{traceparent}", session_id)
+                        if not session_id:
+                            session_id = get_value("session.id")
+                            if session_id:
+                                kv_store.set(f"execution.{traceparent}", session_id)
 
                 headers = {
                     "session_id": session_id if session_id else None,
@@ -138,8 +142,10 @@ class SLIMInstrumentor(BaseInstrumentor):
                 if traceparent:
                     with _kv_lock:
                         session_id = kv_store.get(f"execution.{traceparent}")
-                        if session_id:
-                            kv_store.set(f"execution.{traceparent}", session_id)
+                        if not session_id:
+                            session_id = get_value("session.id")
+                            if session_id:
+                                kv_store.set(f"execution.{traceparent}", session_id)
 
                 headers = {
                     "session_id": session_id if session_id else None,
@@ -201,8 +207,10 @@ class SLIMInstrumentor(BaseInstrumentor):
                 if traceparent:
                     with _kv_lock:
                         session_id = kv_store.get(f"execution.{traceparent}")
-                        if session_id:
-                            kv_store.set(f"execution.{traceparent}", session_id)
+                        if not session_id:
+                            session_id = get_value("session.id")
+                            if session_id:
+                                kv_store.set(f"execution.{traceparent}", session_id)
 
                 headers = {
                     "session_id": session_id if session_id else None,
@@ -670,6 +678,8 @@ class SLIMInstrumentor(BaseInstrumentor):
                         if traceparent:
                             with _kv_lock:
                                 session_id = kv_store.get(f"execution.{traceparent}")
+                                if not session_id:
+                                    session_id = get_value("session.id")
                                 if session_id:
                                     kv_store.set(f"execution.{traceparent}", session_id)
 
@@ -686,7 +696,13 @@ class SLIMInstrumentor(BaseInstrumentor):
                             baggage.set_baggage(f"execution.{traceparent}", session_id)
 
                         # Wrap the message (first argument for publish, second for publish_to)
-                        message_idx = 1 if method_name == "publish_to" else 0
+                        # If the session_class is SessionContext, the message is always in second position
+                        message_idx = (
+                            1
+                            if method_name == "publish_to"
+                            or session_class.__name__ == "SessionContext"
+                            else 0
+                        )
                         if len(args) > message_idx:
                             args_list = list(args)
                             message = args_list[message_idx]
@@ -716,6 +732,10 @@ class SLIMInstrumentor(BaseInstrumentor):
                     if traceparent:
                         with _kv_lock:
                             session_id = kv_store.get(f"execution.{traceparent}")
+                            if not session_id:
+                                session_id = get_value("session.id")
+                                if session_id:
+                                    kv_store.set(f"execution.{traceparent}", session_id)
 
                     if traceparent or session_id:
                         headers = {
@@ -772,7 +792,8 @@ class SLIMInstrumentor(BaseInstrumentor):
         @functools.wraps(original_method)
         async def instrumented_session_method(self, *args, **kwargs):
             if _global_tracer:
-                with _global_tracer.start_as_current_span(f"session.{method_name}"):
+                tracer = get_tracer()
+                with tracer.start_as_current_span(f"session.{method_name}"):
                     traceparent = get_current_traceparent()
 
                     # Handle message wrapping for publish methods
@@ -828,6 +849,10 @@ class SLIMInstrumentor(BaseInstrumentor):
                     if traceparent:
                         with _kv_lock:
                             session_id = kv_store.get(f"execution.{traceparent}")
+                            if not session_id:
+                                session_id = get_value("session.id")
+                                if session_id:
+                                    kv_store.set(f"execution.{traceparent}", session_id)
 
                     if traceparent or session_id:
                         headers = {

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/metrics/metrics.py

@@ -194,26 +194,4 @@ def metric_views() -> Sequence[View]:
                 ]
             ),
         ),
-        # response latency in ms
-        View(
-            instrument_name="gen_ai.ioa.llm.response_latency",
-            aggregation=ExplicitBucketHistogramAggregation(
-                [
-                    0.01,
-                    0.02,
-                    0.04,
-                    0.08,
-                    0.16,
-                    0.32,
-                    0.64,
-                    1.28,
-                    2.56,
-                    5.12,
-                    10.24,
-                    20.48,
-                    40.96,
-                    81.92,
-                ]
-            ),
-        ),
     ]

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe/sdk/tracing/tracing.py

@@ -205,11 +205,11 @@ class TracerWrapper(object):
                 description="Counts agent failures by agent and reason",
                 unit="1",
             )
-            obj.response_latency_histogram = meter.create_histogram(
-                name="response_latency",
-                description="Records the latency of responses",
-                unit="ms",
-            )
+            # obj.response_latency_histogram = meter.create_histogram(
+            #     name="response_latency",
+            #     description="Records the latency of responses",
+            #     unit="ms",
+            # )
             obj.messages_received_counter = meter.create_counter(
                 "slim.messages.received",
                 description="Number of SLIM messages received per agent",
@@ -226,10 +226,10 @@ class TracerWrapper(object):
                 "slim.messages.processed",
                 description="Number of SLIM messages processed",
             )
-            obj.processing_time = meter.create_histogram(
-                "slim.message.processing_time",
-                description="Time taken to process SLIM messages",
-            )
+            # obj.processing_time = meter.create_histogram(
+            #     "slim.message.processing_time",
+            #     description="Time taken to process SLIM messages",
+            # )
             obj.throughput_counter = meter.create_counter(
                 "slim.message.throughput",
                 description="Message throughput for SLIM operations",
@@ -237,11 +237,11 @@ class TracerWrapper(object):
             obj.error_counter = meter.create_counter(
                 "slim.errors", description="Number of SLIM message errors or drops"
             )
-            obj.agent_chain_completion_time_histogram = meter.create_histogram(
-                name="gen_ai.client.ioa.agent.end_to_end_chain_completion_time",
-                description="Records the end-to-end chain completion time for a single agent",
-                unit="s",
-            )
+            # obj.agent_chain_completion_time_histogram = meter.create_histogram(
+            #     name="gen_ai.client.ioa.agent.end_to_end_chain_completion_time",
+            #     description="Records the end-to-end chain completion time for a single agent",
+            #     unit="s",
+            # )
             obj.agent_execution_success_rate = meter.create_observable_gauge(
                 name="gen_ai.client.ioa.agent.execution_success_rate",
                 description="Success rate of agent executions",
@@ -363,7 +363,7 @@ class TracerWrapper(object):
         self._processed_spans.add(span_id)
 
         determine_reliability_score(span)
-        start_time = span.attributes.get("ioa_start_time")
+        # start_time = span.attributes.get("ioa_start_time")
 
         # Apply transformations if enabled
         apply_transform = get_value("apply_transform")
@@ -382,9 +382,9 @@ class TracerWrapper(object):
                 except Exception as e:
                     logging.error(f"Error applying span transformation: {e}")
 
-        if start_time is not None:
-            latency = (time.time() - start_time) * 1000
-            self.response_latency_histogram.record(latency, attributes=span.attributes)
+        # if start_time is not None:
+        #     latency = (time.time() - start_time) * 1000
+        #     self.response_latency_histogram.record(latency, attributes=span.attributes)
 
         # Call original on_end method if it exists
         if (
@@ -684,28 +684,24 @@ def set_session_id(session_id: str, traceparent: str = None) -> None:
 
     # Check if we have an active span first
     current_span = trace.get_current_span()
+    extracted_traceparent = None
 
     if current_span.is_recording():
         # We have an active span, use its context
         carrier = {}
         TraceContextTextMapPropagator().inject(carrier)
         extracted_traceparent = carrier.get("traceparent")
-    else:
-        # Only create new span if absolutely necessary (no existing context)
-        tracer = trace.get_tracer(__name__)
-        with tracer.start_as_current_span("set_session_id"):
-            carrier = {}
-            TraceContextTextMapPropagator().inject(carrier)
-            extracted_traceparent = carrier.get("traceparent")
-
-    # Store execution ID with traceparent as key
+        # Store execution ID with traceparent as key
+        if extracted_traceparent:
+            kv_key = f"execution.{extracted_traceparent}"
+            if kv_store.get(kv_key) is None:
+                kv_store.set(kv_key, session_id)
+    # If there is no active span, we do nothing now and when we need the traceparent
+    # e.g. when propagating context, we update the kv_store with the session_id then
+
+    # Finally, attach to context session.id and current_traceparent if present
+    attach(set_value("session.id", session_id))
     if extracted_traceparent:
-        kv_key = f"execution.{extracted_traceparent}"
-        if kv_store.get(kv_key) is None:
-            kv_store.set(kv_key, session_id)
-
-        # Also store in OpenTelemetry context
-        attach(set_value("session.id", session_id))
         attach(set_value("current_traceparent", extracted_traceparent))
 
 

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/ioa_observe_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ioa-observe-sdk
-Version: 1.0.24
+Version: 1.0.26
 Summary: IOA Observability SDK
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -76,6 +76,37 @@ Alternatively, to download the SDK from git, you could also use the following co
 uv add "git+https://github.com/agntcy/observe"
 ```
 
+### Quick Start
+
+After installation, import and initialize the SDK:
+
+```python
+import os
+from ioa_observe.sdk import Observe
+from ioa_observe.sdk.decorators import agent
+from ioa_observe.sdk.tracing import session_start
+
+# Initialize Observe
+Observe.init(
+    app_name="your_app_name",
+    api_endpoint=os.getenv("OTLP_HTTP_ENDPOINT", "http://localhost:4318")
+)
+
+# Use decorators to instrument your agents
+@agent(name="my_agent", description="Example agent")
+def my_agent_function(state):
+    # Your agent logic here
+    return {"result": "success"}
+
+# Start a session for tracking
+with session_start() as session_id:
+    result = my_agent_function({"input": "data"})
+```
+
+**Note:** The package name for installation is `ioa_observe_sdk`, but imports use `ioa_observe` (underscore, not hyphen).
+
+For comprehensive integration examples with LangGraph, LlamaIndex, and other frameworks, see the [Getting Started Guide](GETTING-STARTED.md).
+
 ## Schema
 
 The AGNTCY observability schema is an extension of the OTel LLM Semantic Conventions for Generative AI systems.

{ioa_observe_sdk-1.0.24 → ioa_observe_sdk-1.0.26}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ioa-observe-sdk"
-version = "1.0.24"
+version = "1.0.26"
 license = "Apache-2.0"
 description = "IOA Observability SDK"
 readme = "README.md"