fix(otel): register LiteLLM_BackgroundInteractionSettlement as a span table

[devin-ai-integration]

TLDR

Problem this solves:

• proxy-infra / Run tests is red on main since 797353f13a (fix(otel): name postgres service spans by operation and table #44240)
• The settlement table from feat(interactions): durable cross-pod settlement for background interaction billing #41955 is missing from the OTel span table set

How it solves it:

• Register LiteLLM_BackgroundInteractionSettlement in _PRISMA_MODELS in litellm/integrations/otel/model/spans.py

User Flow

Before: an operator tracing the proxy with OTel sees background billing settlement queries as unnamed Postgres spans

1. They run the proxy with OTel on and send POST http://localhost:4000/v1beta/interactions with "background": true
2. The proxy records the pending settlement in Postgres
3. Their trace backend shows that query as a generic postgres span with no table in its name

After: the same queries show up named by operation and table, like every other proxy table

1. They run the proxy with OTel on and send the same POST http://localhost:4000/v1beta/interactions with "background": true
2. The proxy records the pending settlement in Postgres, exactly as before
3. Their trace backend shows that query as postgres.insert LiteLLM_BackgroundInteractionSettlement

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests (none needed: the existing schema coverage test is the regression test)
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/unit/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Red main run: run 37136497313, job proxy-infra / Run tests at 4c6c84afb7

Failing test: tests/unit/integrations/otel/test_otel_v2_logger.py::test_every_model_in_the_prisma_schema_is_a_renderable_span_table

Culprit: a merge race between #41955 (8596fe954d), which added the LiteLLM_BackgroundInteractionSettlement model to schema.prisma, and #44240 (797353f13a), which landed later from a branch cut before it. #44240 introduced _PRISMA_MODELS plus a test asserting it equals the schema's model set exactly, so the new model made that equality fail at main tip

Mechanism: parse_prisma_query only names a query by its model when the model is in PRISMA_RELATIONS, and postgres_operation only renders table_name metadata from that set. Without the entry, settlement table queries fall back to an unnamed span. The test pins the intended invariant that every schema model renders, so the code was fixed and the test is untouched

Proof on this PR at c4fd1c921c: proxy-infra / Run tests passed (5,454 passed), in run 37137843363, along with every other required check

Before (4c6c84a)

1. Boot the proxy with callbacks: ["otel"] against real Postgres, then curl -X POST localhost:4711/v1beta/interactions -d '{"agent":"deep-research-pro-preview-12-2025","input":"In one sentence, what is LiteLLM?","background":true}' with a real Gemini key
2. Response: {"id": "v1_ChZHakRCYXZMNkw1cld6N...", "status": "in_progress"} and a pending row appears in LiteLLM_BackgroundInteractionSettlement

After (c4fd1c9)

1. Same boot and the same curl -X POST localhost:4712/v1beta/interactions request
2. Response: {"id": "v1_ChdHekRCYXR5MUlmX19xd...", "status": "in_progress"} and a pending row appears in LiteLLM_BackgroundInteractionSettlement, so request and billing behavior is unchanged

Type

🐛 Bug Fix

Caveats (if any)

Low

• Local console OTel export emitted no Postgres service spans on either side
  • so the span name change itself is proven by CI, not the live run

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/c1360031f5a5497f957e701c52d57a79
Open in Devin Desktop: https://app.devin.ai/desktop/session/c1360031f5a5497f957e701c52d57a79?variant=devin

---

Note

Low Risk
Single allowlist entry for OTel span naming; no runtime behavior change beyond trace labels and the schema parity test.

Overview
Adds LiteLLM_BackgroundInteractionSettlement to _PRISMA_MODELS in litellm/integrations/otel/model/spans.py, so it is included in PRISMA_RELATIONS like the other Prisma tables.

That closes a gap after the settlement model landed in schema.prisma: Postgres OTel spans for background interaction billing can resolve table_name metadata and render as postgres.{verb} LiteLLM_BackgroundInteractionSettlement instead of generic unnamed Postgres spans. It also restores the invariant checked by test_every_model_in_the_prisma_schema_is_a_renderable_span_table on main.

^{Reviewed by Cursor Bugbot for commit c4fd1c9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Confidence Score: 5/5

[Low risk] Adds a table name to observability span registration.

The PR appears safe to merge.

Summary

Registers LiteLLM_BackgroundInteractionSettlement as an OpenTelemetry Prisma span table.

• Brings the span-table registry into line with the Prisma schema.
• Allows settlement queries to be named by operation and table.

_{Reviews (1) · Last reviewed commit: "fix(otel): register LiteLLM_BackgroundIn..."}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_ci_heal_otel_span_settlement_model (c4fd1c9) with main (a5e9f27)}

[mateo-berri]

bugbot run

[mateo-berri]

Closing as superseded, #44384 already added LiteLLM_BackgroundInteractionSettlement to _PRISMA_MODELS on main, so merging this would only add a duplicate entry

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit c4fd1c9. Configure here.}