Add logfire.instrument_system_metrics()

docs/integrations/system_metrics.md

@@ -1,28 +1,68 @@
-By default, **Logfire** does not collect system metrics.
+The [`logfire.instrument_system_metrics()`][logfire.Logfire.instrument_system_metrics] method can be used to collect system metrics with **Logfire**, such as CPU and memory usage.
 
-To enable metrics, you need to install the `logfire[system-metrics]` extra:
+## Installation
+
+Install `logfire` with the `system-metrics` extra:
 
 {{ install_logfire(extras=['system-metrics']) }}
 
-### Available Metrics
-
-Logfire collects the following system metrics:
-
-* `system.cpu.time`: CPU time spent in different modes.
-* `system.cpu.utilization`: CPU utilization in different modes.
-* `system.memory.usage`: Memory usage.
-* `system.memory.utilization`: Memory utilization in different modes.
-* `system.swap.usage`: Swap usage.
-* `system.swap.utilization`: Swap utilization
-* `system.disk.io`: Disk I/O operations (read/write).
-* `system.disk.operations`: Disk operations (read/write).
-* `system.disk.time`: Disk time (read/write).
-* `system.network.dropped.packets`: Dropped packets (transmit/receive).
-* `system.network.packets`: Packets (transmit/receive).
-* `system.network.errors`: Network errors (transmit/receive).
-* `system.network.io`: Network I/O (transmit/receive).
-* `system.network.connections`: Network connections (family/type).
-* `system.thread_count`: Thread count.
-* `process.runtime.memory`: Process memory usage.
-* `process.runtime.cpu.time`: Process CPU time.
-* `process.runtime.gc_count`: Process garbage collection count.
+## Usage
+
+```py
+import logfire
+
+logfire.configure()
+
+logfire.instrument_system_metrics()
+```
+
+Then in your project, click on 'Dashboards' in the top bar, click 'New Dashboard', and select 'Basic System Metrics' from the dropdown.
+
+## Configuration
+
+By default, `instrument_system_metrics` collects only the metrics it needs to display the 'Basic System Metrics' dashboard. You can choose exactly which metrics to collect and how much data to collect about each metric. The default is equivalent to this:
+
+```py
+logfire.instrument_system_metrics({
+    'system.cpu.simple_utilization': None,
+    'system.memory.utilization': ['available'],
+    'system.swap.utilization': ['used'],
+})
+```
+
+To collect lots of detailed data about all available metrics, use `logfire.instrument_system_metrics(base='full')`. This is equivalent to:
+
+```py
+logfire.instrument_system_metrics({
+    'system.cpu.simple_utilization': None,
+    'system.cpu.time': ['idle', 'user', 'system', 'irq', 'softirq', 'nice', 'iowait', 'steal', 'interrupt', 'dpc'],
+    'system.cpu.utilization': ['idle', 'user', 'system', 'irq', 'softirq', 'nice', 'iowait', 'steal', 'interrupt', 'dpc'],
+    'system.memory.usage': ['available', 'used', 'free', 'active', 'inactive', 'buffers', 'cached', 'shared', 'wired', 'slab', 'total'],
+    'system.memory.utilization': ['available', 'used', 'free', 'active', 'inactive', 'buffers', 'cached', 'shared', 'wired', 'slab'],
+    'system.swap.usage': ['used', 'free'],
+    'system.swap.utilization': ['used'],
+    'system.disk.io': ['read', 'write'],
+    'system.disk.operations': ['read', 'write'],
+    'system.disk.time': ['read', 'write'],
+    'system.network.dropped.packets': ['transmit', 'receive'],
+    'system.network.packets': ['transmit', 'receive'],
+    'system.network.errors': ['transmit', 'receive'],
+    'system.network.io': ['transmit', 'receive'],
+    'system.thread_count': None,
+    'process.runtime.memory': ['rss', 'vms'],
+    'process.runtime.cpu.time': ['user', 'system'],
+    'process.runtime.gc_count': None,
+    'process.runtime.thread_count': None,
+    'process.runtime.cpu.utilization': None,
+    'process.runtime.context_switches': ['involuntary', 'voluntary'],
+    'process.open_file_descriptor.count': None,
+})
+```
+
+Each key here is a metric name. The values have different meanings for different metrics. For example, for `system.cpu.utilization`, the value is a list of CPU modes. So there will be a separate row for each CPU core saying what percentage of time it spent idle, another row for the time spent waiting for IO, etc. There are no fields to configure for `system.thread_count`, so the value is `None`.
+
+The first dict argument is merged with the base. For example, if you want to collect disk read operations (but not writes) you can write:
+
+- `logfire.instrument_system_metrics({'system.disk.operations': ['read']})` to collect that data in addition to the basic defaults.
+- `logfire.instrument_system_metrics({'system.disk.operations': ['read']}, base='full')` to collect detailed data about all metrics, excluding disk write operations.
+- `logfire.instrument_system_metrics({'system.disk.operations': ['read']}, base=None)` to collect only disk read operations and nothing else.

