feat(otel): move away from contrib module by cofin · Pull Request #4691 · litestar-org/litestar

cofin · 2026-04-13T15:47:11Z

Moves the OpenTelemetry plugin from litestar.contrib.opentelemetry to its permanent home at litestar.plugins.opentelemetry. The contrib directory is removed entirely on this branch — there's no shim here.

A few things ride along:

Bug: KeyError: 'route_handler' in all routes when setting exclude_opt_key in OpenTelemetryConfig #4468 — guards scope["route_handler"] access in litestar/middleware/_utils.py so the OTel middleware doesn't KeyError when it runs as the outermost ASGI layer (which it does in practice, since it sits before route resolution).
Bug: OpenTelemetryHookHandler has the wrong type #4466 — corrects the type signatures on the client-request and client-response hooks to match opentelemetry-instrumentation-asgi (3 parameters, not 2), so user-supplied hooks actually type-check.
Upstream parity — exposes tracer and http_capture_headers_* config params that were missing from OpenTelemetryConfig but supported by the underlying instrumentation library.

The deprecation shim at litestar.contrib.opentelemetry (with its DeprecationWarning) has been split out to a follow-up PR targeting v2 — that's where 2.x users actually need the migration window before 3.0 GA. This PR is purely the move plus the bug fixes and parity work.

Fixes #4468
Fixes #4466

📚 Documentation preview 📚: https://litestar-org.github.io/litestar-docs-preview/4691

codecov · 2026-04-13T15:51:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.42%. Comparing base (94468a0) to head (0543f3d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4691      +/-   ##
==========================================
+ Coverage   67.40%   67.42%   +0.01%     
==========================================
  Files         292      292              
  Lines       15013    15022       +9     
  Branches     1686     1686              
==========================================
+ Hits        10119    10128       +9     
  Misses       4758     4758              
  Partials      136      136

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

JacobCoffee

lgtm , @provinzkraut ?

provinzkraut · 2026-04-26T11:07:35Z

This seems to be targeting the wrong branch. It's deprecating things to be removed in 3.0, but it's also targeting the 3.0 branch. Should be targeting the v2 branch, and then a follow-up PR made into main that does the removal

…org#4466, add upstream parity

cofin · 2026-04-26T18:12:54Z

@provinzkraut deprecation notices removed and will be bundled in a separate PR.

provinzkraut · 2026-05-09T17:19:29Z

@cofin if this is now intentionally targeting main (i.e. v3.0), it should include a changelog entry

cofin · 2026-05-09T17:24:04Z

@provinzkraut merge conflicts resolved and changelog entry added.

@xronocode

…ns.minijinja (#4760) Moves the MiniJinja template engine integration from `litestar.contrib.minijinja` to `litestar.plugins.minijinja`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim covering both public and private symbols. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). `litestar/plugins/flash.py` lazily imports the private `_transform_state` from MiniJinja, so any deprecation shim has to forward private symbols. That diagnosis came from @xronocode's audit in #4754; this PR preserves it by migrating flash.py before deleting contrib, so every intermediate commit keeps the dependency graph valid. Salvages the contrib tests into `tests/unit/test_plugins/test_minijinja.py` (98% coverage), migrates every internal call site, and adds `docs/reference/plugins/minijinja.rst`. Closes #4718. Co-authored-by: xronocode <myevdokimov@gmail.com>

@xronocode

…4764) Moves the Mako template engine integration from `litestar.contrib.mako` to `litestar.plugins.mako`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim, giving 2.x users a migration window. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). Implementation reference: PR #4753 by @xronocode. Every commit carries a co-author trailer. Salvages the contrib tests into `tests/unit/test_plugins/test_mako.py`, migrates every internal call site (csrf middleware, flash, template suite), and adds `docs/reference/plugins/mako.rst`. Closes #4717. Co-authored-by: xronocode <myevdokimov@gmail.com>

@xronocode

…#4762) Moves the Jinja2 template engine integration from `litestar.contrib.jinja` to `litestar.plugins.jinja`, and removes the contrib path on `main`. A follow-up PR onto `v2` will add a deprecation shim, giving 2.x users a migration window. Same shape as the OTel split (#4691 + #4759) and the repository split (#4735 + #4758). Implementation reference: PR #4752 by @xronocode. Every commit carries a co-author trailer. Salvages the contrib tests into `tests/unit/test_plugins/test_jinja.py`, migrates every internal call site (csrf middleware, flash, template suite, htmx examples), and adds `docs/reference/plugins/jinja.rst`. Closes #4716. Co-authored-by: xronocode <myevdokimov@gmail.com>

