logfire-api 4.40.0__tar.gz → 5.0.0__tar.gz

{logfire_api-4.40.0 → logfire_api-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: logfire-api
-Version: 4.40.0
+Version: 5.0.0
 Summary: Shim for the Logfire SDK which does nothing unless Logfire is installed
 Author-email: Pydantic Team <engineering@pydantic.dev>, Samuel Colvin <samuel@pydantic.dev>, Hasan Ramezani <hasan@pydantic.dev>, Adrian Garcia Badaracco <adrian@pydantic.dev>, David Montague <david@pydantic.dev>, Marcelo Trylesinski <marcelo@pydantic.dev>, David Hewitt <david.hewitt@pydantic.dev>, Alex Hall <alex@pydantic.dev>
 License-Expression: MIT

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/__init__.py

@@ -124,7 +124,8 @@ except ImportError:
             def with_settings(self, *args, **kwargs) -> Logfire:
                 return self
 
-            def force_flush(self, *args, **kwargs) -> None: ...
+            def force_flush(self, *args, **kwargs) -> bool:
+                return True
 
             def log_slow_async_callbacks(self, *args, **kwargs) -> None:  # pragma: no cover
                 return nullcontext()

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/cli/__init__.pyi

@@ -1,9 +1,15 @@
 import argparse
 from collections.abc import Sequence
-from typing import Any
+from typing import Any, NamedTuple
 
 __all__ = ['main', 'logfire_info']
 
+class SavedReadToken(NamedTuple):
+    token: str
+    base_url: str
+    organization: str
+    project_name: str
+
 def logfire_info() -> str:
     """Show versions of logfire, OS and related packages."""
 

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/cli/auth.pyi

@@ -2,6 +2,7 @@ import argparse
 from ...exceptions import LogfireConfigError as LogfireConfigError
 from ..auth import DEFAULT_FILE as DEFAULT_FILE, UserTokenCollection as UserTokenCollection, poll_for_token as poll_for_token, request_device_code as request_device_code
 from ..config import REGIONS as REGIONS
+from ..interactive import is_non_interactive as is_non_interactive, require_answer as require_answer
 
 def parse_auth(args: argparse.Namespace) -> None:
     """Authenticate with Logfire.

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/cli/gateway.pyi

@@ -1,5 +1,6 @@
 import argparse
 import httpx
+from ..interactive import require_answer as require_answer
 from .ai_tools import AiToolIntegration as AiToolIntegration, LOCAL_TOKEN_PLACEHOLDER as LOCAL_TOKEN_PLACEHOLDER, ai_tool_names as ai_tool_names, gateway_template_values as gateway_template_values, resolve_ai_tool as resolve_ai_tool
 from .gateway_auth import CimdOAuthClient as CimdOAuthClient, GATEWAY_CIMD_PATH as GATEWAY_CIMD_PATH, GatewayAuth as GatewayAuth, GatewayError as GatewayError, OAuthSession as OAuthSession, discover_oauth_metadata as discover_oauth_metadata
 from _typeshed import Incomplete

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/client.pyi

@@ -1,7 +1,9 @@
 from .auth import UserToken as UserToken, UserTokenCollection as UserTokenCollection
+from .constants import HTTP_CONNECT_TIMEOUT as HTTP_CONNECT_TIMEOUT
 from .server_response import ServerResponseCallback as ServerResponseCallback, install_logfire_response_hook as install_logfire_response_hook
 from .utils import UnexpectedResponse as UnexpectedResponse
 from _typeshed import Incomplete
+from datetime import datetime
 from logfire.exceptions import LogfireConfigError as LogfireConfigError
 from logfire.version import VERSION as VERSION
 from typing import Any
@@ -55,7 +57,12 @@ class LogfireClient:
         """
     def create_write_token(self, organization: str, project_name: str) -> dict[str, Any]:
         """Create a write token for the given project in the given organization."""
-    def create_read_token(self, organization: str, project_name: str) -> dict[str, Any]:
-        """Create a read token for the given project in the given organization."""
+    def create_read_token(self, organization: str, project_name: str, expires_at: datetime | None = None) -> dict[str, Any]:
+        """Create a read token for the given project in the given organization.
+
+        `expires_at` bounds how long the token stays valid. The CLI has no way to revoke
+        one, so a token it stores on disk gets an expiry; a token it prints for the caller
+        to place somewhere else does not, because we do not know what it was used for.
+        """
     def get_prompt(self, organization: str, project_name: str, issue: str) -> dict[str, Any]:
         """Get a prompt to be used with your favorite LLM."""

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/collect_system_info.pyi

@@ -5,5 +5,5 @@ def collect_package_info() -> dict[str, str]:
     """Retrieve the package information for all installed packages.
 
     Returns:
-        A dicts with the package name and version.
+        A dict with the package name and version.
     """

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/config.pyi

@@ -16,6 +16,7 @@ from .exporters.remove_pending import RemovePendingSpansExporter as RemovePendin
 from .exporters.test import TestExporter as TestExporter
 from .forwarding import OTLPForwardingManager as OTLPForwardingManager
 from .integrations.executors import instrument_executors as instrument_executors
+from .interactive import ask_or_default as ask_or_default, ask_required as ask_required, require_answer as require_answer
 from .logs import ProxyLoggerProvider as ProxyLoggerProvider
 from .main import Logfire as Logfire
 from .metrics import ProxyMeterProvider as ProxyMeterProvider
@@ -23,7 +24,7 @@ from .scrubbing import BaseScrubber as BaseScrubber, NOOP_SCRUBBER as NOOP_SCRUB
 from .server_response import ServerResponseCallback as ServerResponseCallback, install_logfire_response_hook as install_logfire_response_hook
 from .stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
 from .tracer import OPEN_SPANS as OPEN_SPANS, PendingSpanProcessor as PendingSpanProcessor, ProxyTracerProvider as ProxyTracerProvider
-from .utils import SeededRandomIdGenerator as SeededRandomIdGenerator, ensure_data_dir_exists as ensure_data_dir_exists, handle_internal_errors as handle_internal_errors, platform_is_emscripten as platform_is_emscripten, suppress_instrumentation as suppress_instrumentation
+from .utils import SeededRandomIdGenerator as SeededRandomIdGenerator, ensure_data_dir_exists as ensure_data_dir_exists, handle_internal_errors as handle_internal_errors, platform_is_aws_lambda as platform_is_aws_lambda, platform_is_emscripten as platform_is_emscripten, suppress_instrumentation as suppress_instrumentation
 from _typeshed import Incomplete
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
@@ -45,8 +46,8 @@ from opentelemetry.sdk.resources import ResourceDetector
 from opentelemetry.sdk.trace import SpanProcessor
 from opentelemetry.sdk.trace.id_generator import IdGenerator
 from pathlib import Path
-from typing import Any, ClassVar, Literal, TextIO, TypedDict
-from typing_extensions import Self, Unpack
+from typing import Any, ClassVar, Literal, TextIO
+from typing_extensions import Self
 
 CREDENTIALS_FILENAME: str
 COMMON_REQUEST_HEADERS: Incomplete
@@ -76,7 +77,12 @@ class AdvancedOptions:
     emit_configuration_span: bool | None = ...
     server_response_hook: ServerResponseCallback | None = ...
     resource_detectors: Sequence[ResourceDetector | str] | None = ...
-    def generate_base_url(self, token: str) -> str: ...
+    def generate_base_url(self, token: str, warn_unknown_region: bool = True) -> str:
+        """Resolve the base API URL for `token`, honouring an explicitly configured `base_url`.
+
+        Unknown regions warn by default. The background credential check opts out because the
+        synchronous exporter setup has already emitted the same warning.
+        """
 
 @dataclass
 class PydanticPlugin:
@@ -134,9 +140,7 @@ class LocalVariablesOptions:
     instrument: bool = ...
     template_mismatch_policy: TemplateMismatchPolicy = ...
 
-class DeprecatedKwargs(TypedDict): ...
-
-def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | list[str] | None = None, api_key: str | None = None, service_name: str | None = None, service_version: str | None = None, environment: str | None = None, resource_attributes: Mapping[str, Any] | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, min_level: int | LevelName | None = None, add_baggage_to_attributes: bool = True, code_source: CodeSource | None = None, variables: VariablesOptions | LocalVariablesOptions | None = None, distributed_tracing: bool | None = None, advanced: AdvancedOptions | None = None, **deprecated_kwargs: Unpack[DeprecatedKwargs]) -> Logfire:
+def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-present'] | None = None, token: str | list[str] | None = None, api_key: str | None = None, service_name: str | None = None, service_version: str | None = None, environment: str | None = None, resource_attributes: Mapping[str, Any] | None = None, console: ConsoleOptions | Literal[False] | None = None, config_dir: Path | str | None = None, data_dir: Path | str | None = None, additional_span_processors: Sequence[SpanProcessor] | None = None, metrics: MetricsOptions | Literal[False] | None = None, scrubbing: ScrubbingOptions | Literal[False] | None = None, inspect_arguments: bool | None = None, sampling: SamplingOptions | None = None, min_level: int | LevelName | None = None, add_baggage_to_attributes: bool = True, code_source: CodeSource | None = None, variables: VariablesOptions | LocalVariablesOptions | None = None, distributed_tracing: bool | None = None, advanced: AdvancedOptions | None = None) -> Logfire:
     """Configure the logfire SDK.
 
     Args:
@@ -192,7 +196,7 @@ def configure(*, local: bool = False, send_to_logfire: bool | Literal['if-token-
             or provide a `MetricsOptions` object to configure metrics, e.g. additional metric readers.
         scrubbing: Options for scrubbing sensitive data. Set to `False` to disable.
         inspect_arguments: Whether to enable
-            [f-string magic](https://logfire.pydantic.dev/docs/guides/onboarding-checklist/add-manual-tracing/#f-strings).
+            [f-string magic](https://pydantic.dev/docs/logfire/instrument/python/add-manual-tracing/#f-strings).
             If `None` uses the `LOGFIRE_INSPECT_ARGUMENTS` environment variable.
 
             Defaults to `True` if and only if the Python version is at least 3.11.
@@ -264,13 +268,13 @@ class LogfireConfig(_LogfireConfigData):
     def initialize(self) -> None:
         """Configure internals to start exporting traces and metrics."""
     def force_flush(self, timeout_millis: int = 30000) -> bool:
-        """Force flush all spans and metrics.
+        """Force flush all telemetry and forwarding pipelines.
 
         Args:
             timeout_millis: The timeout in milliseconds.
 
         Returns:
-            Whether the flush of spans was successful.
+            Whether every component that reports a status flushed successfully.
         """
     def shutdown(self, timeout_millis: int = 30000, flush: bool = True) -> bool:
         """Shut down variables, forwarding, traces, logs, and metrics."""
