agno 2.3.4__py3-none-any.whl → 2.3.5__py3-none-any.whl

agno/db/dynamo/dynamo.py

@@ -2,7 +2,10 @@ import json
 import time
 from datetime import date, datetime, timedelta, timezone
 from os import getenv
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+if TYPE_CHECKING:
+    from agno.tracing.schemas import Span, Trace
 
 from agno.db.base import BaseDb, SessionType
 from agno.db.dynamo.schemas import get_table_schema_definition
@@ -60,6 +63,8 @@ class DynamoDb(BaseDb):
         metrics_table: Optional[str] = None,
         eval_table: Optional[str] = None,
         knowledge_table: Optional[str] = None,
+        traces_table: Optional[str] = None,
+        spans_table: Optional[str] = None,
         id: Optional[str] = None,
     ):
         """
@@ -76,6 +81,8 @@ class DynamoDb(BaseDb):
             metrics_table: The name of the metrics table.
             eval_table: The name of the eval table.
             knowledge_table: The name of the knowledge table.
+            traces_table: The name of the traces table.
+            spans_table: The name of the spans table.
             id: ID of the database.
         """
         if id is None:
@@ -90,6 +97,8 @@ class DynamoDb(BaseDb):
             metrics_table=metrics_table,
             eval_table=eval_table,
             knowledge_table=knowledge_table,
+            traces_table=traces_table,
+            spans_table=spans_table,
         )
 
         if db_client is not None:
@@ -149,7 +158,7 @@ class DynamoDb(BaseDb):
         Get table name and ensure the table exists, creating it if needed.
 
         Args:
-            table_type: Type of table ("sessions", "memories", "metrics", "evals", "knowledge_sources")
+            table_type: Type of table ("sessions", "memories", "metrics", "evals", "knowledge", "culture", "traces", "spans")
 
         Returns:
             str: The table name
@@ -171,6 +180,12 @@ class DynamoDb(BaseDb):
             table_name = self.knowledge_table_name
         elif table_type == "culture":
             table_name = self.culture_table_name
+        elif table_type == "traces":
+            table_name = self.trace_table_name
+        elif table_type == "spans":
+            # Ensure traces table exists first (spans reference traces)
+            self._get_table("traces", create_table_if_not_found=True)
+            table_name = self.span_table_name
         else:
             raise ValueError(f"Unknown table type: {table_type}")
 
@@ -2059,3 +2074,708 @@ class DynamoDb(BaseDb):
         except Exception as e:
             log_error(f"Failed to upsert cultural knowledge: {e}")
             raise e
