ioa-observe-sdk 1.0.5__py3-none-any.whl → 1.0.7__py3-none-any.whl

ioa_observe/sdk/decorators/base.py

@@ -100,8 +100,8 @@ def _setup_span(
     ]:
         set_workflow_name(entity_name)
         # if tlp_span_kind == "graph":
-        #     execution_id = entity_name + "_" + str(uuid.uuid4())
-        #     set_execution_id(execution_id)
+        #     session_id = entity_name + "_" + str(uuid.uuid4())
+        #     set_session_id(session_id)
     if tlp_span_kind == "graph":
         span_name = f"{entity_name}.{tlp_span_kind}"
     else:
@@ -126,9 +126,9 @@ def _setup_span(
                     },
                 )
             # start_span.end()  # end the span immediately
-        # execution_id = get_value("execution.id")
-        # if execution_id is not None:
-        #     span.set_attribute("execution.id", execution_id)
+        # session_id = get_value("session.id")
+        # if session_id is not None:
+        #     span.set_attribute("session.id", session_id)
         if tlp_span_kind in [
             ObserveSpanKindValues.TASK,
             ObserveSpanKindValues.TOOL,
@@ -145,9 +145,9 @@ def _setup_span(
         if version:
             span.set_attribute(OBSERVE_ENTITY_VERSION, version)
 
-        # if execution_id:
-        #     print(f"Execution ID: {execution_id}")
-        #     span.set_attribute("execution.id", execution_id)
+        # if session_id:
+        #     print(f"Execution ID: {session_id}")
+        #     span.set_attribute("session.id", session_id)
 
     return span, ctx, ctx_token
 

ioa_observe/sdk/decorators/util.py

@@ -21,6 +21,12 @@ def determine_workflow_type(workflow_obj: Any) -> Union[None, dict]:
         for key, value in workflow_obj.items()
     ):
         return build_agent_dict_topology(workflow_obj)
+
+    # Check if it's a list of agent names
+    elif isinstance(workflow_obj, list) and all(
+        isinstance(item, str) for item in workflow_obj
+    ):
+        return build_agent_dict_topology(workflow_obj)
     # Try LlamaIndex built-in workflow types first
     result = determine_llama_index_workflow_type(workflow_obj)
     if result:

ioa_observe/sdk/instrumentations/a2a.py

@@ -0,0 +1,111 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Collection
+import functools
+import threading
+
+from opentelemetry import baggage
+from opentelemetry.baggage.propagation import W3CBaggagePropagator
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+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
+
+_instruments = ("a2a-sdk >= 0.2.5",)
+_global_tracer = None
+_kv_lock = threading.RLock()  # Add thread-safety for kv_store operations
+
+
+class A2AInstrumentor(BaseInstrumentor):
+    def __init__(self):
+        super().__init__()
+        global _global_tracer
+        _global_tracer = TracerWrapper().get_tracer()
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        import importlib
+
+        if importlib.util.find_spec("a2a") is None:
+            raise ImportError("No module named 'a2a-sdk'. Please install it first.")
+
+        # Instrument `publish`
+        from a2a.client import A2AClient
+
+        original_send_message = A2AClient.send_message
+
+        @functools.wraps(original_send_message)
+        async def instrumented_send_message(
+            self, request, *, http_kwargs=None, context=None
+        ):
+            with _global_tracer.start_as_current_span("a2a.send_message"):
+                traceparent = get_current_traceparent()
+                session_id = None
+                if traceparent:
+                    session_id = kv_store.get(f"execution.{traceparent}")
+                    if session_id:
+                        kv_store.set(f"execution.{traceparent}", session_id)
+                # Inject headers into http_kwargs
+                if http_kwargs is None:
+                    http_kwargs = {}
+                headers = http_kwargs.get("headers", {})
+                headers["traceparent"] = traceparent
+                if session_id:
+                    headers["session_id"] = session_id
+                    baggage.set_baggage(f"execution.{traceparent}", session_id)
+                http_kwargs["headers"] = headers
+            return await original_send_message(self, request, http_kwargs=http_kwargs)
+
+        from a2a.client import A2AClient
+
+        A2AClient.send_message = instrumented_send_message
+
+        from a2a.server.request_handlers import DefaultRequestHandler
+
+        original_server_on_message_send = DefaultRequestHandler.on_message_send
+
+        @functools.wraps(original_server_on_message_send)
+        async def instrumented_execute(self, params, context):
+            # Extract headers from context (assume context.request.headers)
+
+            traceparent = context.state.get("headers", {}).get("traceparent")
+            session_id = context.state.get("headers", {}).get("session_id")
+            carrier = {
+                k.lower(): v
+                for k, v in context.state.get("headers", {}).items()
+                if k.lower() in ["traceparent", "baggage"]
+            }
+            if carrier and traceparent:
+                ctx = TraceContextTextMapPropagator().extract(carrier=carrier)
+                ctx = W3CBaggagePropagator().extract(carrier=carrier, context=ctx)
+                if session_id and session_id != "None":
+                    set_session_id(session_id, traceparent=traceparent)
+                    kv_store.set(f"execution.{traceparent}", session_id)
+            return await original_server_on_message_send(self, params, context)
+
+        from a2a.server.request_handlers import DefaultRequestHandler
+
+        DefaultRequestHandler.on_message_send = instrumented_execute
+
+    def _uninstrument(self, **kwargs):
+        import importlib
+
+        if importlib.util.find_spec("a2a") is None:
+            raise ImportError("No module named 'a2a-sdk'. Please install it first.")
+
+        # Uninstrument `send_message`
+        from a2a.client import A2AClient
+
+        A2AClient.send_message = A2AClient.send_message.__wrapped__
+
+        # Uninstrument `execute`
+        from a2a.server.request_handlers import DefaultRequestHandler
+
+        DefaultRequestHandler.on_message_send = (
+            DefaultRequestHandler.on_message_send.__wrapped__
+        )

ioa_observe/sdk/instrumentations/slim.py

@@ -14,7 +14,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_execution_id, get_current_traceparent
+from ioa_observe.sdk.tracing import set_session_id, get_current_traceparent
 
 _instruments = ("slim-bindings >= 0.2",)
 _global_tracer = None
@@ -50,21 +50,21 @@ class SLIMInstrumentor(BaseInstrumentor):
                 traceparent = get_current_traceparent()
 
             # Thread-safe access to kv_store
-            execution_id = None
+            session_id = None
             if traceparent:
                 with _kv_lock:
-                    execution_id = kv_store.get(f"execution.{traceparent}")
-                    if execution_id:
-                        kv_store.set(f"execution.{traceparent}", execution_id)
+                    session_id = kv_store.get(f"execution.{traceparent}")
+                    if session_id:
+                        kv_store.set(f"execution.{traceparent}", session_id)
             # Add tracing context to the message headers
             headers = {
-                "execution_id": execution_id if execution_id else None,
+                "session_id": session_id if session_id else None,
                 "traceparent": traceparent,
             }
 
             # Set baggage context
-            if traceparent and execution_id:
-                baggage.set_baggage(f"execution.{traceparent}", execution_id)
+            if traceparent and session_id:
+                baggage.set_baggage(f"execution.{traceparent}", session_id)
 
             # Process message payload
             if isinstance(message, bytes):
@@ -120,7 +120,7 @@ class SLIMInstrumentor(BaseInstrumentor):
 
                 # Extract traceparent from headers
                 traceparent = headers.get("traceparent")
-                execution_id = headers.get("execution_id")
+                session_id = headers.get("session_id")
 
                 # First, extract and restore the trace context from headers
                 carrier = {}
@@ -130,27 +130,27 @@ class SLIMInstrumentor(BaseInstrumentor):
                             if k.lower() == key.lower():
                                 carrier[key.lower()] = headers[k]
 
-                # Restore the trace context BEFORE calling set_execution_id
+                # Restore the trace context BEFORE calling set_session_id
                 if carrier and traceparent:
                     ctx = TraceContextTextMapPropagator().extract(carrier=carrier)
                     ctx = W3CBaggagePropagator().extract(carrier=carrier, context=ctx)
 
                     # Now set execution ID with the restored context
-                    if execution_id and execution_id != "None":
+                    if session_id and session_id != "None":
                         # Pass the traceparent explicitly to prevent new context creation
-                        set_execution_id(execution_id, traceparent=traceparent)
+                        set_session_id(session_id, traceparent=traceparent)
 
                         # Store in kv_store with thread safety
                         with _kv_lock:
-                            kv_store.set(f"execution.{traceparent}", execution_id)
+                            kv_store.set(f"execution.{traceparent}", session_id)
 
                 # Fallback: check stored execution ID if not found in headers
-                if traceparent and (not execution_id or execution_id == "None"):
+                if traceparent and (not session_id or session_id == "None"):
                     with _kv_lock:
-                        stored_execution_id = kv_store.get(f"execution.{traceparent}")
-                        if stored_execution_id:
-                            execution_id = stored_execution_id
-                            set_execution_id(execution_id, traceparent=traceparent)
+                        stored_session_id = kv_store.get(f"execution.{traceparent}")
+                        if stored_session_id:
+                            session_id = stored_session_id
+                            set_session_id(session_id, traceparent=traceparent)
 
                 # Process payload
                 payload = message_dict.get("payload", raw_message)

ioa_observe/sdk/tracing/__init__.py

@@ -4,7 +4,7 @@
 from ioa_observe.sdk.tracing.context_manager import get_tracer
 from ioa_observe.sdk.tracing.tracing import (
     set_workflow_name,
-    set_execution_id,
+    set_session_id,
     get_current_traceparent,
     session_start,
 )
@@ -12,7 +12,7 @@ from ioa_observe.sdk.tracing.tracing import (
 __all__ = [
     "get_tracer",
     "set_workflow_name",
-    "set_execution_id",
+    "set_session_id",
     "get_current_traceparent",
     "session_start",
 ]

ioa_observe/sdk/tracing/context_utils.py

@@ -4,8 +4,9 @@ from opentelemetry import baggage
 
 from ioa_observe.sdk import TracerWrapper
 from ioa_observe.sdk.client import kv_store
-from ioa_observe.sdk.tracing import set_execution_id, get_current_traceparent
+from ioa_observe.sdk.tracing import set_session_id, get_current_traceparent
 from opentelemetry import context as otel_context
+from opentelemetry.context import attach
 
 """
 Usage Example:
@@ -20,7 +21,7 @@ After receiving a message, extract headers and call set_context_from_headers(hea
 
 def get_current_context_headers():
     """
-    Extracts the current trace context, baggage, and execution_id into headers.
+    Extracts the current trace context, baggage, and session_id into headers.
     """
     _global_tracer = TracerWrapper().get_tracer()
     with _global_tracer.start_as_current_span("get_current_context_headers"):
@@ -30,33 +31,33 @@ def get_current_context_headers():
         TraceContextTextMapPropagator().inject(carrier, context=current_ctx)
         W3CBaggagePropagator().inject(carrier, context=current_ctx)
         traceparent = carrier.get("traceparent")
-        execution_id = None
+        session_id = None
         if traceparent:
-            execution_id = kv_store.get(f"execution.{traceparent}")
-            if execution_id:
-                carrier["execution_id"] = execution_id
+            session_id = kv_store.get(f"execution.{traceparent}")
+            if session_id:
+                carrier["session_id"] = session_id
         return carrier
 
 
 def set_context_from_headers(headers):
     """
-    Restores the trace context, baggage, and execution_id from headers.
+    Restores the trace context, baggage, and session_id from headers.
     """
-    # Extract trace context and baggage
-    _global_tracer = TracerWrapper().get_tracer()
-    with _global_tracer.start_as_current_span("set_context_from_headers"):
-        ctx = TraceContextTextMapPropagator().extract(carrier=headers)
-        ctx = W3CBaggagePropagator().extract(carrier=headers, context=ctx)
-        # Restore execution_id if present
-        if headers is not None:
-            if "traceparent" in headers:
-                traceparent = headers.get("traceparent")
-            if "executionID" in headers:
-                execution_id = headers.get("executionID")
-        if traceparent and execution_id and execution_id != "None":
-            set_execution_id(execution_id, traceparent=traceparent)
-            kv_store.set(f"execution.{traceparent}", execution_id)
-        return ctx
+    carrierHeaders = {}
+    if "traceparentID" in headers:
+        carrierHeaders["traceparent"] = headers["traceparentID"]
+    if "executionID" in headers:
+        carrierHeaders["session_id"] = headers["executionID"]
+    ctx = TraceContextTextMapPropagator().extract(carrier=carrierHeaders)
+    ctx = W3CBaggagePropagator().extract(carrier=carrierHeaders, context=ctx)
+    attach(ctx)
+    # Restore session_id if present
+    traceparent = headers.get("traceparentID")
+    session_id = headers.get("executionID")
+    if traceparent and session_id and session_id != "None":
+        set_session_id(session_id, traceparent=traceparent)
+        kv_store.set(f"execution.{traceparent}", session_id)
+    return ctx
 
 
 def set_baggage_item(key, value):
@@ -67,16 +68,16 @@ def get_baggage_item(key):
     return baggage.get_baggage(key)
 
 
-def get_current_execution_id():
+def get_current_session_id():
     traceparent = get_current_traceparent()
     if traceparent:
         return kv_store.get(f"execution.{traceparent}")
     return None
 
 
-def set_execution_id_from_headers(headers):
+def set_session_id_from_headers(headers):
     traceparent = headers.get("traceparent")
-    execution_id = headers.get("execution_id")
-    if traceparent and execution_id:
-        set_execution_id(execution_id, traceparent=traceparent)
-        kv_store.set(f"execution.{traceparent}", execution_id)
+    session_id = headers.get("session_id")
+    if traceparent and session_id:
+        set_session_id(session_id, traceparent=traceparent)
+        kv_store.set(f"execution.{traceparent}", session_id)

ioa_observe/sdk/tracing/tracing.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import atexit
+import contextlib
 import json
 import logging
 import os
@@ -261,9 +262,9 @@ class TracerWrapper(object):
         if workflow_name is not None:
             span.set_attribute(OBSERVE_WORKFLOW_NAME, workflow_name)
 
-        execution_id = get_value("execution.id")
-        if execution_id is not None:
-            span.set_attribute("execution.id", execution_id)
+        session_id = get_value("session.id")
+        if session_id is not None:
+            span.set_attribute("session.id", session_id)
 
         entity_path = get_value("entity_path")
         if entity_path is not None:
@@ -408,11 +409,11 @@ def session_start():
     As a context manager, yields session metadata.
     As a normal function, just sets up the session.
     """
-    execution_id = TracerWrapper.app_name + "_" + str(uuid.uuid4())
-    set_execution_id(execution_id)
+    session_id = TracerWrapper.app_name + "_" + str(uuid.uuid4())
+    set_session_id(session_id)
     metadata = {
-        "executionID": get_value("execution.id") or execution_id,
-        "traceparent": get_current_traceparent(),
+        "executionID": get_value("session.id") or session_id,
+        "traceparentID": get_current_traceparent(),
     }
     import inspect
 
@@ -427,10 +428,10 @@ def session_start():
 
         return _cm()
     # Used as a normal function
-    return None
+    return contextlib.nullcontext(metadata)
 
 
-def set_execution_id(execution_id: str, traceparent: str = None) -> None:
+def set_session_id(session_id: str, traceparent: str = None) -> None:
     """
     Sets the execution ID in both the key-value store and OpenTelemetry context.
 
@@ -438,10 +439,10 @@ def set_execution_id(execution_id: str, traceparent: str = None) -> None:
     proper trace correlation across distributed systems.
 
     Args:
-        execution_id: The execution ID to set
+        session_id: The execution ID to set
         traceparent: Optional traceparent to use (if None, will extract from context)
     """
-    if not execution_id:
+    if not session_id:
         return
 
     from opentelemetry import trace
@@ -454,10 +455,10 @@ def set_execution_id(execution_id: str, traceparent: str = None) -> None:
         # Store execution ID with provided traceparent
         kv_key = f"execution.{traceparent}"
         if kv_store.get(kv_key) is None:
-            kv_store.set(kv_key, execution_id)
+            kv_store.set(kv_key, session_id)
 
         # Store in OpenTelemetry context
-        attach(set_value("execution.id", execution_id))
+        attach(set_value("session.id", session_id))
         attach(set_value("current_traceparent", traceparent))
         return
 
@@ -472,7 +473,7 @@ def set_execution_id(execution_id: str, traceparent: str = None) -> None:
     else:
         # Only create new span if absolutely necessary (no existing context)
         tracer = trace.get_tracer(__name__)
-        with tracer.start_as_current_span("set_execution_id"):
+        with tracer.start_as_current_span("set_session_id"):
             carrier = {}
             TraceContextTextMapPropagator().inject(carrier)
             extracted_traceparent = carrier.get("traceparent")
@@ -481,10 +482,10 @@ def set_execution_id(execution_id: str, traceparent: str = None) -> None:
     if extracted_traceparent:
         kv_key = f"execution.{extracted_traceparent}"
         if kv_store.get(kv_key) is None:
-            kv_store.set(kv_key, execution_id)
+            kv_store.set(kv_key, session_id)
 
         # Also store in OpenTelemetry context
-        attach(set_value("execution.id", execution_id))
+        attach(set_value("session.id", session_id))
         attach(set_value("current_traceparent", extracted_traceparent))
 
 

{ioa_observe_sdk-1.0.5.dist-info → ioa_observe_sdk-1.0.7.dist-info}/METADATA

@@ -1,38 +1,38 @@
 Metadata-Version: 2.4
 Name: ioa-observe-sdk
-Version: 1.0.5
+Version: 1.0.7
 Summary: IOA Observability SDK
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: aiohappyeyeballs==2.4.8
-Requires-Dist: aiohttp==3.11.18
-Requires-Dist: aiosignal==1.3.2
-Requires-Dist: annotated-types==0.7.0
-Requires-Dist: anyio==4.8.0
-Requires-Dist: async-timeout==4.0.3
-Requires-Dist: attrs==25.1.0
-Requires-Dist: backoff==2.2.1
-Requires-Dist: certifi==2025.1.31
-Requires-Dist: charset-normalizer==3.4.1
+Requires-Dist: aiohappyeyeballs>=2.4.8
+Requires-Dist: aiohttp>=3.11.18
+Requires-Dist: aiosignal>=1.3.2
+Requires-Dist: annotated-types>=0.7.0
+Requires-Dist: anyio>=4.8.0
+Requires-Dist: async-timeout>=4.0.3
+Requires-Dist: attrs>=25.1.0
+Requires-Dist: backoff>=2.2.1
+Requires-Dist: certifi>=2025.1.31
+Requires-Dist: charset-normalizer>=3.4.1
 Requires-Dist: colorama==0.4.6
-Requires-Dist: Deprecated==1.2.18
-Requires-Dist: distro==1.9.0
-Requires-Dist: exceptiongroup==1.2.2
-Requires-Dist: frozenlist==1.5.0
-Requires-Dist: googleapis-common-protos==1.69.0
-Requires-Dist: grpcio==1.70.0
-Requires-Dist: h11==0.16.0
-Requires-Dist: httpcore==1.0.9
-Requires-Dist: httpx==0.28.1
-Requires-Dist: idna==3.10
-Requires-Dist: importlib_metadata==8.5.0
-Requires-Dist: Jinja2==3.1.6
-Requires-Dist: jiter==0.8.2
-Requires-Dist: MarkupSafe==3.0.2
-Requires-Dist: monotonic==1.6
-Requires-Dist: multidict==6.1.0
-Requires-Dist: openai==1.75.0
+Requires-Dist: Deprecated>=1.2.18
+Requires-Dist: distro>=1.9.0
+Requires-Dist: exceptiongroup>=1.2.2
+Requires-Dist: frozenlist>=1.5.0
+Requires-Dist: googleapis-common-protos>=1.69.0
+Requires-Dist: grpcio>=1.70.0
+Requires-Dist: h11>=0.16.0
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: idna>=3.10
+Requires-Dist: importlib_metadata>=8.5.0
+Requires-Dist: Jinja2>=3.1.6
+Requires-Dist: jiter>=0.8.2
+Requires-Dist: MarkupSafe>=3.0.2
+Requires-Dist: monotonic>=1.6
+Requires-Dist: multidict>=6.1.0
+Requires-Dist: openai>=1.75.0
 Requires-Dist: opentelemetry-api==1.33.1
 Requires-Dist: opentelemetry-distro
 Requires-Dist: opentelemetry-exporter-otlp==1.33.1
@@ -52,32 +52,32 @@ Requires-Dist: opentelemetry-sdk==1.33.1
 Requires-Dist: opentelemetry-semantic-conventions==0.54b1
 Requires-Dist: opentelemetry-semantic-conventions-ai==0.4.9
 Requires-Dist: opentelemetry-util-http==0.54b1
-Requires-Dist: packaging==24.2
-Requires-Dist: propcache==0.3.0
-Requires-Dist: protobuf==5.29.3
-Requires-Dist: pydantic==2.10.6
-Requires-Dist: pydantic_core==2.27.2
-Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: packaging>=24.2
+Requires-Dist: propcache>=0.3.0
+Requires-Dist: protobuf>=5.29.3
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pydantic_core>=2.27.2
+Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: regex==2024.11.6
-Requires-Dist: requests==2.32.3
-Requires-Dist: six==1.17.0
-Requires-Dist: sniffio==1.3.1
-Requires-Dist: tenacity==9.0.0
-Requires-Dist: tiktoken==0.9.0
-Requires-Dist: tqdm==4.67.1
-Requires-Dist: typing_extensions==4.12.2
-Requires-Dist: urllib3==2.3.0
-Requires-Dist: wrapt==1.17.2
-Requires-Dist: yarl==1.18.3
-Requires-Dist: zipp==3.21.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: six>=1.17.0
+Requires-Dist: sniffio>=1.3.1
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typing_extensions>=4.12.2
+Requires-Dist: urllib3>=2.3.0
+Requires-Dist: wrapt>=1.17.2
+Requires-Dist: yarl>=1.18.3
+Requires-Dist: zipp>=3.21.0
 Requires-Dist: langgraph>=0.3.2
 Requires-Dist: langchain>=0.3.19
 Requires-Dist: langchain-openai>=0.3.8
 Requires-Dist: langchain-community>=0.3.25
 Requires-Dist: llama-index>=0.12.34
 Requires-Dist: opentelemetry-instrumentation-requests
-Requires-Dist: opentelemetry-instrumentation-transformers>=0.40.2
-Requires-Dist: opentelemetry-instrumentation-crewai>=0.40.2
+Requires-Dist: opentelemetry-instrumentation-transformers>=0.40.8
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.40.8
 Requires-Dist: llama-index-utils-workflow>=0.3.1
 Requires-Dist: pytest
 Requires-Dist: pytest-vcr
@@ -85,6 +85,8 @@ Dynamic: license-file
 
 # Observe-SDK
 
+[![PyPI version](https://img.shields.io/pypi/v/ioa-observe-sdk.svg)](https://pypi.org/project/ioa-observe-sdk/)
+
 IOA observability SDK for your multi-agentic application.
 
 ## Table of Contents
@@ -119,6 +121,20 @@ Link: [AGNTCY Observability Schema](https://github.com/agntcy/observe/blob/main/
 
 ## Dev
 
+Any Opentelemetry compatible backend can be used, but for this guide, we will use ClickhouseDB as the backend database.
+
+### Opentelemetry collector
+
+The OpenTelemetry Collector offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors.
+
+### Clickhouse DB
+
+ClickhouseDB is used as a backend database to store and query the collected telemetry data efficiently, enabling you to analyze and visualize observability information for your multi-agentic applications.
+
+### Grafana (optional)
+
+Grafana can be used to visualize the telemetry data collected by the OpenTelemetry Collector and stored in ClickhouseDB.
+
 To get started with development, start a Clickhouse DB and an OTel collector container locally using docker-compose like so:
 
 ```
@@ -126,6 +142,8 @@ cd deploy/
 docker compose up -d
 ```
 
+Running both locally allows you to test, monitor, and debug your observability setup in a development environment before deploying to production.
+
 Ensure the contents of `otel-collector.yaml` is correct.
 
 Check the logs of the collector to ensure it is running correctly:
@@ -134,6 +152,18 @@ Check the logs of the collector to ensure it is running correctly:
 docker logs -f otel-collector
 ```
 
+Viewing data in Clickhouse DB can be done using the Clickhouse client. The collector is configured to export telemetry data to Clickhouse.
+
+The clickhouse exporter creates various tables in the Clickhouse DB, including `otel_traces`, which is used to store trace data.
+
+For more info, refer to the [OpenTelemetry Clickhouse Exporter documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/clickhouseexporter/README.md)
+
+```bash
+docker exec -it clickhouse-server clickhouse-client
+
+select * from otel_traces LIMIT 10;
+```
+
 Create a `.env` file with the following content:
 
 ```bash
@@ -165,6 +195,28 @@ OPENAI_API_KEY=<KEY> make test
 For getting started with the SDK, please refer to the [Getting Started](https://github.com/agntcy/observe/blob/main/GETTING-STARTED.md)
  file. It contains detailed instructions on how to set up and use the SDK effectively.
 
+### Grafana
+
+To configure Grafana to visualize the telemetry data, follow these steps:
+
+1. Spin up Grafana locally using Docker:
+
+```bash
+docker run -d -p 3000:3000 --name=grafana grafana/grafana
+```
+2. Access Grafana by navigating to `http://localhost:3000` in your web browser.
+   - Default username: `admin`
+   - Default password: `admin`
+
+3. Add a new data source:
+   - Choose "ClickHouse" as the data source type.
+   - Set the URL to `http://0.0.0.0:8123`.
+   - Configure the authentication settings if necessary.
+   - Save and test the connection to ensure it works correctly.
+
+Refer to the [Grafana ClickHouse plugin documentation](https://grafana.com/grafana/plugins/grafana-clickhouse-datasource/) for more details on configuring ClickHouse as a data source.
+
+
 ## Contributing
 
 Contributions are welcome! Please follow these steps to contribute:

{ioa_observe_sdk-1.0.5.dist-info → ioa_observe_sdk-1.0.7.dist-info}/RECORD

@@ -10,10 +10,11 @@ ioa_observe/sdk/config/__init__.py,sha256=8aVNaw0yRNLFPxlf97iOZLlJVcV81ivSDnudH2
 ioa_observe/sdk/connectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ioa_observe/sdk/connectors/slim.py,sha256=NwbKEV7d5NIOqmG8zKqtgGigSJl7kf3QJ65z2gxpsY8,8498
 ioa_observe/sdk/decorators/__init__.py,sha256=4Jf207nnJR1B371aAqYh17JWp2lsbG1IdX4-w1JlVwo,2380
-ioa_observe/sdk/decorators/base.py,sha256=5NAfap6adbemrSAPCSo-rOWsBoh0-T4xY0eiA4OcOzg,24261
-ioa_observe/sdk/decorators/util.py,sha256=QZH5k2vIvf7UVjV5Exw3I4S5NrlWVQdkOyd4bpAsjCw,25097
+ioa_observe/sdk/decorators/base.py,sha256=a6EGP3Xz5t958aqmnSh9qIb8C0S6b3-uqrTwF5ZGF4w,24237
+ioa_observe/sdk/decorators/util.py,sha256=1apEuwDF0GKTcBVuO3p0R7BmUeUDFjwBaWA4o0SYuCQ,25306
 ioa_observe/sdk/instrumentations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ioa_observe/sdk/instrumentations/slim.py,sha256=odOnULHV5WqlyiMQ1W8RmoyWJ1jeU66opiuvl6r2U4s,7708
+ioa_observe/sdk/instrumentations/a2a.py,sha256=ov_9ckkymf_qFXG0iXVWfxlW-3kFcP-knrM_t-Cf72w,4414
+ioa_observe/sdk/instrumentations/slim.py,sha256=w2-1JRB-I05bqH_Y4-98XMOh0x7xgAJWUYUBpe2alXQ,7656
 ioa_observe/sdk/logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ioa_observe/sdk/logging/logging.py,sha256=HZxW9s8Due7jgiNkdI38cIjv5rC9D-Flta3RQMOnpow,2891
 ioa_observe/sdk/metrics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -26,19 +27,19 @@ ioa_observe/sdk/metrics/agents/heuristics.py,sha256=lcos_mzxXrTMpNWShW9Biy9pXoh8
 ioa_observe/sdk/metrics/agents/recovery_tracker.py,sha256=I3bWmA11Ue2Cfxnn7C9r2zvh7Hqa8z6EV8wqQhDLALI,4811
 ioa_observe/sdk/metrics/agents/tool_call_tracker.py,sha256=qmjaaR7rIaQsqCLlDaiYGUeEO3QijhMwyrcpNjvItzI,3169
 ioa_observe/sdk/metrics/agents/tracker.py,sha256=KN3VFPXrgB1f5VF87ppqS4zG2vxn-9oFCG5K1W2IscE,1361
-ioa_observe/sdk/tracing/__init__.py,sha256=RBc_lmUEdCDy1ICW6TtRor_0Tew1SyzYFjT4Sn1pkdo,437
+ioa_observe/sdk/tracing/__init__.py,sha256=jb3_vIAfrChfeaTNnpUKojnn8uUk_ukdFZ1lLru0kRM,433
 ioa_observe/sdk/tracing/content_allow_list.py,sha256=1fAkpIwUQ7vDwCTkIVrqeltWQtrIbYvj8gz6_7P6NrE,945
 ioa_observe/sdk/tracing/context_manager.py,sha256=O0JEXYa9h8anhW78R8KKBuqS0j4by1E1KXxNIMPnLr8,400
-ioa_observe/sdk/tracing/context_utils.py,sha256=CzIXY402ner15E64Dssd1YMJYI3rsYXqFV47gY2O7Lg,3018
+ioa_observe/sdk/tracing/context_utils.py,sha256=-sYS9vPLI87davV9ubneq5xqbV583CC_c0SmOQS1TAs,2933
 ioa_observe/sdk/tracing/manual.py,sha256=KS6WN-zw9vAACzXYmnMoJm9d1fenYMfvzeK1GrGDPDE,1937
-ioa_observe/sdk/tracing/tracing.py,sha256=DuEd_VYdDkA7ZNtASDuDhO_O-LnQET8UwCgdqclGmcw,37879
+ioa_observe/sdk/tracing/tracing.py,sha256=Qsi7GYk1LytnzLhEXg7r_yfQhfQcBm2Y9s3VBrV2Eec,37885
 ioa_observe/sdk/utils/__init__.py,sha256=UPn182U-UblF_XwXaFpx8F-TmQTbm1LYf9y89uSp5Hw,704
 ioa_observe/sdk/utils/const.py,sha256=GwbHakKPjBL4wLqAVkDrSoKB-8p18EUrbaqPuRuV_xg,1099
 ioa_observe/sdk/utils/in_memory_span_exporter.py,sha256=H_4TRaThMO1H6vUQ0OpQvzJk_fZH0OOsRAM1iZQXsR8,2112
 ioa_observe/sdk/utils/json_encoder.py,sha256=g4NQ0tTqgWssY6I1D7r4zo0G6PiUo61jhofTAw5-jno,639
 ioa_observe/sdk/utils/package_check.py,sha256=1d1MjxhwoEZIx9dumirT2pRsEWgn-m-SI4npDeEalew,576
-ioa_observe_sdk-1.0.5.dist-info/licenses/LICENSE.md,sha256=55VjUfgjWOS4vv3Cf55gfq-RxjPgRIO2vlgYPUuC5lA,11362
-ioa_observe_sdk-1.0.5.dist-info/METADATA,sha256=kcLchJ5m1Hsvvj_LAsmOuYIjl394oWKTvQWZEE_Y8cQ,5428
-ioa_observe_sdk-1.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ioa_observe_sdk-1.0.5.dist-info/top_level.txt,sha256=Yt-6Y1olZEDqCs2REeqI30WjYx0pLGQSVqzYmDd67N8,12
-ioa_observe_sdk-1.0.5.dist-info/RECORD,,
+ioa_observe_sdk-1.0.7.dist-info/licenses/LICENSE.md,sha256=55VjUfgjWOS4vv3Cf55gfq-RxjPgRIO2vlgYPUuC5lA,11362
+ioa_observe_sdk-1.0.7.dist-info/METADATA,sha256=AJMuGPihvSbdLiCZh8AA_W_zGHGXTSPgzttA8I8KP0c,7746
+ioa_observe_sdk-1.0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ioa_observe_sdk-1.0.7.dist-info/top_level.txt,sha256=Yt-6Y1olZEDqCs2REeqI30WjYx0pLGQSVqzYmDd67N8,12
+ioa_observe_sdk-1.0.7.dist-info/RECORD,,