…ib namespace (#4759) This moves the OpenTelemetry integration to `litestar.plugins.opentelemetry` and turns `litestar.contrib.opentelemetry` into a deprecation shim. The same move landed on main as #4691; this is the v2 side, so 2.x users get both a real migration target on their current version and a `DeprecationWarning` pointing them at it. They can update imports while still on 2.x and upgrade cleanly to 3.0.0. Three symbols are covered: `OpenTelemetryConfig`, `OpenTelemetryInstrumentationMiddleware`, and `OpenTelemetryPlugin`. The contrib location — which was the real implementation on v2 until now — becomes a thin PEP 562 `__getattr__` shim that re-exports from the plugin namespace. ```python # before from litestar.contrib.opentelemetry import OpenTelemetryPlugin # after from litestar.plugins.opentelemetry import OpenTelemetryPlugin ``` Two upstream bug fixes ride along with the move: - A `route_handler is None` guard in the middleware helper, fixing a `KeyError` when the OTel middleware runs as the outermost layer before route resolution (#4468) - Corrected client request/response hook signatures — three params instead of two, matching `opentelemetry-instrumentation-asgi` (#4466) The config also exposes `tracer` and `http_capture_headers_*` fields that #4691 added on main. Tests split cleanly: `tests/unit/test_contrib/test_opentelemetry.py` is now the deprecation suite (each access fires `DeprecationWarning` and resolves to the same object as the plugin namespace), and `tests/unit/test_plugins/test_opentelemetry.py` carries the behavior tests for the new namespace. Deprecated in 2.22.0, removed in 3.0.0. Changelog entry added under the new 2.22.0 block.

cofin requested review from a team, JacobCoffee and provinzkraut as code owners April 13, 2026 15:47

github-actions Bot added area/docs This PR involves changes to the documentation area/middleware This PR involves changes to the middleware area/private-api This PR involves changes to the privatized API size: medium type/feat pr/internal labels Apr 13, 2026

cofin changed the title ~~feat(otel): move to plugins, fix bugs #4468 and #4466, add upstream parity~~ feat(otel): move away from contrib folder structure Apr 13, 2026

cofin changed the title ~~feat(otel): move away from contrib folder structure~~ feat(otel): move away from contrib module Apr 13, 2026

cofin force-pushed the feat/otel-plugin branch 2 times, most recently from 14ee32a to bb0d601 Compare April 13, 2026 20:48

JacobCoffee reviewed Apr 19, 2026

View reviewed changes

Comment thread litestar/middleware/_utils.py

Comment thread litestar/plugins/opentelemetry/_utils.py

cofin force-pushed the feat/otel-plugin branch from ec9567b to 3215ee2 Compare April 25, 2026 20:45

cofin enabled auto-merge (squash) April 25, 2026 21:02

cofin force-pushed the feat/otel-plugin branch from 3215ee2 to b99976c Compare April 25, 2026 21:48

cofin force-pushed the feat/otel-plugin branch 4 times, most recently from 1df4b4a to 2aa4a1a Compare April 26, 2026 16:05

feat(otel): move to plugins, fix bugs litestar-org#4468 and litestar-…

8bf4c4f

…org#4466, add upstream parity

cofin force-pushed the feat/otel-plugin branch from 2aa4a1a to 8bf4c4f Compare April 26, 2026 18:11

cofin added 2 commits May 9, 2026 17:21

Merge branch 'main' into feat/otel-plugin

7d89b44

chore: updated changelog

0543f3d

provinzkraut approved these changes May 9, 2026

View reviewed changes

cofin merged commit e0204f0 into litestar-org:main May 9, 2026
25 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(otel): move away from contrib module#4691

feat(otel): move away from contrib module#4691
cofin merged 3 commits into
litestar-org:mainfrom
cofin:feat/otel-plugin

cofin commented Apr 13, 2026 •

edited by github-actions Bot

Loading

Uh oh!

codecov Bot commented Apr 13, 2026 •

edited

Loading

Uh oh!

JacobCoffee left a comment

Uh oh!

Uh oh!

Uh oh!

provinzkraut commented Apr 26, 2026

Uh oh!

cofin commented Apr 26, 2026 •

edited

Loading

Uh oh!

provinzkraut commented May 9, 2026

Uh oh!

cofin commented May 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

cofin commented Apr 13, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

JacobCoffee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

provinzkraut commented Apr 26, 2026

Uh oh!

cofin commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

provinzkraut commented May 9, 2026

Uh oh!

cofin commented May 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cofin commented Apr 13, 2026 •

edited by github-actions Bot

Loading

codecov Bot commented Apr 13, 2026 •

edited

Loading

cofin commented Apr 26, 2026 •

edited

Loading