@@ -416,8 +420,15 @@ class LogfireCredentials:
     def print_token_summary(self) -> None:
         """Print a summary of the existing project."""
 
-def get_base_url_from_token(token: str) -> str:
-    """Get the base API URL from the token's region."""
+def get_base_url_from_token(token: str, warn_unknown_region: bool = True) -> str:
+    """Get the base API URL from the token's region.
+
+    Args:
+        token: The Logfire token to read the region from.
+        warn_unknown_region: Whether to emit a `LogfireConfigWarning` when the token's region is
+            unrecognised and the US region is used as a fallback. This is on by default for every
+            caller; disable it only when the same token has already produced the warning.
+    """
 def get_git_revision_hash() -> str:
     """Get the current git commit hash."""
 def sanitize_project_name(name: str) -> str:

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/constants.pyi

@@ -36,4 +36,5 @@ CONTEXT_ATTRIBUTES_KEY: Incomplete
 CONTEXT_SAMPLE_RATE_KEY: Incomplete
 MESSAGE_FORMATTED_VALUE_LENGTH_LIMIT: int
 ONE_SECOND_IN_NANOSECONDS: int
+HTTP_CONNECT_TIMEOUT: int
 ATTRIBUTES_EXCEPTION_FINGERPRINT_KEY: str

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/exporters/otlp.pyi

