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.pyindex 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 dataclassfrom enum import Enumfrom typing import Any, Awaitable, Callable, Dict, List, Mapping, ParamSpec, Set, Type, TypeVar, cast-from opentelemetry.trace import NoOpTracerProvider, TracerProvider+from opentelemetry.trace import TracerProviderfrom ..base import (Agent,@@ -30,7 +30,7 @@ from ..base import (from ..base.exceptions import MessageDroppedExceptionfrom ..base.intervention import DropMessage, InterventionHandlerfrom ._helpers import SubscriptionManager, get_impl-from .telemetry import EnvelopeMetadata, get_telemetry_envelope_metadata, trace_block+from .telemetry import EnvelopeMetadata, MessageRuntimeTracingConfig, TraceHelper, get_telemetry_envelope_metadatalogger = 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 publishasync 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.pyindex 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 TypeSubscriptionfrom ._helpers import SubscriptionManager, get_implfrom .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_metadataif 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 resultfuture = 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__.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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, TracerProviderfrom 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 spandiff --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.pynew file mode 100644index 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"