modal 0.11.1-dev.14 → 0.11.1-dev.15

package/dist/index.cjs

@@ -51,6 +51,7 @@ __export(index_exports, {
   FunctionCallLogsManager: () => FunctionCallLogsManager,
   FunctionCallService: () => FunctionCallService,
   FunctionLogsManager: () => FunctionLogsManager,
+  FunctionMetricsManager: () => FunctionMetricsManager,
   FunctionService: () => FunctionService,
   FunctionTimeoutError: () => FunctionTimeoutError,
   Function_: () => Function_,
@@ -67635,11 +67636,40 @@ var TimeoutError = class extends Error {
     this.name = "TimeoutError";
   }
 };
-var FunctionTimeoutError = class extends Error {
+var FunctionTimeoutError = class _FunctionTimeoutError extends Error {
   constructor(message) {
     super(message);
     this.name = "FunctionTimeoutError";
   }
+  // Backward compatibility: FunctionCall.get() wait timeouts still match
+  // FunctionTimeoutError, with a deprecation warning.
+  static [Symbol.hasInstance](instance) {
+    if (Function.prototype[Symbol.hasInstance].call(this, instance)) {
+      return true;
+    }
+    if (this === _FunctionTimeoutError && instance instanceof FunctionCallGetTimeoutError) {
+      instance.warnFunctionTimeoutErrorMatch();
+      return true;
+    }
+    return false;
+  }
+};
+var warnedFunctionTimeoutErrorMatch = false;
+var FunctionCallGetTimeoutError = class extends TimeoutError {
+  #logger;
+  constructor(message, logger2) {
+    super(message);
+    this.#logger = logger2;
+  }
+  warnFunctionTimeoutErrorMatch() {
+    if (warnedFunctionTimeoutErrorMatch) {
+      return;
+    }
+    warnedFunctionTimeoutErrorMatch = true;
+    this.#logger.warn(
+      "Matching a FunctionCall.get() timeout with `instanceof FunctionTimeoutError` is deprecated and will stop working in a future release; check `instanceof TimeoutError` first instead."
+    );
+  }
 };
 var RemoteError = class extends Error {
   constructor(message) {
@@ -68219,12 +68249,14 @@ async function blobDownload(cpClient, blobId) {
 var outputsTimeoutMs = 55 * 1e3;
 var ControlPlaneInvocation = class _ControlPlaneInvocation {
   cpClient;
+  logger;
   functionCallId;
   input;
   functionCallJwt;
   inputJwt;
-  constructor(cpClient, functionCallId, input, functionCallJwt, inputJwt) {
+  constructor(cpClient, logger2, functionCallId, input, functionCallJwt, inputJwt) {
     this.cpClient = cpClient;
+    this.logger = logger2;
     this.functionCallId = functionCallId;
     this.input = input;
     this.functionCallJwt = functionCallJwt;
@@ -68243,6 +68275,7 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
     });
     return new _ControlPlaneInvocation(
       client.cpClient,
+      client.logger,
       functionMapResponse.functionCallId,
       input,
       functionMapResponse.functionCallJwt,
@@ -68250,11 +68283,16 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
     );
   }
   static fromFunctionCallId(client, functionCallId) {
-    return new _ControlPlaneInvocation(client.cpClient, functionCallId);
+    return new _ControlPlaneInvocation(
+      client.cpClient,
+      client.logger,
+      functionCallId
+    );
   }
   async awaitOutput(timeoutMs, clearOnSuccess = false) {
     return await pollFunctionOutput(
       this.cpClient,
+      this.logger,
       (timeoutMs2) => this.#getOutput(
         timeoutMs2,
         clearOnSuccess,
@@ -68294,12 +68332,14 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
 var InputPlaneInvocation = class _InputPlaneInvocation {
   cpClient;
   ipClient;
+  logger;
   functionId;
   input;
   attemptToken;
-  constructor(cpClient, ipClient, functionId, input, attemptToken) {
+  constructor(cpClient, ipClient, logger2, functionId, input, attemptToken) {
     this.cpClient = cpClient;
     this.ipClient = ipClient;
+    this.logger = logger2;
     this.functionId = functionId;
     this.input = input;
     this.attemptToken = attemptToken;
@@ -68317,6 +68357,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
     return new _InputPlaneInvocation(
       client.cpClient,
       ipClient,
+      client.logger,
       functionId,
       functionPutInputsItem,
       attemptStartResponse.attemptToken
@@ -68325,6 +68366,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
   async awaitOutput(timeoutMs) {
     return await pollFunctionOutput(
       this.cpClient,
+      this.logger,
       (timeoutMs2) => this.#getOutput(timeoutMs2),
       timeoutMs
     );
@@ -68349,7 +68391,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
 function timeNowSeconds() {
   return Date.now() / 1e3;
 }
-async function pollFunctionOutput(cpClient, getOutput, timeoutMs) {
+async function pollFunctionOutput(cpClient, logger2, getOutput, timeoutMs) {
   const startTime = Date.now();
   let pollTimeoutMs = outputsTimeoutMs;
   if (timeoutMs !== void 0) {
@@ -68364,7 +68406,7 @@ async function pollFunctionOutput(cpClient, getOutput, timeoutMs) {
       const remainingMs = timeoutMs - (Date.now() - startTime);
       if (remainingMs <= 0) {
         const message = `Timeout exceeded: ${timeoutMs}ms`;
-        throw new FunctionTimeoutError(message);
+        throw new FunctionCallGetTimeoutError(message, logger2);
       }
       pollTimeoutMs = Math.min(outputsTimeoutMs, remainingMs);
     }
@@ -79002,7 +79044,7 @@ var AuthTokenManager = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.11.1-dev.14";
+var SDK_VERSION = "0.11.1-dev.15";
 function getSDKVersion() {
   return SDK_VERSION;
 }
@@ -80633,7 +80675,12 @@ var FunctionCall = class {
     this.#client = client;
     this.functionCallId = functionCallId;
   }
-  /** Get the result of a FunctionCall, optionally waiting with a timeout. */
+  /**
+   * Get the result of a FunctionCall, optionally waiting with a timeout.
+   *
+   * @throws {@link TimeoutError} if `timeoutMs` elapses before the Function finishes.
+   * @throws {@link FunctionTimeoutError} if the Function exceeds its execution timeout.
+   */
   async get(params = {}) {
     checkForRenamedParams(params, { timeout: "timeoutMs" });
     const invocation = ControlPlaneInvocation.fromFunctionCallId(
@@ -80674,6 +80721,142 @@ var FunctionCall = class {
 // src/function.ts
 var import_nice_grpc17 = require("nice-grpc");
 
+// src/metrics.ts
+function metricsRequest(params) {
+  const until = params.until ?? /* @__PURE__ */ new Date();
+  const since = params.since ?? new Date(until.getTime() - 60 * 60 * 1e3);
+  if (!Number.isFinite(since.getTime()) || !Number.isFinite(until.getTime())) {
+    throw new InvalidError("`since` and `until` must be valid dates.");
+  }
+  if (since >= until) {
+    throw new InvalidError("`since` must be before `until`.");
+  }
+  if (since.getTime() < 0) {
+    throw new InvalidError("`since` must be at or after the Unix epoch.");
+  }
+  if (until.getTime() - since.getTime() > 31 * 24 * 60 * 60 * 1e3) {
+    throw new InvalidError("Metrics time range cannot exceed 31 days.");
+  }
+  if (params.groups !== void 0 && (!Array.isArray(params.groups) || params.groups.some((g) => typeof g !== "string" || !g))) {
+    throw new InvalidError(
+      "`groups` must be an array of nonempty group names."
+    );
+  }
+  const request = FunctionGetMetricsRequest.create({
+    since,
+    until,
+    groups: params.groups ?? [],
+    rollup: params.allVariants ?? false
+  });
+  if (params.bucketSizeSecs !== void 0) {
+    const seconds = params.bucketSizeSecs;
+    if (!Number.isInteger(seconds) || seconds < 60 || seconds > 2 ** 32 - 1) {
+      throw new InvalidError(
+        "`bucketSizeSecs` must be a whole number of seconds, at least one minute."
+      );
+    }
+    if (Math.floor(until.getTime() / (params.bucketSizeSecs * 1e3)) - Math.floor(since.getTime() / (params.bucketSizeSecs * 1e3)) > 500) {
+      throw new InvalidError(
+        "Metrics are limited to 500 points per series; increase `bucketSizeSecs`."
+      );
+    }
+    request.bucketSecs = seconds;
+  }
+  return request;
+}
+var FunctionMetricsManager = class {
+  #client;
+  #functionId;
+  /** @hidden */
+  constructor(client, functionId) {
+    this.#client = client;
+    this.#functionId = functionId;
+  }
+  /**
+   * Fetch metric samples, defaulting to all groups over the last hour.
+   *
+   * The maximum range is 31 days, with at most 500 points per series. Omit
+   * bucketSizeSecs to let Modal select a supported width targeting approximately
+   * 100 buckets. Bounds round down to UTC bucket boundaries: data before since
+   * may be included, and the partial bucket at until is excluded.
+   * Missing observations have value null. Use schema() to discover definitions.
+   *
+   * @example
+   * ```typescript
+   * const metrics = await fn.metrics.export({
+   *   bucketSizeSecs: 5 * 60,
+   *   groups: ["calls"],
+   * });
+   * for (const point of metrics.series["successful_calls_count"].points) {
+   *   console.log(point.time, point.value);
+   * }
+   * ```
+   */
+  async export(params = {}) {
+    const request = metricsRequest(params);
+    request.functionId = this.#functionId;
+    const response = await this.#client.cpClient.functionGetMetrics(request);
+    const series = Object.fromEntries(
+      response.series.map((item) => [
+        item.name,
+        {
+          name: item.name,
+          unit: item.unit,
+          aggregation: item.name.slice(item.name.lastIndexOf("_") + 1),
+          description: item.description,
+          points: item.points.map((point) => ({
+            time: point.timestamp ?? /* @__PURE__ */ new Date(0),
+            value: point.value ?? null
+          }))
+        }
+      ])
+    );
+    return {
+      objectId: this.#functionId,
+      since: response.since ?? /* @__PURE__ */ new Date(0),
+      until: response.until ?? /* @__PURE__ */ new Date(0),
+      bucketSizeSecs: response.bucketSecs,
+      pointCount: Object.values(series).reduce(
+        (count, item) => count + item.points.length,
+        0
+      ),
+      series
+    };
+  }
+  /**
+   * Return metric definitions keyed by group name, without fetching samples.
+   * Omit groups to return all groups. Each group's definitions include all its
+   * individual series.
+   */
+  async schema(params = {}) {
+    const window = metricsRequest(params);
+    const response = await this.#client.cpClient.metricsGetInfo(
+      MetricsGetInfoRequest.create({
+        targetType: 1 /* METRICS_TARGET_TYPE_FUNCTION */,
+        since: window.since,
+        until: window.until,
+        groups: window.groups
+      })
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of response.groups) {
+      let group = groups.get(row.name);
+      if (!group) {
+        group = { name: row.name, definitions: [] };
+        groups.set(row.name, group);
+      }
+      group.definitions.push(
+        ...row.metrics.map((metric) => ({
+          name: metric.name,
+          unit: metric.unit,
+          description: metric.description
+        }))
+      );
+    }
+    return Object.fromEntries(groups);
+  }
+};
+
 // src/retries.ts
 var Retries = class {
   maxRetries;
@@ -81056,6 +81239,10 @@ var Function_ = class _Function_ {
       this.#handleMetadata?.appId ?? ""
     );
   }
+  /** Access metric samples with export() and series definitions with schema(). */
+  get metrics() {
+    return new FunctionMetricsManager(this.#client, this.functionId);
+  }
   /** Override the static Function configuration at runtime. */
   withOptions(options) {
     return new _Function_(
@@ -81621,6 +81808,7 @@ var ExperimentalOutboundPolicy2 = class _ExperimentalOutboundPolicy {
   FunctionCallLogsManager,
   FunctionCallService,
   FunctionLogsManager,
+  FunctionMetricsManager,
   FunctionService,
   FunctionTimeoutError,
   Function_,

package/dist/index.d.cts

@@ -3320,7 +3320,7 @@ interface MethodDefinition {
     supportedOutputFormats: DataFormat[];
 }
 declare const MethodDefinition: MessageFns$1<MethodDefinition>;
-interface MetricDefinition {
+interface MetricDefinition$1 {
     /** Exact series name returned by the metrics RPC. */
     name: string;
     /** Matches FunctionMetricSeries.unit. */
@@ -3328,14 +3328,14 @@ interface MetricDefinition {
     /** Meaning and aggregation semantics of the series. */
     description: string;
 }
-declare const MetricDefinition: MessageFns$1<MetricDefinition>;
+declare const MetricDefinition$1: MessageFns$1<MetricDefinition$1>;
 interface MetricGroupDefinition {
     /** Group selector, such as "calls". Multiple catalogue rows can share this name. */
     name: string;
     /** Shared description of this catalogue row's series. */
     description: string;
     /** Individual series represented by this row, ordered by name; all have the same unit. */
-    metrics: MetricDefinition[];
+    metrics: MetricDefinition$1[];
     /** Display label, such as "execution_time_{p50,p90,p99}". */
     displayName: string;
 }
@@ -8186,7 +8186,12 @@ declare class FunctionCall {
     readonly functionCallId: string;
     /** @ignore */
     constructor(client: ModalClient, functionCallId: string, appId: string, functionId: string);
-    /** Get the result of a FunctionCall, optionally waiting with a timeout. */
+    /**
+     * Get the result of a FunctionCall, optionally waiting with a timeout.
+     *
+     * @throws {@link TimeoutError} if `timeoutMs` elapses before the Function finishes.
+     * @throws {@link FunctionTimeoutError} if the Function exceeds its execution timeout.
+     */
     get(params?: FunctionCallGetParams): Promise<any>;
     /** Cancel a running FunctionCall. */
     cancel(params?: FunctionCallCancelParams): Promise<void>;
@@ -8204,6 +8209,91 @@ declare class FunctionCall {
     get logs(): FunctionCallLogsManager;
 }
 
+/** An observation at a UTC-aligned bucket start. */
+interface TimeSeriesPoint {
+    time: Date;
+    /** Missing observations are null; observed zeroes remain zero. */
+    value: number | null;
+}
+/** An individual metric series with points ordered by time. */
+interface MetricSeries {
+    name: string;
+    unit: string;
+    aggregation: string;
+    description: string;
+    points: TimeSeriesPoint[];
+}
+/** The name, unit, and meaning of an exportable series. */
+interface MetricDefinition {
+    name: string;
+    unit: string;
+    description: string;
+}
+/** A metrics group and its individual series definitions. */
+interface MetricsSchema {
+    name: string;
+    definitions: MetricDefinition[];
+}
+/** Exported metrics over the effective, UTC-aligned [since, until) range. */
+interface ObjectMetrics {
+    objectId: string;
+    since: Date;
+    until: Date;
+    bucketSizeSecs: number;
+    /** Total points across series, including missing observations. */
+    pointCount: number;
+    series: Record<string, MetricSeries>;
+}
+/** Options for discovering metric definitions. */
+interface MetricsSchemaParams {
+    /** Omit or pass an empty array to select all groups. */
+    groups?: string[];
+}
+/** Options for exporting Function metric samples. */
+interface FunctionMetricsExportParams extends MetricsSchemaParams {
+    /** Defaults to one hour before until. */
+    since?: Date;
+    /** Defaults to the current time. */
+    until?: Date;
+    /** Bucket width in whole seconds. */
+    bucketSizeSecs?: number;
+    /** Include the root Function and all its variants. Defaults to false. */
+    allVariants?: boolean;
+}
+/** Namespace for Function metric samples and definitions. */
+declare class FunctionMetricsManager {
+    #private;
+    /** @hidden */
+    constructor(client: ModalClient, functionId: string);
+    /**
+     * Fetch metric samples, defaulting to all groups over the last hour.
+     *
+     * The maximum range is 31 days, with at most 500 points per series. Omit
+     * bucketSizeSecs to let Modal select a supported width targeting approximately
+     * 100 buckets. Bounds round down to UTC bucket boundaries: data before since
+     * may be included, and the partial bucket at until is excluded.
+     * Missing observations have value null. Use schema() to discover definitions.
+     *
+     * @example
+     * ```typescript
+     * const metrics = await fn.metrics.export({
+     *   bucketSizeSecs: 5 * 60,
+     *   groups: ["calls"],
+     * });
+     * for (const point of metrics.series["successful_calls_count"].points) {
+     *   console.log(point.time, point.value);
+     * }
+     * ```
+     */
+    export(params?: FunctionMetricsExportParams): Promise<ObjectMetrics>;
+    /**
+     * Return metric definitions keyed by group name, without fetching samples.
+     * Omit groups to return all groups. Each group's definitions include all its
+     * individual series.
+     */
+    schema(params?: MetricsSchemaParams): Promise<Record<string, MetricsSchema>>;
+}
+
 type HeartbeatFunction = () => Promise<any>;
 declare class EphemeralHeartbeatManager {
     private readonly heartbeatFn;
@@ -8440,6 +8530,8 @@ declare class Function_ {
      * for CLI access to logs for an App.
      */
     get logs(): FunctionLogsManager;
+    /** Access metric samples with export() and series definitions with schema(). */
+    get metrics(): FunctionMetricsManager;
     /** Override the static Function configuration at runtime. */
     withOptions(options: FunctionWithOptionsParams): Function_;
     /** Override the static Function concurrency configuration at runtime. */
@@ -10813,9 +10905,17 @@ declare class App {
 declare class TimeoutError extends Error {
     constructor(message?: string);
 }
-/** Function execution exceeds the allowed time limit. */
+/**
+ * Function execution exceeds the allowed time limit.
+ *
+ * {@link FunctionCall#get FunctionCall.get()} throws {@link TimeoutError}
+ * instead when `timeoutMs` elapses before the Function finishes. Matching that
+ * case with `instanceof FunctionTimeoutError` is deprecated and will stop
+ * working in a future release.
+ */
 declare class FunctionTimeoutError extends Error {
     constructor(message: string);
+    static [Symbol.hasInstance](instance: unknown): boolean;
 }
 /** An error on the Modal server, or a Python exception. */
 declare class RemoteError extends Error {
@@ -10904,4 +11004,4 @@ declare class ClientClosedError extends Error {
 
 declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
 
-export { AlreadyExistsError, App, type AppFromNameParams, type AppInfo, type AppInfoParams, type AppLifecycle, AppService, type AppState, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, Environment, EnvironmentAppsService, type EnvironmentCreateParams, type EnvironmentFromNameParams, EnvironmentObjectsService, EnvironmentService, ExecutionError, ExperimentalOutboundPolicy, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionCurrentStats, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, FunctionService, type FunctionStats, type FunctionStatsParams, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, ResourceExhaustedError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxLogFetchParams, type SandboxLogTailParams, SandboxLogsManager, type SandboxMountImageParams, type SandboxReloadVolumesParams, type SandboxRuntime, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, type SidecarMountImageParams, SidecarService, type SidecarSnapshotDirectoryParams, type SidecarSnapshotFilesystemParams, type SidecarTerminateParams, type SidecarUnmountImageParams, SnapshotCreationError, type StatsPercentile, type StatsPercentileDistribution, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };
+export { AlreadyExistsError, App, type AppFromNameParams, type AppInfo, type AppInfoParams, type AppLifecycle, AppService, type AppState, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, Environment, EnvironmentAppsService, type EnvironmentCreateParams, type EnvironmentFromNameParams, EnvironmentObjectsService, EnvironmentService, ExecutionError, ExperimentalOutboundPolicy, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionCurrentStats, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, type FunctionMetricsExportParams, FunctionMetricsManager, FunctionService, type FunctionStats, type FunctionStatsParams, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, type MetricDefinition, type MetricSeries, type MetricsSchema, type MetricsSchemaParams, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, type ObjectMetrics, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, ResourceExhaustedError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxLogFetchParams, type SandboxLogTailParams, SandboxLogsManager, type SandboxMountImageParams, type SandboxReloadVolumesParams, type SandboxRuntime, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, type SidecarMountImageParams, SidecarService, type SidecarSnapshotDirectoryParams, type SidecarSnapshotFilesystemParams, type SidecarTerminateParams, type SidecarUnmountImageParams, SnapshotCreationError, type StatsPercentile, type StatsPercentileDistribution, type StdioBehavior, type StreamMode, type TimeSeriesPoint, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };

package/dist/index.d.ts

@@ -3320,7 +3320,7 @@ interface MethodDefinition {
     supportedOutputFormats: DataFormat[];
 }
 declare const MethodDefinition: MessageFns$1<MethodDefinition>;
-interface MetricDefinition {
+interface MetricDefinition$1 {
     /** Exact series name returned by the metrics RPC. */
     name: string;
     /** Matches FunctionMetricSeries.unit. */
@@ -3328,14 +3328,14 @@ interface MetricDefinition {
     /** Meaning and aggregation semantics of the series. */
     description: string;
 }
-declare const MetricDefinition: MessageFns$1<MetricDefinition>;
+declare const MetricDefinition$1: MessageFns$1<MetricDefinition$1>;
 interface MetricGroupDefinition {
     /** Group selector, such as "calls". Multiple catalogue rows can share this name. */
     name: string;
     /** Shared description of this catalogue row's series. */
     description: string;
     /** Individual series represented by this row, ordered by name; all have the same unit. */
-    metrics: MetricDefinition[];
+    metrics: MetricDefinition$1[];
     /** Display label, such as "execution_time_{p50,p90,p99}". */
     displayName: string;
 }
@@ -8186,7 +8186,12 @@ declare class FunctionCall {
     readonly functionCallId: string;
     /** @ignore */
     constructor(client: ModalClient, functionCallId: string, appId: string, functionId: string);
-    /** Get the result of a FunctionCall, optionally waiting with a timeout. */
+    /**
+     * Get the result of a FunctionCall, optionally waiting with a timeout.
+     *
+     * @throws {@link TimeoutError} if `timeoutMs` elapses before the Function finishes.
+     * @throws {@link FunctionTimeoutError} if the Function exceeds its execution timeout.
+     */
     get(params?: FunctionCallGetParams): Promise<any>;
     /** Cancel a running FunctionCall. */
     cancel(params?: FunctionCallCancelParams): Promise<void>;
@@ -8204,6 +8209,91 @@ declare class FunctionCall {
     get logs(): FunctionCallLogsManager;
 }
 
+/** An observation at a UTC-aligned bucket start. */
+interface TimeSeriesPoint {
+    time: Date;
+    /** Missing observations are null; observed zeroes remain zero. */
+    value: number | null;
+}
+/** An individual metric series with points ordered by time. */
+interface MetricSeries {
+    name: string;
+    unit: string;
+    aggregation: string;
+    description: string;
+    points: TimeSeriesPoint[];
+}
+/** The name, unit, and meaning of an exportable series. */
+interface MetricDefinition {
+    name: string;
+    unit: string;
+    description: string;
+}
+/** A metrics group and its individual series definitions. */
+interface MetricsSchema {
+    name: string;
+    definitions: MetricDefinition[];
+}
+/** Exported metrics over the effective, UTC-aligned [since, until) range. */
+interface ObjectMetrics {
+    objectId: string;
+    since: Date;
+    until: Date;
+    bucketSizeSecs: number;
+    /** Total points across series, including missing observations. */
+    pointCount: number;
+    series: Record<string, MetricSeries>;
+}
+/** Options for discovering metric definitions. */
+interface MetricsSchemaParams {
+    /** Omit or pass an empty array to select all groups. */
+    groups?: string[];
+}
+/** Options for exporting Function metric samples. */
+interface FunctionMetricsExportParams extends MetricsSchemaParams {
+    /** Defaults to one hour before until. */
+    since?: Date;
+    /** Defaults to the current time. */
+    until?: Date;
+    /** Bucket width in whole seconds. */
+    bucketSizeSecs?: number;
+    /** Include the root Function and all its variants. Defaults to false. */
+    allVariants?: boolean;
+}
+/** Namespace for Function metric samples and definitions. */
+declare class FunctionMetricsManager {
+    #private;
+    /** @hidden */
+    constructor(client: ModalClient, functionId: string);
+    /**
+     * Fetch metric samples, defaulting to all groups over the last hour.
+     *
+     * The maximum range is 31 days, with at most 500 points per series. Omit
+     * bucketSizeSecs to let Modal select a supported width targeting approximately
+     * 100 buckets. Bounds round down to UTC bucket boundaries: data before since
+     * may be included, and the partial bucket at until is excluded.
+     * Missing observations have value null. Use schema() to discover definitions.
+     *
+     * @example
+     * ```typescript
+     * const metrics = await fn.metrics.export({
+     *   bucketSizeSecs: 5 * 60,
+     *   groups: ["calls"],
+     * });
+     * for (const point of metrics.series["successful_calls_count"].points) {
+     *   console.log(point.time, point.value);
+     * }
+     * ```
+     */
+    export(params?: FunctionMetricsExportParams): Promise<ObjectMetrics>;
+    /**
+     * Return metric definitions keyed by group name, without fetching samples.
+     * Omit groups to return all groups. Each group's definitions include all its
+     * individual series.
+     */
+    schema(params?: MetricsSchemaParams): Promise<Record<string, MetricsSchema>>;
+}
+
 type HeartbeatFunction = () => Promise<any>;
 declare class EphemeralHeartbeatManager {
     private readonly heartbeatFn;
@@ -8440,6 +8530,8 @@ declare class Function_ {
      * for CLI access to logs for an App.
      */
     get logs(): FunctionLogsManager;
+    /** Access metric samples with export() and series definitions with schema(). */
+    get metrics(): FunctionMetricsManager;
     /** Override the static Function configuration at runtime. */
     withOptions(options: FunctionWithOptionsParams): Function_;
     /** Override the static Function concurrency configuration at runtime. */
@@ -10813,9 +10905,17 @@ declare class App {
 declare class TimeoutError extends Error {
     constructor(message?: string);
 }
-/** Function execution exceeds the allowed time limit. */
+/**
+ * Function execution exceeds the allowed time limit.
+ *
+ * {@link FunctionCall#get FunctionCall.get()} throws {@link TimeoutError}
+ * instead when `timeoutMs` elapses before the Function finishes. Matching that
+ * case with `instanceof FunctionTimeoutError` is deprecated and will stop
+ * working in a future release.
+ */
 declare class FunctionTimeoutError extends Error {
     constructor(message: string);
+    static [Symbol.hasInstance](instance: unknown): boolean;
 }
 /** An error on the Modal server, or a Python exception. */
 declare class RemoteError extends Error {
@@ -10904,4 +11004,4 @@ declare class ClientClosedError extends Error {
 
 declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
 
-export { AlreadyExistsError, App, type AppFromNameParams, type AppInfo, type AppInfoParams, type AppLifecycle, AppService, type AppState, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, Environment, EnvironmentAppsService, type EnvironmentCreateParams, type EnvironmentFromNameParams, EnvironmentObjectsService, EnvironmentService, ExecutionError, ExperimentalOutboundPolicy, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionCurrentStats, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, FunctionService, type FunctionStats, type FunctionStatsParams, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, ResourceExhaustedError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxLogFetchParams, type SandboxLogTailParams, SandboxLogsManager, type SandboxMountImageParams, type SandboxReloadVolumesParams, type SandboxRuntime, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, type SidecarMountImageParams, SidecarService, type SidecarSnapshotDirectoryParams, type SidecarSnapshotFilesystemParams, type SidecarTerminateParams, type SidecarUnmountImageParams, SnapshotCreationError, type StatsPercentile, type StatsPercentileDistribution, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };
+export { AlreadyExistsError, App, type AppFromNameParams, type AppInfo, type AppInfoParams, type AppLifecycle, AppService, type AppState, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, Environment, EnvironmentAppsService, type EnvironmentCreateParams, type EnvironmentFromNameParams, EnvironmentObjectsService, EnvironmentService, ExecutionError, ExperimentalOutboundPolicy, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionCurrentStats, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, type FunctionMetricsExportParams, FunctionMetricsManager, FunctionService, type FunctionStats, type FunctionStatsParams, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, type MetricDefinition, type MetricSeries, type MetricsSchema, type MetricsSchemaParams, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, type ObjectMetrics, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, ResourceExhaustedError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxLogFetchParams, type SandboxLogTailParams, SandboxLogsManager, type SandboxMountImageParams, type SandboxReloadVolumesParams, type SandboxRuntime, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, type SidecarMountImageParams, SidecarService, type SidecarSnapshotDirectoryParams, type SidecarSnapshotFilesystemParams, type SidecarTerminateParams, type SidecarUnmountImageParams, SnapshotCreationError, type StatsPercentile, type StatsPercentileDistribution, type StdioBehavior, type StreamMode, type TimeSeriesPoint, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };

package/dist/index.js

@@ -67536,11 +67536,40 @@ var TimeoutError = class extends Error {
     this.name = "TimeoutError";
   }
 };
-var FunctionTimeoutError = class extends Error {
+var FunctionTimeoutError = class _FunctionTimeoutError extends Error {
   constructor(message) {
     super(message);
     this.name = "FunctionTimeoutError";
   }
+  // Backward compatibility: FunctionCall.get() wait timeouts still match
+  // FunctionTimeoutError, with a deprecation warning.
+  static [Symbol.hasInstance](instance) {
+    if (Function.prototype[Symbol.hasInstance].call(this, instance)) {
+      return true;
+    }
+    if (this === _FunctionTimeoutError && instance instanceof FunctionCallGetTimeoutError) {
+      instance.warnFunctionTimeoutErrorMatch();
+      return true;
+    }
+    return false;
+  }
+};
+var warnedFunctionTimeoutErrorMatch = false;
+var FunctionCallGetTimeoutError = class extends TimeoutError {
+  #logger;
+  constructor(message, logger2) {
+    super(message);
+    this.#logger = logger2;
+  }
+  warnFunctionTimeoutErrorMatch() {
+    if (warnedFunctionTimeoutErrorMatch) {
+      return;
+    }
+    warnedFunctionTimeoutErrorMatch = true;
+    this.#logger.warn(
+      "Matching a FunctionCall.get() timeout with `instanceof FunctionTimeoutError` is deprecated and will stop working in a future release; check `instanceof TimeoutError` first instead."
+    );
+  }
 };
 var RemoteError = class extends Error {
   constructor(message) {
@@ -68120,12 +68149,14 @@ async function blobDownload(cpClient, blobId) {
 var outputsTimeoutMs = 55 * 1e3;
 var ControlPlaneInvocation = class _ControlPlaneInvocation {
   cpClient;
+  logger;
   functionCallId;
   input;
   functionCallJwt;
   inputJwt;
-  constructor(cpClient, functionCallId, input, functionCallJwt, inputJwt) {
+  constructor(cpClient, logger2, functionCallId, input, functionCallJwt, inputJwt) {
     this.cpClient = cpClient;
+    this.logger = logger2;
     this.functionCallId = functionCallId;
     this.input = input;
     this.functionCallJwt = functionCallJwt;
@@ -68144,6 +68175,7 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
     });
     return new _ControlPlaneInvocation(
       client.cpClient,
+      client.logger,
       functionMapResponse.functionCallId,
       input,
       functionMapResponse.functionCallJwt,
@@ -68151,11 +68183,16 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
     );
   }
   static fromFunctionCallId(client, functionCallId) {
-    return new _ControlPlaneInvocation(client.cpClient, functionCallId);
+    return new _ControlPlaneInvocation(
+      client.cpClient,
+      client.logger,
+      functionCallId
+    );
   }
   async awaitOutput(timeoutMs, clearOnSuccess = false) {
     return await pollFunctionOutput(
       this.cpClient,
+      this.logger,
       (timeoutMs2) => this.#getOutput(
         timeoutMs2,
         clearOnSuccess,
@@ -68195,12 +68232,14 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
 var InputPlaneInvocation = class _InputPlaneInvocation {
   cpClient;
   ipClient;
+  logger;
   functionId;
   input;
   attemptToken;
-  constructor(cpClient, ipClient, functionId, input, attemptToken) {
+  constructor(cpClient, ipClient, logger2, functionId, input, attemptToken) {
     this.cpClient = cpClient;
     this.ipClient = ipClient;
+    this.logger = logger2;
     this.functionId = functionId;
     this.input = input;
     this.attemptToken = attemptToken;
@@ -68218,6 +68257,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
     return new _InputPlaneInvocation(
       client.cpClient,
       ipClient,
+      client.logger,
       functionId,
       functionPutInputsItem,
       attemptStartResponse.attemptToken
@@ -68226,6 +68266,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
   async awaitOutput(timeoutMs) {
     return await pollFunctionOutput(
       this.cpClient,
+      this.logger,
       (timeoutMs2) => this.#getOutput(timeoutMs2),
       timeoutMs
     );
@@ -68250,7 +68291,7 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
 function timeNowSeconds() {
   return Date.now() / 1e3;
 }
-async function pollFunctionOutput(cpClient, getOutput, timeoutMs) {
+async function pollFunctionOutput(cpClient, logger2, getOutput, timeoutMs) {
   const startTime = Date.now();
   let pollTimeoutMs = outputsTimeoutMs;
   if (timeoutMs !== void 0) {
@@ -68265,7 +68306,7 @@ async function pollFunctionOutput(cpClient, getOutput, timeoutMs) {
       const remainingMs = timeoutMs - (Date.now() - startTime);
       if (remainingMs <= 0) {
         const message = `Timeout exceeded: ${timeoutMs}ms`;
-        throw new FunctionTimeoutError(message);
+        throw new FunctionCallGetTimeoutError(message, logger2);
       }
       pollTimeoutMs = Math.min(outputsTimeoutMs, remainingMs);
     }
@@ -78916,7 +78957,7 @@ var AuthTokenManager = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.11.1-dev.14";
+var SDK_VERSION = "0.11.1-dev.15";
 function getSDKVersion() {
   return SDK_VERSION;
 }
@@ -80552,7 +80593,12 @@ var FunctionCall = class {
     this.#client = client;
     this.functionCallId = functionCallId;
   }
-  /** Get the result of a FunctionCall, optionally waiting with a timeout. */
+  /**
+   * Get the result of a FunctionCall, optionally waiting with a timeout.
+   *
+   * @throws {@link TimeoutError} if `timeoutMs` elapses before the Function finishes.
+   * @throws {@link FunctionTimeoutError} if the Function exceeds its execution timeout.
+   */
   async get(params = {}) {
     checkForRenamedParams(params, { timeout: "timeoutMs" });
     const invocation = ControlPlaneInvocation.fromFunctionCallId(
@@ -80593,6 +80639,142 @@ var FunctionCall = class {
 // src/function.ts
 import { ClientError as ClientError16, Status as Status16 } from "nice-grpc";
 
+// src/metrics.ts
+function metricsRequest(params) {
+  const until = params.until ?? /* @__PURE__ */ new Date();
+  const since = params.since ?? new Date(until.getTime() - 60 * 60 * 1e3);
+  if (!Number.isFinite(since.getTime()) || !Number.isFinite(until.getTime())) {
+    throw new InvalidError("`since` and `until` must be valid dates.");
+  }
+  if (since >= until) {
+    throw new InvalidError("`since` must be before `until`.");
+  }
+  if (since.getTime() < 0) {
+    throw new InvalidError("`since` must be at or after the Unix epoch.");
+  }
+  if (until.getTime() - since.getTime() > 31 * 24 * 60 * 60 * 1e3) {
+    throw new InvalidError("Metrics time range cannot exceed 31 days.");
+  }
+  if (params.groups !== void 0 && (!Array.isArray(params.groups) || params.groups.some((g) => typeof g !== "string" || !g))) {
+    throw new InvalidError(
+      "`groups` must be an array of nonempty group names."
+    );
+  }
+  const request = FunctionGetMetricsRequest.create({
+    since,
+    until,
+    groups: params.groups ?? [],
+    rollup: params.allVariants ?? false
+  });
+  if (params.bucketSizeSecs !== void 0) {
+    const seconds = params.bucketSizeSecs;
+    if (!Number.isInteger(seconds) || seconds < 60 || seconds > 2 ** 32 - 1) {
+      throw new InvalidError(
+        "`bucketSizeSecs` must be a whole number of seconds, at least one minute."
+      );
+    }
+    if (Math.floor(until.getTime() / (params.bucketSizeSecs * 1e3)) - Math.floor(since.getTime() / (params.bucketSizeSecs * 1e3)) > 500) {
+      throw new InvalidError(
+        "Metrics are limited to 500 points per series; increase `bucketSizeSecs`."
+      );
+    }
+    request.bucketSecs = seconds;
+  }
+  return request;
+}
+var FunctionMetricsManager = class {
+  #client;
+  #functionId;
+  /** @hidden */
+  constructor(client, functionId) {
+    this.#client = client;
+    this.#functionId = functionId;
+  }
+  /**
+   * Fetch metric samples, defaulting to all groups over the last hour.
+   *
+   * The maximum range is 31 days, with at most 500 points per series. Omit
+   * bucketSizeSecs to let Modal select a supported width targeting approximately
+   * 100 buckets. Bounds round down to UTC bucket boundaries: data before since
+   * may be included, and the partial bucket at until is excluded.
+   * Missing observations have value null. Use schema() to discover definitions.
+   *
+   * @example
+   * ```typescript
+   * const metrics = await fn.metrics.export({
+   *   bucketSizeSecs: 5 * 60,
+   *   groups: ["calls"],
+   * });
+   * for (const point of metrics.series["successful_calls_count"].points) {
+   *   console.log(point.time, point.value);
+   * }
+   * ```
+   */
+  async export(params = {}) {
+    const request = metricsRequest(params);
+    request.functionId = this.#functionId;
+    const response = await this.#client.cpClient.functionGetMetrics(request);
+    const series = Object.fromEntries(
+      response.series.map((item) => [
+        item.name,
+        {
+          name: item.name,
+          unit: item.unit,
+          aggregation: item.name.slice(item.name.lastIndexOf("_") + 1),
+          description: item.description,
+          points: item.points.map((point) => ({
+            time: point.timestamp ?? /* @__PURE__ */ new Date(0),
+            value: point.value ?? null
+          }))
+        }
+      ])
+    );
+    return {
+      objectId: this.#functionId,
+      since: response.since ?? /* @__PURE__ */ new Date(0),
+      until: response.until ?? /* @__PURE__ */ new Date(0),
+      bucketSizeSecs: response.bucketSecs,
+      pointCount: Object.values(series).reduce(
+        (count, item) => count + item.points.length,
+        0
+      ),
+      series
+    };
+  }
+  /**
+   * Return metric definitions keyed by group name, without fetching samples.
+   * Omit groups to return all groups. Each group's definitions include all its
+   * individual series.
+   */
+  async schema(params = {}) {
+    const window = metricsRequest(params);
+    const response = await this.#client.cpClient.metricsGetInfo(
+      MetricsGetInfoRequest.create({
+        targetType: 1 /* METRICS_TARGET_TYPE_FUNCTION */,
+        since: window.since,
+        until: window.until,
+        groups: window.groups
+      })
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of response.groups) {
+      let group = groups.get(row.name);
+      if (!group) {
+        group = { name: row.name, definitions: [] };
+        groups.set(row.name, group);
+      }
+      group.definitions.push(
+        ...row.metrics.map((metric) => ({
+          name: metric.name,
+          unit: metric.unit,
+          description: metric.description
+        }))
+      );
+    }
+    return Object.fromEntries(groups);
+  }
+};
+
 // src/retries.ts
 var Retries = class {
   maxRetries;
@@ -80975,6 +81157,10 @@ var Function_ = class _Function_ {
       this.#handleMetadata?.appId ?? ""
     );
   }
+  /** Access metric samples with export() and series definitions with schema(). */
+  get metrics() {
+    return new FunctionMetricsManager(this.#client, this.functionId);
+  }
   /** Override the static Function configuration at runtime. */
   withOptions(options) {
     return new _Function_(
@@ -81539,6 +81725,7 @@ export {
   FunctionCallLogsManager,
   FunctionCallService,
   FunctionLogsManager,
+  FunctionMetricsManager,
   FunctionService,
   FunctionTimeoutError,
   Function_,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modal",
-  "version": "0.11.1-dev.14",
+  "version": "0.11.1-dev.15",
   "description": "Modal SDK for JavaScript/TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://modal.com/docs/guide/sdk-javascript-go",