feat: add log span kind (agentops.log) for arbitrary trace logging

agentops/__init__.py

@@ -27,6 +27,7 @@
 from agentops.client import Client
 from agentops.sdk.core import TraceContext, tracer
 from agentops.sdk.decorators import trace, session, agent, task, workflow, operation, tool, guardrail, track_endpoint
+from agentops.sdk.decorators.log import log
 from agentops.enums import TraceState, SUCCESS, ERROR, UNSET
 from opentelemetry.trace.status import StatusCode
 
@@ -485,4 +486,6 @@ def extract_key_from_attr(attr_value: str) -> str:
     "validate_trace_spans",
     "print_validation_summary",
     "ValidationError",
+    # Log function
+    "log",
 ]

agentops/sdk/decorators/log.py

@@ -0,0 +1,60 @@
+"""
+Standalone log() function for creating log-style spans in traces.
+
+Provides `log(name, message, level)` to record arbitrary log entries
+as spans with kind="log" for observability and debugging.
+"""
+
+from typing import Optional
+
+from agentops.logging import logger
+from agentops.sdk.core import tracer
+from agentops.semconv.span_kinds import AgentOpsSpanKindValues
+from agentops.semconv.span_attributes import SpanAttributes
+
+
+LOG_LEVELS = {"DEFAULT", "WARNING", "ERROR"}
+
+
+def log(
+    name: str,
+    message: str,
+    level: str = "DEFAULT",
+) -> None:
+    """
+    Create a standalone log-style span with the given name, message, and level.
+
+    This function is designed for ad-hoc logging within traces — e.g., recording
+    when a tool call limit is reached, when a decision boundary is crossed, or
+    any other noteworthy point during execution.
+
+    Args:
+        name: Short identifier for the log entry (e.g. "xml_tool_call_limit_reached").
+        message: Human-readable description of the log event.
+        level: Severity level. One of "DEFAULT", "WARNING", or "ERROR".
+               Defaults to "DEFAULT".
+    """
+    # Validate level
+    if level not in LOG_LEVELS:
+        logger.warning(f"Invalid log level '{level}'. Falling back to 'DEFAULT'.")
+        level = "DEFAULT"
+
+    if not tracer.initialized:
+        logger.warning("AgentOps SDK not initialized. Cannot create log span.")
+        return
+
+    try:
+        span, ctx, token = tracer.make_span(
+            name,
+            AgentOpsSpanKindValues.LOG.value,
+            attributes={
+                SpanAttributes.AGENTOPS_SPAN_KIND: AgentOpsSpanKindValues.LOG.value,
+                SpanAttributes.LOG_MESSAGE: message,
+                SpanAttributes.LOG_LEVEL: level,
+            },
+        )
+        span.set_attribute(SpanAttributes.LOG_MESSAGE, message)
+        span.set_attribute(SpanAttributes.LOG_LEVEL, level)
+        tracer.finalize_span(span, token)
+    except Exception as e:
+        logger.error(f"Failed to create log span: {e}")

agentops/semconv/span_attributes.py

@@ -116,3 +116,7 @@ class SpanAttributes:
     HTTP_RESPONSE_BODY = "http.response.body"
     HTTP_USER_AGENT = "http.user_agent"
     HTTP_REQUEST_ID = "http.request_id"
+
+    # Log-specific attributes
+    LOG_MESSAGE = "agentops.log.message"
+    LOG_LEVEL = "agentops.log.level"

agentops/semconv/span_kinds.py

@@ -17,6 +17,7 @@ class AgentOpsSpanKindValues(Enum):
     TEXT = "text"
     GUARDRAIL = "guardrail"
     HTTP = "http"
+    LOG = "log"
     UNKNOWN = "unknown"