@@ -1,14 +1,17 @@
 import atexit
 import requests
-from ..utils import logger as logger, platform_is_emscripten as platform_is_emscripten
+from ..constants import ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, HTTP_CONNECT_TIMEOUT as HTTP_CONNECT_TIMEOUT, OTLP_MAX_INT_SIZE as OTLP_MAX_INT_SIZE, log_level_attributes as log_level_attributes
+from ..stack_info import STACK_INFO_KEYS as STACK_INFO_KEYS
+from ..utils import logger as logger, platform_is_emscripten as platform_is_emscripten, truncate_string as truncate_string
 from .wrapper import WrapperLogExporter as WrapperLogExporter, WrapperSpanExporter as WrapperSpanExporter
 from _typeshed import Incomplete
 from collections import deque
 from collections.abc import Mapping, Sequence
 from functools import cached_property
+from logfire._internal.utils import handle_internal_errors as handle_internal_errors
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
 from opentelemetry.sdk._logs import ReadableLogRecord as ReadableLogRecord
-from opentelemetry.sdk.trace import ReadableSpan as ReadableSpan
+from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExportResult
 from pathlib import Path
 from requests import Session
@@ -25,6 +28,7 @@ class BodySizeCheckingOTLPSpanExporter(OTLPSpanExporter):
 
 class OTLPExporterHttpSession(Session):
     """A requests.Session subclass that defers failed requests to a DiskRetryer."""
