From f35f0e10032cd7ba5f6c09c32ce4c672e9d41f87 Mon Sep 17 00:00:00 2001
From: Dhruv Ahuja <83733638+dhruv-ahuja@users.noreply.github.com>
Date: Sat, 13 Sep 2025 16:01:37 +0530
Subject: [PATCH 1/2] docs: document sqlalchemy's engine=None and multiple
 engines behaviour

- add multiple engines' instrumentation example
- create tabbed code blocks for the examples
-  add note for using None value for `engine` kwarg
---
 docs/integrations/databases/sqlalchemy.md | 32 ++++++++++++++++++-----
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/docs/integrations/databases/sqlalchemy.md b/docs/integrations/databases/sqlalchemy.md
index 855bff744..d64257a50 100644
--- a/docs/integrations/databases/sqlalchemy.md
+++ b/docs/integrations/databases/sqlalchemy.md
@@ -14,18 +14,36 @@ Install `logfire` with the `sqlalchemy` extra:
 
 Let's see a minimal example below. You can run it with `python main.py`:
 
-```py title="main.py"
-import logfire
-from sqlalchemy import create_engine
+=== "Instrument a Single Engine"
 
-logfire.configure()
+    ```py title="main.py"
+    import logfire
+    from sqlalchemy import create_engine
 
-engine = create_engine("sqlite:///:memory:")
-logfire.instrument_sqlalchemy(engine=engine)
-```
+    logfire.configure()
+
+    engine = create_engine("sqlite:///:memory:")
+    logfire.instrument_sqlalchemy(engine=engine)
+    ```
+
+=== "Instrument Multiple Engines"
+
+    ```py title="main.py"
+    import logfire
+    from sqlalchemy import create_engine
+
+    logfire.configure()
+
+    engine_one = create_engine("sqlite:///:memory:")
+    engine_two = create_engine("sqlite:///:memory:")
+    logfire.instrument_sqlalchemy(engines=[engine_one, engine_two])
+    ```
 
 The keyword arguments of `logfire.instrument_sqlalchemy()` are passed to the `SQLAlchemyInstrumentor().instrument()` method of the OpenTelemetry SQLAlchemy Instrumentation package, read more about it [here][opentelemetry-sqlalchemy].
 
+!!! info
+    To ensure instrumentation captures all emitted events, avoid using `None` value for `engine` keyword argument.
+
 !!! tip
     If you use [SQLModel][sqlmodel], you can use the same `SQLAlchemyInstrumentor` to instrument it.
 

From edb2d5beb6a5b960b80c55b725104ea7ea87d7dd Mon Sep 17 00:00:00 2001
From: Dhruv Ahuja <83733638+dhruv-ahuja@users.noreply.github.com>
Date: Sat, 20 Sep 2025 12:16:13 +0530
Subject: [PATCH 2/2] docs: improve engine instrumentation behaviour
 explanation

---
 docs/integrations/databases/sqlalchemy.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/databases/sqlalchemy.md b/docs/integrations/databases/sqlalchemy.md
index d64257a50..5f4d85767 100644
--- a/docs/integrations/databases/sqlalchemy.md
+++ b/docs/integrations/databases/sqlalchemy.md
@@ -41,8 +41,9 @@ Let's see a minimal example below. You can run it with `python main.py`:
 
 The keyword arguments of `logfire.instrument_sqlalchemy()` are passed to the `SQLAlchemyInstrumentor().instrument()` method of the OpenTelemetry SQLAlchemy Instrumentation package, read more about it [here][opentelemetry-sqlalchemy].
 
-!!! info
-    To ensure instrumentation captures all emitted events, avoid using `None` value for `engine` keyword argument.
+!!! warning
+    It's best to use the `engine` or `engines` arguments. If no engine is specified, then `instrument_sqlalchemy` may
+    only work if it's called before `sqlalchemy` is imported, in which case all engines are instrumented.
 
 !!! tip
     If you use [SQLModel][sqlmodel], you can use the same `SQLAlchemyInstrumentor` to instrument it.