+
+    # --- Traces ---
+    def create_trace(self, trace: "Trace") -> None:
+        """Create a single trace record in the database.
+
+        Args:
+            trace: The Trace object to store (one per trace_id).
+        """
+        try:
+            table_name = self._get_table("traces", create_table_if_not_found=True)
+            if table_name is None:
+                return
+
+            # Check if trace already exists
+            response = self.client.get_item(
+                TableName=table_name,
+                Key={"trace_id": {"S": trace.trace_id}},
+            )
+
+            existing_item = response.get("Item")
+            if existing_item:
+                # Update existing trace
+                existing = deserialize_from_dynamodb_item(existing_item)
+
+                # Determine component level for name update priority
+                def get_component_level(workflow_id, team_id, agent_id, name):
+                    is_root_name = ".run" in name or ".arun" in name
+                    if not is_root_name:
+                        return 0
+                    elif workflow_id:
+                        return 3
+                    elif team_id:
+                        return 2
+                    elif agent_id:
+                        return 1
+                    else:
+                        return 0
+
+                existing_level = get_component_level(
+                    existing.get("workflow_id"),
+                    existing.get("team_id"),
+                    existing.get("agent_id"),
+                    existing.get("name", ""),
+                )
+                new_level = get_component_level(trace.workflow_id, trace.team_id, trace.agent_id, trace.name)
+                should_update_name = new_level > existing_level
+
+                # Parse existing start_time to calculate correct duration
+                existing_start_time_str = existing.get("start_time")
+                if isinstance(existing_start_time_str, str):
+                    existing_start_time = datetime.fromisoformat(existing_start_time_str.replace("Z", "+00:00"))
+                else:
+                    existing_start_time = trace.start_time
+
+                recalculated_duration_ms = int((trace.end_time - existing_start_time).total_seconds() * 1000)
+
+                # Build update expression
+                update_parts = [
+                    "end_time = :end_time",
+                    "duration_ms = :duration_ms",
+                    "#status = :status",
+                ]
+                expression_attr_names = {"#status": "status"}
+                expression_attr_values: Dict[str, Any] = {
+                    ":end_time": {"S": trace.end_time.isoformat()},
+                    ":duration_ms": {"N": str(recalculated_duration_ms)},
+                    ":status": {"S": trace.status},
+                }
+
+                if should_update_name:
+                    update_parts.append("#name = :name")
+                    expression_attr_names["#name"] = "name"
+                    expression_attr_values[":name"] = {"S": trace.name}
+
+                if trace.run_id is not None:
+                    update_parts.append("run_id = :run_id")
+                    expression_attr_values[":run_id"] = {"S": trace.run_id}
+                if trace.session_id is not None:
+                    update_parts.append("session_id = :session_id")
+                    expression_attr_values[":session_id"] = {"S": trace.session_id}
+                if trace.user_id is not None:
+                    update_parts.append("user_id = :user_id")
+                    expression_attr_values[":user_id"] = {"S": trace.user_id}
+                if trace.agent_id is not None:
+                    update_parts.append("agent_id = :agent_id")
+                    expression_attr_values[":agent_id"] = {"S": trace.agent_id}
+                if trace.team_id is not None:
+                    update_parts.append("team_id = :team_id")
+                    expression_attr_values[":team_id"] = {"S": trace.team_id}
+                if trace.workflow_id is not None:
+                    update_parts.append("workflow_id = :workflow_id")
+                    expression_attr_values[":workflow_id"] = {"S": trace.workflow_id}
+
+                self.client.update_item(
+                    TableName=table_name,
+                    Key={"trace_id": {"S": trace.trace_id}},
+                    UpdateExpression="SET " + ", ".join(update_parts),
+                    ExpressionAttributeNames=expression_attr_names,
+                    ExpressionAttributeValues=expression_attr_values,
+                )
+            else:
+                # Create new trace with initialized counters
+                trace_dict = trace.to_dict()
+                trace_dict["total_spans"] = 0
+                trace_dict["error_count"] = 0
+                item = serialize_to_dynamo_item(trace_dict)
+                self.client.put_item(TableName=table_name, Item=item)
+
+        except Exception as e:
+            log_error(f"Error creating trace: {e}")
+
+    def get_trace(
+        self,
+        trace_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+    ):
+        """Get a single trace by trace_id or other filters.
+
+        Args:
+            trace_id: The unique trace identifier.
+            run_id: Filter by run ID (returns first match).
+
+        Returns:
+            Optional[Trace]: The trace if found, None otherwise.
+
+        Note:
+            If multiple filters are provided, trace_id takes precedence.
+            For other filters, the most recent trace is returned.
+        """
+        try:
+            from agno.tracing.schemas import Trace
+
+            table_name = self._get_table("traces")
+            if table_name is None:
+                return None
+
+            if trace_id:
+                # Direct lookup by primary key
+                response = self.client.get_item(
+                    TableName=table_name,
+                    Key={"trace_id": {"S": trace_id}},
+                )
+                item = response.get("Item")
+                if item:
+                    trace_data = deserialize_from_dynamodb_item(item)
+                    trace_data.setdefault("total_spans", 0)
+                    trace_data.setdefault("error_count", 0)
+                    return Trace.from_dict(trace_data)
+                return None
+
+            elif run_id:
+                # Query using GSI
+                response = self.client.query(
+                    TableName=table_name,
+                    IndexName="run_id-start_time-index",
+                    KeyConditionExpression="run_id = :run_id",
+                    ExpressionAttributeValues={":run_id": {"S": run_id}},
+                    ScanIndexForward=False,  # Descending order
+                    Limit=1,
+                )
+                items = response.get("Items", [])
+                if items:
+                    trace_data = deserialize_from_dynamodb_item(items[0])
+                    # Use stored values (default to 0 if not present)
+                    trace_data.setdefault("total_spans", 0)
+                    trace_data.setdefault("error_count", 0)
+                    return Trace.from_dict(trace_data)
+                return None
+
+            else:
+                log_debug("get_trace called without any filter parameters")
+                return None
+
+        except Exception as e:
+            log_error(f"Error getting trace: {e}")
+            return None
+
+    def get_traces(
+        self,
+        run_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        status: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: Optional[int] = 20,
+        page: Optional[int] = 1,
+    ) -> tuple[List, int]:
+        """Get traces matching the provided filters.
+
+        Args:
+            run_id: Filter by run ID.
+            session_id: Filter by session ID.
+            user_id: Filter by user ID.
+            agent_id: Filter by agent ID.
+            team_id: Filter by team ID.
+            workflow_id: Filter by workflow ID.
+            status: Filter by status (OK, ERROR, UNSET).
+            start_time: Filter traces starting after this datetime.
+            end_time: Filter traces ending before this datetime.
+            limit: Maximum number of traces to return per page.
+            page: Page number (1-indexed).
+
+        Returns:
+            tuple[List[Trace], int]: Tuple of (list of matching traces, total count).
+        """
+        try:
+            from agno.tracing.schemas import Trace
+
+            table_name = self._get_table("traces")
+            if table_name is None:
+                return [], 0
+
+            # Determine if we can use a GSI query or need to scan
+            use_gsi = False
+            gsi_name = None
+            key_condition = None
+            key_values: Dict[str, Any] = {}
+
+            # Check for GSI-compatible filters (only one can be used as key condition)
+            if session_id:
+                use_gsi = True
+                gsi_name = "session_id-start_time-index"
+                key_condition = "session_id = :session_id"
+                key_values[":session_id"] = {"S": session_id}
+            elif user_id:
+                use_gsi = True
+                gsi_name = "user_id-start_time-index"
+                key_condition = "user_id = :user_id"
+                key_values[":user_id"] = {"S": user_id}
+            elif agent_id:
+                use_gsi = True
+                gsi_name = "agent_id-start_time-index"
+                key_condition = "agent_id = :agent_id"
+                key_values[":agent_id"] = {"S": agent_id}
+            elif team_id:
+                use_gsi = True
+                gsi_name = "team_id-start_time-index"
+                key_condition = "team_id = :team_id"
+                key_values[":team_id"] = {"S": team_id}
+            elif workflow_id:
+                use_gsi = True
+                gsi_name = "workflow_id-start_time-index"
+                key_condition = "workflow_id = :workflow_id"
+                key_values[":workflow_id"] = {"S": workflow_id}
+            elif run_id:
+                use_gsi = True
+                gsi_name = "run_id-start_time-index"
+                key_condition = "run_id = :run_id"
+                key_values[":run_id"] = {"S": run_id}
+            elif status:
+                use_gsi = True
+                gsi_name = "status-start_time-index"
+                key_condition = "#status = :status"
+                key_values[":status"] = {"S": status}
+
+            # Build filter expression for additional filters
+            filter_parts = []
+            filter_values: Dict[str, Any] = {}
+            expression_attr_names: Dict[str, str] = {}
+
+            if start_time:
+                filter_parts.append("start_time >= :start_time")
+                filter_values[":start_time"] = {"S": start_time.isoformat()}
+            if end_time:
+                filter_parts.append("end_time <= :end_time")
+                filter_values[":end_time"] = {"S": end_time.isoformat()}
+
+            if status and gsi_name != "status-start_time-index":
+                filter_parts.append("#status = :filter_status")
+                filter_values[":filter_status"] = {"S": status}
+                expression_attr_names["#status"] = "status"
+
+            items = []
+            if use_gsi and gsi_name and key_condition:
+                # Use GSI query
+                query_kwargs: Dict[str, Any] = {
+                    "TableName": table_name,
+                    "IndexName": gsi_name,
+                    "KeyConditionExpression": key_condition,
+                    "ExpressionAttributeValues": {**key_values, **filter_values},
+                    "ScanIndexForward": False,  # Descending order by start_time
+                }
+                if gsi_name == "status-start_time-index":
+                    expression_attr_names["#status"] = "status"
+                if expression_attr_names:
+                    query_kwargs["ExpressionAttributeNames"] = expression_attr_names
+                if filter_parts:
+                    query_kwargs["FilterExpression"] = " AND ".join(filter_parts)
+
+                response = self.client.query(**query_kwargs)
+                items.extend(response.get("Items", []))
+
+                while "LastEvaluatedKey" in response:
+                    query_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                    response = self.client.query(**query_kwargs)
+                    items.extend(response.get("Items", []))
+            else:
+                # Use scan
+                scan_kwargs: Dict[str, Any] = {"TableName": table_name}
+                if filter_parts:
+                    scan_kwargs["FilterExpression"] = " AND ".join(filter_parts)
+                    scan_kwargs["ExpressionAttributeValues"] = filter_values
+                if expression_attr_names:
+                    scan_kwargs["ExpressionAttributeNames"] = expression_attr_names
+
+                response = self.client.scan(**scan_kwargs)
+                items.extend(response.get("Items", []))
+
+                while "LastEvaluatedKey" in response:
+                    scan_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                    response = self.client.scan(**scan_kwargs)
+                    items.extend(response.get("Items", []))
+
+            # Deserialize items
+            traces_data = [deserialize_from_dynamodb_item(item) for item in items]
+
+            # Sort by start_time descending
+            traces_data.sort(key=lambda x: x.get("start_time", ""), reverse=True)
+
+            # Get total count
+            total_count = len(traces_data)
+
+            # Apply pagination
+            offset = (page - 1) * limit if page and limit else 0
+            paginated_data = traces_data[offset : offset + limit] if limit else traces_data
+
+            # Use stored total_spans and error_count (default to 0 if not present)
+            traces = []
+            for trace_data in paginated_data:
+                # Use stored values - these are updated by create_spans
+                trace_data.setdefault("total_spans", 0)
+                trace_data.setdefault("error_count", 0)
+                traces.append(Trace.from_dict(trace_data))
+
+            return traces, total_count
+
+        except Exception as e:
+            log_error(f"Error getting traces: {e}")
+            return [], 0
+
+    def get_trace_stats(
+        self,
+        user_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        team_id: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        start_time: Optional[datetime] = None,
+        end_time: Optional[datetime] = None,
+        limit: Optional[int] = 20,
+        page: Optional[int] = 1,
+    ) -> tuple[List[Dict[str, Any]], int]:
+        """Get trace statistics grouped by session.
+
+        Args:
+            user_id: Filter by user ID.
+            agent_id: Filter by agent ID.
+            team_id: Filter by team ID.
+            workflow_id: Filter by workflow ID.
+            start_time: Filter sessions with traces created after this datetime.
+            end_time: Filter sessions with traces created before this datetime.
+            limit: Maximum number of sessions to return per page.
+            page: Page number (1-indexed).
+
+        Returns:
+            tuple[List[Dict], int]: Tuple of (list of session stats dicts, total count).
+                Each dict contains: session_id, user_id, agent_id, team_id, workflow_id, total_traces,
+                first_trace_at, last_trace_at.
+        """
+        try:
+            table_name = self._get_table("traces")
+            if table_name is None:
+                return [], 0
+
+            # Fetch all traces and aggregate in memory (DynamoDB doesn't support GROUP BY)
+            scan_kwargs: Dict[str, Any] = {"TableName": table_name}
+
+            # Build filter expression
+            filter_parts = []
+            filter_values: Dict[str, Any] = {}
+
+            if user_id:
+                filter_parts.append("user_id = :user_id")
+                filter_values[":user_id"] = {"S": user_id}
+            if agent_id:
+                filter_parts.append("agent_id = :agent_id")
+                filter_values[":agent_id"] = {"S": agent_id}
+            if team_id:
+                filter_parts.append("team_id = :team_id")
+                filter_values[":team_id"] = {"S": team_id}
+            if workflow_id:
+                filter_parts.append("workflow_id = :workflow_id")
+                filter_values[":workflow_id"] = {"S": workflow_id}
+            if start_time:
+                filter_parts.append("created_at >= :start_time")
+                filter_values[":start_time"] = {"S": start_time.isoformat()}
+            if end_time:
+                filter_parts.append("created_at <= :end_time")
+                filter_values[":end_time"] = {"S": end_time.isoformat()}
+
+            # Filter for records with session_id
+            filter_parts.append("attribute_exists(session_id)")
+
+            if filter_parts:
+                scan_kwargs["FilterExpression"] = " AND ".join(filter_parts)
+            if filter_values:
+                scan_kwargs["ExpressionAttributeValues"] = filter_values
+
+            # Scan all matching traces
+            items = []
+            response = self.client.scan(**scan_kwargs)
+            items.extend(response.get("Items", []))
+
+            while "LastEvaluatedKey" in response:
+                scan_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                response = self.client.scan(**scan_kwargs)
+                items.extend(response.get("Items", []))
+
+            # Aggregate by session_id
+            session_stats: Dict[str, Dict[str, Any]] = {}
+            for item in items:
+                trace_data = deserialize_from_dynamodb_item(item)
+                session_id = trace_data.get("session_id")
+                if not session_id:
+                    continue
+
+                if session_id not in session_stats:
+                    session_stats[session_id] = {
+                        "session_id": session_id,
+                        "user_id": trace_data.get("user_id"),
+                        "agent_id": trace_data.get("agent_id"),
+                        "team_id": trace_data.get("team_id"),
+                        "workflow_id": trace_data.get("workflow_id"),
+                        "total_traces": 0,
+                        "first_trace_at": trace_data.get("created_at"),
+                        "last_trace_at": trace_data.get("created_at"),
+                    }
+
+                session_stats[session_id]["total_traces"] += 1
+
+                created_at = trace_data.get("created_at")
+                if (
+                    created_at
+                    and session_stats[session_id]["first_trace_at"]
+                    and session_stats[session_id]["last_trace_at"]
+                ):
+                    if created_at < session_stats[session_id]["first_trace_at"]:
+                        session_stats[session_id]["first_trace_at"] = created_at
+                    if created_at > session_stats[session_id]["last_trace_at"]:
+                        session_stats[session_id]["last_trace_at"] = created_at
+
+            # Convert to list and sort by last_trace_at descending
+            stats_list = list(session_stats.values())
+            stats_list.sort(key=lambda x: x.get("last_trace_at", ""), reverse=True)
+
+            # Convert datetime strings to datetime objects
+            for stat in stats_list:
+                first_trace_at = stat["first_trace_at"]
+                last_trace_at = stat["last_trace_at"]
+                if isinstance(first_trace_at, str):
+                    stat["first_trace_at"] = datetime.fromisoformat(first_trace_at.replace("Z", "+00:00"))
+                if isinstance(last_trace_at, str):
+                    stat["last_trace_at"] = datetime.fromisoformat(last_trace_at.replace("Z", "+00:00"))
+
+            # Get total count
+            total_count = len(stats_list)
+
+            # Apply pagination
+            offset = (page - 1) * limit if page and limit else 0
+            paginated_stats = stats_list[offset : offset + limit] if limit else stats_list
+
+            return paginated_stats, total_count
+
+        except Exception as e:
+            log_error(f"Error getting trace stats: {e}")
+            return [], 0
+
+    # --- Spans ---
+    def create_span(self, span: "Span") -> None:
+        """Create a single span in the database.
+
+        Args:
+            span: The Span object to store.
+        """
+        try:
+            table_name = self._get_table("spans", create_table_if_not_found=True)
+            if table_name is None:
+                return
+
+            span_dict = span.to_dict()
+            # Serialize attributes as JSON string
+            if "attributes" in span_dict and isinstance(span_dict["attributes"], dict):
+                span_dict["attributes"] = json.dumps(span_dict["attributes"])
+
+            item = serialize_to_dynamo_item(span_dict)
+            self.client.put_item(TableName=table_name, Item=item)
+
+            # Increment total_spans and error_count on trace
+            traces_table_name = self._get_table("traces")
+            if traces_table_name:
+                try:
+                    update_expr = "ADD total_spans :inc"
+                    expr_values: Dict[str, Any] = {":inc": {"N": "1"}}
+
+                    if span.status_code == "ERROR":
+                        update_expr += ", error_count :inc"
+
+                    self.client.update_item(
+                        TableName=traces_table_name,
+                        Key={"trace_id": {"S": span.trace_id}},
+                        UpdateExpression=update_expr,
+                        ExpressionAttributeValues=expr_values,
+                    )
+                except Exception as update_error:
+                    log_debug(f"Could not update trace span counts: {update_error}")
+
+        except Exception as e:
+            log_error(f"Error creating span: {e}")
+
+    def create_spans(self, spans: List) -> None:
+        """Create multiple spans in the database as a batch.
+
+        Args:
+            spans: List of Span objects to store.
+        """
+        if not spans:
+            return
+
+        try:
+            table_name = self._get_table("spans", create_table_if_not_found=True)
+            if table_name is None:
+                return
+
+            for i in range(0, len(spans), DYNAMO_BATCH_SIZE_LIMIT):
+                batch = spans[i : i + DYNAMO_BATCH_SIZE_LIMIT]
+                put_requests = []
+
+                for span in batch:
+                    span_dict = span.to_dict()
+                    # Serialize attributes as JSON string
+                    if "attributes" in span_dict and isinstance(span_dict["attributes"], dict):
+                        span_dict["attributes"] = json.dumps(span_dict["attributes"])
+
+                    item = serialize_to_dynamo_item(span_dict)
+                    put_requests.append({"PutRequest": {"Item": item}})
+
+                if put_requests:
+                    self.client.batch_write_item(RequestItems={table_name: put_requests})
+
+            # Update trace with total_spans and error_count using ADD (atomic increment)
+            trace_id = spans[0].trace_id
+            spans_count = len(spans)
+            error_count = sum(1 for s in spans if s.status_code == "ERROR")
+
+            traces_table_name = self._get_table("traces")
+            if traces_table_name:
+                try:
+                    # Use ADD for atomic increment - works even if attributes don't exist yet
+                    update_expr = "ADD total_spans :spans_inc"
+                    expr_values: Dict[str, Any] = {":spans_inc": {"N": str(spans_count)}}
+
+                    if error_count > 0:
+                        update_expr += ", error_count :error_inc"
+                        expr_values[":error_inc"] = {"N": str(error_count)}
+
+                    self.client.update_item(
+                        TableName=traces_table_name,
+                        Key={"trace_id": {"S": trace_id}},
+                        UpdateExpression=update_expr,
+                        ExpressionAttributeValues=expr_values,
+                    )
+                except Exception as update_error:
+                    log_debug(f"Could not update trace span counts: {update_error}")
+
+        except Exception as e:
+            log_error(f"Error creating spans batch: {e}")
+
+    def get_span(self, span_id: str):
+        """Get a single span by its span_id.
+
+        Args:
+            span_id: The unique span identifier.
+
+        Returns:
+            Optional[Span]: The span if found, None otherwise.
+        """
+        try:
+            from agno.tracing.schemas import Span
+
+            table_name = self._get_table("spans")
+            if table_name is None:
+                return None
+
+            response = self.client.get_item(
+                TableName=table_name,
+                Key={"span_id": {"S": span_id}},
+            )
+
+            item = response.get("Item")
+            if item:
+                span_data = deserialize_from_dynamodb_item(item)
+                # Deserialize attributes from JSON string
+                if "attributes" in span_data and isinstance(span_data["attributes"], str):
+                    span_data["attributes"] = json.loads(span_data["attributes"])
+                return Span.from_dict(span_data)
+            return None
+
+        except Exception as e:
+            log_error(f"Error getting span: {e}")
+            return None
+
+    def get_spans(
+        self,
+        trace_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+        limit: Optional[int] = 1000,
+    ) -> List:
+        """Get spans matching the provided filters.
+
+        Args:
+            trace_id: Filter by trace ID.
+            parent_span_id: Filter by parent span ID.
+            limit: Maximum number of spans to return.
+
+        Returns:
+            List[Span]: List of matching spans.
+        """
+        try:
+            from agno.tracing.schemas import Span
+
+            table_name = self._get_table("spans")
+            if table_name is None:
+                return []
+
+            items = []
+
+            if trace_id:
+                # Use GSI query
+                query_kwargs: Dict[str, Any] = {
+                    "TableName": table_name,
+                    "IndexName": "trace_id-start_time-index",
+                    "KeyConditionExpression": "trace_id = :trace_id",
+                    "ExpressionAttributeValues": {":trace_id": {"S": trace_id}},
+                }
+                if limit:
+                    query_kwargs["Limit"] = limit
+
+                response = self.client.query(**query_kwargs)
+                items.extend(response.get("Items", []))
+
+                while "LastEvaluatedKey" in response and (limit is None or len(items) < limit):
+                    query_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                    response = self.client.query(**query_kwargs)
+                    items.extend(response.get("Items", []))
+
+            elif parent_span_id:
+                # Use GSI query
+                query_kwargs = {
+                    "TableName": table_name,
+                    "IndexName": "parent_span_id-start_time-index",
+                    "KeyConditionExpression": "parent_span_id = :parent_span_id",
+                    "ExpressionAttributeValues": {":parent_span_id": {"S": parent_span_id}},
+                }
+                if limit:
+                    query_kwargs["Limit"] = limit
+
+                response = self.client.query(**query_kwargs)
+                items.extend(response.get("Items", []))
+
+                while "LastEvaluatedKey" in response and (limit is None or len(items) < limit):
+                    query_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                    response = self.client.query(**query_kwargs)
+                    items.extend(response.get("Items", []))
+
+            else:
+                # Scan all spans
+                scan_kwargs: Dict[str, Any] = {"TableName": table_name}
+                if limit:
+                    scan_kwargs["Limit"] = limit
+
+                response = self.client.scan(**scan_kwargs)
+                items.extend(response.get("Items", []))
+
+                while "LastEvaluatedKey" in response and (limit is None or len(items) < limit):
+                    scan_kwargs["ExclusiveStartKey"] = response["LastEvaluatedKey"]
+                    response = self.client.scan(**scan_kwargs)
+                    items.extend(response.get("Items", []))
+
+            # Deserialize items
+            spans = []
+            for item in items[:limit] if limit else items:
+                span_data = deserialize_from_dynamodb_item(item)
+                # Deserialize attributes from JSON string
+                if "attributes" in span_data and isinstance(span_data["attributes"], str):
+                    span_data["attributes"] = json.loads(span_data["attributes"])
+                spans.append(Span.from_dict(span_data))
+
+            return spans
+
+        except Exception as e:
+            log_error(f"Error getting spans: {e}")
+            return []