Remove default min_duration for install_auto_tracing (#446)

Author: alexmojaki

docs/guides/onboarding-checklist/add-auto-tracing.md

@@ -14,7 +14,7 @@ you could create another file outside of the `app` package, e.g:
 import logfire
 
 logfire.configure()
-logfire.install_auto_tracing(modules=['app'])
+logfire.install_auto_tracing(modules=['app'], min_duration=0.01)
 
 from app.main import main
 
@@ -24,6 +24,20 @@ main()
 !!! note
     Generator functions will not be traced for reasons explained [here](../advanced/generators.md).
 
+## Only tracing functions above a minimum duration
+
+In most situations you don't want to trace every single function call in your application.
+The most convenient way to exclude functions from tracing is with the [`min_duration`][logfire.Logfire.install_auto_tracing(min_duration)] argument. For example, the code snippet above will only trace functions that take longer than 0.01 seconds.
+This means you automatically get observability for the heavier parts of your application without too much overhead or data. Note that there are some caveats:
+
+- A function will only start being traced after it runs longer than `min_duration` once. This means that:
+    - If it runs faster than `min_duration` the first few times, you won't get data about those first calls.
+    - The first time that it runs longer than `min_duration`, you also won't get data about that call.
+- After a function runs longer than `min_duration` once, it will be traced every time it's called afterwards, regardless of how long it takes.
+- Measuring the duration of a function call still adds a small overhead. For tiny functions that are called very frequently, it's best to still use the `@no_auto_trace` decorator to avoid any overhead. Auto-tracing with `min_duration` will still work for other undecorated functions.
+
+If you want to trace all function calls from the beginning, set `min_duration=0`.
+
 ## Filtering modules to trace
 
 The `modules` argument can be a list of module names.
@@ -89,20 +103,3 @@ Renaming/aliasing either the function or module won't work.
 Neither will calling this indirectly via another function.
 
 This decorator simply returns the argument unchanged, so there is zero runtime overhead.
-
-## Only tracing functions above a minimum duration
-
-A more convenient way to exclude functions from tracing is to set the [`min_duration`][logfire.Logfire.install_auto_tracing(min_duration)] argument, e.g:
-
-```python
-# Only trace functions that take longer than 0.1 seconds
-logfire.install_auto_tracing(modules=['app'], min_duration=0.1)
-```
-
-This means you automatically get observability for the heavier parts of your application without too much overhead or data. Note that there are some caveats:
-
-- A function will only start being traced after it runs longer than `min_duration` once. This means that:
-    - If it runs faster than `min_duration` the first few times, you won't get data about those first calls.
-    - The first time that it runs longer than `min_duration`, you also won't get data about that call.
-- After a function runs longer than `min_duration` once, it will be traced every time it's called afterwards, regardless of how long it takes.
-- Measuring the duration of a function call still adds a small overhead. For tiny functions that are called very frequently, it's best to still use the `@no_auto_trace` decorator to avoid any overhead. Auto-tracing with `min_duration` will still work for other undecorated functions.

logfire/_internal/auto_trace/__init__.py

@@ -16,8 +16,8 @@ def install_auto_tracing(
     logfire: Logfire,
     modules: Sequence[str] | Callable[[AutoTraceModule], bool],
     *,
+    min_duration: float,
     check_imported_modules: Literal['error', 'warn', 'ignore'] = 'error',
-    min_duration: float = 0,
 ) -> None:
     """Install automatic tracing.
 

logfire/_internal/main.py

@@ -763,11 +763,14 @@ def install_auto_tracing(
         self,
         modules: Sequence[str] | Callable[[AutoTraceModule], bool],
         *,
+        min_duration: float,
         check_imported_modules: Literal['error', 'warn', 'ignore'] = 'error',
-        min_duration: float = 0,
     ) -> None:
         """Install automatic tracing.
 
+        See the [Auto-Tracing guide](https://logfire.pydantic.dev/docs/guides/onboarding_checklist/add_auto_tracing/)
+        for more info.
+
         This will trace all non-generator function calls in the modules specified by the modules argument.
         It's equivalent to wrapping the body of every function in matching modules in `with logfire.span(...):`.
 
@@ -786,13 +789,13 @@ def install_auto_tracing(
         Args:
             modules: List of module names to trace, or a function which returns True for modules that should be traced.
                 If a list is provided, any submodules within a given module will also be traced.
+            min_duration: A minimum duration in seconds for which a function must run before it's traced.
+                Setting to `0` causes all functions to be traced from the beginning.
+                Otherwise, the first time(s) each function is called, it will be timed but not traced.
+                Only after the function has run for at least `min_duration` will it be traced in subsequent calls.
             check_imported_modules: If this is `'error'` (the default), then an exception will be raised if any of the
                 modules in `sys.modules` (i.e. modules that have already been imported) match the modules to trace.
                 Set to `'warn'` to issue a warning instead, or `'ignore'` to skip the check.
-            min_duration: An optional minimum duration in seconds for which a function must run before it's traced.
-                The default is `0`, which means all functions are traced from the beginning.
-                Otherwise, the first time(s) each function is called, it will be timed but not traced.
-                Only after the function has run for at least `min_duration` will it be traced in subsequent calls.
         """
         install_auto_tracing(self, modules, check_imported_modules=check_imported_modules, min_duration=min_duration)
 

tests/test_auto_trace.py

@@ -8,7 +8,7 @@
 from inline_snapshot import snapshot
 
 import logfire
-from logfire import DEFAULT_LOGFIRE_INSTANCE, AutoTraceModule, install_auto_tracing
+from logfire import DEFAULT_LOGFIRE_INSTANCE, AutoTraceModule
 from logfire._internal.auto_trace import (
     AutoTraceModuleAlreadyImportedException,
     AutoTraceModuleAlreadyImportedWarning,
@@ -22,9 +22,9 @@
 def test_auto_trace_sample(exporter: TestExporter) -> None:
     meta_path = sys.meta_path.copy()
 
-    logfire.with_tags('testing', 'auto-tracing').install_auto_tracing('tests.auto_trace_samples')
+    logfire.with_tags('testing', 'auto-tracing').install_auto_tracing('tests.auto_trace_samples', min_duration=0)
     # Check that having multiple LogfireFinders doesn't break things
-    install_auto_tracing('tests.blablabla')
+    logfire.install_auto_tracing('tests.blablabla', min_duration=0)
 
     assert sys.meta_path[2:] == meta_path
     finder = sys.meta_path[1]
@@ -40,7 +40,7 @@ def test_auto_trace_sample(exporter: TestExporter) -> None:
     from tests.auto_trace_samples import foo
 
     # Check ignoring imported modules
-    install_auto_tracing('tests.auto_trace_samples', check_imported_modules='ignore')
+    logfire.install_auto_tracing('tests.auto_trace_samples', check_imported_modules='ignore', min_duration=0)
 
     loader = foo.__loader__
     assert isinstance(loader, LogfireLoader)
@@ -144,16 +144,16 @@ def test_check_already_imported() -> None:
     meta_path = sys.meta_path.copy()
 
     with pytest.raises(AutoTraceModuleAlreadyImportedException, match=r"The module 'tests.*' matches modules to trace"):
-        install_auto_tracing(['tests'])
+        logfire.install_auto_tracing(['tests'], min_duration=0)
 
     with pytest.raises(ValueError):
-        install_auto_tracing(['tests'], check_imported_modules='other')  # type: ignore
+        logfire.install_auto_tracing(['tests'], check_imported_modules='other', min_duration=0)  # type: ignore
 
     # No tracing installed.
     assert sys.meta_path == meta_path
 
     with pytest.warns(AutoTraceModuleAlreadyImportedWarning, match=r"The module 'tests.*' matches modules to trace"):
-        install_auto_tracing(['tests'], check_imported_modules='warn')
+        logfire.install_auto_tracing(['tests'], check_imported_modules='warn', min_duration=0)
 
     # The tracing was installed, undo it.
     assert sys.meta_path[1:] == meta_path
@@ -438,7 +438,7 @@ def test_generators():
 
 
 def test_min_duration(exporter: TestExporter):
-    install_auto_tracing('tests.auto_trace_samples.simple_nesting', min_duration=5)
+    logfire.install_auto_tracing('tests.auto_trace_samples.simple_nesting', min_duration=5)
 
     from tests.auto_trace_samples import simple_nesting
 
@@ -491,4 +491,4 @@ def test_min_duration(exporter: TestExporter):
 
 def test_wrong_type_modules():
     with pytest.raises(TypeError, match='modules must be a list of strings or a callable'):
-        install_auto_tracing(123)  # type: ignore
+        logfire.install_auto_tracing(123, min_duration=0)  # type: ignore

tests/test_logfire_api.py

@@ -113,7 +113,7 @@ def test_runtime(logfire_api_factory: Callable[[], ModuleType], module_name: str
     logfire__all__.remove('log_slow_async_callbacks')
 
     assert hasattr(logfire_api, 'install_auto_tracing')
-    logfire_api.install_auto_tracing(modules=['all'])
+    logfire_api.install_auto_tracing(modules=['all'], min_duration=0)
     logfire__all__.remove('install_auto_tracing')
 
     assert hasattr(logfire_api, 'instrument')