Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/actions/spelling/allow.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
a2a

Check warning on line 1 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
A2A

Check warning on line 2 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
A2AFastAPI

Check warning on line 3 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
AAgent
Expand Down Expand Up @@ -29,7 +29,7 @@
AUser
autouse
backticks
base64url

Check warning on line 32 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
buf
bufbuild
cla
Expand All @@ -49,7 +49,7 @@
dsn
DSNs
dunders
ES256

Check warning on line 52 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
euo
EUR
evt
Expand All @@ -66,8 +66,8 @@
gowebpki
GVsb
hazmat
HS256

Check warning on line 69 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
HS384

Check warning on line 70 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
ietf
importlib
initdb
Expand Down Expand Up @@ -110,11 +110,11 @@
Oneof
OpenAPI
openapiv
openapiv2

Check warning on line 113 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
opensource
otherurl
outerjoin
pb2

Check warning on line 117 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
PLW
podman
Podman
Expand All @@ -139,11 +139,12 @@
respx
resub
rmi
RS256

Check warning on line 142 in .github/actions/spelling/allow.txt

View workflow job for this annotation

GitHub Actions / Check Spelling

Ignoring entry because it contains non-alpha characters (non-alpha-in-dictionary)
RUF
Rundgren
SECP
SECP256R1
semconv
SFIXED
signings
SLF
Expand Down
14 changes: 9 additions & 5 deletions src/a2a/client/base_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -441,6 +441,8 @@ async def _execute_with_interceptors(

request = self._client_request(input_data, method, context)
await plugins.before_client_request(request)
result: Any = None
error: BaseException | None = None
try:
result = await plugins.wrap_client_call(
request,
Expand All @@ -449,13 +451,15 @@ async def _execute_with_interceptors(
),
)
except Exception as e:
error = e
raise
finally:
# Also runs when the call is cancelled, which is not an error.
await plugins.after_client_request(
ClientResponse(request.method, None, request.context, error=e)
ClientResponse(
request.method, result, request.context, error=error
)
)
raise
await plugins.after_client_request(
ClientResponse(request.method, result, request.context)
)
return result

async def _call_through_interceptors(
Expand Down
14 changes: 14 additions & 0 deletions src/a2a/plugins/otel/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
"""OpenTelemetry instrumentation for the A2A SDK.

Importing this package requires the ``telemetry`` extra::

pip install "a2a-sdk[telemetry]"

`a2a.plugins` does not import it, so installs without that extra are
unaffected.
"""

from a2a.plugins.otel._plugin import OpenTelemetryPlugin


__all__ = ['OpenTelemetryPlugin']
260 changes: 260 additions & 0 deletions src/a2a/plugins/otel/_plugin.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
"""The OpenTelemetry plugin."""

from __future__ import annotations

import logging
import os

from importlib.metadata import version
from typing import TYPE_CHECKING, Any

from a2a.plugins.base import CompletePlugin
from a2a.plugins.otel import _semconv
from a2a.types.a2a_pb2 import SendMessageResponse, StreamResponse, Task


if TYPE_CHECKING:
from collections.abc import Awaitable, Callable
from contextlib import AbstractContextManager

from opentelemetry.trace import Span, Tracer, TracerProvider

from a2a.plugins.types import ClientRequest, ClientResponse
from a2a.types.a2a_pb2 import AgentInterface


logger = logging.getLogger(__name__)

try:
from opentelemetry import trace
from opentelemetry.propagate import inject
from opentelemetry.trace import SpanKind, StatusCode

_otel_installed = True
except ImportError:
_otel_installed = False


ENABLED_ENV_VAR = 'A2A_OTEL_PLUGIN_ENABLED'

INSTRUMENTING_MODULE_NAME = 'a2a-python-sdk.otel'

_SPAN_KEY = 'a2a.otel.span'

# Task and context IDs of a ListTasks call describe the listed tasks, not the
# operation, so they are never reported for it.
_SKIP_TASK_ATTRIBUTES = frozenset({'list_tasks'})

# Methods whose request `id` is the task ID. Elsewhere `id` can name something
# else: on the push notification config requests it is the config's ID.
_ID_IS_TASK_ID = frozenset({'get_task', 'cancel_task', 'subscribe'})


def _current(span: Span) -> AbstractContextManager[Span]:
"""Makes the span current without letting OTel set its status or events."""
return trace.use_span(
span,
end_on_exit=False,
record_exception=False,
set_status_on_exception=False,
)


def _env_enabled() -> bool:
return os.getenv(ENABLED_ENV_VAR, 'true').lower() == 'true'


def _sdk_version() -> str:
return version('a2a-sdk')


class OpenTelemetryPlugin(CompletePlugin):
"""Reports A2A client and server calls as OpenTelemetry spans.

Register it before creating clients and request handlers::

from a2a import plugins
from a2a.plugins.otel import OpenTelemetryPlugin

plugins.set_global(plugins.sequential(OpenTelemetryPlugin()))

The application configures the OpenTelemetry SDK and its exporter; this
plugin only creates spans. Set ``A2A_OTEL_PLUGIN_ENABLED=false`` to turn
it into a no-op without removing it.
"""

name = 'opentelemetry'

def __init__(self, tracer_provider: TracerProvider | None = None) -> None:
"""Initializes the plugin.

Args:
tracer_provider: Provider the tracer is taken from. Defaults to
the global provider, which the application configures.

Raises:
ImportError: If OpenTelemetry is not installed. Asking for this
plugin states intent, so a silent no-op would hide the
missing dependency.
"""
if not _otel_installed:
raise ImportError(
'OpenTelemetryPlugin requires OpenTelemetry. Install it '
'with: \'pip install "a2a-sdk[telemetry]"\''
)

self._enabled = _env_enabled()
if not self._enabled:
logger.debug(
'A2A OpenTelemetry plugin disabled via %s. No spans will '
'be reported.',
ENABLED_ENV_VAR,
)
return

provider: Any = tracer_provider if tracer_provider else trace
self._tracer: Tracer = provider.get_tracer(
INSTRUMENTING_MODULE_NAME, _sdk_version()
)

async def before_client_request(self, request: ClientRequest) -> None:
"""Starts the client span and propagates it to the agent."""
if not self._enabled:
return

method = _semconv.METHOD_NAMES.get(request.method, request.method)
span = self._tracer.start_span(method, kind=SpanKind.CLIENT)
request.context.state[_SPAN_KEY] = span

span.set_attribute(_semconv.A2A_METHOD_NAME, method)
_set_request_attributes(span, request)

carrier = dict(request.context.service_parameters or {})
with _current(span):
inject(carrier)
request.context.service_parameters = carrier

async def wrap_client_call(
self, request: ClientRequest, call: Callable[[], Awaitable[Any]]
) -> Any:
"""Runs the call with the span current, so transport spans nest."""
span = request.context.state.get(_SPAN_KEY)
if span is None:
return await call()
with _current(span):
return await call()

async def after_client_request(self, response: ClientResponse) -> None:
"""Records what the response carries, and ends the span when final."""
if not self._enabled:
return

span = response.context.state.get(_SPAN_KEY)
if span is None:
return

_set_response_attributes(span, response)
if not response.is_final:
return

del response.context.state[_SPAN_KEY]
if response.error is not None:
span.set_status(StatusCode.ERROR, str(response.error))
span.set_attribute(
_semconv.ERROR_TYPE, _semconv.error_type(response.error)
)
span.end()


def _set_request_attributes(span: Span, request: ClientRequest) -> None:
"""Sets the attributes known before the request is sent."""
card = request.agent_card
if card.name:
span.set_attribute(_semconv.GEN_AI_AGENT_NAME, card.name)
if card.description:
span.set_attribute(_semconv.GEN_AI_AGENT_DESCRIPTION, card.description)
if card.version:
span.set_attribute(_semconv.GEN_AI_AGENT_VERSION, card.version)

payload = request.payload
message = getattr(payload, 'message', None)
if message is not None and message.message_id:
span.set_attribute(_semconv.A2A_MESSAGE_ID, message.message_id)
if message.reference_task_ids:
span.set_attribute(
_semconv.A2A_MESSAGE_REFERENCE_TASK_IDS,
list(message.reference_task_ids),
)

if request.method not in _SKIP_TASK_ATTRIBUTES:
_set_ids(span, payload, request.method)
if message is not None:
_set_ids(span, message, request.method)

interface = request.interface
tenant = getattr(payload, 'tenant', '') or (
interface.tenant if interface else ''
)
if tenant:
span.set_attribute(_semconv.A2A_TENANT, tenant)
if interface is not None:
_set_interface_attributes(span, interface)


def _set_interface_attributes(span: Span, interface: AgentInterface) -> None:
"""Sets the attributes taken from the selected Agent Card interface."""
if interface.protocol_version:
span.set_attribute(
_semconv.A2A_PROTOCOL_VERSION, interface.protocol_version
)
address, port = _semconv.host_port(interface.url)
if address:
span.set_attribute(_semconv.SERVER_ADDRESS, address)
if port is not None:
span.set_attribute(_semconv.SERVER_PORT, port)


def _set_response_attributes(span: Span, response: ClientResponse) -> None:
"""Sets the task attributes a response payload carries.

The task state is reported for unary calls only: a stream moves through
several states, which no single value describes.
"""
if response.payload is None or response.method in _SKIP_TASK_ATTRIBUTES:
return
payload = _unwrap(response.payload)
_set_ids(span, payload, response.method)
if response.is_stream_event:
return
status = getattr(payload, 'status', None)
if status is not None and (state := _semconv.task_state_name(status.state)):
span.set_attribute(_semconv.A2A_TASK_STATE, state)


def _unwrap(payload: Any) -> Any:
"""Returns the task, message or event a response wraps."""
if isinstance(payload, (SendMessageResponse, StreamResponse)):
which = payload.WhichOneof('payload')
return getattr(payload, which) if which else payload
return payload


def _set_ids(span: Span, payload: Any, method: str) -> None:
"""Sets the task and context IDs a payload carries."""
if task_id := _task_id(payload, method):
span.set_attribute(_semconv.A2A_TASK_ID, task_id)
if context_id := getattr(payload, 'context_id', ''):
span.set_attribute(_semconv.GEN_AI_CONVERSATION_ID, context_id)


def _task_id(payload: Any, method: str) -> str:
"""Returns the task ID a payload carries, or ''.

Most shapes name it `task_id`. A `Task` and the requests of the methods in
`_ID_IS_TASK_ID` name it `id`, which elsewhere can identify something else.
"""
if task_id := getattr(payload, 'task_id', ''):
return task_id
if isinstance(payload, Task) or method in _ID_IS_TASK_ID:
return getattr(payload, 'id', '')
return ''
75 changes: 75 additions & 0 deletions src/a2a/plugins/otel/_semconv.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
"""A2A semantic conventions: attribute keys and value mapping.

Keys are spelled out rather than imported, because no released
``opentelemetry-semantic-conventions`` package carries the A2A attributes yet.
"""

from __future__ import annotations

from urllib.parse import urlparse

from a2a.types.a2a_pb2 import TaskState
from a2a.utils.errors import A2A_ERROR_REASONS, A2AError


A2A_METHOD_NAME = 'a2a.method.name'
A2A_PROTOCOL_VERSION = 'a2a.protocol.version'
A2A_TENANT = 'a2a.tenant'
A2A_MESSAGE_ID = 'a2a.message.id'
A2A_MESSAGE_REFERENCE_TASK_IDS = 'a2a.message.reference_task_ids'
A2A_TASK_ID = 'a2a.task.id'
A2A_TASK_STATE = 'a2a.task.state'
GEN_AI_CONVERSATION_ID = 'gen_ai.conversation.id'
GEN_AI_AGENT_NAME = 'gen_ai.agent.name'
GEN_AI_AGENT_DESCRIPTION = 'gen_ai.agent.description'
GEN_AI_AGENT_VERSION = 'gen_ai.agent.version'
ERROR_TYPE = 'error.type'
SERVER_ADDRESS = 'server.address'
SERVER_PORT = 'server.port'

METHOD_NAMES = {
'send_message': 'SendMessage',
'send_message_streaming': 'SendStreamingMessage',
'get_task': 'GetTask',
'cancel_task': 'CancelTask',
'subscribe': 'SubscribeToTask',
'list_tasks': 'ListTasks',
'create_task_push_notification_config': (
'CreateTaskPushNotificationConfig'
),
'get_task_push_notification_config': 'GetTaskPushNotificationConfig',
'list_task_push_notification_configs': ('ListTaskPushNotificationConfigs'),
'delete_task_push_notification_config': (
'DeleteTaskPushNotificationConfig'
),
'get_extended_agent_card': 'GetExtendedAgentCard',
}


def task_state_name(state: int) -> str | None:
"""Returns the conventions' name for a `TaskState`, or None if unset."""
if state == TaskState.TASK_STATE_UNSPECIFIED:
return None
return TaskState.Name(state)


def error_type(error: BaseException) -> str:
"""Returns the `error.type` value for an exception.

Prefers the A2A error reason, and falls back to the canonical name of the
exception. The conventions also allow a protocol status code, but no
client exception carries one as an attribute.
"""
if isinstance(error, A2AError) and (
reason := A2A_ERROR_REASONS.get(type(error))
):
return reason
return f'{type(error).__module__}.{type(error).__qualname__}'


def host_port(url: str) -> tuple[str | None, int | None]:
"""Splits an interface URL into its `server.address` and `server.port`."""
if not url:
return None, None
parsed = urlparse(url)
return parsed.hostname, parsed.port
Loading
Loading