logfire-api/logfire_api/__init__.py

@@ -123,6 +123,8 @@ def instrument_openai(self, *args, **kwargs) -> ContextManager[None]:
 
             def instrument_aiohttp_client(self, *args, **kwargs) -> None: ...
 
+            def instrument_system_metrics(self, *args, **kwargs) -> None: ...
+
             def shutdown(self, *args, **kwargs) -> None: ...
 
         DEFAULT_LOGFIRE_INSTANCE = Logfire()
@@ -158,6 +160,7 @@ def shutdown(self, *args, **kwargs) -> None: ...
         instrument_redis = DEFAULT_LOGFIRE_INSTANCE.instrument_redis
         instrument_pymongo = DEFAULT_LOGFIRE_INSTANCE.instrument_pymongo
         instrument_mysql = DEFAULT_LOGFIRE_INSTANCE.instrument_mysql
+        instrument_system_metrics = DEFAULT_LOGFIRE_INSTANCE.instrument_system_metrics
         shutdown = DEFAULT_LOGFIRE_INSTANCE.shutdown
 
         def no_auto_trace(x):

logfire-api/logfire_api/__init__.pyi

@@ -11,7 +11,7 @@ from .integrations.logging import LogfireLoggingHandler as LogfireLoggingHandler
 from .integrations.structlog import LogfireProcessor as StructlogProcessor
 from .version import VERSION as VERSION
 
-__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'ConsoleOptions', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'METRICS_PREFERRED_TEMPORALITY', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'TailSamplingOptions']
+__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'ConsoleOptions', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_fastapi', 'instrument_openai', 'instrument_anthropic', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_sqlalchemy', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_system_metrics', 'AutoTraceModule', 'with_tags', 'with_settings', 'shutdown', 'load_spans_from_file', 'no_auto_trace', 'METRICS_PREFERRED_TEMPORALITY', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'TailSamplingOptions']
 
 DEFAULT_LOGFIRE_INSTANCE = Logfire()
 span = DEFAULT_LOGFIRE_INSTANCE.span
@@ -35,6 +35,7 @@ instrument_sqlalchemy = DEFAULT_LOGFIRE_INSTANCE.instrument_sqlalchemy
 instrument_redis = DEFAULT_LOGFIRE_INSTANCE.instrument_redis
 instrument_pymongo = DEFAULT_LOGFIRE_INSTANCE.instrument_pymongo
 instrument_mysql = DEFAULT_LOGFIRE_INSTANCE.instrument_mysql
+instrument_system_metrics = DEFAULT_LOGFIRE_INSTANCE.instrument_system_metrics
 shutdown = DEFAULT_LOGFIRE_INSTANCE.shutdown
 with_tags = DEFAULT_LOGFIRE_INSTANCE.with_tags
 with_settings = DEFAULT_LOGFIRE_INSTANCE.with_settings

logfire-api/logfire_api/_internal/config.pyi

@@ -14,7 +14,7 @@ from .exporters.remove_pending import RemovePendingSpansExporter as RemovePendin
 from .exporters.tail_sampling import TailSamplingOptions as TailSamplingOptions, TailSamplingProcessor as TailSamplingProcessor
 from .exporters.test import TestExporter as TestExporter
 from .integrations.executors import instrument_executors as instrument_executors
-from .metrics import ProxyMeterProvider as ProxyMeterProvider, configure_metrics as configure_metrics
+from .metrics import ProxyMeterProvider as ProxyMeterProvider
 from .scrubbing import BaseScrubber as BaseScrubber, NOOP_SCRUBBER as NOOP_SCRUBBER, ScrubCallback as ScrubCallback, Scrubber as Scrubber, ScrubbingOptions as ScrubbingOptions
 from .stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
 from .tracer import PendingSpanProcessor as PendingSpanProcessor, ProxyTracerProvider as ProxyTracerProvider
@@ -54,7 +54,7 @@ class PydanticPlugin:
     include: set[str] = ...
     exclude: set[str] = ...
 
