Release v3.25.0 (#1261)

Author: alexmojaki

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release Notes
 
+## [v3.25.0] (2025-07-18)
+
+* Use local timezone in console logging by @fswair in [#1255](https://github.com/pydantic/logfire/pull/1255)
+* Add `logfire run` command by @Kludex in [#1139](https://github.com/pydantic/logfire/pull/1139)
+* Allow removing extra FastAPI spans by @alexmojaki in [#1258](https://github.com/pydantic/logfire/pull/1258)
+* Fix `litellm` instrumentation by @alexmojaki in [#1249](https://github.com/pydantic/logfire/pull/1249)
+* Add `logfire.exception.fingerprint` attribute to spans with exceptions by @alexmojaki in [#1253](https://github.com/pydantic/logfire/pull/1253)
+
 ## [v3.24.2] (2025-07-14)
 
 * Fix auto-tracing Python 3.12 ParamSpec syntax by @alexmojaki in [#1247](https://github.com/pydantic/logfire/pull/1247)
@@ -792,3 +800,4 @@ First release from new repo!
 [v3.24.0]: https://github.com/pydantic/logfire/compare/v3.23.0...v3.24.0
 [v3.24.1]: https://github.com/pydantic/logfire/compare/v3.24.0...v3.24.1
 [v3.24.2]: https://github.com/pydantic/logfire/compare/v3.24.1...v3.24.2
+[v3.25.0]: https://github.com/pydantic/logfire/compare/v3.24.2...v3.25.0

logfire-api/logfire_api/_internal/cli/__init__.pyi

@@ -0,0 +1,14 @@
+import argparse
+from collections.abc import Sequence
+from typing import Any
+
+__all__ = ['main', 'logfire_info']
+
+def logfire_info() -> str:
+    """Show versions of logfire, OS and related packages."""
+
+class SplitArgs(argparse.Action):
+    def __call__(self, parser: argparse.ArgumentParser, namespace: argparse.Namespace, values: str | Sequence[Any] | None, option_string: str | None = None): ...
+
+def main(args: list[str] | None = None) -> None:
+    """Run the CLI."""

logfire-api/logfire_api/_internal/cli/run.pyi

@@ -0,0 +1,49 @@
+import argparse
+from _typeshed import Incomplete
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from rich.console import Console
+from rich.text import Text
+
+STANDARD_LIBRARY_PACKAGES: Incomplete
+OTEL_INSTRUMENTATION_MAP: Incomplete
+
+@dataclass
+class InstrumentationContext:
+    instrument_pkg_map: dict[str, str]
+    installed_pkgs: set[str]
+    installed_otel_pkgs: set[str]
+    recommendations: set[tuple[str, str]]
+
+def parse_run(args: argparse.Namespace) -> None: ...
+@contextmanager
+def alter_sys_argv(argv: list[str], cmd: str) -> Generator[None, None, None]: ...
+def is_uv_installed() -> bool:
+    """Check if uv package manager is installed and available in the PATH."""
+def instrument_packages(installed_otel_packages: set[str], instrument_pkg_map: dict[str, str]) -> list[str]:
+    """Call every `logfire.instrument_x()` we can based on what's installed.
+
+    Returns a list of packages that were successfully instrumented.
+    """
+def instrument_package(import_name: str): ...
+def find_recommended_instrumentations_to_install(instrument_pkg_map: dict[str, str], installed_otel_pkgs: set[str], installed_pkgs: set[str]) -> set[tuple[str, str]]:
+    """Determine which OpenTelemetry instrumentation packages are recommended for installation.
+
+    Args:
+        instrument_pkg_map: Mapping of instrumentation package names to the packages they instrument.
+        installed_otel_pkgs: Set of already installed instrumentation package names.
+        installed_pkgs: Set of all installed package names.
+
+    Returns:
+        Set of tuples where each tuple is (instrumentation_package, target_package) that
+            is recommended for installation.
+    """
+def instrumented_packages_text(installed_otel_pkgs: set[str], instrumented_packages: list[str], installed_pkgs: set[str]) -> Text: ...
+def get_recommendation_texts(recommendations: set[tuple[str, str]]) -> tuple[Text, Text]:
+    """Return (recommended_packages_text, install_all_text) as Text objects."""
+def print_otel_summary(*, console: Console, instrumented_packages_text: Text | None = None, recommendations: set[tuple[str, str]]) -> None: ...
+def installed_packages() -> set[str]:
+    """Get a set of all installed packages."""
+def collect_instrumentation_context(exclude: set[str]) -> InstrumentationContext:
+    """Collects all relevant context for instrumentation and recommendations."""

logfire-api/logfire_api/_internal/constants.pyi

@@ -35,3 +35,4 @@ CONTEXT_ATTRIBUTES_KEY: Incomplete
 CONTEXT_SAMPLE_RATE_KEY: Incomplete
 MESSAGE_FORMATTED_VALUE_LENGTH_LIMIT: int
 ONE_SECOND_IN_NANOSECONDS: int
+ATTRIBUTES_EXCEPTION_FINGERPRINT_KEY: str

logfire-api/logfire_api/_internal/integrations/fastapi.pyi

@@ -1,19 +1,21 @@
-from ..main import Logfire as Logfire, set_user_attributes_on_raw_span as set_user_attributes_on_raw_span
+from ..constants import ONE_SECOND_IN_NANOSECONDS as ONE_SECOND_IN_NANOSECONDS
+from ..main import Logfire as Logfire, NoopSpan as NoopSpan, set_user_attributes_on_raw_span as set_user_attributes_on_raw_span
 from ..stack_info import StackInfo as StackInfo, get_code_object_info as get_code_object_info
 from ..utils import handle_internal_errors as handle_internal_errors, maybe_capture_server_headers as maybe_capture_server_headers
 from .asgi import tweak_asgi_spans_tracer_provider as tweak_asgi_spans_tracer_provider
 from _typeshed import Incomplete
 from collections.abc import Awaitable, Iterable
-from contextlib import AbstractContextManager
+from contextlib import AbstractContextManager, contextmanager
 from fastapi import FastAPI
 from functools import lru_cache
+from opentelemetry.trace import Span
 from starlette.requests import Request
 from starlette.websockets import WebSocket
 from typing import Any, Callable
 
 def find_mounted_apps(app: FastAPI) -> list[FastAPI]:
     """Fetch all sub-apps mounted to a FastAPI app, including nested sub-apps."""
-def instrument_fastapi(logfire_instance: Logfire, app: FastAPI, *, capture_headers: bool = False, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None] | None = None, excluded_urls: str | Iterable[str] | None = None, record_send_receive: bool = False, **opentelemetry_kwargs: Any) -> AbstractContextManager[None]:
+def instrument_fastapi(logfire_instance: Logfire, app: FastAPI, *, capture_headers: bool = False, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None] | None = None, excluded_urls: str | Iterable[str] | None = None, record_send_receive: bool = False, extra_spans: bool = True, **opentelemetry_kwargs: Any) -> AbstractContextManager[None]:
     """Instrument a FastAPI app so that spans and logs are automatically created for each request.
 
     See `Logfire.instrument_fastapi` for more details.
@@ -24,8 +26,13 @@ def patch_fastapi():
 
 class FastAPIInstrumentation:
     logfire_instance: Incomplete
+    timestamp_generator: Incomplete
     request_attributes_mapper: Incomplete
-    def __init__(self, logfire_instance: Logfire, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None]) -> None: ...
+    extra_spans: Incomplete
+    def __init__(self, logfire_instance: Logfire, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None], extra_spans: bool) -> None: ...
+    @contextmanager
+    def pseudo_span(self, namespace: str, root_span: Span):
+        """Record start and end timestamps in the root span, and possibly exceptions."""
     async def solve_dependencies(self, request: Request | WebSocket, original: Awaitable[Any]) -> Any: ...
     async def run_endpoint_function(self, original_run_endpoint_function: Any, request: Request, dependant: Any, values: dict[str, Any], **kwargs: Any) -> Any: ...
 

logfire-api/logfire_api/_internal/main.pyi

@@ -432,7 +432,7 @@ class Logfire:
     def instrument_pydantic_ai(self, obj: pydantic_ai.Agent | None = None, /, *, event_mode: Literal['attributes', 'logs'] = 'attributes', include_binary_content: bool | None = None, **kwargs: Any) -> None: ...
     @overload
     def instrument_pydantic_ai(self, obj: pydantic_ai.models.Model, /, *, event_mode: Literal['attributes', 'logs'] = 'attributes', include_binary_content: bool | None = None, **kwargs: Any) -> pydantic_ai.models.Model: ...
-    def instrument_fastapi(self, app: FastAPI, *, capture_headers: bool = False, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None] | None = None, excluded_urls: str | Iterable[str] | None = None, record_send_receive: bool = False, **opentelemetry_kwargs: Any) -> AbstractContextManager[None]:
+    def instrument_fastapi(self, app: FastAPI, *, capture_headers: bool = False, request_attributes_mapper: Callable[[Request | WebSocket, dict[str, Any]], dict[str, Any] | None] | None = None, excluded_urls: str | Iterable[str] | None = None, record_send_receive: bool = False, extra_spans: bool = True, **opentelemetry_kwargs: Any) -> AbstractContextManager[None]:
         """Instrument a FastAPI app so that spans and logs are automatically created for each request.
 
         Uses the [OpenTelemetry FastAPI Instrumentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/fastapi/fastapi.html)
@@ -465,6 +465,7 @@ class Logfire:
                 These are disabled by default to reduce overhead and the number of spans created,
                 since many can be created for a single request, and they are not often useful.
                 If enabled, they will be set to debug level, meaning they will usually still be hidden in the UI.
+            extra_spans: Whether to include the extra 'FastAPI arguments' and 'endpoint function' spans.
             opentelemetry_kwargs: Additional keyword arguments to pass to the OpenTelemetry FastAPI instrumentation.
 
         Returns:

logfire-api/logfire_api/_internal/tracer.pyi

@@ -1,7 +1,7 @@
 import opentelemetry.trace as trace_api
 from .config import LogfireConfig as LogfireConfig
-from .constants import ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_PENDING_SPAN_REAL_PARENT_KEY as ATTRIBUTES_PENDING_SPAN_REAL_PARENT_KEY, ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, ATTRIBUTES_VALIDATION_ERROR_KEY as ATTRIBUTES_VALIDATION_ERROR_KEY, log_level_attributes as log_level_attributes
-from .utils import handle_internal_errors as handle_internal_errors
+from .constants import ATTRIBUTES_EXCEPTION_FINGERPRINT_KEY as ATTRIBUTES_EXCEPTION_FINGERPRINT_KEY, ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_PENDING_SPAN_REAL_PARENT_KEY as ATTRIBUTES_PENDING_SPAN_REAL_PARENT_KEY, ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, ATTRIBUTES_VALIDATION_ERROR_KEY as ATTRIBUTES_VALIDATION_ERROR_KEY, log_level_attributes as log_level_attributes
+from .utils import canonicalize_exception_traceback as canonicalize_exception_traceback, handle_internal_errors as handle_internal_errors, sha256_string as sha256_string
 from _typeshed import Incomplete
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field

logfire-api/logfire_api/_internal/utils.pyi

@@ -17,6 +17,10 @@ from requests import RequestException, Response
 from types import TracebackType
 from typing import Any, Callable, ParamSpec, TypeVar, TypedDict
 
+_ = BaseExceptionGroup
+
+class BaseExceptionGroup(BaseException):
+    """Stub for BaseExceptionGroup for Python < 3.11."""
 SysExcInfo = tuple[type[BaseException], BaseException, TracebackType | None] | tuple[None, None, None]
 P = ParamSpec('P')
 T = TypeVar('T')
@@ -125,3 +129,15 @@ def platform_is_emscripten() -> bool:
 
     Threads cannot be created on Emscripten, so we need to avoid any code that creates threads.
     """
+def canonicalize_exception_traceback(exc: BaseException) -> str:
+    """Return a canonical string representation of an exception traceback.
+
+    Exceptions with the same representation are considered the same for fingerprinting purposes.
+    The source line is used, but not the line number, so that changes elsewhere in a file are irrelevant.
+    The module is used instead of the filename.
+    The same line appearing multiple times in a stack is ignored.
+    Exception group sub-exceptions are sorted and deduplicated.
+    If the exception has a cause or (not suppressed) context, it is included in the representation.
+    Cause and context are treated as different.
+    """
+def sha256_string(s: str) -> str: ...

logfire-api/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logfire-api"
-version = "3.24.2"
+version = "3.25.0"
 description = "Shim for the Logfire SDK which does nothing unless Logfire is installed"
 authors = [
     { name = "Pydantic Team", email = "[email protected]" },

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logfire"
-version = "3.24.2"
+version = "3.25.0"
 description = "The best Python observability tool! 🪵🔥"
 requires-python = ">=3.9"
 authors = [