modal 1.6.2.dev4__py3-none-any.whl → 1.6.2.dev5__py3-none-any.whl

modal/__init__.py

@@ -43,11 +43,11 @@ try:
     from .queue import Queue
     from .retries import Retries
     from .sandbox import Probe, Sandbox
+    from .sandbox.sandbox import SandboxSnapshot
     from .schedule import Cron, Period
     from .scheduler_placement import SchedulerPlacement
     from .secret import Secret
     from .server import Server
-    from .snapshot import SandboxSnapshot
     from .volume import Volume
     from .workspace import Workspace
 except Exception:

modal/_functions.py

@@ -27,6 +27,7 @@ from ._image import _Image
 from ._load_context import LoadContext
 from ._logs import LogsFilters
 from ._logs_manager import _FunctionCallLogsManager, _FunctionLogsManager
+from ._metrics import _FunctionMetricsManager
 from ._object import _Object, live_method, live_method_gen
 from ._output.pty import get_pty_info
 from ._output.status import FunctionCreationStatus
@@ -661,6 +662,11 @@ class _Function(typing.Generic[P, ReturnType, OriginalReturnType], _Object, type
             source_object_id=self.object_id,
         )
 
+    @property
+    def metrics(self) -> "_FunctionMetricsManager":
+        """Access metric samples with `export()` and series definitions with `schema()`."""
+        return _FunctionMetricsManager(self)
+
     @property
     def logs(self) -> _FunctionLogsManager:
         """Access logs for a `Function`.

modal/_logs.py

@@ -3,9 +3,9 @@ from __future__ import annotations
 
 import asyncio
 import dataclasses
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Awaitable, Callable
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Sequence, TypeVar
 
 from google.protobuf.timestamp_pb2 import Timestamp
 
@@ -13,6 +13,9 @@ from modal._utils.async_utils import TaskContext
 from modal.exception import LogsFetchError
 from modal_proto import api_pb2
 
+_T = TypeVar("_T")
+_CountRanges = Callable[[float, float, int], Awaitable[list[tuple[float, float, int]]]]
+
 if TYPE_CHECKING:
     from modal.client import _Client
 
@@ -194,6 +197,32 @@ def _next_smaller_bucket_secs(current_bucket_secs: int) -> int | None:
     return None
 
 
+async def _count_log_ranges(
+    client: _Client,
+    app_id: str,
+    since: float,
+    until: float,
+    bucket_secs: int,
+    filters: LogsFilters,
+) -> list[tuple[float, float, int]]:
+    count_req = api_pb2.AppCountLogsRequest(
+        app_id=app_id,
+        since=_seconds_to_timestamp(since),
+        until=_seconds_to_timestamp(until),
+        bucket_secs=bucket_secs,
+        source=filters.source,
+        function_id=filters.function_id,
+        parametrized_function_id=filters.parametrized_function_id,
+        function_call_id=filters.function_call_id,
+        task_id=filters.task_id,
+        sandbox_id=filters.sandbox_id,
+        search_text=filters.search_text,
+    )
+    count_resp: api_pb2.AppCountLogsResponse = await client._stub.AppCountLogs(count_req)
+
+    return _buckets_to_ranges(list(count_resp.buckets), bucket_secs)
+
+
 async def _refine_dense_ranges(
     client: _Client,
     app_id: str,
@@ -201,6 +230,19 @@ async def _refine_dense_ranges(
     filters: LogsFilters,
     max_ranges: int,
     max_iterations: int,
+) -> list[tuple[float, float, int]]:
+    async def count_ranges(start: float, end: float, bucket_secs: int) -> list[tuple[float, float, int]]:
+        return await _count_log_ranges(client, app_id, start, end, bucket_secs, filters)
+
+    return await _refine_ranges(ranges, count_ranges, max_ranges, max_iterations)
+
+
+async def _refine_ranges(
+    ranges: list[tuple[float, float, int]],
+    count_ranges: _CountRanges,
+    max_ranges: int,
+    max_iterations: int,
+    max_concurrent_counts: int = _MAX_CONCURRENT_COUNTS,
 ) -> list[tuple[float, float, int]]:
     """Refine ranges exceeding _FETCH_LIMIT by subdividing with smaller buckets.
 