+    def request(self, method: str, url: str, **kwargs: Any): ...
     def post(self, url: str, data: bytes, **kwargs: Any): ...
     @cached_property
     def retryer(self) -> DiskRetryer: ...
@@ -59,7 +63,7 @@ class RetryFewerSpansSpanExporter(WrapperSpanExporter):
 class BodyTooLargeError(Exception):
     size: Incomplete
     max_size: Incomplete
-    def __init__(self, size: int, max_size: int) -> None: ...
+    def __init__(self, size: int, max_size: int | None) -> None: ...
 
 class SuppressedConnectionError(Exception): ...
 

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/forwarding.pyi

@@ -4,14 +4,16 @@ from collections.abc import Callable as Callable, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
 from logfire._internal.exporters.otlp import OTLPExporterHttpSession as OTLPExporterHttpSession
+from logfire._internal.main import Logfire as Logfire
 from logfire._internal.server_response import install_logfire_response_hook as install_logfire_response_hook
 from logfire._internal.utils import suppress_instrumentation as suppress_instrumentation
-from logfire.experimental.forwarding import ForwardExportRequestResponse as ForwardExportRequestResponse
 from logfire.types import ServerResponseCallback as ServerResponseCallback
 from logfire.version import VERSION as VERSION
 from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import ExportLogsServiceResponse
 from opentelemetry.proto.collector.metrics.v1.metrics_service_pb2 import ExportMetricsServiceResponse
 from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceResponse
+from starlette.requests import Request
+from starlette.responses import Response
 from threading import Thread
 from typing import Literal
 
@@ -48,6 +50,13 @@ class ForwardingErrorResponse:
     status_code: int
     content: bytes
 
+@dataclass
+class ForwardExportRequestResponse:
+    """Response returned from a forwarded export request to Logfire."""
+    status_code: int
+    headers: Mapping[str, str]
+    content: bytes
+
 @dataclass(frozen=True)
 class ForwardingAdmissionResult:
     response: Literal['success', 'partial_success']
@@ -81,5 +90,15 @@ class OTLPForwardingManager:
 
 def parse_forwarding_content_type(content_type: str) -> ForwardingContentType | None: ...
 def build_forwarding_request(*, path: str, headers: Mapping[str, str], body: bytes, max_body_size: int = ...) -> ForwardingRequest | ForwardingErrorResponse: ...
+def forward_export_request(*, path: str, headers: Mapping[str, str], body: bytes, logfire_instance: Logfire | None = None, max_body_size: int = ...) -> ForwardExportRequestResponse:
+    """Forward an export request to the Logfire API.
+
+    See the Logfire.forward_export_request method for more details.
+    """
+async def logfire_proxy(request: Request, *, logfire_instance: Logfire | None = None, max_body_size: int = ...) -> Response:
+    """A Starlette/FastAPI handler to proxy requests to Logfire.
+
+    See the Logfire.forward_export_request_starlette method for more details.
+    """
 def build_success_response(request: ForwardingRequest) -> ForwardExportRequestResponse: ...
 def build_partial_success_response(request: ForwardingRequest, *, message: str) -> ForwardExportRequestResponse: ...

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/integrations/claude_agent_sdk.pyi

