fix(llmobs): swallow LLMObsAnnotateSpanError on auto-annotation in @llm decorator (#17093)

## Summary

- Fixes a regression introduced in #16892 where the `@llm` decorator raised `LLMObsAnnotateSpanError: Failed to parse output messages` when a decorated function returned a value that couldn't be parsed as LLM messages (e.g. a plain string, integer, or non-messages dict).
- The decorator now catches `LLMObsAnnotateSpanError` from auto-annotation, logs a warning, and continues — the user's function still succeeds and the span is still created.
- Also adds the missing `operation_kind != "embedding"` guard from the 4.6 backport branch to `main`.

## Test plan
- [x] Two regression tests added (sync + async) verifying the warning is logged and no exception is raised
- [x] Full lint checks pass



Co-authored-by: zach.groves <zach.groves@datadoghq.com>

Author: ZStriker19

ddtrace/llmobs/decorators.py

@@ -13,6 +13,7 @@
 from ddtrace.llmobs._constants import OUTPUT_MESSAGES
 from ddtrace.llmobs._constants import OUTPUT_VALUE
 from ddtrace.llmobs._constants import SPAN_START_WHILE_DISABLED_WARNING
+from ddtrace.llmobs._llmobs import LLMObsAnnotateSpanError
 
 
 log = get_logger(__name__)
@@ -107,10 +108,18 @@ async def wrapper(*args, **kwargs):
                         resp = await func(*args, **kwargs)
                         if (
                             resp is not None
+                            and operation_kind != "embedding"
                             and span._get_ctx_item(OUTPUT_VALUE) is None
                             and span._get_ctx_item(OUTPUT_MESSAGES) is None
                         ):
-                            LLMObs.annotate(span=span, output_data=resp)
+                            try:
+                                LLMObs.annotate(span=span, output_data=resp)
+                            except LLMObsAnnotateSpanError:
+                                log.debug(
+                                    "Failed to auto-annotate output for @%s decorated function. "
+                                    "Use LLMObs.annotate() to manually annotate the output.",
+                                    operation_kind,
+                                )
                         return resp
 
             else:
@@ -159,10 +168,18 @@ def wrapper(*args, **kwargs):
                         resp = func(*args, **kwargs)
                         if (
                             resp is not None
+                            and operation_kind != "embedding"
                             and span._get_ctx_item(OUTPUT_VALUE) is None
                             and span._get_ctx_item(OUTPUT_MESSAGES) is None
                         ):
-                            LLMObs.annotate(span=span, output_data=resp)
+                            try:
+                                LLMObs.annotate(span=span, output_data=resp)
+                            except LLMObsAnnotateSpanError:
+                                log.debug(
+                                    "Failed to auto-annotate output for @%s decorated function. "
+                                    "Use LLMObs.annotate() to manually annotate the output.",
+                                    operation_kind,
+                                )
                         return resp
 
             return generator_wrapper if (isgeneratorfunction(func) or isasyncgenfunction(func)) else wrapper

releasenotes/notes/llm-decorator-auto-annotation-error-a9ff1d25e3706cd3.yaml

@@ -0,0 +1,7 @@
+---
+fixes:
+  - |
+    LLM Observability: Fixes an issue where the ``@llm`` decorator raised a
+    ``LLMObsAnnotateSpanError`` exception when
+    a decorated function returned a value that could not be parsed as LLM messages.
+    Note that manual annotation still overrides this automatic annotation.

tests/llmobs/test_llmobs_decorators.py

@@ -305,6 +305,43 @@ async def f():
     )
 
 
+def test_llm_decorator_unparseable_output_logs_warning_not_raises(llmobs, llmobs_events, mock_logs, test_spans):
+    """Test that @llm decorator does not raise when return value cannot be parsed as messages."""
+
+    @llm(model_name="test_model", model_provider="test_provider", name="test_function")
+    def f():
+        return 42  # int cannot be parsed as LLM messages
+
+    f()  # should not raise LLMObsAnnotateSpanError
+    mock_logs.debug.assert_called_once_with(
+        "Failed to auto-annotate output for @%s decorated function. "
+        "Use LLMObs.annotate() to manually annotate the output.",
+        "llm",
+    )
+    test_spans.pop()
+    # span is still created, output messages are not set
+    assert llmobs_events[0].get("output", {}) == {}
+
+
+async def test_llm_decorator_unparseable_output_logs_warning_not_raises_async(
+    llmobs, llmobs_events, mock_logs, test_spans
+):
+    """Test that async @llm decorator does not raise when return value cannot be parsed as messages."""
+
+    @llm(model_name="test_model", model_provider="test_provider", name="test_function")
+    async def f():
+        return 42  # int cannot be parsed as LLM messages
+
+    await f()  # should not raise LLMObsAnnotateSpanError
+    mock_logs.debug.assert_called_once_with(
+        "Failed to auto-annotate output for @%s decorated function. "
+        "Use LLMObs.annotate() to manually annotate the output.",
+        "llm",
+    )
+    test_spans.pop()
+    assert llmobs_events[0].get("output", {}) == {}
+
+
 def test_llm_decorator_manual_annotation_not_overridden(llmobs, llmobs_events, test_spans):
     """Test that manual LLMObs.annotate() is not overridden by automatic output annotation."""