Add logfire.instrument_requests() (#196)

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>

docs/integrations/requests.md

@@ -1,6 +1,7 @@
 # Requests
 
-The [OpenTelemetry Instrumentation Requests][opentelemetry-requests] package can be used to instrument [Requests][requests].
+The [`logfire.instrument_requests()`][logfire.Logfire.instrument_requests] method can be used to
+instrument [`requests`][requests] with **Logfire**.
 
 ## Installation
 
@@ -13,15 +14,16 @@ Install `logfire` with the `requests` extra:
 ```py title="main.py"
 import logfire
 import requests
-from opentelemetry.instrumentation.requests import RequestsInstrumentor
 
 logfire.configure()
-RequestsInstrumentor().instrument()
+logfire.instrument_requests()
 
 requests.get("https://httpbin.org/get")
 ```
 
-You can read more about the [`requests`][requests] OpenTelemetry package [here][opentelemetry-requests].
+[`logfire.instrument_requests()`][logfire.Logfire.instrument_requests] uses the
+**OpenTelemetry requests Instrumentation** package,
+which you can find more information about [here][opentelemetry-requests].
 
 [opentelemetry-requests]: https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/requests/requests.html
 [requests]: https://docs.python-requests.org/en/master/

logfire/__init__.py

@@ -23,6 +23,7 @@
 instrument_openai = DEFAULT_LOGFIRE_INSTANCE.instrument_openai
 instrument_anthropic = DEFAULT_LOGFIRE_INSTANCE.instrument_anthropic
 instrument_asyncpg = DEFAULT_LOGFIRE_INSTANCE.instrument_asyncpg
+instrument_requests = DEFAULT_LOGFIRE_INSTANCE.instrument_requests
 instrument_psycopg = DEFAULT_LOGFIRE_INSTANCE.instrument_psycopg
 shutdown = DEFAULT_LOGFIRE_INSTANCE.shutdown
 with_tags = DEFAULT_LOGFIRE_INSTANCE.with_tags

logfire/_internal/integrations/requests.py

@@ -0,0 +1,11 @@
+from typing import Any, Optional
+
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+
+
+def instrument_requests(excluded_urls: Optional[str] = None, **kwargs: Any):
+    """Instrument the `requests` module so that spans are automatically created for each request.
+
+    See the `Logfire.instrument_requests` method for details.
+    """
+    RequestsInstrumentor().instrument(excluded_urls=excluded_urls, **kwargs)  # type: ignore[reportUnknownMemberType]

logfire/_internal/main.py

@@ -9,7 +9,18 @@
 from functools import cached_property, partial
 from time import time
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, Callable, ContextManager, Iterable, Literal, Sequence, TypeVar, Union, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ContextManager,
+    Iterable,
+    Literal,
+    Sequence,
+    TypeVar,
+    Union,
+    cast,
+)
 
 import opentelemetry.context as context_api
 import opentelemetry.trace as trace_api
@@ -971,6 +982,18 @@ def instrument_asyncpg(self):
 
         return instrument_asyncpg()
 
+    def instrument_requests(self, excluded_urls: str | None = None, **kwargs: Any):
+        """Instrument the `requests` module so that spans are automatically created for each request.
+
+        Args:
+            excluded_urls: A string containing a comma-delimited list of regexes used to exclude URLs from tracking
+            **kwargs: Additional keyword arguments to pass to the OpenTelemetry `instrument` methods,
+                particularly `request_hook` and `response_hook`.
+        """
+        from .integrations.requests import instrument_requests
+
+        return instrument_requests(excluded_urls=excluded_urls, **kwargs)
+
     def instrument_psycopg(self, conn_or_module: Any = None, **kwargs: Any):
         """Instrument a `psycopg` connection or module so that spans are automatically created for each query.
 

tests/otel_integrations/test_requests.py

@@ -21,9 +21,9 @@ def send(self: Any, request: requests.Request, **kwargs: Any):
 
     monkeypatch.setattr(requests.Session, 'send', send)
 
-    instrumentor = RequestsInstrumentor()
-    instrumentor.instrument()  # type: ignore
+    logfire.instrument_requests()
     yield
+    instrumentor = RequestsInstrumentor()
     instrumentor.uninstrument()  # type: ignore