@@ -4,6 +4,7 @@ from claude_agent_sdk.types import HookContext, SyncHookJSONOutput
 from contextlib import AbstractContextManager
 from logfire._internal.integrations.llm_providers.semconv import CONVERSATION_ID as CONVERSATION_ID, ChatMessage as ChatMessage, ERROR_TYPE as ERROR_TYPE, INPUT_MESSAGES as INPUT_MESSAGES, MessagePart as MessagePart, OPERATION_NAME as OPERATION_NAME, OUTPUT_MESSAGES as OUTPUT_MESSAGES, OutputMessage as OutputMessage, PROVIDER_NAME as PROVIDER_NAME, REQUEST_MODEL as REQUEST_MODEL, RESPONSE_MODEL as RESPONSE_MODEL, ReasoningPart as ReasoningPart, SYSTEM as SYSTEM, SYSTEM_INSTRUCTIONS as SYSTEM_INSTRUCTIONS, TOOL_CALL_ARGUMENTS as TOOL_CALL_ARGUMENTS, TOOL_CALL_ID as TOOL_CALL_ID, TOOL_CALL_RESULT as TOOL_CALL_RESULT, TOOL_NAME as TOOL_NAME, TextPart as TextPart, ToolCallPart as ToolCallPart, ToolCallResponsePart as ToolCallResponsePart
 from logfire._internal.main import Logfire as Logfire, LogfireSpan as LogfireSpan
+from logfire._internal.stack_info import get_user_stack_info as get_user_stack_info
 from logfire._internal.utils import handle_internal_errors as handle_internal_errors
 from typing import Any
 
@@ -35,7 +36,19 @@ class _ConversationState:
     root_span: Incomplete
     active_tool_spans: dict[str, LogfireSpan]
     model: str | None
+    announced_tool_ids: set[str]
+    tool_announcement_timeout: float
+    code_attrs: Incomplete
     def __init__(self, *, logfire: Logfire, root_span: LogfireSpan, input_messages: list[ChatMessage], system_instructions: list[TextPart] | None = None) -> None: ...
+    async def wait_for_tool_announcement(self, tool_use_id: str) -> None:
+        """Wait until the assistant message announcing `tool_use_id` has been handled.
+
+        The CLI sends the assistant message (containing the `tool_use` block) before it
+        invokes the PreToolUse hook, but hooks run in separate anyio tasks, so the hook
+        can be scheduled before the main task has applied that message to this state.
+        Closing the chat span at that point would lose its output and model attributes.
+        The timeout is a safety valve for tool calls that are never announced.
+        """
     def add_tool_result(self, tool_use_id: str, tool_name: str, result: Any) -> None:
         """Record a tool result to include in the next chat span's input messages."""
     def open_chat_span(self) -> None:

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/integrations/flask.pyi

@@ -1,5 +1,4 @@
 from flask.app import Flask
-from logfire._internal.stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
 from logfire._internal.utils import maybe_capture_server_headers as maybe_capture_server_headers
 from logfire.integrations.flask import CommenterOptions as CommenterOptions, RequestHook as RequestHook, ResponseHook as ResponseHook
 from typing import Any

logfire_api-5.0.0/logfire_api/_internal/integrations/google_genai.pyi

@@ -0,0 +1,12 @@
+import logfire
+from _typeshed import Incomplete
+from logfire._internal.utils import safe_repr as safe_repr
+from typing import Any
+
+CAPTURE_MESSAGE_CONTENT_ENV_VAR: str
+LEGACY_CAPTURE_MESSAGE_CONTENT_VALUES: Incomplete
+EMIT_EVENT_ENV_VAR: str
+original_flatten_compound_value: Incomplete
+
+def wrapped_flatten_compound_value(key: str, value: Any, *args: Any, **kwargs: Any): ...
+def instrument_google_genai(logfire_instance: logfire.Logfire, **kwargs: Any): ...

{logfire_api-4.40.0 → logfire_api-5.0.0}/logfire_api/_internal/integrations/openai_agents.pyi