-def configure(*, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, project_name: str | None = None, service_name: str | None = None, service_version: str | None = None, trace_sample_rate: float | None = None, console: ConsoleOptions | Literal[False] | None = None, show_summary: bool | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, base_url: str | None = None, collect_system_metrics: bool | None = None, id_generator: IdGenerator | None = None, ns_timestamp_generator: Callable[[], int] | None = None, processors: None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None = None, metric_readers: None = None, additional_metric_readers: Sequence[MetricReader] | None = None, pydantic_plugin: PydanticPlugin | None = None, fast_shutdown: bool = False, scrubbing_patterns: Sequence[str] | None = None, scrubbing_callback: ScrubCallback | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, tail_sampling: TailSamplingOptions | None = None) -> None:
+def configure(*, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | None = None, project_name: str | None = None, service_name: str | None = None, service_version: str | None = None, trace_sample_rate: float | None = None, console: ConsoleOptions | Literal[False] | None = None, show_summary: bool | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, base_url: str | None = None, collect_system_metrics: None = None, id_generator: IdGenerator | None = None, ns_timestamp_generator: Callable[[], int] | None = None, processors: None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None = None, metric_readers: None = None, additional_metric_readers: Sequence[MetricReader] | None = None, pydantic_plugin: PydanticPlugin | None = None, fast_shutdown: bool = False, scrubbing_patterns: Sequence[str] | None = None, scrubbing_callback: ScrubCallback | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, tail_sampling: TailSamplingOptions | None = None) -> None:
     """Configure the logfire SDK.
 
     Args:
@@ -81,8 +81,7 @@ def configure(*, send_to_logfire: bool | Literal['if-token-present'] | None = No
             `LOGFIRE_CONFIG_DIR` environment variable, otherwise defaults to the current working directory.
         data_dir: Directory to store credentials, and logs. If `None` uses the `LOGFIRE_CREDENTIALS_DIR` environment variable, otherwise defaults to `'.logfire'`.
         base_url: Root URL for the Logfire API. If `None` uses the `LOGFIRE_BASE_URL` environment variable, otherwise defaults to https://logfire-api.pydantic.dev.
-        collect_system_metrics: Whether to collect system metrics like CPU and memory usage. If `None` uses the `LOGFIRE_COLLECT_SYSTEM_METRICS` environment variable,
-            otherwise defaults to `True`.
+        collect_system_metrics: Legacy argument, use `logfire.instrument_system_metrics()` instead.
         id_generator: Generator for span IDs. Defaults to `RandomIdGenerator()` from the OpenTelemetry SDK.
         ns_timestamp_generator: Generator for nanosecond timestamps. Defaults to [`time.time_ns`][time.time_ns] from the
             Python standard library.
@@ -127,7 +126,6 @@ class _LogfireConfigData:
     console: ConsoleOptions | Literal[False] | None
     show_summary: bool
     data_dir: Path
-    collect_system_metrics: bool
     id_generator: IdGenerator
     ns_timestamp_generator: Callable[[], int]
     additional_span_processors: Sequence[SpanProcessor] | None
@@ -139,14 +137,14 @@ class _LogfireConfigData:
     tail_sampling: TailSamplingOptions | None
 
 class LogfireConfig(_LogfireConfigData):
-    def __init__(self, base_url: str | None = None, send_to_logfire: bool | None = None, token: str | None = None, project_name: str | None = None, service_name: str | None = None, service_version: str | None = None, trace_sample_rate: float | None = None, console: ConsoleOptions | Literal[False] | None = None, show_summary: bool | None = None, config_dir: Path | None = None, data_dir: Path | None = None, collect_system_metrics: bool | None = None, id_generator: IdGenerator | None = None, ns_timestamp_generator: Callable[[], int] | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None = None, additional_metric_readers: Sequence[MetricReader] | None = None, pydantic_plugin: PydanticPlugin | None = None, fast_shutdown: bool = False, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, tail_sampling: TailSamplingOptions | None = None) -> None:
+    def __init__(self, base_url: str | None = None, send_to_logfire: bool | None = None, token: str | None = None, project_name: str | None = None, service_name: str | None = None, service_version: str | None = None, trace_sample_rate: float | None = None, console: ConsoleOptions | Literal[False] | None = None, show_summary: bool | None = None, config_dir: Path | None = None, data_dir: Path | None = None, id_generator: IdGenerator | None = None, ns_timestamp_generator: Callable[[], int] | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None = None, additional_metric_readers: Sequence[MetricReader] | None = None, pydantic_plugin: PydanticPlugin | None = None, fast_shutdown: bool = False, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, tail_sampling: TailSamplingOptions | None = None) -> None:
         """Create a new LogfireConfig.
 
         Users should never need to call this directly, instead use `logfire.configure`.
 
         See `_LogfireConfigData` for parameter documentation.
         """
-    def configure(self, base_url: str | None, send_to_logfire: bool | Literal['if-token-present'] | None, token: str | None, project_name: str | None, service_name: str | None, service_version: str | None, trace_sample_rate: float | None, console: ConsoleOptions | Literal[False] | None, show_summary: bool | None, config_dir: Path | None, data_dir: Path | None, collect_system_metrics: bool | None, id_generator: IdGenerator | None, ns_timestamp_generator: Callable[[], int] | None, additional_span_processors: Sequence[SpanProcessor] | None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None, additional_metric_readers: Sequence[MetricReader] | None, pydantic_plugin: PydanticPlugin | None, fast_shutdown: bool, scrubbing: ScrubbingOptions | Literal[False] | None, inspect_arguments: bool | None, tail_sampling: TailSamplingOptions | None) -> None: ...
+    def configure(self, base_url: str | None, send_to_logfire: bool | Literal['if-token-present'] | None, token: str | None, project_name: str | None, service_name: str | None, service_version: str | None, trace_sample_rate: float | None, console: ConsoleOptions | Literal[False] | None, show_summary: bool | None, config_dir: Path | None, data_dir: Path | None, id_generator: IdGenerator | None, ns_timestamp_generator: Callable[[], int] | None, additional_span_processors: Sequence[SpanProcessor] | None, default_span_processor: Callable[[SpanExporter], SpanProcessor] | None, additional_metric_readers: Sequence[MetricReader] | None, pydantic_plugin: PydanticPlugin | None, fast_shutdown: bool, scrubbing: ScrubbingOptions | Literal[False] | None, inspect_arguments: bool | None, tail_sampling: TailSamplingOptions | None) -> None: ...
     def initialize(self) -> ProxyTracerProvider:
         """Configure internals to start exporting traces and metrics."""
     def force_flush(self, timeout_millis: int = 30000) -> bool:

logfire-api/logfire_api/_internal/config_params.pyi

@@ -9,7 +9,6 @@ from logfire.exceptions import LogfireConfigError as LogfireConfigError
 from pathlib import Path
 from typing import Any, Callable, TypeVar
 
-COLLECT_SYSTEM_METRICS_DEFAULT: bool
 T = TypeVar('T')
 slots_true: Incomplete
 PydanticPluginRecordValues: Incomplete
@@ -38,7 +37,6 @@ SERVICE_NAME: Incomplete
 SERVICE_VERSION: Incomplete
 SHOW_SUMMARY: Incomplete
 CREDENTIALS_DIR: Incomplete
-COLLECT_SYSTEM_METRICS: Incomplete
 CONSOLE: Incomplete
 CONSOLE_COLORS: Incomplete
 CONSOLE_SPAN_STYLE: Incomplete

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

@@ -0,0 +1,15 @@
+from _typeshed import Incomplete
+from opentelemetry.metrics import MeterProvider
+from typing import Any, Iterable
+
+MetricName: Incomplete
+ConfigString: Incomplete
+ConfigDict = dict[MetricName, Iterable[str] | None]
+Config: Incomplete
+CPU_FIELDS: Incomplete
+MEMORY_FIELDS: Incomplete
+DEFAULT_CONFIG: ConfigDict
+BASIC_METRICS: list[MetricName]
+
+def parse_config(config: Config) -> ConfigDict: ...
+def instrument_system_metrics(meter_provider: MeterProvider, config: Any = 'basic') -> None: ...

logfire-api/logfire_api/_internal/main.pyi

@@ -18,6 +18,7 @@ from .integrations.pymongo import PymongoInstrumentKwargs as PymongoInstrumentKw
 from .integrations.redis import RedisInstrumentKwargs as RedisInstrumentKwargs
 from .integrations.sqlalchemy import SQLAlchemyInstrumentKwargs as SQLAlchemyInstrumentKwargs
 from .integrations.starlette import StarletteInstrumentKwargs as StarletteInstrumentKwargs
+from .integrations.system_metrics import Config as SystemMetricsConfig
 from .json_encoder import logfire_json_dumps as logfire_json_dumps
 from .json_schema import JsonSchemaProperties as JsonSchemaProperties, attributes_json_schema as attributes_json_schema, attributes_json_schema_properties as attributes_json_schema_properties, create_json_schema as create_json_schema
 from .metrics import ProxyMeterProvider as ProxyMeterProvider
@@ -643,6 +644,12 @@ class Logfire:
             If a connection is provided, returns the instrumented connection. If no connection is provided, returns None.
 
         """
+    def instrument_system_metrics(self, config: SystemMetricsConfig = 'basic'):
+        """Instrument the system metrics.
+
+        Args:
+            config: The system metrics configuration.
+        """
     def metric_counter(self, name: str, *, unit: str = '', description: str = '') -> Counter:
         """Create a counter metric.
 

logfire-api/logfire_api/_internal/metrics.pyi

@@ -8,12 +8,6 @@ from typing import Any, Generic, Sequence, TypeVar
 from weakref import WeakSet
 
 Gauge: Incomplete
-CPU_FIELDS: Incomplete
-MEMORY_FIELDS: Incomplete
-DEFAULT_CONFIG: Incomplete
-INSTRUMENTOR: Incomplete
-
-def configure_metrics(meter_provider: MeterProvider) -> None: ...
 
 @dataclasses.dataclass
 class ProxyMeterProvider(MeterProvider):