chore(llmobs): decorators can infer span links

[lievan]

Decorators set span links by tracking common objects passed as inputs & outputs of functions.

We maintain a dictionary in the LLMObs service that remembers which objects are used as the input/output for a spans generated by LLM Obs decorators. This is how we record the from direction of span links.

When objects are encountered again as the input/output for another span, we now know to set the to direction for a span link.

In my opinion, this does not need to be gated behind a feature flag since it's a read-only on app data. A follow up PR will mutate data actually used in the user app for enhanced span link inferencing, and the features introduced then should be gated by a flag.

Implementation notes:

• Objects are remembered by generating a string object id through the type + memory location of the object.
• We ignore "input" -> "output" edges. This is not a valid edge.
• Spans can only be linked to other spans belonging to the same trace

Limitations:

• it is very easy for link information to be lost if an object is mutated or used to create another object. A follow up PR will implement a best-effort attempt for objects to inherit link info from other objects
• doesn't work for distributed tracing scenarios

Checklist

• PR author has checked that all the criteria below are met
• The PR description includes an overview of the change
• The PR description articulates the motivation for the change
• The change includes tests OR the PR description describes a testing strategy
• The PR description notes risks associated with the change, if any
• Newly-added code is easy to change
• The change follows the library release note guidelines
• The change includes or references documentation updates if necessary
• Backport labels are set (if applicable)

Reviewer Checklist

• Reviewer has checked that all the criteria below are met
• Title is accurate
• All changes are related to the pull request's stated goal
• Avoids breaking API changes
• Testing strategy adequately addresses listed risks
• Newly-added code is easy to change
• Release note makes sense to a user of the library
• If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment
• Backport labels are set in a manner that is consistent with the release branch maintenance policy

[datadog-datadog-prod-us1]

🟠 Code Quality Violation

variable name is the same as a function parameter (...read more)

A function parameter should only be read and not be modified. If your intent is to modify the value of the parameter, return the value in the function and handle the new value in the caller of the function.

    

[github-actions]

CODEOWNERS have been resolved as:

ddtrace/llmobs/_llmobs.py                                               @DataDog/ml-observability
ddtrace/llmobs/_utils.py                                                @DataDog/ml-observability
ddtrace/llmobs/decorators.py                                            @DataDog/ml-observability
tests/llmobs/_utils.py                                                  @DataDog/ml-observability
tests/llmobs/test_llmobs_decorators.py                                  @DataDog/ml-observability

[datadog-dd-trace-py-rkomorn]

Datadog Report

Branch report: evan.li/span-links-dec
Commit report: f2ed301
Test service: dd-trace-py

✅ 0 Failed, 130 Passed, 1468 Skipped, 5m 8.1s Total duration (35m 45.03s time saved)

[pr-commenter]

Benchmarks

Benchmark execution time: 2025-01-23 18:47:06

Comparing candidate commit 7b76ed1 in PR branch evan.li/span-links-dec with baseline commit 2f52abb in branch main.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 394 metrics, 2 unstable metrics.

[Kyle-Verhoog]

we should guard these so we don't run this for users not opted into the feature