fix #4251: wrap BackgroundTasks in their own span

[davidgss04]

Description

Fixes #4251

FastAPI background tasks were not properly instrumented. While request spans were created correctly, background tasks executed after the response without their own span. As a result, any spans created inside a background task were incorrectly attached directly to the request span, which had already finished, leading to broken trace hierarchies and inaccurate timing information.

The fix patches BackgroundTask.__call__ to wrap its execution in a dedicated span. This ensures that each background task runs within its own span, correctly parented to the request span, and that any spans created inside the task are properly nested.

The patch is applied only once using a guard (hasattr) to avoid double instrumentation, and the original method is restored during uninstrument_app to prevent side effects.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Testing

Added three regression tests:

• test_background_task_span_parents_inner_spans — verifies that background tasks create a wrapper span and that spans created inside the task are correctly parented

• test_uninstrument_app_restores_background_task_call — ensures the original BackgroundTask.__call__ is restored after uninstrumentation

• test_background_task_span_not_duplicated_on_double_instrument_app — verifies that repeated instrumentation does not create duplicate spans or apply the patch multiple times

Does This PR Require a Core Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: aabmass / name: Aaron Abbott (1d8c099, d6d0f82)
• ✅ login: davidgss04 / name: David Santos (ab9b962, c8d6158, fbcac7a)
• ✅ login: tammy-baylis-swi / name: Tammy Baylis (0407cff)

[tammy-baylis-swi]

Thanks for this! The fix to Background tracing makes sense to me and there is no semconv requirement to add HTTP attributes to that particular span. Metrics generated will be the same.

Please could you also commit fixes from:

• tox -e precommit
• tox -e lint-instrumentation-fastapi

[tammy-baylis-swi]

Thanks @davidgss04 ! Forgot to also mention: please add an entry to CHANGELOG.md linking this PR.

[tammy-baylis-swi]

Thanks again! This lgtm. 👍 The maintainers will also have to review this.

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

[davidgss04]

Good evening @tammy-baylis-swi,

Regarding the failing tests, I noticed that they are all related to Python 3.9 environments. To investigate, I synced my local repository with upstream/main and ran the same failing tox environments locally. The failures occur during dependency resolution, as the current opentelemetry-api (from main) now requires Python >=3.10, making the Python 3.9 environments unsatisfiable.

Based on this, it seems the issue is not related to the changes in this PR, but rather to the current test configuration or dependency versions for Python 3.9.

I also observed that some recent passing PRs do not appear to run Python 3.9 tests.

Do you have any guidance on how this should be handled?

[aabmass]

I'm OK with this PR but I think I remember seeing something related to this in FastAPI upstream. If the background tasks are explicitly run by FastAPI with an isolated contextvars.Context instance, they will end up detached from the request by default. IIRC FastAPI made this the default behavior.