@tailglow/cli 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailglow/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "The Tailglow command line. Every command is generated from the Tailglow API reference, so the CLI and the documentation can never describe different APIs.",
   "bin": {

package/src/commands.generated.js

@@ -3014,7 +3014,7 @@ export const CLI_COMMANDS = [
         "name": "preview_token",
         "type": "string",
         "required": false,
-        "description": "The `edit_report.preview_token` from this edit's dry run. Required to save: it pins the save to the set of schema versions the preview reported on, so a version promoted or reassigned in between is rejected instead of silently included. Optional. Minimum length: `1`. Maximum length: `128`.",
+        "description": "The `edit_report.preview_token` from this edit's dry run. Required to save: it pins the save to the set of schema versions the preview reported on, so a version assigned or reassigned in between is rejected instead of silently included. Optional. Minimum length: `1`. Maximum length: `128`.",
         "allowed_values": [],
         "deprecated": null
       }
@@ -4713,9 +4713,10 @@ export const CLI_COMMANDS = [
     "notes": [
       "The monitor starts evaluating on its schedule as soon as it is created.",
       "`scope` decides how many alerts a monitor can raise at once: `any_series` fires once for the metric as a whole, `each_series` tracks every series separately.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
       "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
       "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
-      "`schedule_cron` must be a valid cron expression.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
       "A monitor cannot be created active with an `expires_at` already in the past."
     ],
     "path_params": [
@@ -4800,9 +4801,223 @@ export const CLI_COMMANDS = [
       },
       {
         "name": "time_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "condition_type",
+        "type": "MonitorConditionType",
+        "required": false,
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional. Defaults to `\"threshold\"`.",
+        "allowed_values": [
+          "threshold",
+          "sustained",
+          "existence",
+          "absence"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "operator",
+        "type": "MonitorOperator",
+        "required": false,
+        "description": "How the metric value is compared against the threshold. Optional. Defaults to `\"gt\"`.",
+        "allowed_values": [
+          "gt",
+          "gte",
+          "lt",
+          "lte",
+          "eq",
+          "neq"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "threshold_value",
+        "type": "number | null",
+        "required": false,
+        "description": "The value the metric is compared against. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "sustained_minutes",
         "type": "number | null",
         "required": false,
-        "description": "How far back each evaluation looks when it reads the metric. Optional.",
+        "description": "How long the condition must hold before the monitor fires. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "schedule_cron",
+        "type": "string",
+        "required": false,
+        "description": "Cron expression, in UTC, setting how often the monitor evaluates. Optional. Defaults to `\"* * * * *\"`. Minimum length: `1`. Maximum length: `128`.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "alert_mode",
+        "type": "MonitorAlertMode",
+        "required": false,
+        "description": "Whether an alert stays open until the condition clears, or opens and ends in one moment. Optional. Defaults to `\"spanning\"`.",
+        "allowed_values": [
+          "spanning",
+          "instant"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "expires_at",
+        "type": "ISODateString | null",
+        "required": false,
+        "description": "When the monitor stops evaluating. Leave null for no expiry. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "series_filters",
+        "type": "object | null",
+        "required": false,
+        "description": "Narrows which of the metric's series this monitor watches. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "min_occurrences",
+        "type": "integer | null",
+        "required": false,
+        "description": "How many times the condition must be met before the monitor fires. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "occurrence_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "The window those occurrences have to fall within. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "metric_id",
+        "type": "string",
+        "required": false,
+        "description": "Metric to watch. Optional when using the /metrics/:metric/monitors route. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ]
+  },
+  {
+    "resource": "monitors",
+    "command": "preview",
+    "operation_id": "previewMonitor",
+    "summary": "Preview Monitor",
+    "description": "Preview a monitor condition over its current evaluation window without saving or raising alerts.",
+    "method": "POST",
+    "path": "/v1/projects/:project_id/metrics/:metric_id/monitors/preview",
+    "alternate_paths": [],
+    "scopes": [
+      "monitors:read"
+    ],
+    "notes": [
+      "Uses the same series filtering and condition evaluation as scheduled monitors. This is a condition preview, not a simulation of cron timing, sustained duration, or occurrence counting.",
+      "An incomplete window returns ready=false with no verdicts. No-data conditions count observations across the whole window, including when the chart displays missing buckets as gaps.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
+      "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
+      "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
+      "A monitor cannot be created active with an `expires_at` already in the past."
+    ],
+    "path_params": [
+      {
+        "name": "project_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the project.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "metric_id",
+        "type": "string",
+        "required": true,
+        "description": "Unique identifier of the metric.",
+        "allowed_values": [],
+        "deprecated": null
+      }
+    ],
+    "query_params": [],
+    "body_fields": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": false,
+        "description": "Name shown for this monitor. Optional. Minimum length: `2`. Maximum length: `64`.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "description",
+        "type": "string | null",
+        "required": false,
+        "description": "What this monitor watches for. Optional.",
+        "allowed_values": [],
+        "deprecated": null
+      },
+      {
+        "name": "status",
+        "type": "string",
+        "required": false,
+        "description": "Whether the monitor starts evaluating immediately or switched off. `disabled` is not accepted: the system uses it to record that it stopped the monitor itself. Optional. Defaults to `\"active\"`.",
+        "allowed_values": [
+          "active",
+          "paused"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "chart_value",
+        "type": "MetricChartValue",
+        "required": false,
+        "description": "Which value of the metric is compared against the threshold. Optional. Defaults to `\"sum\"`.",
+        "allowed_values": [
+          "count",
+          "average",
+          "min",
+          "max",
+          "sum",
+          "last",
+          "cumulative_count",
+          "cumulative_sum",
+          "p50",
+          "p95",
+          "p99",
+          "count_unique"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "scope",
+        "type": "MonitorScope",
+        "required": false,
+        "description": "Whether the monitor fires once for the metric as a whole, or tracks each series separately. Optional. Defaults to `\"total\"`.",
+        "allowed_values": [
+          "total",
+          "any_series",
+          "each_series"
+        ],
+        "deprecated": null
+      },
+      {
+        "name": "time_window_minutes",
+        "type": "integer | null",
+        "required": false,
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
         "allowed_values": [],
         "deprecated": null
       },
@@ -4810,11 +5025,12 @@ export const CLI_COMMANDS = [
         "name": "condition_type",
         "type": "MonitorConditionType",
         "required": false,
-        "description": "Whether the condition is a plain threshold or one that must hold for a duration. Optional. Defaults to `\"threshold\"`.",
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional. Defaults to `\"threshold\"`.",
         "allowed_values": [
           "threshold",
           "sustained",
-          "existence"
+          "existence",
+          "absence"
         ],
         "deprecated": null
       },
@@ -4927,9 +5143,10 @@ export const CLI_COMMANDS = [
       "Changing what the monitor MEANS (its condition, scope, series filters or alert mode) ends any period currently firing, because the old alert no longer describes the new rule.",
       "`metric_id` cannot be changed. Create a new monitor against the other metric instead.",
       "The metric a monitor watches cannot be changed. Create a second monitor instead.",
+      "No-data (`absence`) conditions require `chart_value=count` and a finite `time_window_minutes`.",
       "`sustained_minutes` is required when `condition_type` is `sustained`, and `threshold_value` is required when it is `threshold`.",
       "`min_occurrences` and `occurrence_window_minutes` must both be set or both be null, and occurrence-based triggering cannot be combined with a sustained condition.",
-      "`schedule_cron` must be a valid cron expression.",
+      "`schedule_cron` must be a valid cron expression. It is evaluated in UTC, and the finest granularity is one minute.",
       "`status` is not editable here. Use the pause and resume operations, which is also what keeps a customer from writing the `disabled` the system uses for expiry.",
       "Moving `expires_at` is rejected when that would leave an active monitor with an expiry already in the past. Editing a monitor that has already expired is allowed, including the update that extends its expiry.",
       "Conditions are checked against the monitor as it will be stored, not against the fields you send, so a change that would leave the monitor in an invalid combination is rejected even when the conflicting value is one you did not send."
@@ -5013,9 +5230,9 @@ export const CLI_COMMANDS = [
       },
       {
         "name": "time_window_minutes",
-        "type": "number | null",
+        "type": "integer | null",
         "required": false,
-        "description": "How far back each evaluation looks when it reads the metric. Optional.",
+        "description": "Evaluation lookback in whole minutes (1 to 525600). Null means since the metric was created. No-data conditions require a finite window. Optional.",
         "allowed_values": [],
         "deprecated": null
       },
@@ -5023,11 +5240,12 @@ export const CLI_COMMANDS = [
         "name": "condition_type",
         "type": "MonitorConditionType",
         "required": false,
-        "description": "Whether the condition is a plain threshold or one that must hold for a duration. Optional.",
+        "description": "threshold compares a value, sustained requires that comparison to hold, existence fires when the selected value is greater than zero, and absence fires when no observations exist in the complete evaluation window, regardless of chart gap handling. Optional.",
         "allowed_values": [
           "threshold",
           "sustained",
-          "existence"
+          "existence",
+          "absence"
         ],
         "deprecated": null
       },