@tonbo/cli 0.23.0 → 0.24.0

package/dist/bin/tonbo.js

@@ -613,6 +613,22 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo database activity"
   },
+  "getDatabaseMetrics": {
+    "method": "GET",
+    "path": "/databases/{name}/metrics",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "series",
+      "window",
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo database metrics"
+  },
   "listDatabaseUsage": {
     "method": "GET",
     "path": "/usage/databases",
@@ -752,6 +768,34 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo metrics machines"
   },
+  "getAccountDatabaseMetrics": {
+    "method": "GET",
+    "path": "/metrics/databases",
+    "pathParams": [],
+    "query": [
+      "series",
+      "window",
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo metrics databases"
+  },
+  "getAccountStreamMetrics": {
+    "method": "GET",
+    "path": "/metrics/streams",
+    "pathParams": [],
+    "query": [
+      "series",
+      "window",
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo metrics streams"
+  },
   "listMachineShapes": {
     "method": "GET",
     "path": "/machine-shapes",
@@ -1083,6 +1127,22 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo stream activity"
   },
+  "getStreamMetrics": {
+    "method": "GET",
+    "path": "/streams/{name}/metrics",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "series",
+      "window",
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo stream metrics"
+  },
   "listStreamUsage": {
     "method": "GET",
     "path": "/usage/streams",
@@ -2335,10 +2395,19 @@ var ManagementApi = class {
   deleteDatabase(key, name) {
     return this.call("deleteDatabase", key, { params: { name } });
   }
-  /** A database's writes per hour or day and its size at each step's end. */
+  /** Deprecated (`getDatabaseMetrics`): a database's writes per hour or day
+   * and its size at each step's end, for `tonbo database activity`. */
   getDatabaseActivity(key, name, query = {}) {
     return this.call("getDatabaseActivity", key, { params: { name }, query });
   }
+  /** A live database's metrics per UTC hour or day. */
+  getDatabaseMetrics(key, name, query = {}) {
+    return this.call("getDatabaseMetrics", key, { params: { name }, query });
+  }
+  /** The account's databases' metrics, each and summed. */
+  getAccountDatabaseMetrics(key, query = {}) {
+    return this.call("getAccountDatabaseMetrics", key, { query });
+  }
   /** The whole usage page: its rows, `other`, prices and checkpoint. */
   listDatabaseUsage(key, page, query = {}) {
     return this.page("listDatabaseUsage", key, page, query);
@@ -2363,10 +2432,19 @@ var ManagementApi = class {
   deleteStream(key, name) {
     return this.call("deleteStream", key, { params: { name } });
   }
-  /** A stream's appends per hour or day and its size at each step's end. */
+  /** Deprecated (`getStreamMetrics`): a stream's appends per hour or day and
+   * its size at each step's end, for `tonbo stream activity`. */
   getStreamActivity(key, name, query = {}) {
     return this.call("getStreamActivity", key, { params: { name }, query });
   }
+  /** A live stream's metrics per UTC hour or day. */
+  getStreamMetrics(key, name, query = {}) {
+    return this.call("getStreamMetrics", key, { params: { name }, query });
+  }
+  /** The account's streams' metrics, each and summed. */
+  getAccountStreamMetrics(key, query = {}) {
+    return this.call("getAccountStreamMetrics", key, { query });
+  }
   /** The whole usage page: its rows, `other`, prices and checkpoint. */
   listStreamUsage(key, page, query = {}) {
     return this.page("listStreamUsage", key, page, query);
@@ -5234,6 +5312,128 @@ async function databaseActivityCommand(deps, name, options = {}) {
   );
   printActivity(deps, options.json, activity, "Database");
 }
+var REGISTRY_COLUMNS = {
+  stored_bytes: ["STORED", (value) => bytes(value)],
+  log_bytes: ["LOG", (value) => bytes(value)],
+  snapshot_bytes: ["SNAPSHOT", (value) => bytes(value)],
+  write_units: ["WRITE UNITS", String],
+  write_bytes: ["WRITTEN", (value) => bytes(value)],
+  records: ["RECORDS", String],
+  reads: ["READS", String],
+  read_bytes: ["READ", (value) => bytes(value)],
+  live_reads: ["LIVE READS", String],
+  live_read_bytes: ["LIVE READ", (value) => bytes(value)],
+  server_write_latency_p50_ms: ["WRITE P50", (value) => `${value} ms`],
+  server_write_latency_p99_ms: ["WRITE P99", (value) => `${value} ms`],
+  server_read_latency_p50_ms: ["READ P50", (value) => `${value} ms`],
+  server_read_latency_p99_ms: ["READ P99", (value) => `${value} ms`]
+};
+var SERVER_LATENCY = "Latency is server latency: measured at Tonbo's servers, from request to response headers; your network adds to this.";
+function registryMetricsTable(granularity, points) {
+  const series = Object.keys(REGISTRY_COLUMNS).filter(
+    (name) => points.some((point) => name in point)
+  );
+  return {
+    latency: series.some((name) => name.startsWith("server_")),
+    text: table(
+      [
+        granularity === "hour" ? "HOUR (UTC)" : "DAY (UTC)",
+        ...series.map((name) => REGISTRY_COLUMNS[name][0])
+      ],
+      points.map((point) => [
+        granularity === "hour" ? point.start.slice(0, 16).replace("T", " ") : point.start.slice(0, 10),
+        ...series.map((name) => {
+          const value = point[name];
+          if (value === null || value === void 0)
+            return Date.parse(point.start) > Date.now() ? "" : "-";
+          return REGISTRY_COLUMNS[name][1](value);
+        })
+      ])
+    )
+  };
+}
+function printRegistryMetrics(deps, noun, metrics, options) {
+  const rendered = registryMetricsTable(metrics.granularity, metrics.points);
+  print(
+    deps,
+    options.json,
+    metrics,
+    [
+      `${noun} ${metrics.name} in ${metrics.region} from ${metrics.from} to ${metrics.to} (UTC; metered up to ${when(metrics.as_of, "not yet metered")})`,
+      rendered.text,
+      ...rendered.latency ? [SERVER_LATENCY] : []
+    ].join("\n")
+  );
+}
+async function databaseMetricsCommand(deps, name, options = {}) {
+  const metrics = await deps.api.getDatabaseMetrics(
+    await deps.auth.apiKey(),
+    name,
+    metricsQuery(options)
+  );
+  printRegistryMetrics(deps, "Database", metrics, options);
+}
+async function streamMetricsCommand(deps, name, options = {}) {
+  const metrics = await deps.api.getStreamMetrics(
+    await deps.auth.apiKey(),
+    name,
+    metricsQuery(options)
+  );
+  printRegistryMetrics(deps, "Stream", metrics, options);
+}
+function printAccountRegistryMetrics(deps, noun, metrics, options) {
+  const rendered = registryMetricsTable(metrics.granularity, metrics.total.points);
+  const lines = [
+    `The account's ${noun} from ${metrics.from} to ${metrics.to} (UTC; metered up to ${when(metrics.as_of, "not yet metered")})`,
+    rendered.text
+  ];
+  const counted = ["write_units", "write_bytes", "records", "reads", "read_bytes"].filter((name) => metrics.total.points.some((point) => name in point));
+  const sized = metrics.total.points.some((point) => "stored_bytes" in point);
+  if (metrics.resources.length > 0 && (counted.length > 0 || sized)) {
+    lines.push(
+      "",
+      table(
+        [
+          noun === "databases" ? "DATABASE" : "STREAM",
+          "REGION",
+          ...sized ? ["STORED"] : [],
+          ...counted.map((name) => REGISTRY_COLUMNS[name][0])
+        ],
+        metrics.resources.map((resource) => {
+          const stored = [...resource.points].reverse().find((point) => point.stored_bytes !== null && point.stored_bytes !== void 0);
+          return [
+            resource.name,
+            resource.region,
+            ...sized ? [stored ? bytes(stored.stored_bytes ?? 0) : "-"] : [],
+            ...counted.map(
+              (name) => REGISTRY_COLUMNS[name][1](
+                resource.points.reduce((total, point) => total + (point[name] ?? 0), 0)
+              )
+            )
+          ];
+        })
+      )
+    );
+  }
+  if (rendered.latency) lines.push(SERVER_LATENCY);
+  if (metrics.unavailable_regions.length > 0)
+    lines.push(`Not read: ${metrics.unavailable_regions.join(", ")}`);
+  print(deps, options.json, metrics, lines.join("\n"));
+}
+async function metricsDatabasesCommand(deps, options = {}) {
+  const metrics = await deps.api.getAccountDatabaseMetrics(
+    await deps.auth.apiKey(),
+    metricsQuery(options)
+  );
+  printAccountRegistryMetrics(deps, "databases", metrics, options);
+}
+async function metricsStreamsCommand(deps, options = {}) {
+  const metrics = await deps.api.getAccountStreamMetrics(
+    await deps.auth.apiKey(),
+    metricsQuery(options)
+  );
+  printAccountRegistryMetrics(deps, "streams", metrics, options);
+}
 function streamFields(stream) {
   return fields([
     ["Name", stream.name],
@@ -7263,6 +7463,18 @@ var COMMAND_HELP = {
     arguments: NAME("database"),
     defaults: ACTIVITY_DEFAULTS
   },
+  "tonbo database metrics": {
+    about: [
+      "Prints the database's metrics, one row per UTC hour or day: its stored size at the step's end (the log and snapshots it keeps), the write units, bytes and records written, the successful reads and live (long-poll or SSE) reads and the bytes they streamed, and the median and 99th percentile server latency of its appends and catch-up reads. Server latency is measured at Tonbo's servers, from request to response headers; your network adds to this. A dash is a value not measured (a size before the meter's first sample, a latency with no request); the current step is still growing.",
+      "Give `--window`, or `--from` and `--to` with `--granularity` (at most 31 days hourly, 92 days daily; server latency is kept 8 days hourly). `--series` prints only the series it names. It carries no money: `tonbo database usage` says what it cost."
+    ],
+    examples: [
+      "tonbo database metrics notes --window 7d",
+      "tonbo database metrics notes --series server_write_latency_p50_ms,server_write_latency_p99_ms"
+    ],
+    arguments: NAME("database"),
+    defaults: { "--window": "24h" }
+  },
   "tonbo database usage": {
     about: [
       "Prints each database's usage of one calendar month in UTC at list price, before the monthly allowance and credit: its write units, log and snapshot GiB-months and list value, then the account's other metered usage (its streams and everything else). The charges after allowance and credit are in `tonbo usage show`."
@@ -7321,6 +7533,18 @@ var COMMAND_HELP = {
     arguments: NAME("stream"),
     defaults: ACTIVITY_DEFAULTS
   },
+  "tonbo stream metrics": {
+    about: [
+      "Prints the stream's metrics, one row per UTC hour or day: its stored size at the step's end (the log and snapshots it keeps), the write units, bytes and records written, the successful reads and live (long-poll or SSE) reads and the bytes they streamed, and the median and 99th percentile server latency of its appends and catch-up reads. Server latency is measured at Tonbo's servers, from request to response headers; your network adds to this. A dash is a value not measured (a size before the meter's first sample, a latency with no request); the current step is still growing.",
+      "Give `--window`, or `--from` and `--to` with `--granularity` (at most 31 days hourly, 92 days daily; server latency is kept 8 days hourly). `--series` prints only the series it names. It carries no money: `tonbo stream usage` says what it cost."
+    ],
+    examples: [
+      "tonbo stream metrics events --window 7d",
+      "tonbo stream metrics events --series server_write_latency_p50_ms,server_write_latency_p99_ms"
+    ],
+    arguments: NAME("stream"),
+    defaults: { "--window": "24h" }
+  },
   "tonbo stream usage": {
     about: [
       "Prints each stream's usage of one calendar month in UTC at list price, before the monthly allowance and credit, then the account's other metered usage (its databases and everything else). The charges after allowance and credit are in `tonbo usage show`."
@@ -7681,6 +7905,22 @@ var COMMAND_HELP = {
     examples: ["tonbo metrics machines --window 30d"],
     defaults: { "--window": "7d" }
   },
+  "tonbo metrics databases": {
+    about: [
+      "Prints the account's databases per UTC hour or day, summed over every region, with the same series as `tonbo database metrics`: the total's server latency comes from every database's merged histograms, never an average of percentiles. Server latency is measured at Tonbo's servers, from request to response headers; your network adds to this. Then each database's row over the window: its stored size at the last measured step and its counts summed.",
+      "Give `--window`, or `--from` and `--to` with `--granularity` (at most 31 days hourly, 92 days daily)."
+    ],
+    examples: ["tonbo metrics databases --window 30d --series stored_bytes,write_units"],
+    defaults: { "--window": "7d" }
+  },
+  "tonbo metrics streams": {
+    about: [
+      "Prints the account's streams per UTC hour or day, summed over every region, with the same series as `tonbo stream metrics`: the total's server latency comes from every stream's merged histograms, never an average of percentiles. Server latency is measured at Tonbo's servers, from request to response headers; your network adds to this. Then each stream's row over the window: its stored size at the last measured step and its counts summed.",
+      "Give `--window`, or `--from` and `--to` with `--granularity` (at most 31 days hourly, 92 days daily)."
+    ],
+    examples: ["tonbo metrics streams --window 30d --series stored_bytes,write_units"],
+    defaults: { "--window": "7d" }
+  },
   "tonbo metrics volumes": {
     about: [
       "Prints what the account's Volumes stored, one line per UTC day of the window: the average bytes their files held that day, compressed, summed over every region, which is what they are billed for. Today, and a day not fully rated yet, is marked `so far`. Then the change between the window's first and last complete days.",
@@ -9323,6 +9563,15 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, options) => databaseActivityCommand(dependencies(), name, options)
   );
+  operationOptions(
+    database.command("metrics <name>").description("show a database's writes, reads, stored size and server latency over time").option("--window <window>", "24h or 7d hourly, 30d or 90d daily; 24h when omitted").option(
+      "--series <series>",
+      "the series to print, comma-separated; every series when omitted"
+    ).option("--granularity <step>", "with --from and --to, hour or day").option("--from <time>", "with --to, the window's start, on a UTC hour or day").option("--to <time>", "with --from, the window's end, exclusive"),
+    "getDatabaseMetrics"
+  ).action(
+    async (name, options) => databaseMetricsCommand(dependencies(), name, options)
+  );
   operationOptions(
     database.command("usage").description("each database's usage of one month at list price, before allowance and credit").option("--period <month>", "the calendar month in UTC, as YYYY-MM").option("--sort <order>", "list_value (highest first) or name", parseUsageSort).option("--prefix <prefix>", "only databases whose name starts with this").option("--names <names>", "only these databases, up to 100 names, comma-separated"),
     "listDatabaseUsage"
@@ -9384,6 +9633,15 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, options) => streamActivityCommand(dependencies(), name, options)
   );
+  operationOptions(
+    stream.command("metrics <name>").description("show a stream's writes, reads, stored size and server latency over time").option("--window <window>", "24h or 7d hourly, 30d or 90d daily; 24h when omitted").option(
+      "--series <series>",
+      "the series to print, comma-separated; every series when omitted"
+    ).option("--granularity <step>", "with --from and --to, hour or day").option("--from <time>", "with --to, the window's start, on a UTC hour or day").option("--to <time>", "with --from, the window's end, exclusive"),
+    "getStreamMetrics"
+  ).action(
+    async (name, options) => streamMetricsCommand(dependencies(), name, options)
+  );
   operationOptions(
     stream.command("usage").description("each stream's usage of one month at list price, before allowance and credit").option("--period <month>", "the calendar month in UTC, as YYYY-MM").option("--sort <order>", "list_value (highest first) or name", parseUsageSort).option("--prefix <prefix>", "only streams whose name starts with this").option("--names <names>", "only these streams, up to 100 names, comma-separated"),
     "listStreamUsage"
@@ -9692,6 +9950,24 @@ function createProgram(makeDependencies = createDependencies) {
     ).option("--granularity <step>", "with --from and --to, hour or day").option("--from <time>", "with --to, the window's start, on a UTC hour or day").option("--to <time>", "with --from, the window's end, exclusive"),
     "getAccountMachineMetrics"
   ).action(async (options) => metricsMachinesCommand(dependencies(), options));
+  operationOptions(
+    metrics.command("databases").description(
+      "show the account's databases' writes, reads, stored size and server latency over time"
+    ).option("--window <window>", "24h or 7d hourly, 30d or 90d daily; 7d when omitted").option(
+      "--series <series>",
+      "the series to print, comma-separated; every series when omitted"
+    ).option("--granularity <step>", "with --from and --to, hour or day").option("--from <time>", "with --to, the window's start, on a UTC hour or day").option("--to <time>", "with --from, the window's end, exclusive"),
+    "getAccountDatabaseMetrics"
+  ).action(async (options) => metricsDatabasesCommand(dependencies(), options));
+  operationOptions(
+    metrics.command("streams").description(
+      "show the account's streams' writes, reads, stored size and server latency over time"
+    ).option("--window <window>", "24h or 7d hourly, 30d or 90d daily; 7d when omitted").option(
+      "--series <series>",
+      "the series to print, comma-separated; every series when omitted"
+    ).option("--granularity <step>", "with --from and --to, hour or day").option("--from <time>", "with --to, the window's start, on a UTC hour or day").option("--to <time>", "with --from, the window's end, exclusive"),
+    "getAccountStreamMetrics"
+  ).action(async (options) => metricsStreamsCommand(dependencies(), options));
   const ssh = program.command("ssh").description("open a terminal on a Machine, or run a command there, over SSH").argument("<machine>", "the Machine's name").argument("[command...]", "a command to run instead of a shell, after --").action(async (name, command) => sshCommand(dependencies(), name, command));
   ssh.command("config").description(
     "print the ssh_config block that lets ssh, scp, sftp and Remote-SSH reach every Machine"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "The Tonbo CLI. Compute, disks, databases and streams for AI agents: your agent picks what it needs, sets it up, and knows what it costs, from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {