Skip to content

fix: correctly label tool result messages in OpenTelemetry events #839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 15, 2025
Merged

fix: correctly label tool result messages in OpenTelemetry events #839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
30 changes: 27 additions & 3 deletions src/strands/telemetry/tracer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,30 @@ def _add_event(self, span: Optional[Span], event_name: str, event_attributes: Di

span.add_event(event_name, attributes=event_attributes)

def _get_event_name_for_message(self, message: Message) -> str:
"""Determine the appropriate OpenTelemetry event name for a message.

According to OpenTelemetry semantic conventions v1.36.0, messages containing tool results
should be labeled as 'gen_ai.tool.message' regardless of their role field.
This ensures proper categorization of tool responses in traces.

Note: The GenAI namespace is experimental and may change in future versions.

Reference: https://github.com/open-telemetry/semantic-conventions/blob/v1.36.0/docs/gen-ai/gen-ai-events.md#event-gen_aitoolmessage

Args:
message: The message to determine the event name for

Returns:
The OpenTelemetry event name (e.g., 'gen_ai.user.message', 'gen_ai.tool.message')
"""
# Check if the message contains a tool result
for content_block in message.get("content", []):
if "toolResult" in content_block:
return "gen_ai.tool.message"

return f"gen_ai.{message['role']}.message"

def start_model_invoke_span(
self,
messages: Messages,
Expand Down Expand Up @@ -240,7 +264,7 @@ def start_model_invoke_span(
for message in messages:
self._add_event(
span,
f"gen_ai.{message['role']}.message",
self._get_event_name_for_message(message),
{"content": serialize(message["content"])},
)
return span
Expand Down Expand Up @@ -379,7 +403,7 @@ def start_event_loop_cycle_span(
for message in messages or []:
self._add_event(
span,
f"gen_ai.{message['role']}.message",
self._get_event_name_for_message(message),
{"content": serialize(message["content"])},
)

Expand Down Expand Up @@ -456,7 +480,7 @@ def start_agent_span(
for message in messages:
self._add_event(
span,
f"gen_ai.{message['role']}.message",
self._get_event_name_for_message(message),
{"content": serialize(message["content"])},
)

Expand Down
201 changes: 201 additions & 0 deletions tests/strands/telemetry/test_tracer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -746,3 +746,204 @@ def test_serialize_vs_json_dumps():
custom_result = serialize({"text": japanese_text})
assert japanese_text in custom_result
assert "\\u" not in custom_result


@pytest.mark.parametrize(
"message, expected_event_name, description",
[
# Regular role-based messages
(
{"role": "user", "content": [{"text": "Hello"}]},
"gen_ai.user.message",
"regular user message",
),
(
{"role": "assistant", "content": [{"text": "Hello"}]},
"gen_ai.assistant.message",
"regular assistant message",
),
(
{"role": "system", "content": [{"text": "You are a helpful assistant"}]},
"gen_ai.system.message",
"regular system message",
),
# Messages with tool results should always be labeled as tool messages
(
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "123",
"status": "success",
"content": [{"text": "Tool response"}],
}
}
],
},
"gen_ai.tool.message",
"user message containing tool result",
),
(
{
"role": "assistant",
"content": [
{
"toolResult": {
"toolUseId": "123",
"status": "success",
"content": [{"text": "Tool response"}],
}
}
],
},
"gen_ai.tool.message",
"assistant message containing tool result",
),
# Mixed content with tool results
(
{
"role": "user",
"content": [
{"text": "Here are the results:"},
{
"toolResult": {
"toolUseId": "123",
"status": "success",
"content": [{"text": "Tool response"}],
}
},
],
},
"gen_ai.tool.message",
"message with both text and tool result",
),
# Multiple tool results
(
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "123",
"status": "success",
"content": [{"text": "First tool"}],
}
},
{
"toolResult": {
"toolUseId": "456",
"status": "success",
"content": [{"text": "Second tool"}],
}
},
],
},
"gen_ai.tool.message",
"message with multiple tool results",
),
# Edge cases
(
{"role": "user", "content": []},
"gen_ai.user.message",
"message with empty content",
),
(
{"role": "assistant"},
"gen_ai.assistant.message",
"message with no content key",
),
],
)
def test_get_event_name_for_message(message, expected_event_name, description):
"""Test getting event name for various message types using data-driven approach."""
tracer = Tracer()

event_name = tracer._get_event_name_for_message(message)

assert event_name == expected_event_name, f"Failed for {description}"


def test_start_model_invoke_span_with_tool_result_message(mock_tracer):
"""Test that start_model_invoke_span correctly labels tool result messages."""
with mock.patch("strands.telemetry.tracer.trace_api.get_tracer", return_value=mock_tracer):
tracer = Tracer()
tracer.tracer = mock_tracer

mock_span = mock.MagicMock()
mock_tracer.start_span.return_value = mock_span

# Message that contains a tool result
messages = [
{
"role": "user",
"content": [
{"toolResult": {"toolUseId": "123", "status": "success", "content": [{"text": "Weather is sunny"}]}}
],
}
]

span = tracer.start_model_invoke_span(messages=messages, model_id="test-model")

# Should use gen_ai.tool.message event name instead of gen_ai.user.message
mock_span.add_event.assert_called_with(
"gen_ai.tool.message", attributes={"content": json.dumps(messages[0]["content"])}
)
assert span is not None


def test_start_agent_span_with_tool_result_message(mock_tracer):
"""Test that start_agent_span correctly labels tool result messages."""
with mock.patch("strands.telemetry.tracer.trace_api.get_tracer", return_value=mock_tracer):
tracer = Tracer()
tracer.tracer = mock_tracer

mock_span = mock.MagicMock()
mock_tracer.start_span.return_value = mock_span

# Message that contains a tool result
messages = [
{
"role": "user",
"content": [
{"toolResult": {"toolUseId": "123", "status": "success", "content": [{"text": "Weather is sunny"}]}}
],
}
]

span = tracer.start_agent_span(messages=messages, agent_name="WeatherAgent", model_id="test-model")

# Should use gen_ai.tool.message event name instead of gen_ai.user.message
mock_span.add_event.assert_called_with(
"gen_ai.tool.message", attributes={"content": json.dumps(messages[0]["content"])}
)
assert span is not None


def test_start_event_loop_cycle_span_with_tool_result_message(mock_tracer):
"""Test that start_event_loop_cycle_span correctly labels tool result messages."""
with mock.patch("strands.telemetry.tracer.trace_api.get_tracer", return_value=mock_tracer):
tracer = Tracer()
tracer.tracer = mock_tracer

mock_span = mock.MagicMock()
mock_tracer.start_span.return_value = mock_span

# Message that contains a tool result
messages = [
{
"role": "user",
"content": [
{"toolResult": {"toolUseId": "123", "status": "success", "content": [{"text": "Weather is sunny"}]}}
],
}
]

event_loop_kwargs = {"event_loop_cycle_id": "cycle-123"}
span = tracer.start_event_loop_cycle_span(event_loop_kwargs, messages=messages)

# Should use gen_ai.tool.message event name instead of gen_ai.user.message
mock_span.add_event.assert_called_with(
"gen_ai.tool.message", attributes={"content": json.dumps(messages[0]["content"])}
)
assert span is not None
Loading