@@ -239,25 +281,11 @@ async def _refine_dense_ranges(
             break
 
         # Fire off all re-count RPCs in parallel with bounded concurrency
-        semaphore = asyncio.Semaphore(_MAX_CONCURRENT_COUNTS)
+        semaphore = asyncio.Semaphore(max_concurrent_counts)
 
         async def _recount(start: float, end: float, smaller_secs: int) -> list[tuple[float, float, int]]:
             async with semaphore:
-                sub_req = api_pb2.AppCountLogsRequest(
-                    app_id=app_id,
-                    since=_seconds_to_timestamp(start),
-                    until=_seconds_to_timestamp(end),
-                    bucket_secs=smaller_secs,
-                    source=filters.source,
-                    function_id=filters.function_id,
-                    parametrized_function_id=filters.parametrized_function_id,
-                    function_call_id=filters.function_call_id,
-                    task_id=filters.task_id,
-                    sandbox_id=filters.sandbox_id,
-                    search_text=filters.search_text,
-                )
-                sub_resp = await client._stub.AppCountLogs(sub_req)
-                sub_ranges = _buckets_to_ranges(list(sub_resp.buckets), smaller_secs)
+                sub_ranges = await count_ranges(start, end, smaller_secs)
                 # Clamp the edge sub-ranges to the parent boundaries. Bucket
                 # alignment can make the first bucket begin before the parent
                 # (e.g. parent (6,12) with 4s buckets produces (4,8)) or make
@@ -418,26 +446,34 @@ async def fetch_logs(
 
     if until - since > _MAX_FETCH_RANGE:
         raise LogsFetchError(f"Time range cannot exceed {_MAX_FETCH_RANGE.days} days.")
-    # Phase 1: Count logs per bucket
-    bucket_secs = _pick_bucket_secs(since, until)
-    count_req = api_pb2.AppCountLogsRequest(
-        app_id=app_id,
-        since=_datetime_to_timestamp(since),
-        until=_datetime_to_timestamp(until),
-        bucket_secs=bucket_secs,
-        source=filters.source,
-        function_id=filters.function_id,
-        parametrized_function_id=filters.parametrized_function_id,
-        function_call_id=filters.function_call_id,
-        task_id=filters.task_id,
-        sandbox_id=filters.sandbox_id,
-        search_text=filters.search_text,
-    )
-    count_resp: api_pb2.AppCountLogsResponse = await client._stub.AppCountLogs(count_req)
 
-    ranges = _buckets_to_ranges(list(count_resp.buckets), bucket_secs)
-    total_logs = sum(count for _, _, count in ranges)
-    if total_logs == 0:
+    async def count_ranges(start: float, end: float, bucket_secs: int) -> list[tuple[float, float, int]]:
+        return await _count_log_ranges(client, app_id, start, end, bucket_secs, filters)
+
+    async def fetch_interval(start: float, end: float, limit: int) -> list[api_pb2.TaskLogsBatch]:
+        return await _fetch_interval(client, app_id, start, end, limit, filters)
+
+    async for batch in _fetch_time_range(
+        since,
+        until,
+        count_ranges,
+        fetch_interval,
+    ):
+        yield batch
+
+
+async def _fetch_time_range(
+    since: datetime,
+    until: datetime,
+    count_ranges: _CountRanges,
+    fetch_interval: Callable[[float, float, int], Awaitable[Sequence[_T]]],
+    *,
+    max_concurrent_counts: int = _MAX_CONCURRENT_COUNTS,
+) -> AsyncGenerator[_T]:
+    """Count, refine, and fetch time intervals with bounded concurrency and ordered results."""
+    ranges = await count_ranges(since.timestamp(), until.timestamp(), _pick_bucket_secs(since, until))
+    total_records = sum(count for _, _, count in ranges)
+    if total_records == 0:
         return
 
     # Trim leading/trailing empty buckets so they don't consume refinement
@@ -449,19 +485,17 @@ async def fetch_logs(
 
     # Phase 1b: Refine any ranges that exceed the per-fetch limit.
     # Budget: at most _MAX_FETCHES intervals, each fetching up to _FETCH_LIMIT entries.
-    ranges = await _refine_dense_ranges(
-        client,
-        app_id,
+    ranges = await _refine_ranges(
         ranges,
-        filters,
+        count_ranges,
         max_ranges=_MAX_FETCHES,
         max_iterations=_MAX_REFINE_ITERATIONS,
+        max_concurrent_counts=max_concurrent_counts,
     )
-    fetch_error_message = "Too many logs to fetch in time range. Consider narrowing the range or adding filters."
     # Check that all ranges fit within the per-fetch limit.
     over_limit = [r for r in ranges if r[2] > _FETCH_LIMIT]
     if over_limit:
-        raise LogsFetchError(fetch_error_message)
+        raise LogsFetchError("Too many logs to fetch in time range. Consider narrowing the range or adding filters.")
 
     # Phase 2: Build intervals from non-empty ranges and fetch in parallel
     since_secs = since.timestamp()
@@ -476,24 +510,17 @@ async def fetch_logs(
         return
 
     if len(intervals) > _MAX_FETCHES:
-        raise LogsFetchError(fetch_error_message)
+        raise LogsFetchError("Too many logs to fetch in time range. Consider narrowing the range or adding filters.")
 
     # Fetch all intervals concurrently (bounded by semaphore), but yield
-    # results in interval order so logs stay chronological. Awaiting each
+    # results in interval order so records stay chronological. Awaiting each
     # task in sequence lets us stream batches to the caller as soon as all
     # preceding intervals have completed.
     semaphore = asyncio.Semaphore(_MAX_CONCURRENT_FETCHES)
 
-    async def _bounded_fetch(since_s: float, until_s: float) -> list[api_pb2.TaskLogsBatch]:
+    async def _bounded_fetch(since_s: float, until_s: float) -> Sequence[_T]:
         async with semaphore:
-            return await _fetch_interval(
-                client,
-                app_id,
-                since_s,
-                until_s,
-                _FETCH_LIMIT,
-                filters,
-            )
+            return await fetch_interval(since_s, until_s, _FETCH_LIMIT)
 
     tasks = [asyncio.create_task(_bounded_fetch(s, u)) for s, u in intervals]
 
@@ -504,3 +531,4 @@ async def fetch_logs(
     finally:
         for task in tasks:
             task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)

modal/_metrics.py

@@ -0,0 +1,212 @@
+# Copyright Modal Labs 2026
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from modal_proto import api_pb2
+
+from ._object import _Object
+from ._utils.async_utils import synchronize_api
+from .exception import InvalidError
+from .types import MetricDefinition, MetricSeries, MetricsSchema, ObjectMetrics, TimeSeriesPoint
+
+
+def _metrics_request(
+    since: datetime | None, until: datetime | None, bucket_size: timedelta | None, groups: list[str] | None
+) -> api_pb2.FunctionGetMetricsRequest:
+    until = (until or datetime.now(timezone.utc)).astimezone(timezone.utc)
+    since = (since or until - timedelta(hours=1)).astimezone(timezone.utc)
+    if since >= until:
+        raise InvalidError("`since` must be before `until`.")
+    if since.timestamp() < 0:
+        raise InvalidError("`since` must be at or after the Unix epoch.")
+    if until - since > timedelta(days=31):
+        raise InvalidError("Metrics time range cannot exceed 31 days.")
+    if groups is not None and (not isinstance(groups, list) or any(not isinstance(g, str) or not g for g in groups)):
+        raise InvalidError("`groups` must be a list of nonempty group names.")
+    request = api_pb2.FunctionGetMetricsRequest(groups=groups or [])
+    request.since.FromDatetime(since)
+    request.until.FromDatetime(until)
+    if bucket_size is not None:
+        if not isinstance(bucket_size, timedelta):
+            raise InvalidError("`bucket_size` must be a timedelta.")
+        seconds = bucket_size.total_seconds()
+        if not seconds.is_integer() or not 60 <= seconds <= 2**32 - 1:
+            raise InvalidError("`bucket_size` must be a whole number of seconds, at least one minute.")
+        request.bucket_secs = int(seconds)
+        if int(until.timestamp()) // request.bucket_secs - int(since.timestamp()) // request.bucket_secs > 500:
+            raise InvalidError("Metrics are limited to 500 points per series; increase `bucket_size`.")
+    return request
+
+
+def _object_metrics(
+    object_id: str, response: api_pb2.FunctionGetMetricsResponse | api_pb2.ServerGetMetricsResponse
+) -> ObjectMetrics:
+    series = {
+        item.name: MetricSeries(
+            name=item.name,
+            unit=item.unit,
+            aggregation=item.name.rsplit("_", 1)[-1],
+            description=item.description,
+            points=[
+                TimeSeriesPoint(
+                    time=point.timestamp.ToDatetime(tzinfo=timezone.utc),
+                    value=point.value if point.HasField("value") else None,
+                )
+                for point in item.points
+            ],
+        )
+        for item in response.series
+    }
+    return ObjectMetrics(
+        object_id=object_id,
+        since=response.since.ToDatetime(tzinfo=timezone.utc),
+        until=response.until.ToDatetime(tzinfo=timezone.utc),
+        bucket_size=timedelta(seconds=response.bucket_secs),
+        point_count=sum(len(item.points) for item in series.values()),
+        series=series,
+    )
+
+
+class _MetricsManager:
+    """mdmd:namespace"""
+
+    def __init__(self, function: _Object, *, is_server: bool):
+        """mdmd:hidden"""
+        self._function = function
+        self._is_server = is_server
+
+    async def schema(self, groups: list[str] | None = None) -> dict[str, MetricsSchema]:
+        """Return metric definitions keyed by group name without fetching samples.
+
+        Omit `groups` to list all groups. Each group contains its exact individual
+        series definitions.
+        """
+        response = await self._schema(groups=groups)
+        schema: dict[str, MetricsSchema] = {}
+        for row in response.groups:
+            if row.name not in schema:
+                schema[row.name] = MetricsSchema(name=row.name, definitions=[])
+            schema[row.name].definitions.extend(
+                MetricDefinition(name=m.name, unit=m.unit, description=m.description) for m in row.metrics
+            )
+        return schema
+
+    async def _schema(
+        self,
+        *,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        bucket_size: timedelta | None = None,
+        groups: list[str] | None = None,
+    ) -> api_pb2.MetricsGetInfoResponse:
+        """Fetch schema rows and resolved bucket metadata for a preview window."""
+        window = _metrics_request(since, until, bucket_size, groups)
+        await self._function.hydrate()
+        target = api_pb2.MetricsGetInfoRequest
+        request = target(
+            target_type=target.METRICS_TARGET_TYPE_SERVER if self._is_server else target.METRICS_TARGET_TYPE_FUNCTION,
+            since=window.since,
+            until=window.until,
+            groups=groups,
+        )
+        if window.HasField("bucket_secs"):
+            request.bucket_secs = window.bucket_secs
+        return await self._function.client._stub.MetricsGetInfo(request)
+
+    async def _export(
+        self,
+        since: datetime | None,
+        until: datetime | None,
+        bucket_size: timedelta | None,
+        groups: list[str] | None,
+        all_variants: bool = False,
+    ) -> ObjectMetrics:
+        request = _metrics_request(since, until, bucket_size, groups)
+        await self._function.hydrate()
+        request.function_id = self._function.object_id
+        if self._is_server:
+            server_request = api_pb2.ServerGetMetricsRequest(
+                function_id=request.function_id,
+                since=request.since,
+                until=request.until,
+                groups=request.groups,
+            )
+            if request.HasField("bucket_secs"):
+                server_request.bucket_secs = request.bucket_secs
+            response = await self._function.client._stub.ServerGetMetrics(server_request)
+        else:
+            request.rollup = all_variants
+            response = await self._function.client._stub.FunctionGetMetrics(request)
+        return _object_metrics(self._function.object_id, response)
+
+
+class _FunctionMetricsManager(_MetricsManager):
+    """mdmd:namespace"""
+
+    def __init__(self, function: _Object):
+        """mdmd:hidden"""
+        super().__init__(function, is_server=False)
+
+    async def export(
+        self,
+        *,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        bucket_size: timedelta | None = None,
+        groups: list[str] | None = None,
+        all_variants: bool = False,
+    ) -> ObjectMetrics:
+        """Fetch metric samples for a Function.
+
+        Defaults to all groups over the last hour. `since` defaults to one hour
+        before `until`; naive datetimes use local time. The maximum range is 31
+        days, with at most 500 points per series. If `bucket_size` is omitted,
+        Modal selects a supported width targeting approximately 100 buckets.
+        Bounds round down to UTC bucket boundaries, so data before `since` may
+        be included and the partial bucket at `until` is excluded.
+
+        Set `all_variants=True` to include the root Function and its variants.
+        Missing observations have value None. Use `schema()` to discover
+        group names and series definitions without fetching samples.
+
+        ```python notest
+        metrics = function.metrics.export(bucket_size=timedelta(minutes=5), groups=["calls"])
+        for point in metrics["successful_calls_count"].points:
+            print(point.time, point.value)
+        ```
+        """
+        return await self._export(since, until, bucket_size, groups, all_variants)
+
+
+class _ServerMetricsManager(_MetricsManager):
+    """mdmd:namespace"""
+
+    def __init__(self, function: _Object):
+        """mdmd:hidden"""
+        super().__init__(function, is_server=True)
+
+    async def export(
+        self,
+        *,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        bucket_size: timedelta | None = None,
+        groups: list[str] | None = None,
+    ) -> ObjectMetrics:
+        """Fetch metric samples for a Server.
+
+        Defaults to all groups over the last hour. `since` defaults to one hour
+        before `until`; naive datetimes use local time. The maximum range is 31
+        days, with at most 500 points per series. Omit `bucket_size` for automatic
+        sizing. Bounds round down to UTC bucket boundaries; the partial bucket
+        at `until` is excluded. Missing observations have value None.
+
+        Use `schema()` to discover groups and series without fetching samples.
+        """
+        return await self._export(since, until, bucket_size, groups)
+
+
+MetricsManager = synchronize_api(_MetricsManager, target_module=__name__)
+FunctionMetricsManager = synchronize_api(_FunctionMetricsManager, target_module=__name__)
+ServerMetricsManager = synchronize_api(_ServerMetricsManager, target_module=__name__)