@@ -7,7 +7,7 @@ from agents.tracing.spans import SpanError, TSpanData
 from dataclasses import dataclass
 from logfire import Logfire as Logfire, LogfireSpan as LogfireSpan
 from logfire._internal.formatter import logfire_format as logfire_format
-from logfire._internal.integrations.llm_providers.openai import inputs_to_events as inputs_to_events, responses_output_events as responses_output_events
+from logfire._internal.integrations.llm_providers.openai import get_openai_usage_attributes as get_openai_usage_attributes, inputs_to_events as inputs_to_events, responses_output_events as responses_output_events
 from logfire._internal.scrubbing import NOOP_SCRUBBER as NOOP_SCRUBBER
 from logfire._internal.utils import handle_internal_errors as handle_internal_errors, log_internal_error as log_internal_error, truncate_string as truncate_string
 from openai.types.responses import Response
@@ -29,6 +29,7 @@ class LogfireTraceProviderWrapper:
 class LogfireSpanHelper:
     span: LogfireSpan
     parent: Trace | Span[Any] | None = ...
+    openai_cost_provider_url: str | None = ...
     def start(self, mark_as_current: bool): ...
     def end(self, reset_current: bool): ...
     def maybe_detach(self, reset_current: bool): ...
@@ -94,7 +95,7 @@ class LogfireSpanWrapper(LogfireWrapperBase[Span[TSpanData]], Span[TSpanData]):
     @property
     def tracing_api_key(self) -> str | None: ...
 
-def attributes_from_span_data(span_data: SpanData, msg_template: str) -> dict[str, Any]: ...
+def attributes_from_span_data(span_data: SpanData, msg_template: str, openai_cost_provider_url: str | None = None) -> dict[str, Any]: ...
 def get_basic_response_attributes(response: Response): ...
-def get_magic_response_attributes() -> dict[str, Any]: ...
+def get_magic_response_attributes() -> tuple[dict[str, Any], str | None]: ...
 def get_response_span_events(span: ResponseSpanData): ...

logfire_api-5.0.0/logfire_api/_internal/integrations/system_metrics.pyi

@@ -0,0 +1,49 @@
+from _typeshed import Incomplete
+from collections.abc import Iterable
+from logfire import Logfire as Logfire
+from typing import Literal
+from typing_extensions import LiteralString
+
+MetricName: type[Literal['system.cpu.simple_utilization', 'system.cpu.time', 'system.cpu.utilization', 'system.cpu.load_average.1m', 'system.memory.usage', 'system.memory.utilization', 'system.swap.usage', 'system.swap.utilization', 'system.disk.io', 'system.disk.operations', 'system.disk.time', 'system.network.dropped.packets', 'system.network.packets', 'system.network.errors', 'system.network.io', 'system.network.connections', 'system.process.count', 'system.thread_count', 'process.open_file_descriptor.count', 'process.context_switches', 'process.cpu.time', 'process.cpu.utilization', 'process.cpu.core_utilization', 'process.disk.io', 'process.memory.usage', 'process.memory.virtual', 'process.thread.count', 'process.runtime.gc_count', 'cpython.gc.collected_objects', 'cpython.gc.collections', 'cpython.gc.uncollectable_objects']]
+Config = dict[MetricName, Iterable[str] | None]
+CPU_FIELDS: list[LiteralString]
+MEMORY_FIELDS: list[LiteralString]
+FULL_CONFIG: Config
+BASIC_CONFIG: Config
+Base: Incomplete
+
+def get_base_config(base: Base) -> Config: ...
+def instrument_system_metrics(logfire_instance: Logfire, config: Config | None = None, base: Base = 'basic'): ...
+def measure_simple_cpu_utilization(logfire_instance: Logfire): ...
+def measure_process_runtime_cpu_utilization(logfire_instance: Logfire): ...
+def measure_process_cpu_utilization(logfire_instance: Logfire): ...
+def measure_process_cpu_core_utilization(logfire_instance: Logfire):
+    """Same as process.cpu.utilization, but not divided by the number of available cores."""
+def measure_system_cpu_load_average_1m(logfire_instance: Logfire):
+    """1-minute system load average.
+
+    OTel semconv defines no load average metric. The system metrics spec only
+    floats `system.linux.cpu.load_1m` as a hypothetical illustration of OS-prefixed
+    naming, so there's nothing to conform to. The name, gauge instrument, and
+    `{thread}` unit here match the OTel Collector's `hostmetrics` load scraper,
+    which is where most host load averages reaching Logfire come from. Matching it
+    means SDK-reported and Collector-reported hosts land on one series instead of two.
+
+    Upstream `SystemMetricsInstrumentor` doesn't emit this. On Windows,
+    `psutil.getloadavg()` is an emulated polling shim — the first call returns 0
+    and subsequent values update every ~5s.
+    """
+def measure_system_process_count(logfire_instance: Logfire):
+    """Total number of processes on the system.
+
+    Name, instrument, and unit follow OTel semconv's `system.process.count`
+    (an UpDownCounter in `{process}`). Its `process.state` attribute is omitted:
+    `psutil.pids()` is a single cheap syscall, while splitting by state needs a
+    `process_iter` over every process and multiplies the series count. This metric
+    is in the basic base, so that cost would land on every default install.
+
+    Note that the OTel Collector's `hostmetrics` receiver still emits the older
+    `system.processes.count` for the same measurement.
+
+    Upstream `SystemMetricsInstrumentor` doesn't emit this.
+    """

