Version 2.3.0 (#603)

Author: Kludex

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release Notes
 
+## [v2.3.0] (2024-11-14)
+
+* Respect repr on fields when logging a dataclass by @dmontagu in [#592](https://github.com/pydantic/logfire/pull/592)
+* Allow `extract_args` to be an iterable of argument names by @alexmojaki in [#570](https://github.com/pydantic/logfire/pull/570)
+* Make metric instrument methods compatible with older OTel versions by @alexmojaki in [#600](https://github.com/pydantic/logfire/pull/600)
+* Add span links by @Kludex in [#587](https://github.com/pydantic/logfire/pull/587)
+
 ## [v2.2.1] (2024-11-13)
 
 * Ignore trivial/empty functions in auto-tracing by @alexmojaki in [#596](https://github.com/pydantic/logfire/pull/596)
@@ -419,3 +426,4 @@ First release from new repo!
 [v2.1.2]: https://github.com/pydantic/logfire/compare/v2.1.1...v2.1.2
 [v2.2.0]: https://github.com/pydantic/logfire/compare/v2.1.2...v2.2.0
 [v2.2.1]: https://github.com/pydantic/logfire/compare/v2.2.0...v2.2.1
+[v2.3.0]: https://github.com/pydantic/logfire/compare/v2.2.1...v2.3.0

logfire-api/logfire_api/_internal/instrument.pyi

@@ -5,7 +5,7 @@ from .utils import safe_repr as safe_repr, uniquify_sequence as uniquify_sequenc
 from _typeshed import Incomplete
 from collections.abc import Sequence
 from opentelemetry.util import types as otel_types
-from typing import Any, Callable, TypeVar
+from typing import Any, Callable, ContextManager, Iterable, TypeVar
 from typing_extensions import LiteralString, ParamSpec
 
 P = ParamSpec('P')
@@ -14,5 +14,6 @@ CONTEXTMANAGER_HELPER_CODE: Incomplete
 ASYNCCONTEXTMANAGER_HELPER_CODE: Incomplete
 GENERATOR_WARNING_MESSAGE: str
 
-def instrument(logfire: Logfire, tags: Sequence[str], msg_template: LiteralString | None, span_name: str | None, extract_args: bool, allow_generator: bool) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+def instrument(logfire: Logfire, tags: Sequence[str], msg_template: LiteralString | None, span_name: str | None, extract_args: bool | Iterable[str], allow_generator: bool) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+def get_open_span(logfire: Logfire, attributes: dict[str, otel_types.AttributeValue], span_name: str | None, extract_args: bool | Iterable[str], func: Callable[P, R]) -> Callable[P, ContextManager[Any]]: ...
 def get_attributes(func: Any, msg_template: str | None, tags: Sequence[str] | None) -> dict[str, otel_types.AttributeValue]: ...

logfire-api/logfire_api/_internal/main.pyi

@@ -34,7 +34,7 @@ from fastapi import FastAPI
 from flask.app import Flask
 from opentelemetry.metrics import CallbackT as CallbackT, Counter, Histogram, UpDownCounter, _Gauge as Gauge
 from opentelemetry.sdk.trace import ReadableSpan, Span
-from opentelemetry.trace import Tracer
+from opentelemetry.trace import SpanContext, Tracer
 from opentelemetry.util import types as otel_types
 from starlette.applications import Starlette
 from starlette.requests import Request as Request
@@ -202,7 +202,7 @@ class Logfire:
             _exc_info: Set to an exception or a tuple as returned by [`sys.exc_info()`][sys.exc_info]
                 to record a traceback with the log message.
         """
-    def span(self, msg_template: str, /, *, _tags: Sequence[str] | None = None, _span_name: str | None = None, _level: LevelName | None = None, **attributes: Any) -> LogfireSpan:
+    def span(self, msg_template: str, /, *, _tags: Sequence[str] | None = None, _span_name: str | None = None, _level: LevelName | None = None, _links: Sequence[tuple[SpanContext, otel_types.Attributes]] = (), **attributes: Any) -> LogfireSpan:
         """Context manager for creating a span.
 
         ```py
@@ -219,10 +219,11 @@ class Logfire:
             _span_name: The span name. If not provided, the `msg_template` will be used.
             _tags: An optional sequence of tags to include in the span.
             _level: An optional log level name.
+            _links: An optional sequence of links to other spans. Each link is a tuple of a span context and attributes.
             attributes: The arguments to include in the span and format the message template with.
                 Attributes starting with an underscore are not allowed.
         """
-    def instrument(self, msg_template: LiteralString | None = None, *, span_name: str | None = None, extract_args: bool = True, allow_generator: bool = False) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def instrument(self, msg_template: LiteralString | None = None, *, span_name: str | None = None, extract_args: bool | Iterable[str] = True, allow_generator: bool = False) -> Callable[[Callable[P, R]], Callable[P, R]]:
         """Decorator for instrumenting a function as a span.
 
         ```py
@@ -239,7 +240,8 @@ class Logfire:
         Args:
             msg_template: The template for the span message. If not provided, the module and function name will be used.
             span_name: The span name. If not provided, the `msg_template` will be used.
-            extract_args: Whether to extract arguments from the function signature and log them as span attributes.
+            extract_args: By default, all function call arguments are logged as span attributes.
+                Set to `False` to disable this, or pass an iterable of argument names to include.
             allow_generator: Set to `True` to prevent a warning when instrumenting a generator function.
                 Read https://logfire.pydantic.dev/docs/guides/advanced/generators/#using-logfireinstrument first.
         """
@@ -973,7 +975,7 @@ class FastLogfireSpan:
 
 class LogfireSpan(ReadableSpan):
     end_on_exit: bool
-    def __init__(self, span_name: str, otlp_attributes: dict[str, otel_types.AttributeValue], tracer: Tracer, json_schema_properties: JsonSchemaProperties) -> None: ...
+    def __init__(self, span_name: str, otlp_attributes: dict[str, otel_types.AttributeValue], tracer: Tracer, json_schema_properties: JsonSchemaProperties, links: Sequence[tuple[SpanContext, otel_types.Attributes]]) -> None: ...
     def __getattr__(self, name: str) -> Any: ...
     def __enter__(self) -> LogfireSpan: ...
     def __exit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: Any) -> None: ...
@@ -1006,6 +1008,7 @@ class LogfireSpan(ReadableSpan):
         """
     def set_attributes(self, attributes: dict[str, Any]) -> None:
         """Sets the given attributes on the span."""
+    def add_link(self, context: SpanContext, attributes: otel_types.Attributes = None) -> None: ...
     def record_exception(self, exception: BaseException, attributes: otel_types.Attributes = None, timestamp: int | None = None, escaped: bool = False) -> None:
         """Records an exception as a span event.
 

logfire-api/logfire_api/_internal/metrics.pyi

@@ -5,7 +5,8 @@ from opentelemetry.context import Context
 from opentelemetry.metrics import CallbackT as CallbackT, Counter, Histogram, Instrument, Meter, MeterProvider, ObservableCounter, ObservableGauge, ObservableUpDownCounter, UpDownCounter, _Gauge
 from opentelemetry.util.types import Attributes
 from threading import Lock
-from typing import Any, Generic, Sequence, TypeVar
+from typing import Any, Generic, Sequence, TypeVar, TypedDict
+from typing_extensions import Unpack
 from weakref import WeakSet
 
 Gauge: Incomplete
@@ -37,6 +38,15 @@ class _ProxyMeter(Meter):
     def create_observable_up_down_counter(self, name: str, callbacks: Sequence[CallbackT] | None = None, unit: str = '', description: str = '') -> ObservableUpDownCounter: ...
 InstrumentT = TypeVar('InstrumentT', bound=Instrument)
 
+class MaybeContext(TypedDict, total=False):
+    """Backward-compatible keyword arguments for methods like `Counter.add`.
+
+    Starting with opentelemetry-sdk 1.28.0, these methods accept an additional optional `context` argument.
+    This is passed to the underlying instrument using `**kwargs` for compatibility with older versions.
+    This is the type hint for those kwargs.
+    """
+    context: Context | None
+
 class _ProxyInstrument(ABC, Generic[InstrumentT]):
     def __init__(self, instrument: InstrumentT, name: str, unit: str, description: str) -> None: ...
     def on_meter_set(self, meter: Meter) -> None:
@@ -46,17 +56,17 @@ class _ProxyAsynchronousInstrument(_ProxyInstrument[InstrumentT], ABC):
     def __init__(self, instrument: InstrumentT, name: str, callbacks: Sequence[CallbackT] | None, unit: str, description: str) -> None: ...
 
 class _ProxyCounter(_ProxyInstrument[Counter], Counter):
-    def add(self, amount: int | float, attributes: Attributes | None = None, context: Context | None = None) -> None: ...
+    def add(self, amount: int | float, attributes: Attributes | None = None, **kwargs: Unpack[MaybeContext]) -> None: ...
 
 class _ProxyHistogram(_ProxyInstrument[Histogram], Histogram):
-    def record(self, amount: int | float, attributes: Attributes | None = None, context: Context | None = None) -> None: ...
+    def record(self, amount: int | float, attributes: Attributes | None = None, **kwargs: Unpack[MaybeContext]) -> None: ...
 
 class _ProxyObservableCounter(_ProxyAsynchronousInstrument[ObservableCounter], ObservableCounter): ...
 class _ProxyObservableGauge(_ProxyAsynchronousInstrument[ObservableGauge], ObservableGauge): ...
 class _ProxyObservableUpDownCounter(_ProxyAsynchronousInstrument[ObservableUpDownCounter], ObservableUpDownCounter): ...
 
 class _ProxyUpDownCounter(_ProxyInstrument[UpDownCounter], UpDownCounter):
-    def add(self, amount: int | float, attributes: Attributes | None = None, context: Context | None = None) -> None: ...
+    def add(self, amount: int | float, attributes: Attributes | None = None, **kwargs: Unpack[MaybeContext]) -> None: ...
 
 class _ProxyGauge(_ProxyInstrument[Gauge], Gauge):
-    def set(self, amount: int | float, attributes: Attributes | None = None, context: Context | None = None) -> None: ...
+    def set(self, amount: int | float, attributes: Attributes | None = None, **kwargs: Unpack[MaybeContext]) -> None: ...

logfire-api/logfire_api/_internal/tracer.pyi

@@ -38,6 +38,7 @@ class _MaybeDeterministicTimestampSpan(trace_api.Span, ReadableSpan):
     def get_span_context(self) -> SpanContext: ...
     def set_attributes(self, attributes: dict[str, otel_types.AttributeValue]) -> None: ...
     def set_attribute(self, key: str, value: otel_types.AttributeValue) -> None: ...
+    def add_link(self, context: SpanContext, attributes: otel_types.Attributes = None) -> None: ...
     def add_event(self, name: str, attributes: otel_types.Attributes = None, timestamp: int | None = None) -> None: ...
     def update_name(self, name: str) -> None: ...
     def is_recording(self) -> bool: ...

logfire-api/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logfire-api"
-version = "2.2.1"
+version = "2.3.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 = "2.2.1"
+version = "2.3.0"
 description = "The best Python observability tool! 🪵🔥"
 requires-python = ">=3.8"
 authors = [