Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

fix(tracing): keep tool and task outputs whole in exported spans (#7833)

João Mourafbcf2de39d3f
diff --git a/lib/crewai/src/crewai/telemetry/tracing/gen_ai_shapes.py b/lib/crewai/src/crewai/telemetry/tracing/gen_ai_shapes.py
index ac8a593af..ff0b27070 100644
--- a/lib/crewai/src/crewai/telemetry/tracing/gen_ai_shapes.py
+++ b/lib/crewai/src/crewai/telemetry/tracing/gen_ai_shapes.py
@@ -17,16 +17,41 @@ Spec: https://opentelemetry.io/docs/specs/semconv/gen-ai/
from __future__ import annotations
+from functools import lru_cache
import json
+import logging
+import math
import os
from typing import Any
from crewai.utilities.serialization import to_serializable
+logger = logging.getLogger(__name__)
+
+
_MAX_DEPTH = 14
-DEFAULT_MAX_ATTR_BYTES = 32 * 1024
+DEFAULT_MAX_ATTR_BYTES = 384 * 1024
+"""Upper bound, in UTF-8 bytes, on one exported span attribute value.
+
+Tool results, task outputs, agent prompts and answers, and LLM messages are
+evidence: whoever reads the trace (a person in the trace viewer, an evaluator
+checking that a summary matches the data a tool returned) needs them whole, so
+the bound sits well above what a real run produces (a 300 KB tool result fits).
+It is set by Wharf, which refuses an OTLP request whose encoded body is over
+3,072,000 bytes, so seven attributes at this bound still fit one request with
+room for the rest of the span (a span that does not fit is cut further at
+export, see ``grants._fit_span``). A value over the bound is cut as little as possible and says so:
+``<attr>.truncated`` and ``<attr>.original_size_bytes`` ride next to it.
+
+It is also the ceiling: ``CREWAI_OTEL_MAX_ATTR_BYTES`` and the OpenTelemetry
+SDK's span attribute length limit (``OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT``,
+else ``OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT``) can lower it, never raise it; a
+higher ``CREWAI_OTEL_MAX_ATTR_BYTES`` is clamped to it with one warning. The
+SDK cuts without a marker, so a lower SDK limit lowers the bound and the SDK
+never has anything left to cut.
+"""
_PLACEHOLDER_ROLE = "system"
_TRUNCATION_LOOP_LIMIT = 8
@@ -351,7 +376,7 @@ def truncate_attr(
if payload is None:
return None, {}
- cap = max_bytes if max_bytes is not None else _max_attr_bytes()
+ cap = max_bytes if max_bytes is not None else max_attr_bytes()
original_size = _byte_len(payload)
if original_size <= cap:
return payload, {}
@@ -371,15 +396,111 @@ def truncate_attr(
return _envelope(payload, original_size, cap), markers
-def _max_attr_bytes() -> int:
- raw = os.environ.get("CREWAI_OTEL_MAX_ATTR_BYTES")
+def _positive_env_int(name: str) -> int | None:
+ raw = os.environ.get(name)
if not raw:
- return DEFAULT_MAX_ATTR_BYTES
+ return None
try:
value = int(raw)
except ValueError:
- return DEFAULT_MAX_ATTR_BYTES
- return value if value > 0 else DEFAULT_MAX_ATTR_BYTES
+ return None
+ return value if value > 0 else None
+
+
+_UNLIMITED = object()
+
+
+def _sdk_env_limit(name: str) -> int | None | object:
+ """Read one SDK length limit the way the OpenTelemetry SDK does.
+
+ Absent → ``None`` (fall through to the next setting); empty → unlimited;
+ a non-negative integer → that limit, ``0`` included (the SDK then cuts
+ every string to nothing). A value the SDK would reject is ignored here.
+ """
+ if name not in os.environ:
+ return None
+ raw = os.environ[name].strip().lower()
+ if raw == "":
+ return _UNLIMITED
+ try:
+ value = int(raw)
+ except ValueError:
+ return None
+ return value if value >= 0 else None
+
+
+def _sdk_span_attribute_limit() -> int | None:
+ """The SDK's span attribute length limit; ``None`` when unlimited.
+
+ The span setting takes precedence over the general one, also when it is
+ explicitly empty (unlimited), as in ``SpanLimits``.
+ """
+ for name in (
+ "OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT",
+ "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT",
+ ):
+ limit = _sdk_env_limit(name)
+ if limit is _UNLIMITED:
+ return None
+ if isinstance(limit, int):
+ return limit
+ return None
+
+
+def max_attr_bytes() -> int:
+ """The byte bound :func:`truncate_attr` applies when given none.
+
+ See :data:`DEFAULT_MAX_ATTR_BYTES`. The SDK's limit counts characters and a
+ character is at least one byte, so a value within this many bytes is
+ within the SDK's limit too.
+ """
+ cap = DEFAULT_MAX_ATTR_BYTES
+ configured = _positive_env_int("CREWAI_OTEL_MAX_ATTR_BYTES")
+ if configured is not None:
+ if configured > DEFAULT_MAX_ATTR_BYTES:
+ _warn_clamped(configured)
+ else:
+ cap = configured
+ sdk_limit = _sdk_span_attribute_limit()
+ return min(cap, sdk_limit) if sdk_limit is not None else cap
+
+
+@lru_cache(maxsize=8)
+def _warn_clamped(configured: int) -> None:
+ """Say once per configured value that it was clamped, and why."""
+ logger.warning(
+ "CREWAI_OTEL_MAX_ATTR_BYTES=%d is above the %d-byte ceiling; using %d. "
+ "Wharf refuses an OTLP request over 3,072,000 bytes, and a span with "
+ "several attributes above the ceiling would not fit one request.",
+ configured,
+ DEFAULT_MAX_ATTR_BYTES,
+ DEFAULT_MAX_ATTR_BYTES,
+ )
+
+
+def truncate_plain(
+ payload: str | None,
+ *,
+ attr: str,
+ max_bytes: int | None = None,
+) -> tuple[str | None, dict[str, Any]]:
+ """Bound a plain (non-GenAI) string attribute: keep its head, mark the cut.
+
+ No shape is assumed: a JSON array whose items carry ``role`` may be a user
+ list or a chat log a task produced, not a GenAI conversation, so it is
+ never rewritten the way :func:`truncate_attr` rewrites messages.
+ """
+ if payload is None:
+ return None, {}
+ cap = max_bytes if max_bytes is not None else max_attr_bytes()
+ encoded = payload.encode("utf-8")
+ if len(encoded) <= cap:
+ return payload, {}
+ markers = {
+ f"{attr}.truncated": True,
+ f"{attr}.original_size_bytes": len(encoded),
+ }
+ return encoded[:cap].decode("utf-8", errors="ignore"), markers
def _byte_len(s: str) -> int:
@@ -446,7 +567,14 @@ def _shrink_text_until_fits(
if target is None:
break
part, content = target
- new_content = _trunc_text(content, _byte_len(content) // 2)
+ # Cut what is over and no more. JSON escaping makes each byte of the
+ # text weigh more once serialized, so scale the cut by that weight;
+ # a later pass takes whatever is still over.
+ overshoot = _byte_len(serialized) - cap
+ raw_bytes = _byte_len(content)
+ weight = _byte_len(json.dumps(content)) / max(1, raw_bytes)
+ cut = math.ceil(overshoot / weight) + 64
+ new_content = _trunc_text(content, raw_bytes - cut)
if new_content == content:
break
part["content"] = new_content
@@ -473,9 +601,12 @@ def _largest_text_part(
def _trunc_text(content: str, target_bytes: int) -> str:
+ """Keep the head and the tail of ``content`` in about ``target_bytes``."""
encoded = content.encode("utf-8")
- head_bytes = max(target_bytes // 2, 256)
- tail_bytes = max(target_bytes // 4, 128)
+ head_bytes = max(target_bytes * 2 // 3, 256)
+ tail_bytes = max(target_bytes // 3, 128)
+ if head_bytes + tail_bytes >= len(encoded):
+ return content
head = encoded[:head_bytes].decode("utf-8", errors="ignore")
tail = encoded[-tail_bytes:].decode("utf-8", errors="ignore")
omitted_kb = max(1, (len(encoded) - head_bytes - tail_bytes) // 1024)
@@ -489,9 +620,9 @@ def _envelope(payload: str, original_size: int, cap: int) -> str | None:
Used when the structural strategy doesn't apply (non-message JSON,
malformed JSON) or didn't fit (rare — message envelopes dominate).
"""
- preview_bytes = min(cap // 4, 4 * 1024)
encoded = payload.encode("utf-8")
- preview = encoded[:preview_bytes].decode("utf-8", errors="ignore")
+ # As much of the payload as fits: the preview is what a reader still has.
+ preview = encoded[:cap].decode("utf-8", errors="ignore")
while True:
envelope = json.dumps(
{
@@ -500,9 +631,13 @@ def _envelope(payload: str, original_size: int, cap: int) -> str | None:
"_preview": preview,
}
)
- if _byte_len(envelope) <= cap:
+ overshoot = _byte_len(envelope) - cap
+ if overshoot <= 0:
return envelope
if not preview:
return None
- # JSON escaping can expand the preview, so measure the encoded result.
- preview = preview[: len(preview) // 2]
+ # JSON escaping can expand the preview, so measure what each kept
+ # character weighs once encoded and drop just enough of them.
+ weight = _byte_len(json.dumps(preview)) / len(preview)
+ drop = math.ceil(overshoot / weight) + 8
+ preview = preview[: max(0, len(preview) - drop)]
diff --git a/lib/crewai/src/crewai/telemetry/tracing/grants.py b/lib/crewai/src/crewai/telemetry/tracing/grants.py
index 3fd85312e..25b9cf3f3 100644
--- a/lib/crewai/src/crewai/telemetry/tracing/grants.py
+++ b/lib/crewai/src/crewai/telemetry/tracing/grants.py
@@ -9,6 +9,7 @@ from ipaddress import ip_address
import logging
import os
from threading import Lock
+from typing import Any
from urllib.parse import urlsplit
from uuid import UUID
@@ -28,7 +29,7 @@ from crewai.events.listeners.tracing.utils import (
should_suppress_tracing_messages,
)
from crewai.telemetry.telemetry import Telemetry
-from crewai.telemetry.tracing import last_run
+from crewai.telemetry.tracing import gen_ai_shapes, last_run
from crewai.telemetry.tracing.session import MAX_EXPORT_BATCH_SIZE, otlp_exporter
@@ -37,6 +38,75 @@ logger = logging.getLogger(__name__)
MAX_EXPORT_BODY_BYTES = 3_072_000
+_FIT_ATTEMPTS = 16
+
+
+def _fit_span(span: ReadableSpan, size: int) -> ReadableSpan | None:
+ """``span`` with its largest string attributes cut until it fits a request.
+
+ Each attribute is bounded on its own, so only a span carrying many large
+ ones gets here. Cutting the largest by the overshoot, with the usual
+ ``<attr>.truncated`` / ``<attr>.original_size_bytes`` markers, keeps the
+ span (its place in the tree, its timing, its status) where dropping it
+ would lose all of it. ``None`` when its strings cannot make it fit — the
+ excess is in the resource, the scope or the events.
+ """
+ attributes = dict(span.attributes or {})
+ for _ in range(_FIT_ATTEMPTS):
+ overshoot = size - MAX_EXPORT_BODY_BYTES
+ if overshoot <= 0:
+ return _with_attributes(span, attributes)
+ key, value = max(
+ (
+ (k, v)
+ for k, v in attributes.items()
+ if isinstance(v, str) and not k.endswith(".truncated")
+ ),
+ key=lambda item: len(item[1].encode("utf-8")),
+ default=(None, None),
+ )
+ if key is None or value is None:
+ return None
+ length = len(value.encode("utf-8"))
+ target = max(0, length - overshoot - 1024)
+ if key.startswith("gen_ai."):
+ cut, markers = gen_ai_shapes.truncate_attr(
+ value, attr=key, max_bytes=target
+ )
+ else:
+ cut, markers = gen_ai_shapes.truncate_plain(
+ value, attr=key, max_bytes=target
+ )
+ if cut is None:
+ cut = ""
+ if cut == value:
+ return None
+ attributes[key] = cut
+ # A value already cut keeps the size it had before the first cut.
+ markers.pop(f"{key}.original_size_bytes", None)
+ attributes.setdefault(f"{key}.original_size_bytes", length)
+ attributes.update(markers)
+ size = encode_spans([_with_attributes(span, attributes)]).ByteSize()
+ return None
+
+
+def _with_attributes(span: ReadableSpan, attributes: dict[str, Any]) -> ReadableSpan:
+ return ReadableSpan(
+ name=span.name,
+ context=span.get_span_context(),
+ parent=span.parent,
+ resource=span.resource,
+ attributes=attributes,
+ events=span.events,
+ links=span.links,
+ kind=span.kind,
+ status=span.status,
+ start_time=span.start_time,
+ end_time=span.end_time,
+ instrumentation_scope=span.instrumentation_scope,
+ )
+
+
class TraceGrantError(Exception):
"""AMP could not authorize tracing; never downgrade a supplied credential."""
@@ -265,6 +335,18 @@ class GrantSpanExporter(SpanExporter):
size = encode_spans(batch).ByteSize()
if size > MAX_EXPORT_BODY_BYTES:
if len(batch) == 1:
+ fitted = _fit_span(batch[0], size)
+ if fitted is not None:
+ logger.warning(
+ "Execution trace span %r encoded to %d bytes, over "
+ "Wharf's %d-byte request limit; its largest "
+ "attributes were cut, each marked <attr>.truncated",
+ batch[0].name,
+ size,
+ MAX_EXPORT_BODY_BYTES,
+ )
+ pending.append([fitted])
+ continue
logger.warning(
"Skipping execution trace span: encoded size %d exceeds "
"Wharf's %d-byte request limit",
diff --git a/lib/crewai/src/crewai/telemetry/tracing/handlers.py b/lib/crewai/src/crewai/telemetry/tracing/handlers.py
index 2c7003502..4d5870ffa 100644
--- a/lib/crewai/src/crewai/telemetry/tracing/handlers.py
+++ b/lib/crewai/src/crewai/telemetry/tracing/handlers.py
@@ -112,7 +112,7 @@ from crewai.events.types.skill_events import (
SkillUsedEvent,
)
from crewai.tasks.output_format import OutputFormat
-from crewai.telemetry.tracing import semantic_conventions
+from crewai.telemetry.tracing import gen_ai_shapes, semantic_conventions
from crewai.telemetry.tracing.context import (
PendingSpanEnd,
TelemetryExecutionContext,
@@ -589,9 +589,25 @@ def _task_output_format(task: Any, output: Any = None) -> str:
def _set_span_attributes(span: Span, attributes: dict[str, Any]) -> None:
+ """Set ``attributes`` on ``span``, no string value over the export bound.
+
+ The ``gen_ai.*`` content attributes arrive already bounded (and marked),
+ message-aware, by ``semantic_conventions``; this catches every other
+ string — a task's ``crewai.task.output``, an MCP tool's ``crewai.mcp.tool_result``, a flow's
+ serialized state — with a plain cut (the head, up to the bound) so one
+ oversized value marks itself instead of making the whole span too large
+ for Wharf to accept, and is never reshaped as if it were a conversation.
+ """
for key, value in attributes.items():
- if value is not None:
- span.set_attribute(key, value)
+ if value is None:
+ continue
+ if isinstance(value, str) and f"{key}.truncated" not in attributes:
+ value, markers = gen_ai_shapes.truncate_plain(value, attr=key)
+ for marker, marker_value in markers.items():
+ span.set_attribute(marker, marker_value)
+ if value is None:
+ continue
+ span.set_attribute(key, value)
def _get_parent_context(
diff --git a/lib/crewai/tests/telemetry/test_grant_export_bounds.py b/lib/crewai/tests/telemetry/test_grant_export_bounds.py
index cf5b8411f..34db60d2b 100644
--- a/lib/crewai/tests/telemetry/test_grant_export_bounds.py
+++ b/lib/crewai/tests/telemetry/test_grant_export_bounds.py
@@ -113,17 +113,52 @@ def test_exact_body_limit_and_oversized_span_preserve_fitting_neighbors(
assert encode_spans([large]).ByteSize() == BODY_LIMIT + extra_bytes
spans = [make_span(0), large, make_span(2)]
- expected = SpanExportResult.FAILURE if extra_bytes else SpanExportResult.SUCCESS
- assert exporter.export(spans) == expected
+ # One byte over is no longer a dropped span: its largest attribute is cut,
+ # marked, and the span is sent with its neighbours.
+ assert exporter.export(spans) == SpanExportResult.SUCCESS
exported = [span for batch in exported_batches(delegate) for span in batch]
- assert exported == ([spans[0], spans[2]] if extra_bytes else spans)
+ assert [span.context.span_id for span in exported] == [1, 2, 3]
if extra_bytes:
+ fitted = exported[1]
+ assert fitted.attributes["gen_ai.input.messages.truncated"] is True
+ assert fitted.attributes[
+ "gen_ai.input.messages.original_size_bytes"
+ ] == BODY_LIMIT - overhead + extra_bytes
+ assert encode_spans([fitted]).ByteSize() <= BODY_LIMIT
assert "3072001" in caplog.text and "3072000" in caplog.text
assert "synthetic-grant" not in caplog.text
+ else:
+ assert exported == spans
client.create.assert_not_called()
+def test_a_span_with_many_large_attributes_is_shrunk_not_dropped(
+ destination, caplog
+):
+ """Each attribute fits its own bound, the span does not fit a request: the
+ largest are cut, each marked, until it fits; nothing else changes."""
+ exporter, _, delegate = destination
+ attributes = {f"crewai.part.{i}": f"{i}" * 390_000 for i in range(9)}
+ attributes["crewai.task.name"] = "summary"
+ span = make_span(0, attributes=attributes)
+ assert encode_spans([span]).ByteSize() > BODY_LIMIT
+
+ assert exporter.export([span]) == SpanExportResult.SUCCESS
+
+ (fitted,) = [s for batch in exported_batches(delegate) for s in batch]
+ assert fitted.context == span.context and fitted.name == span.name
+ assert fitted.attributes["crewai.task.name"] == "summary"
+ cut = [k for k in attributes if fitted.attributes.get(f"{k}.truncated")]
+ assert cut
+ for key in cut:
+ assert fitted.attributes[f"{key}.original_size_bytes"] == 390_000
+ assert attributes[key].startswith(fitted.attributes[key])
+ for key in set(attributes) - set(cut):
+ assert fitted.attributes[key] == attributes[key]
+ assert "were cut" in caplog.text
+
+
def test_oversized_metadata_returns_failure_without_sending(destination, caplog):
exporter, _, delegate = destination
span = make_span(
diff --git a/lib/crewai/tests/telemetry/test_span_attribute_bound.py b/lib/crewai/tests/telemetry/test_span_attribute_bound.py
new file mode 100644
index 000000000..5c042c62c
--- /dev/null
+++ b/lib/crewai/tests/telemetry/test_span_attribute_bound.py
@@ -0,0 +1,403 @@
+"""What a run produced reaches the exported span whole, up to one stated bound.
+
+A graded run of a flow could not be judged because the span carried a cut copy
+of a tool's result: a summary task had to report "the issue count and
+source_issue_ids exactly match the Linear results", and the grader saw 4 KB of
+a 33 KB result. Tool results, task outputs and LLM messages are what a reader
+of the trace checks the run against, so they now arrive whole up to
+``DEFAULT_MAX_ATTR_BYTES`` (sized to Wharf's request limit), and a value over
+it is cut as little as possible and says so — never silently.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+
+from crewai import Agent, Crew, Task
+from crewai.events.types.task_events import TaskCompletedEvent, TaskStartedEvent
+from crewai.events.types.tool_usage_events import (
+ ToolUsageFinishedEvent,
+ ToolUsageStartedEvent,
+)
+from crewai.tasks.task_output import TaskOutput
+from crewai.telemetry.tracing import gen_ai_shapes, handlers, semantic_conventions
+from crewai.telemetry.tracing.context import TelemetryExecutionContext
+from crewai.telemetry.tracing.grants import MAX_EXPORT_BODY_BYTES
+from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+import pytest
+
+
+BOUND = gen_ai_shapes.DEFAULT_MAX_ATTR_BYTES
+
+
+def _text(size: int, label: str = "issue") -> str:
+ """Non-repeating text of about ``size`` bytes: a cut copy cannot compare equal."""
+ lines: list[str] = []
+ total = 0
+ i = 0
+ while total < size:
+ line = f'{{"id": "{label}-{i}", "title": "Linear issue number {i}"}}\n'
+ lines.append(line)
+ total += len(line)
+ i += 1
+ return "".join(lines)
+
+
[email protected](autouse=True)
+def enable_otel_sdk(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The suite otherwise runs with OTEL_SDK_DISABLED, which makes every
+ assertion here pass vacuously against non-recording spans."""
+ for name in (
+ "OTEL_SDK_DISABLED",
+ "CREWAI_DISABLE_TELEMETRY",
+ "CREWAI_DISABLE_TRACKING",
+ "CREWAI_OTEL_MAX_ATTR_BYTES",
+ "OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT",
+ "OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT",
+ ):
+ monkeypatch.delenv(name, raising=False)
+
+
+class _Providers:
+ def __init__(self, tracer) -> None:
+ self._tracer = tracer
+
+ def get_tracer(self, name: str | None = None):
+ return self._tracer
+
+ def emit_log(self, *args, **kwargs) -> None:
+ pass
+
+
+def _pipeline():
+ """Built inside each test, after any env change: the SDK reads its span
+ limits when the provider is constructed."""
+ exporter = InMemorySpanExporter()
+ provider = TracerProvider()
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
+ tracer = provider.get_tracer("test")
+ ctx = TelemetryExecutionContext(
+ kickoff_id="kickoff", automation_name="test", tracer=tracer
+ )
+ return provider, _Providers(tracer), ctx, exporter
+
+
+def _only_span(exporter: InMemorySpanExporter, name: str):
+ matches = [s for s in exporter.get_finished_spans() if s.name == name]
+ assert len(matches) == 1, [s.name for s in exporter.get_finished_spans()]
+ return matches[0]
+
+
+def _tool_span(result: str):
+ provider, providers, ctx, exporter = _pipeline()
+ now = datetime.now(timezone.utc)
+ args = {"query": "issues in cycle 42"}
+ started = ToolUsageStartedEvent(
+ tool_name="linear_run_query", tool_args=args, agent_key="k", agent_role="r"
+ )
+ handlers.handle_tool_usage_started(providers, ctx, None, started)
+ handlers.handle_tool_usage_finished(
+ providers,
+ ctx,
+ None,
+ ToolUsageFinishedEvent(
+ tool_name="linear_run_query",
+ tool_args=args,
+ agent_key="k",
+ agent_role="r",
+ started_at=now,
+ finished_at=now,
+ output=result,
+ started_event_id=started.event_id,
+ ),
+ )
+ span = _only_span(exporter, "call tool")
+ provider.shutdown()
+ return span
+
+
[email protected]("size", [50_000, 300_000], ids=["50KB", "300KB"])
+def test_a_tool_result_arrives_whole(size: int) -> None:
+ result = _text(size)
+
+ span = _tool_span(result)
+
+ assert json.loads(span.attributes["gen_ai.tool.call.result"]) == result
+ assert "gen_ai.tool.call.result.truncated" not in span.attributes
+
+
+def test_a_tool_result_over_the_bound_is_cut_with_the_marker_and_its_size() -> None:
+ result = _text(BOUND + 200_000)
+ original = len(json.dumps(result).encode("utf-8"))
+
+ span = _tool_span(result)
+
+ payload = span.attributes["gen_ai.tool.call.result"]
+ assert span.attributes["gen_ai.tool.call.result.truncated"] is True
+ assert span.attributes["gen_ai.tool.call.result.original_size_bytes"] == original
+ assert len(payload.encode("utf-8")) <= BOUND
+ envelope = json.loads(payload)
+ assert envelope["_truncated"] is True
+ assert envelope["_original_size_bytes"] == original
+ # Cut as little as possible: the preview fills the bound, it is not a
+ # 4 KB sample of a value that was barely over it.
+ assert len(payload.encode("utf-8")) > BOUND * 0.99
+ assert json.dumps(result).startswith(envelope["_preview"])
+
+
+def _task_span(raw: str):
+ provider, providers, ctx, exporter = _pipeline()
+ agent = Agent(role="Analyst", goal="g", backstory="b")
+ task = Task(description="d", expected_output="e", agent=agent)
+ agent.crew = Crew(agents=[agent], tasks=[task])
+ started = TaskStartedEvent(context=None, task=task)
+ handlers.handle_task_started(providers, ctx, task, started)
+ handlers.handle_task_completed(
+ providers,
+ ctx,
+ task,
+ TaskCompletedEvent(
+ output=TaskOutput(description="d", raw=raw, agent="Analyst"),
+ task=task,
+ started_event_id=started.event_id,
+ ),
+ )
+ span = _only_span(exporter, "execute task")
+ provider.shutdown()
+ return span
+
+
+def test_a_task_output_arrives_whole_under_both_keys() -> None:
+ raw = _text(300_000, label="summary")
+
+ span = _task_span(raw)
+
+ assert span.attributes["crewai.task.output"] == raw
+ assert "crewai.task.output.truncated" not in span.attributes
+ messages = json.loads(span.attributes["gen_ai.output.messages"])
+ assert messages[0]["parts"][0]["content"] == raw
+ assert "gen_ai.output.messages.truncated" not in span.attributes
+
+
+def test_a_plain_attribute_over_the_bound_marks_itself_too() -> None:
+ """``crewai.task.output`` used to have no bound at all: one huge output made
+ the whole span too large for Wharf, which then never stored it."""
+ raw = _text(BOUND + 50_000, label="summary")
+
+ span = _task_span(raw)
+
+ assert span.attributes["crewai.task.output.truncated"] is True
+ assert span.attributes["crewai.task.output.original_size_bytes"] == len(
+ raw.encode("utf-8")
+ )
+ assert len(span.attributes["crewai.task.output"].encode("utf-8")) <= BOUND
+ assert span.attributes["gen_ai.output.messages.truncated"] is True
+
+
+def test_llm_messages_and_response_arrive_whole() -> None:
+ tool_result = _text(300_000)
+ messages = [
+ {"role": "system", "content": "You are an analyst."},
+ {"role": "user", "content": "Summarise the cycle."},
+ {"role": "tool", "content": tool_result},
+ ]
+ answer = _text(100_000, label="answer")
+
+ attrs = semantic_conventions.gen_ai(
+ input_messages=messages, output_messages=answer
+ )
+
+ shaped = json.loads(attrs["gen_ai.input.messages"])
+ assert shaped[-1]["parts"][0]["content"] == tool_result
+ assert json.loads(attrs["gen_ai.output.messages"])[0]["parts"][0][
+ "content"
+ ] == answer
+ assert not any(key.endswith(".truncated") for key in attrs)
+
+
+def test_a_conversation_over_the_bound_keeps_its_ends_and_names_the_cut() -> None:
+ """The repeated conversation on an LLM call is where a large tool result
+ would otherwise be copied into every later call: past the bound its middle
+ is replaced by a placeholder; the tool span keeps the result whole."""
+ messages = [{"role": "system", "content": "You are an analyst."}]
+ messages += [{"role": "tool", "content": _text(200_000, f"r{i}")} for i in range(3)]
+ messages.append({"role": "user", "content": "Now write the summary."})
+
+ attrs = semantic_conventions.gen_ai(input_messages=messages)
+
+ payload = attrs["gen_ai.input.messages"]
+ assert attrs["gen_ai.input.messages.truncated"] is True
+ assert len(payload.encode("utf-8")) <= BOUND
+ shaped = json.loads(payload)
+ assert shaped[0]["parts"][0]["content"] == "You are an analyst."
+ assert shaped[-1]["parts"][0]["content"] == "Now write the summary."
+ assert "[truncated 3 messages" in shaped[1]["parts"][0]["content"]
+
+
+def test_one_cut_message_keeps_all_but_the_overshoot() -> None:
+ """A single message over the bound loses what is over, not half of itself."""
+ content = _text(BOUND + 20_000)
+
+ attrs = semantic_conventions.gen_ai(output_messages=content)
+
+ payload = attrs["gen_ai.output.messages"]
+ assert attrs["gen_ai.output.messages.truncated"] is True
+ assert len(payload.encode("utf-8")) <= BOUND
+ kept = json.loads(payload)[0]["parts"][0]["content"]
+ assert "...[truncated " in kept
+ assert len(payload.encode("utf-8")) > BOUND * 0.99
+
+
+def test_an_sdk_length_limit_lowers_the_bound_so_the_sdk_never_cuts(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The OpenTelemetry SDK cuts a value over its limit with no marker. A user
+ who set that limit gets it, but cut by crewAI, which says so."""
+ limit = 20_000
+ monkeypatch.setenv("OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT", str(limit))
+ assert gen_ai_shapes.max_attr_bytes() == limit
+
+ span = _tool_span(_text(50_000))
+
+ payload = span.attributes["gen_ai.tool.call.result"]
+ assert span.attributes["gen_ai.tool.call.result.truncated"] is True
+ assert len(payload) <= limit
+ # Still valid JSON: crewAI's envelope, not a string the SDK chopped.
+ assert json.loads(payload)["_truncated"] is True
+
+
+def test_the_span_limit_wins_over_the_general_one(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setenv("OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT", "10000")
+ monkeypatch.setenv("OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT", "30000")
+ assert gen_ai_shapes.max_attr_bytes() == 30_000
+ monkeypatch.setenv("CREWAI_OTEL_MAX_ATTR_BYTES", "5000")
+ assert gen_ai_shapes.max_attr_bytes() == 5_000
+
+
+def test_a_lower_crewai_setting_is_honoured(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setenv("CREWAI_OTEL_MAX_ATTR_BYTES", "65536")
+ assert gen_ai_shapes.max_attr_bytes() == 65_536
+ monkeypatch.setenv("CREWAI_OTEL_MAX_ATTR_BYTES", "not a number")
+ assert gen_ai_shapes.max_attr_bytes() == BOUND
+
+
+def test_a_higher_crewai_setting_is_clamped_to_the_ceiling_with_one_warning(
+ monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+ """Above the ceiling, several bounded attributes would not fit one Wharf
+ request; the setting is clamped, said once, never silently raised."""
+ gen_ai_shapes._warn_clamped.cache_clear()
+ monkeypatch.setenv("CREWAI_OTEL_MAX_ATTR_BYTES", "1048576")
+
+ with caplog.at_level("WARNING", logger=gen_ai_shapes.__name__):
+ assert gen_ai_shapes.max_attr_bytes() == BOUND
+ assert gen_ai_shapes.max_attr_bytes() == BOUND
+
+ warnings = [r for r in caplog.records if "CREWAI_OTEL_MAX_ATTR_BYTES" in r.message]
+ assert len(warnings) == 1
+ assert "1048576" in warnings[0].message and str(BOUND) in warnings[0].message
+ assert "3,072,000" in warnings[0].message
+
+
+def test_an_sdk_limit_above_the_ceiling_does_not_raise_the_bound(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setenv("OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT", "2000000")
+ assert gen_ai_shapes.max_attr_bytes() == BOUND
+
+
+def test_a_span_with_every_content_attribute_at_the_bound_fits_one_wharf_request() -> (
+ None
+):
+ """Wharf refuses a request over 3,072,000 encoded bytes and the exporter
+ drops a span that alone is over it. An LLM call carries the most content
+ attributes, so seven of them at the bound must still fit."""
+ provider, providers, ctx, exporter = _pipeline()
+ span = providers.get_tracer().start_span("call llm")
+ big = _text(BOUND * 2)
+ handlers._set_span_attributes(
+ span,
+ {
+ **semantic_conventions.gen_ai(
+ input_messages=[{"role": "user", "content": big}],
+ output_messages=big,
+ system_instructions=big,
+ tool_definitions=[{"name": "t", "description": big}],
+ ),
+ "crewai.a": big,
+ "crewai.b": big,
+ "crewai.c": big,
+ },
+ )
+ span.end()
+ finished = exporter.get_finished_spans()
+ provider.shutdown()
+
+ assert sum(1 for key in finished[0].attributes if key.endswith(".truncated")) == 7
+ assert encode_spans(finished).ByteSize() < MAX_EXPORT_BODY_BYTES
+
+
+def test_a_role_bearing_plain_attribute_is_cut_plainly_never_reshaped() -> None:
+ """A task may produce a JSON list whose items carry ``role`` (a roster, a
+ chat log). On ``crewai.task.output`` that is data, not a GenAI
+ conversation: over the bound it keeps its head, nothing is replaced."""
+ roster = json.dumps(
+ [
+ {"role": "engineer", "name": f"person-{i}", "team": f"team-{i % 7}"}
+ for i in range(12_000)
+ ]
+ )
+ assert len(roster.encode("utf-8")) > BOUND
+
+ span = _task_span(roster)
+
+ kept = span.attributes["crewai.task.output"]
+ assert span.attributes["crewai.task.output.truncated"] is True
+ assert span.attributes["crewai.task.output.original_size_bytes"] == len(
+ roster.encode("utf-8")
+ )
+ assert len(kept.encode("utf-8")) == BOUND
+ assert roster.startswith(kept)
+ assert "truncated" not in kept
+
+
+def test_an_sdk_span_limit_of_zero_is_kept_and_cuts_everything_with_the_marker(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The SDK accepts 0 and cuts every string to nothing; crewAI does the
+ same cut first, so it carries the marker."""
+ monkeypatch.setenv("OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT", "0")
+ monkeypatch.setenv("OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT", "20000")
+ assert gen_ai_shapes.max_attr_bytes() == 0
+
+ span = _task_span("a summary")
+
+ assert span.attributes["crewai.task.output"] == ""
+ assert span.attributes["crewai.task.output.truncated"] is True
+ assert span.attributes["crewai.task.output.original_size_bytes"] == len(
+ "a summary"
+ )
+
+
+def test_an_explicitly_empty_span_limit_is_unlimited_not_the_general_limit(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """In the SDK an empty span setting means unlimited and wins over the
+ general one; the bound is then crewAI's own."""
+ monkeypatch.setenv("OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT", "")
+ monkeypatch.setenv("OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT", "20000")
+ assert gen_ai_shapes.max_attr_bytes() == BOUND
+
+ result = _text(50_000)
+ span = _tool_span(result)
+
+ assert json.loads(span.attributes["gen_ai.tool.call.result"]) == result
+ assert "gen_ai.tool.call.result.truncated" not in span.attributes
diff --git a/lib/crewai/tests/telemetry/test_span_task_agent_tool_attributes.py b/lib/crewai/tests/telemetry/test_span_task_agent_tool_attributes.py
index 14ef8da7b..4665ffa5d 100644
--- a/lib/crewai/tests/telemetry/test_span_task_agent_tool_attributes.py
+++ b/lib/crewai/tests/telemetry/test_span_task_agent_tool_attributes.py
@@ -39,7 +39,7 @@ import pytest
# Long and non-repeating, so a truncated or elided copy cannot compare equal.
-# Under the default 32 KiB attribute cap, so it must arrive whole.
+# Under the default attribute bound, so it must arrive whole.
LONG_TEXT = "".join(
f"paragraph {i}: the quick brown fox jumps over the lazy dog\n" for i in range(400)
)