logfire_api-5.0.0/logfire_api/_internal/interactive.pyi

@@ -0,0 +1,53 @@
+from collections.abc import Callable
+from logfire.exceptions import LogfireConfigError as LogfireConfigError
+from typing import TypeVar
+
+T = TypeVar('T')
+
+class NonInteractiveError(LogfireConfigError):
+    """A prompt was needed, but nobody could answer it.
+
+    Carries the guidance the user needs rather than a traceback: the CLI catches this and
+    prints `message` before exiting non-zero. Raised either because `--non-interactive`
+    said so up front (`require_answer`), or because stdin ran out before an answer arrived
+    (`ask_required`) -- the same question/remedy structure either way (only the reason
+    line differs), since both mean the same thing to whoever reads it.
+    """
+
+def set_non_interactive(value: bool) -> None:
+    """Record whether prompts are allowed. Called once, from CLI argument parsing."""
+def is_non_interactive() -> bool:
+    """Whether the caller declared that it cannot answer prompts."""
+def require_answer(question: str, remedy: str, *more_remedies: str) -> None:
+    """Fail instead of prompting, when the caller said it cannot answer.
+
+    At least one remedy is required by the signature: refusing to prompt while offering no
+    way forward just moves the dead end, and telling the caller what to pass is the entire
+    value of failing here rather than blocking.
+
+    Args:
+        question: what would have been asked, in plain terms.
+        remedy: a runnable suggestion.
+        more_remedies: further suggestions. Each is printed on its own line, so each must
+            be individually pasteable -- `--org a|b` is a shell pipeline, not a suggestion.
+    """
+def ask_or_default(ask: Callable[[], T], default: T) -> T:
+    '''Run a prompt, falling back to `default` when stdin runs out before an answer does.
+
+    Mirrors accepting a blank Enter keypress: the caller already declared what "no answer"
+    means by passing this SAME value as the prompt\'s own `default=`, so an exhausted stdin
+    reaches the outcome a person pressing Enter would, rather than an `EOFError` traceback.
+    Only for prompts where that default is genuinely safe to assume -- see `ask_required`
+    for one that has no safe default to fall back on.
+    '''
+def ask_required(ask: Callable[[], T], question: str, remedy: str, *more_remedies: str) -> T:
+    """Run a prompt that has no safe default, raising if stdin runs out before an answer does.
+
+    The reactive half of `require_answer`'s proactive check: that covers a caller who
+    declared `--non-interactive` up front, this covers one that did not but ran out of
+    input anyway -- a command copied out of the docs into an agent, mid-conversation.
+    Raises the same `NonInteractiveError` structure `require_answer` would -- question,
+    then reason, then remedies -- with a reason line naming stdin instead of the flag,
+    since both mean the same thing to whoever reads it: there was no answer, and here is
+    how to supply one.
+    """