Skip to content

A programming framework for agentic AI

Add messaging attributes to telemetry spans (#490)

Aamire25bd2c074e3
diff --git a/python/packages/autogen-core/src/autogen_core/application/_single_threaded_agent_runtime.py b/python/packages/autogen-core/src/autogen_core/application/_single_threaded_agent_runtime.py
index 8a0fb63aa..1f98c65f9 100644
--- a/python/packages/autogen-core/src/autogen_core/application/_single_threaded_agent_runtime.py
+++ b/python/packages/autogen-core/src/autogen_core/application/_single_threaded_agent_runtime.py
@@ -11,7 +11,7 @@ from dataclasses import dataclass
from enum import Enum
from typing import Any, Awaitable, Callable, Dict, List, Mapping, ParamSpec, Set, Type, TypeVar, cast
-from opentelemetry.trace import NoOpTracerProvider, TracerProvider
+from opentelemetry.trace import TracerProvider
from ..base import (
Agent,
@@ -30,7 +30,7 @@ from ..base import (
from ..base.exceptions import MessageDroppedException
from ..base.intervention import DropMessage, InterventionHandler
from ._helpers import SubscriptionManager, get_impl
-from .telemetry import EnvelopeMetadata, get_telemetry_envelope_metadata, trace_block
+from .telemetry import EnvelopeMetadata, MessageRuntimeTracingConfig, TraceHelper, get_telemetry_envelope_metadata
logger = logging.getLogger("autogen_core")
event_logger = logging.getLogger("autogen_core.events")
@@ -151,7 +151,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):
intervention_handlers: List[InterventionHandler] | None = None,
tracer_provider: TracerProvider | None = None,
) -> None:
- self._tracer = (tracer_provider if tracer_provider else NoOpTracerProvider()).get_tracer(__name__)
+ self._tracer_helper = TraceHelper(tracer_provider, MessageRuntimeTracingConfig("SingleThreadedAgentRuntime"))
self._message_queue: List[PublishMessageEnvelope | SendMessageEnvelope | ResponseMessageEnvelope] = []
# (namespace, type) -> List[AgentId]
self._agent_factories: Dict[
@@ -200,7 +200,12 @@ class SingleThreadedAgentRuntime(AgentRuntime):
# )
# )
- with trace_block(self._tracer, "create", recipient, parent=None):
+ with self._tracer_helper.trace_block(
+ "create",
+ recipient,
+ parent=None,
+ extraAttributes={"message_type": type(message).__name__},
+ ):
future = asyncio.get_event_loop().create_future()
if recipient.type not in self._known_agent_names:
future.set_exception(Exception("Recipient not found"))
@@ -231,7 +236,12 @@ class SingleThreadedAgentRuntime(AgentRuntime):
sender: AgentId | None = None,
cancellation_token: CancellationToken | None = None,
) -> None:
- with trace_block(self._tracer, "create", topic_id, parent=None):
+ with self._tracer_helper.trace_block(
+ "create",
+ topic_id,
+ parent=None,
+ extraAttributes={"message_type": type(message).__name__},
+ ):
if cancellation_token is None:
cancellation_token = CancellationToken()
content = message.__dict__ if hasattr(message, "__dict__") else message
@@ -270,7 +280,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):
(await self._get_agent(agent_id)).load_state(state[str(agent_id)])
async def _process_send(self, message_envelope: SendMessageEnvelope) -> None:
- with trace_block(self._tracer, "send", message_envelope.recipient, parent=message_envelope.metadata):
+ with self._tracer_helper.trace_block("send", message_envelope.recipient, parent=message_envelope.metadata):
recipient = message_envelope.recipient
# todo: check if recipient is in the known namespaces
# assert recipient in self._agents
@@ -319,7 +329,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):
self._outstanding_tasks.decrement()
async def _process_publish(self, message_envelope: PublishMessageEnvelope) -> None:
- with trace_block(self._tracer, "publish", message_envelope.topic_id, parent=message_envelope.metadata):
+ with self._tracer_helper.trace_block("publish", message_envelope.topic_id, parent=message_envelope.metadata):
responses: List[Awaitable[Any]] = []
recipients = await self._subscription_manager.get_subscribed_recipients(message_envelope.topic_id)
for agent_id in recipients:
@@ -352,7 +362,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):
agent = await self._get_agent(agent_id)
async def _on_message(agent: Agent, message_context: MessageContext) -> Any:
- with trace_block(self._tracer, "process", agent.id, parent=None):
+ with self._tracer_helper.trace_block("process", agent.id, parent=None):
return await agent.on_message(
message_envelope.message,
ctx=message_context,
@@ -375,7 +385,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):
# TODO if responses are given for a publish
async def _process_response(self, message_envelope: ResponseMessageEnvelope) -> None:
- with trace_block(self._tracer, "ack", message_envelope.recipient, parent=message_envelope.metadata):
+ with self._tracer_helper.trace_block("ack", message_envelope.recipient, parent=message_envelope.metadata):
content = (
message_envelope.message.__dict__
if hasattr(message_envelope.message, "__dict__")
@@ -409,8 +419,8 @@ class SingleThreadedAgentRuntime(AgentRuntime):
case SendMessageEnvelope(message=message, sender=sender, recipient=recipient, future=future):
if self._intervention_handlers is not None:
for handler in self._intervention_handlers:
- with trace_block(
- self._tracer, "intercept", handler.__class__.__name__, parent=message_envelope.metadata
+ with self._tracer_helper.trace_block(
+ "intercept", handler.__class__.__name__, parent=message_envelope.metadata
):
try:
temp_message = await handler.on_send(message, sender=sender, recipient=recipient)
@@ -432,8 +442,8 @@ class SingleThreadedAgentRuntime(AgentRuntime):
):
if self._intervention_handlers is not None:
for handler in self._intervention_handlers:
- with trace_block(
- self._tracer, "intercept", handler.__class__.__name__, parent=message_envelope.metadata
+ with self._tracer_helper.trace_block(
+ "intercept", handler.__class__.__name__, parent=message_envelope.metadata
):
try:
temp_message = await handler.on_publish(message, sender=sender)
diff --git a/python/packages/autogen-core/src/autogen_core/application/_worker_runtime.py b/python/packages/autogen-core/src/autogen_core/application/_worker_runtime.py
index 74efecfc8..7297d125a 100644
--- a/python/packages/autogen-core/src/autogen_core/application/_worker_runtime.py
+++ b/python/packages/autogen-core/src/autogen_core/application/_worker_runtime.py
@@ -50,7 +50,7 @@ from ..base import (
from ..components import TypeSubscription
from ._helpers import SubscriptionManager, get_impl
from .protos import agent_worker_pb2, agent_worker_pb2_grpc
-from .telemetry import get_telemetry_grpc_metadata, trace_block
+from .telemetry import MessageRuntimeTracingConfig, TraceHelper, get_telemetry_grpc_metadata
if TYPE_CHECKING:
from .protos.agent_worker_pb2_grpc import AgentRpcAsyncStub
@@ -157,7 +157,7 @@ class HostConnection:
class WorkerAgentRuntime(AgentRuntime):
def __init__(self, tracer_provider: TracerProvider | None = None) -> None:
- self._tracer = (tracer_provider if tracer_provider else NoOpTracerProvider()).get_tracer(__name__)
+ self._trace_helper = TraceHelper(tracer_provider, MessageRuntimeTracingConfig("Worker Runtime"))
self._per_type_subscribers: DefaultDict[tuple[str, str], Set[AgentId]] = defaultdict(set)
self._agent_factories: Dict[
str, Callable[[], Agent | Awaitable[Agent]] | Callable[[AgentRuntime, AgentId], Agent | Awaitable[Agent]]
@@ -241,7 +241,7 @@ class WorkerAgentRuntime(AgentRuntime):
) -> None:
if self._host_connection is None:
raise RuntimeError("Host connection is not set.")
- with trace_block(self._tracer, send_type, recipient, parent=telemetry_metadata):
+ with self._trace_helper.trace_block(send_type, recipient, parent=telemetry_metadata):
await self._host_connection.send(runtime_message)
async def send_message(
@@ -257,7 +257,9 @@ class WorkerAgentRuntime(AgentRuntime):
if self._host_connection is None:
raise RuntimeError("Host connection is not set.")
data_type = MESSAGE_TYPE_REGISTRY.type_name(message)
- with trace_block(self._tracer, "create", recipient, parent=None, attributes={"message_type": data_type}):
+ with self._trace_helper.trace_block(
+ "create", recipient, parent=None, extraAttributes={"message_type": data_type, "message_size": len(message)}
+ ):
# create a new future for the result
future = asyncio.get_event_loop().create_future()
async with self._pending_requests_lock:
@@ -304,7 +306,9 @@ class WorkerAgentRuntime(AgentRuntime):
if self._host_connection is None:
raise RuntimeError("Host connection is not set.")
message_type = MESSAGE_TYPE_REGISTRY.type_name(message)
- with trace_block(self._tracer, "create", topic_id, parent=None, attributes={"message_type": message_type}):
+ with self._trace_helper.trace_block(
+ "create", topic_id, parent=None, extraAttributes={"message_type": message_type}
+ ):
serialized_message = MESSAGE_TYPE_REGISTRY.serialize(
message, type_name=message_type, data_content_type=JSON_DATA_CONTENT_TYPE
)
@@ -368,12 +372,12 @@ class WorkerAgentRuntime(AgentRuntime):
# Call the target agent.
try:
with MessageHandlerContext.populate_context(target_agent.id):
- with trace_block(
- self._tracer,
+ with self._trace_helper.trace_block(
"process",
target_agent.id,
parent=request.metadata,
attributes={"request_id": request.request_id},
+ extraAttributes={"message_type": request.payload.data_type},
):
result = await target_agent.on_message(message, ctx=message_context)
except BaseException as e:
@@ -411,8 +415,12 @@ class WorkerAgentRuntime(AgentRuntime):
await self._host_connection.send(response_message)
async def _process_response(self, response: agent_worker_pb2.RpcResponse) -> None:
- with trace_block(
- self._tracer, "ack", None, parent=response.metadata, attributes={"request_id": response.request_id}
+ with self._trace_helper.trace_block(
+ "ack",
+ None,
+ parent=response.metadata,
+ attributes={"request_id": response.request_id},
+ extraAttributes={"message_type": response.payload.data_type},
):
# Deserialize the result.
result = MESSAGE_TYPE_REGISTRY.deserialize(
@@ -448,7 +456,12 @@ class WorkerAgentRuntime(AgentRuntime):
with MessageHandlerContext.populate_context(agent.id):
async def send_message(agent: Agent, message_context: MessageContext) -> Any:
- with trace_block(self._tracer, "process", agent.id, parent=event.metadata):
+ with self._trace_helper.trace_block(
+ "process",
+ agent.id,
+ parent=event.metadata,
+ extraAttributes={"message_type": event.payload.data_type},
+ ):
await agent.on_message(message, ctx=message_context)
future = send_message(agent, message_context)
diff --git a/python/packages/autogen-core/src/autogen_core/application/telemetry/__init__.py b/python/packages/autogen-core/src/autogen_core/application/telemetry/__init__.py
index 7d01bc2e4..6432edf43 100644
--- a/python/packages/autogen-core/src/autogen_core/application/telemetry/__init__.py
+++ b/python/packages/autogen-core/src/autogen_core/application/telemetry/__init__.py
@@ -1,15 +1,17 @@
-from ._tracing import (
+from ._propagation import (
EnvelopeMetadata,
TelemetryMetadataContainer,
get_telemetry_envelope_metadata,
get_telemetry_grpc_metadata,
- trace_block,
)
+from ._tracing import TraceHelper
+from ._tracing_config import MessageRuntimeTracingConfig
__all__ = [
"EnvelopeMetadata",
"get_telemetry_envelope_metadata",
"get_telemetry_grpc_metadata",
"TelemetryMetadataContainer",
- "trace_block",
+ "TraceHelper",
+ "MessageRuntimeTracingConfig",
]
diff --git a/python/packages/autogen-core/src/autogen_core/application/telemetry/_constants.py b/python/packages/autogen-core/src/autogen_core/application/telemetry/_constants.py
new file mode 100644
index 000000000..e5bc8030e
--- /dev/null
+++ b/python/packages/autogen-core/src/autogen_core/application/telemetry/_constants.py
@@ -0,0 +1 @@
+NAMESPACE = "autogen"
diff --git a/python/packages/autogen-core/src/autogen_core/application/telemetry/_propagation.py b/python/packages/autogen-core/src/autogen_core/application/telemetry/_propagation.py
new file mode 100644
index 000000000..51941fe90
--- /dev/null
+++ b/python/packages/autogen-core/src/autogen_core/application/telemetry/_propagation.py
@@ -0,0 +1,97 @@
+from dataclasses import dataclass
+from typing import Dict, Mapping, Optional
+
+from opentelemetry.context import Context
+from opentelemetry.propagate import extract
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+
+@dataclass(kw_only=True)
+class EnvelopeMetadata:
+ """Metadata for an envelope."""
+
+ traceparent: Optional[str] = None
+ tracestate: Optional[str] = None
+
+
+def _get_carrier_for_envelope_metadata(envelope_metadata: EnvelopeMetadata) -> Dict[str, str]:
+ carrier: Dict[str, str] = {}
+ if envelope_metadata.traceparent is not None:
+ carrier["traceparent"] = envelope_metadata.traceparent
+ if envelope_metadata.tracestate is not None:
+ carrier["tracestate"] = envelope_metadata.tracestate
+ return carrier
+
+
+def get_telemetry_envelope_metadata() -> EnvelopeMetadata:
+ """
+ Retrieves the telemetry envelope metadata.
+
+ Returns:
+ EnvelopeMetadata: The envelope metadata containing the traceparent and tracestate.
+ """
+ carrier: Dict[str, str] = {}
+ TraceContextTextMapPropagator().inject(carrier)
+ return EnvelopeMetadata(
+ traceparent=carrier.get("traceparent"),
+ tracestate=carrier.get("tracestate"),
+ )
+
+
+def _get_carrier_for_remote_call_metadata(remote_call_metadata: Mapping[str, str]) -> Dict[str, str]:
+ carrier: Dict[str, str] = {}
+ traceparent = remote_call_metadata.get("traceparent")
+ tracestate = remote_call_metadata.get("tracestate")
+ if traceparent:
+ carrier["traceparent"] = traceparent
+ if tracestate:
+ carrier["tracestate"] = tracestate
+ return carrier
+
+
+def get_telemetry_grpc_metadata(existingMetadata: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+ """
+ Retrieves the telemetry gRPC metadata.
+
+ Args:
+ existingMetadata (Optional[Mapping[str, str]]): The existing metadata to include in the gRPC metadata.
+
+ Returns:
+ Mapping[str, str]: The gRPC metadata containing the traceparent and tracestate.
+ """
+ carrier: Dict[str, str] = {}
+ TraceContextTextMapPropagator().inject(carrier)
+ traceparent = carrier.get("traceparent")
+ tracestate = carrier.get("tracestate")
+ metadata: Dict[str, str] = {}
+ if existingMetadata is not None:
+ for key, value in existingMetadata.items():
+ metadata[key] = value
+ if traceparent is not None:
+ metadata["traceparent"] = traceparent
+ if tracestate is not None:
+ metadata["tracestate"] = tracestate
+ return metadata
+
+
+TelemetryMetadataContainer = Optional[EnvelopeMetadata] | Mapping[str, str]
+
+
+def get_telemetry_context(metadata: TelemetryMetadataContainer) -> Context:
+ """
+ Retrieves the telemetry context from the given metadata.
+
+ Args:
+ metadata (Optional[EnvelopeMetadata]): The metadata containing the telemetry context.
+
+ Returns:
+ Context: The telemetry context extracted from the metadata, or an empty context if the metadata is None.
+ """
+ if metadata is None:
+ return Context()
+ elif isinstance(metadata, EnvelopeMetadata):
+ return extract(_get_carrier_for_envelope_metadata(metadata))
+ elif hasattr(metadata, "__getitem__"):
+ return extract(_get_carrier_for_remote_call_metadata(metadata))
+ else:
+ raise ValueError(f"Unknown metadata type: {type(metadata)}")
diff --git a/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing.py b/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing.py
index 188344ca2..885c6f916 100644
--- a/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing.py
+++ b/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing.py
@@ -1,225 +1,90 @@
import contextlib
-import logging
-from dataclasses import dataclass
-from typing import Dict, Iterator, List, Literal, Mapping, Optional, Sequence, Union
+from typing import Dict, Generic, Iterator, Optional, Sequence
-from opentelemetry.context import Context
-from opentelemetry.propagate import extract
-from opentelemetry.trace import Link, Span, SpanKind, Tracer
-from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.trace import Link, NoOpTracerProvider, Span, SpanKind, TracerProvider
from opentelemetry.util import types
-from ...base import AgentId, TopicId
+from ._propagation import TelemetryMetadataContainer, get_telemetry_context
+from ._tracing_config import Destination, ExtraAttributes, Operation, TracingConfig
-NAMESPACE = "autogen"
-logger = logging.getLogger("autogen_core")
-event_logger = logging.getLogger("autogen_core.events")
-
-
-@dataclass(kw_only=True)
-class EnvelopeMetadata:
- """Metadata for an envelope."""
-
- traceparent: Optional[str] = None
- tracestate: Optional[str] = None
-
-
-def _get_carrier_for_envelope_metadata(envelope_metadata: EnvelopeMetadata) -> Dict[str, str]:
- carrier: Dict[str, str] = {}
- if envelope_metadata.traceparent is not None:
- carrier["traceparent"] = envelope_metadata.traceparent
- if envelope_metadata.tracestate is not None:
- carrier["tracestate"] = envelope_metadata.tracestate
- return carrier
-
-
-def get_telemetry_envelope_metadata() -> EnvelopeMetadata:
- """
- Retrieves the telemetry envelope metadata.
-
- Returns:
- EnvelopeMetadata: The envelope metadata containing the traceparent and tracestate.
- """
- carrier: Dict[str, str] = {}
- TraceContextTextMapPropagator().inject(carrier)
- return EnvelopeMetadata(
- traceparent=carrier.get("traceparent"),
- tracestate=carrier.get("tracestate"),
- )
-
-
-def _get_carrier_for_remote_call_metadata(remote_call_metadata: Mapping[str, str]) -> Dict[str, str]:
- carrier: Dict[str, str] = {}
- traceparent = remote_call_metadata.get("traceparent")
- tracestate = remote_call_metadata.get("tracestate")
- if traceparent:
- carrier["traceparent"] = traceparent
- if tracestate:
- carrier["tracestate"] = tracestate
- return carrier
-
-
-def get_telemetry_grpc_metadata(existingMetadata: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
- """
- Retrieves the telemetry gRPC metadata.
-
- Args:
- existingMetadata (Optional[Mapping[str, str]]): The existing metadata to include in the gRPC metadata.
-
- Returns:
- Mapping[str, str]: The gRPC metadata containing the traceparent and tracestate.
- """
- carrier: Dict[str, str] = {}
- TraceContextTextMapPropagator().inject(carrier)
- traceparent = carrier.get("traceparent")
- tracestate = carrier.get("tracestate")
- metadata: Dict[str, str] = {}
- if existingMetadata is not None:
- for key, value in existingMetadata.items():
- metadata[key] = value
- if traceparent is not None:
- metadata["traceparent"] = traceparent
- if tracestate is not None:
- metadata["tracestate"] = tracestate
- return metadata
-
-
-TelemetryMetadataContainer = Optional[EnvelopeMetadata] | Mapping[str, str]
-
-
-def _get_telemetry_context(metadata: TelemetryMetadataContainer) -> Context:
- """
- Retrieves the telemetry context from the given metadata.
-
- Args:
- metadata (Optional[EnvelopeMetadata]): The metadata containing the telemetry context.
-
- Returns:
- Context: The telemetry context extracted from the metadata, or an empty context if the metadata is None.
- """
- if metadata is None:
- return Context()
- elif isinstance(metadata, EnvelopeMetadata):
- return extract(_get_carrier_for_envelope_metadata(metadata))
- elif hasattr(metadata, "__getitem__"):
- return extract(_get_carrier_for_remote_call_metadata(metadata))
- else:
- raise ValueError(f"Unknown metadata type: {type(metadata)}")
-
-
-MessagingDestination = Union[AgentId, TopicId, str, None]
-
-
-# TODO: Once we figure out how the destinations are stringified, we can use that convention
-# https://github.com/microsoft/agnext/issues/399
-def _get_destination_str(destination: MessagingDestination) -> str:
- if isinstance(destination, AgentId):
- return f"{destination.type}.({destination.key})-A"
- elif isinstance(destination, TopicId):
- return f"{destination.type}.({destination.source})-T"
- elif isinstance(destination, str):
- return destination
- elif destination is None:
- return ""
- else:
- raise ValueError(f"Unknown destination type: {type(destination)}")
-
-
-MessagingOperation = Literal["create", "send", "publish", "receive", "intercept", "process", "ack"]
-
-
-def _get_span_name(
- operation: MessagingOperation,
- destination: Optional[MessagingDestination],
-) -> str:
+class TraceHelper(Generic[Operation, Destination, ExtraAttributes]):
"""
- Returns the span name based on the given operation and destination.
- Semantic Conventions - https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#span-name
+ TraceHelper is a utility class to assist with tracing operations using OpenTelemetry.
- Parameters:
- operation (MessagingOperation): The messaging operation.
- destination (Optional[MessagingDestination]): The messaging destination.
+ This class provides a context manager `trace_block` to create and manage spans for tracing operations,
+ following semantic conventions and supporting nested spans through metadata contexts.
- Returns:
- str: The span name.
"""
- span_parts: List[str] = [operation]
- destination_str = _get_destination_str(destination)
- if destination_str:
- span_parts.append(destination_str)
- span_name = " ".join(span_parts)
- return f"{NAMESPACE} {span_name}"
-
-def _get_span_kind(operation: MessagingOperation) -> SpanKind:
- """
- Determines the span kind based on the given messaging operation.
- Semantic Conventions - https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#span-kind
-
- Parameters:
- operation (MessagingOperation): The messaging operation.
-
- Returns:
- SpanKind: The span kind based on the messaging operation.
- """
- if operation in ["create", "send", "publish"]:
- return SpanKind.PRODUCER
- elif operation in ["receive", "intercept", "process", "ack"]:
- return SpanKind.CONSUMER
- else:
- return SpanKind.CLIENT
-
-
-def trace_block(
- tracer: Tracer,
- operation: MessagingOperation,
- destination: MessagingDestination,
- parent: Optional[TelemetryMetadataContainer],
- *,
- kind: Optional[SpanKind] = None,
- attributes: Optional[types.Attributes] = None,
- links: Optional[Sequence[Link]] = None,
- start_time: Optional[int] = None,
- record_exception: bool = True,
- set_status_on_exception: bool = True,
- end_on_exit: bool = True,
-) -> Iterator[Span]:
- """
- Thin wrapper on top of start_as_current_span.
- 1. It helps us follow semantic conventions
- 2. It helps us get contexts from metadata so we can get nested spans
-
- Args:
- tracer (Tracer): The tracer to use for tracing.
- operation (MessagingOperation): The messaging operation being performed.
- destination (MessagingDestination): The messaging destination being used.
- parent Optional[TelemetryMetadataContainer]: The parent telemetry metadta context
- kind (SpanKind, optional): The kind of span. If not provided, it maps to PRODUCER or CONSUMER depending on the operation.
- attributes (Optional[types.Attributes], optional): Additional attributes for the span. Defaults to None.
- links (Optional[Sequence[Link]], optional): Links to other spans. Defaults to None.
- start_time (Optional[int], optional): The start time of the span. Defaults to None.
- record_exception (bool, optional): Whether to record exceptions. Defaults to True.
- set_status_on_exception (bool, optional): Whether to set the status on exception. Defaults to True.
- end_on_exit (bool, optional): Whether to end the span on exit. Defaults to True.
-
- Yields:
- Iterator[Span]: The span object.
-
- """
- span_name = _get_span_name(operation, destination)
- span_kind = kind or _get_span_kind(operation)
- context = _get_telemetry_context(parent) if parent else None
- with tracer.start_as_current_span(
- span_name,
- context,
- span_kind,
- attributes,
- links,
- start_time,
- record_exception,
- set_status_on_exception,
- end_on_exit,
- ) as span:
- yield span
+ def __init__(
+ self,
+ tracer_provider: TracerProvider | None,
+ instrumentation_builder_config: TracingConfig[Operation, Destination, ExtraAttributes],
+ ) -> None:
+ self.tracer = (tracer_provider if tracer_provider else NoOpTracerProvider()).get_tracer(
+ f"autogen {instrumentation_builder_config.name}"
+ )
+ self.instrumentation_builder_config = instrumentation_builder_config
+
+ @contextlib.contextmanager
+ def trace_block(
+ self,
+ operation: Operation,
+ destination: Destination,
+ parent: Optional[TelemetryMetadataContainer],
+ *,
+ extraAttributes: ExtraAttributes | None = None,
+ kind: Optional[SpanKind] = None,
+ attributes: Optional[types.Attributes] = None,
+ links: Optional[Sequence[Link]] = None,
+ start_time: Optional[int] = None,
+ record_exception: bool = True,
+ set_status_on_exception: bool = True,
+ end_on_exit: bool = True,
+ ) -> Iterator[Span]:
+ """
+ Thin wrapper on top of start_as_current_span.
+ 1. It helps us follow semantic conventions
+ 2. It helps us get contexts from metadata so we can get nested spans
+
+ Args:
+ operation (MessagingOperation): The messaging operation being performed.
+ destination (MessagingDestination): The messaging destination being used.
+ parent Optional[TelemetryMetadataContainer]: The parent telemetry metadta context
+ kind (SpanKind, optional): The kind of span. If not provided, it maps to PRODUCER or CONSUMER depending on the operation.
+ extraAttributes (ExtraAttributes, optional): Additional defined attributes for the span. Defaults to None.
+ attributes (Optional[types.Attributes], optional): Additional non-defined attributes for the span. Defaults to None.
+ links (Optional[Sequence[Link]], optional): Links to other spans. Defaults to None.
+ start_time (Optional[int], optional): The start time of the span. Defaults to None.
+ record_exception (bool, optional): Whether to record exceptions. Defaults to True.
+ set_status_on_exception (bool, optional): Whether to set the status on exception. Defaults to True.
+ end_on_exit (bool, optional): Whether to end the span on exit. Defaults to True.
+
+ Yields:
+ Iterator[Span]: The span object.
+
+ """
+ span_name = self.instrumentation_builder_config.get_span_name(operation, destination)
+ span_kind = kind or self.instrumentation_builder_config.get_span_kind(operation)
+ context = get_telemetry_context(parent) if parent else None
+ attributes_with_defaults: Dict[str, types.AttributeValue] = {}
+ for key, value in (attributes or {}).items():
+ attributes_with_defaults[key] = value
+ instrumentation_attributes = self.instrumentation_builder_config.build_attributes(
+ operation, destination, extraAttributes
+ )
+ for key, value in instrumentation_attributes.items():
+ attributes_with_defaults[key] = value
+ with self.tracer.start_as_current_span(
+ span_name,
+ context,
+ span_kind,
+ attributes_with_defaults,
+ links,
+ start_time,
+ record_exception,
+ set_status_on_exception,
+ end_on_exit,
+ ) as span:
+ yield span
diff --git a/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing_config.py b/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing_config.py
new file mode 100644
index 000000000..78aff2562
--- /dev/null
+++ b/python/packages/autogen-core/src/autogen_core/application/telemetry/_tracing_config.py
@@ -0,0 +1,201 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, Generic, List, Literal, TypedDict, TypeVar, Union
+
+from opentelemetry.trace import SpanKind
+from opentelemetry.util import types
+from typing_extensions import NotRequired
+
+from ...base import AgentId, TopicId
+from ._constants import NAMESPACE
+
+logger = logging.getLogger("autogen_core")
+event_logger = logging.getLogger("autogen_core.events")
+
+Operation = TypeVar("Operation", bound=str)
+Destination = TypeVar("Destination")
+ExtraAttributes = TypeVar("ExtraAttributes")
+
+
+class TracingConfig(ABC, Generic[Operation, Destination, ExtraAttributes]):
+ """
+ A protocol that defines the configuration for instrumentation.
+
+ This protocol specifies the required properties and methods that any
+ instrumentation configuration class must implement. It includes a
+ property to get the name of the module being instrumented and a method
+ to build attributes for the instrumentation configuration.
+ """
+
+ @property
+ @abstractmethod
+ def name(self) -> str:
+ """
+ Returns:
+ The name of the module that is being instrumented.
+ """
+ ...
+
+ @abstractmethod
+ def build_attributes(
+ self,
+ operation: Operation,
+ destination: Destination,
+ extraAttributes: ExtraAttributes | None,
+ ) -> Dict[str, types.AttributeValue]:
+ """
+ Builds the attributes for the instrumentation configuration.
+
+ Returns:
+ Dict[str, str]: The attributes for the instrumentation configuration.
+ """
+ ...
+
+ @abstractmethod
+ def get_span_name(
+ self,
+ operation: Operation,
+ destination: Destination,
+ ) -> str:
+ """
+ Returns the span name based on the given operation and destination.
+
+ Parameters:
+ operation (MessagingOperation): The messaging operation.
+ destination (Optional[MessagingDestination]): The messaging destination.
+
+ Returns:
+ str: The span name.
+ """
+ ...
+
+ @abstractmethod
+ def get_span_kind(
+ self,
+ operation: Operation,
+ ) -> SpanKind:
+ """
+ Determines the span kind based on the given messaging operation.
+
+ Parameters:
+ operation (MessagingOperation): The messaging operation.
+
+ Returns:
+ SpanKind: The span kind based on the messaging operation.
+ """
+
+
+class ExtraMessageRuntimeAttributes(TypedDict):
+ message_size: NotRequired[int]
+ message_type: NotRequired[str]
+
+
+MessagingDestination = Union[AgentId, TopicId, str, None]
+MessagingOperation = Literal["create", "send", "publish", "receive", "intercept", "process", "ack"]
+
+
+class MessageRuntimeTracingConfig(
+ TracingConfig[MessagingOperation, MessagingDestination, ExtraMessageRuntimeAttributes]
+):
+ """
+ A class that defines the configuration for message runtime instrumentation.
+
+ This class implements the TracingConfig protocol and provides
+ the name of the module being instrumented and the attributes for the
+ instrumentation configuration.
+ """
+
+ def __init__(self, runtime_name: str) -> None:
+ self._runtime_name = runtime_name
+
+ @property
+ def name(self) -> str:
+ return self._runtime_name
+
+ def build_attributes(
+ self,
+ operation: MessagingOperation,
+ destination: MessagingDestination,
+ extraAttributes: ExtraMessageRuntimeAttributes | None,
+ ) -> Dict[str, types.AttributeValue]:
+ attrs: Dict[str, types.AttributeValue] = {
+ "messaging.operation": self._get_operation_type(operation),
+ "messaging.destination": self._get_destination_str(destination),
+ }
+ if extraAttributes:
+ # TODO: Make this more pythonic?
+ if "message_size" in extraAttributes:
+ attrs["messaging.message.envelope.size"] = extraAttributes["message_size"]
+ if "message_type" in extraAttributes:
+ attrs["messaging.message.type"] = extraAttributes["message_type"]
+ return attrs
+
+ def get_span_name(
+ self,
+ operation: MessagingOperation,
+ destination: MessagingDestination,
+ ) -> str:
+ """
+ Returns the span name based on the given operation and destination.
+ Semantic Conventions - https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#span-name
+
+ Parameters:
+ operation (MessagingOperation): The messaging operation.
+ destination (Optional[MessagingDestination]): The messaging destination.
+
+ Returns:
+ str: The span name.
+ """
+ span_parts: List[str] = [operation]
+ destination_str = self._get_destination_str(destination)
+ if destination_str:
+ span_parts.append(destination_str)
+ span_name = " ".join(span_parts)
+ return f"{NAMESPACE} {span_name}"
+
+ def get_span_kind(
+ self,
+ operation: MessagingOperation,
+ ) -> SpanKind:
+ """
+ Determines the span kind based on the given messaging operation.
+ Semantic Conventions - https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/#span-kind
+
+ Parameters:
+ operation (MessagingOperation): The messaging operation.
+
+ Returns:
+ SpanKind: The span kind based on the messaging operation.
+ """
+ if operation in ["create", "send", "publish"]:
+ return SpanKind.PRODUCER
+ elif operation in ["receive", "intercept", "process", "ack"]:
+ return SpanKind.CONSUMER
+ else:
+ return SpanKind.CLIENT
+
+ # TODO: Once we figure out how the destinations are stringified, we can use that convention
+ # https://github.com/microsoft/agnext/issues/399
+ def _get_destination_str(self, destination: MessagingDestination) -> str:
+ if isinstance(destination, AgentId):
+ return f"{destination.type}.({destination.key})-A"
+ elif isinstance(destination, TopicId):
+ return f"{destination.type}.({destination.source})-T"
+ elif isinstance(destination, str):
+ return destination
+ elif destination is None:
+ return ""
+ else:
+ raise ValueError(f"Unknown destination type: {type(destination)}")
+
+ def _get_operation_type(self, operation: MessagingOperation) -> str:
+ if operation in ["send", "publish"]:
+ return "publish"
+ if operation in ["create"]:
+ return "create"
+ elif operation in ["receive", "intercept", "ack"]:
+ return "receive"
+ elif operation in ["process"]:
+ return "process"
+ else:
+ return "Unknown"