@dx-do/cli 6.0.1 → 6.0.4

package/README.md

@@ -47,7 +47,7 @@ bunx @dx-do/cli@<version> <--config=<config-file>> command-group command <parame
 #### Output
 
 ```
-ℹ  info      dx-do v6.0.1 on node v24.16.0 on linux-x64 via node (ssl: 3.5.6)
+ℹ  info      dx-do v6.0.4 on node v24.16.0 on linux-x64 via node (ssl: 3.5.6)
 ⚠  warning   Not loading configuration
 ✖  error     Usage: dx-do --option[=value]... <command-group> <command> <command-param>=<value>...
 ℹ  info      Available command-groups: acc, agent, agentic, alarm, alert, apm-universe, asm, attribute, audit, auth, axa, blob, channel, config, dashboard, diagnose, event, experience, graph, help, inventory, jsextension, log, managementmodule, metrex, metric, metricgrouping, nass, o2-alert, o2-managementmodule, o2-metricgrouping, o2-universe, perspective, service, situation, sql, tas, topographer, trace, ui, vertex
@@ -208,6 +208,8 @@ bunx @dx-do/cli@<version> <--config=<config-file>> command-group command <parame
 ⤜ copy-with-metric-grouping.........................: copy an alert with it's metric grouping
 ⤜ analyze...........................................: analyzes an alert and it's threshold
 ⤜ detail............................................: get alert definition
+⤜ delete............................................: deletes an APM alert (dry-run by default)
+⤜ create............................................: creates a new APM simple alert (dry-run by default)
 ```
 #### nass
 ```nass
@@ -420,6 +422,15 @@ bunx @dx-do/cli@<version> <--config=<config-file>> command-group command <parame
 ⤜ import............................................: imports a management module from json
 ⤜ export............................................: exports a management module and its metric groupings, alerts and calculators.
 ```
+#### metricgrouping
+```metricgrouping
+⤜ update............................................: updates an existing APM metric grouping (dry-run by default)
+⤜ detail............................................: get full detail of an APM metric grouping
+⤜ delete............................................: deletes an APM metric grouping (dry-run by default)
+⤜ create............................................: creates a new APM metric grouping (dry-run by default)
+⤜ list-by-managementmodule..........................: lists all metric groupings in management modules.
+⤜ list-metrics......................................: lists all live metrics in metric grouping
+```
 #### log
 ```log
 ⤜ query.............................................: queries DXO2 Log analytics
@@ -437,11 +448,6 @@ bunx @dx-do/cli@<version> <--config=<config-file>> command-group command <parame
 ⤜ export............................................: Export Map View Perspective
 ⤜ delete............................................: Delete Map View Perspective
 ```
-#### metricgrouping
-```metricgrouping
-⤜ list-by-managementmodule..........................: lists all metric groupings in management modules.
-⤜ list-metrics......................................: lists all live metrics in metric grouping
-```
 #### asm
 ```asm
 ⤜ list-folders......................................: lists asm folders

package/dist-node/{03-discover-sources.nassql.data-store-by6sqk23.json5 → 03-discover-sources.nassql.data-store-d6hb6wf7.json5}

@@ -50,9 +50,10 @@
       "columns": [{ "column": "metric_count", "sortDescending": true }]
     },
     /*
-     * KEEP must be the LAST op in a pipeline (server returns
-     * HTTP 400 if anything follows KEEP). It's the projection
-     * step — selects which columns the response includes.
+     * KEEP is optional; if used it must be the LAST op (server returns
+     * HTTP 400 if anything follows KEEP). It's the projection step —
+     * selects which columns the response includes. Pipelines that end
+     * in AGG / COUNT / TOP / BOTTOM / DESCRIBE need no KEEP at all.
      */
     {
       "op": "KEEP",

package/dist-node/{20-nassql-from-metadata-basic.nassql.data-store-zdf1gp1v.json5 → 20-nassql-from-metadata-basic.nassql.data-store-mq1hn0qz.json5}

@@ -30,8 +30,10 @@
       "as": "total"
     },
     /*
-     * KEEP must be the LAST op (server returns HTTP 400 if anything
-     * follows). Selects which columns appear in the response.
+     * KEEP is optional; if used it must be the LAST op (server returns
+     * HTTP 400 if anything follows). Selects which columns appear in
+     * the response — pipelines ending in AGG / COUNT / TOP / BOTTOM /
+     * DESCRIBE need no KEEP at all.
      */
     {
       "op": "KEEP",

package/dist-node/34-nassql-entity-to-metric-ids.nassql-jn6t8zxs.md

@@ -0,0 +1,76 @@
+# 34-nassql-entity-to-metric-ids (NASSQL)
+
+## Purpose
+
+Given a vertex externalId, list every `metric.id` the entity emits. The canonical "what metrics does this entity produce?" pattern — answered as a flat row-per-metric table that downstream queries (or a human) can iterate over.
+
+Inverse of `42-metadata-metric-id-to-entities`. The two together form the metricId ↔ entity round-trip.
+
+## Query construction
+
+Three-step pipeline:
+
+1. **`FROM_TOPOLOGY`** with a `VERTEX` filter narrowing to the target externalId(s). The filter takes an array, so multiple vertices can be enumerated in a single call.
+2. **`JOIN_METADATA(ALL)`** joins metric metadata rows for those vertices. The join key is implicit — DataStore correlates each topology vertex with the metric descriptors registered against it (the inverse of the `external_ids` association documented in `42-`).
+3. **`KEEP vertex.externalId, metric.id`** — the round-trip-friendly projection. Two columns, one row per metric.
+
+```json
+{
+  "query": [
+    { "op": "FROM_TOPOLOGY",
+      "querySpecifier": { "filter": { "op": "VERTEX", "externalId": ["<vertex-id>"] } } },
+    { "op": "JOIN_METADATA", "querySpecifier": { "op": "ALL" } },
+    { "op": "KEEP", "columns": ["vertex.externalId", "metric.id"] }
+  ],
+  "limit": 200
+}
+```
+
+## API surface exercised
+
+- **TAS `VERTEX` filter** — narrow `FROM_TOPOLOGY` to specific vertices by their externalId list.
+- **`JOIN_METADATA`** — the cross-domain join from topology rows to metric-metadata rows.
+- **The implicit topology↔metadata join key** — DataStore handles the correlation; you don't supply a `metricIdColumn` (only `JOIN_DATA` needs that).
+
+## Sample output
+
+```
+[
+  ["vertex.externalId", "metric.id"],
+  ["ATC:CTS1A01:GENERICFRONTEND:Apps|...", "WCUZP-EQ-_5Y-fp0YUJ0B"],
+  ["ATC:CTS1A01:GENERICFRONTEND:Apps|...", "ABC1d-XY-_3Q-rt7uYJ0B"],
+  ["ATC:CTS1A01:GENERICFRONTEND:Apps|...", "DEFgh-12-_8R-mn5xZK1C"],
+  ...
+]
+```
+
+One row per metric the entity emits. For an entity with rich instrumentation (a JVM-monitored servlet, an Infrastructure-agent host) the count can be in the hundreds.
+
+## The round-trip
+
+| Direction | Query | Field consumed | Field produced |
+|---|---|---|---|
+| entity → metricIds | `34-nassql-entity-to-metric-ids` (this query) | `vertex.externalId` | `metric.id` rows |
+| metricId → entities | `42-metadata-metric-id-to-entities` | `metric.id` | `metric.attributes.external_ids[]` |
+
+A common composite flow: start with a metric.id, run `42-` to find its entity associations, then run `34-` against one of those externalIds to enumerate the entity's full metric catalog.
+
+## Common variations
+
+- **Narrow the joined metrics** — replace `JOIN_METADATA.querySpecifier: { "op": "ALL" }` with a SPEC, an ID list, or a TYPE-bitmask filter (see `40-metadata-filter-by-typeenum`). Useful when you only care about, say, every duration metric the entity emits.
+- **Pivot to data values** — chain `JOIN_DATA` after `JOIN_METADATA` (with `metricIdColumn: "metric.id"`) to attach time-series rows.
+- **Multi-entity** — pass multiple externalIds in the `VERTEX` filter array; rows are per-entity-per-metric.
+
+## When this is useful
+
+- You have an entity (vertex externalId) from a TAS query, an alert, or a service-membership lookup, and need its metric inventory.
+- Building a tenant-coverage audit ("which entities have zero metrics? which have the most?").
+- Feeding a NASSQL `JOIN_DATA` step that needs an enumerated `metric.id` list scoped to a known entity set.
+
+## See also
+
+- `42-metadata-metric-id-to-entities` — the inverse direction (metricId → entity list).
+- `23-nassql-join-topology-metadata` — the same join shape, but aggregating to per-entity counts rather than per-metric rows.
+- `40-metadata-filter-by-typeenum` — for narrowing the joined metric set by metric kind (duration / rate / counter / saturation).
+- `cookbooks/metric-source-names.md` — the metric-name terminology, now extended to cover `external_ids` as the entity-association field.
+- `cookbooks/nassql-cookbook.md` — `JOIN_METADATA` reference.

package/dist-node/34-nassql-entity-to-metric-ids.nassql.data-store-t8ecm336.json5

@@ -0,0 +1,69 @@
+/*
+ * entity → metricIds: given a vertex externalId, list every metric.id
+ * that the entity emits.
+ *
+ * Shape: NASSQL `FROM_TOPOLOGY` filtered to one (or many) vertices by
+ * externalId, then `JOIN_METADATA(ALL)` to pick up the metric metadata
+ * rows for those vertices. `KEEP` projects the round-trip-friendly
+ * pair `(vertex.externalId, metric.id)`.
+ *
+ * The externalId values consumed here are exactly what the sister query
+ * `42-metadata-metric-id-to-entities` produces from its
+ * `metric.attributes.external_ids` field. The two queries form a clean
+ * round-trip:
+ *   externalId → [metric.id, ...] (this query)
+ *   metricId  → external_ids[]   (#42)
+ *
+ * To use this against your tenant: replace the placeholder externalId
+ * with a real vertex externalId. You can obtain one by:
+ *   - running `42-metadata-metric-id-to-entities` and reading
+ *     `metric.attributes.external_ids` from the response, or
+ *   - running a TAS query that includes `externalId` in its projection.
+ *
+ * The shape `<universe-prefix>:<id>:<vertex-type>:<...>` is consistent
+ * across tenants. ExternalIds round-trip without reformatting.
+ *
+ * The placeholder externalId below will return zero rows. That's fine
+ * for parse/validate runs — substitute a real externalId before pulling
+ * an actual metric.id list.
+ */
+{
+  "query": [
+    /*
+     * Source: load topology rows for the named vertex/vertices. The
+     * `VERTEX` filter accepts an array of externalIds and selects every
+     * vertex whose externalId is in the list — typically one row per
+     * matching vertex.
+     */
+    {
+      "op": "FROM_TOPOLOGY",
+      "querySpecifier": {
+        "filter": {
+          "op": "VERTEX",
+          "externalId": ["REPLACE-WITH-REAL-EXTERNAL-ID"]
+        }
+      },
+      "alias": "entities"
+    },
+    /*
+     * Join in metric metadata for those vertices. `op: ALL` includes
+     * every metric the entity emits; substitute a SPEC specifier to
+     * narrow (e.g. duration metrics only — see `40-metadata-filter-by-typeenum`
+     * for the typeEnum bitmask shape).
+     */
+    {
+      "op": "JOIN_METADATA",
+      "querySpecifier": { "op": "ALL" },
+      "alias": "entity_metrics"
+    },
+    /*
+     * Project the round-trip pair: externalId on the left, metric.id on
+     * the right. Each row is one metric the entity emits.
+     */
+    {
+      "op": "KEEP",
+      "columns": ["vertex.externalId", "metric.id"]
+    }
+  ],
+  "limit": 200
+}

package/dist-node/34-nassql-entity-to-metric-ids.nassql.data-store-tmd-9vbg6p76.json

@@ -0,0 +1,4 @@
+{
+  "description": "entity → metricIds: NASSQL FROM_TOPOLOGY (VERTEX externalId filter) + JOIN_METADATA + KEEP — list every metric.id an entity emits",
+  "tags": ["nassql", "topology", "metadata", "id-lookup", "entity-to-metric", "round-trip"]
+}

package/dist-node/40-metadata-filter-by-typeenum.metadata-kmcc85ac.md

@@ -0,0 +1,66 @@
+# 40-metadata-filter-by-typeenum (Metrics Metadata)
+
+## Purpose
+
+Return every metric on the tenant whose `type` is a DURATION variant — the natural query for "show me the latency-shaped metrics" investigations (slow / fast analysis, p99 hunting, response-time dashboards).
+
+Generalizes to any single-axis filter: any RATE, any COUNTER, any SATURATION, any PERCENTAGE — just change `bitMask` / `bitMatch` to the target axis bit.
+
+## Query construction
+
+`metric.type` is a 32-bit integer composed by bitwise-OR of named `typeEnum` values. Each semantic class lives in a fixed bit:
+
+| Class | Bit | Hex |
+|---|---|---|
+| DURATION | 10 | `0x400` |
+| RATE | 9 | `0x200` |
+| COUNTER | 8 | `0x100` |
+| PERCENTAGE | 12 | `0x1000` |
+| INTERVAL_COUNTER | 13 | `0x2000` |
+| SATURATION | 14 | `0x4000` |
+
+The `TYPE` AttributeNameSpecifier matches metrics where `((metric.type & bitMask) operator bitMatch)`. To match "any DURATION variant — INT, LONG, or DOUBLE — regardless of whether it carries a TYPE_INFO_* flag", set both `bitMask` and `bitMatch` to the DURATION bit (`0x400`):
+
+```json
+{ "op": "TYPE", "bitMask": 1024, "bitMatch": 1024, "operator": "EQ",
+  "specifier": { "op": "ALL" } }
+```
+
+The full table of `typeEnum` names → bit values lives in `cookbooks/metrics-grounding.md`. To compose more complex filters in code, use `composeMetricTypeBits([...names])` from `@dx-do/client`.
+
+The same package exposes 6 `ANY_*` axis names (`ANY_DURATION`, `ANY_RATE`, `ANY_COUNTER`, `ANY_PERCENTAGE`, `ANY_INTERVAL_COUNTER`, `ANY_SATURATION`) that resolve to just the semantic-class bit — `composeMetricTypeBits(['ANY_DURATION'])` returns `1024` directly. The chips picker in the visual MM editor groups these under "ANY_* (numeric-info axis)".
+
+## API surface exercised
+
+- **MM `SPEC`** with all three sub-specifier slots filled — the most common MM compose pattern.
+- **`AttributeNameSpecifier.TYPE`** — bitwise type filter, the only way to scope a query by metric kind on the read side (`/metadata/queryMetric` accepts no `typeEnum` field).
+- **`clamp`** — required for safety on real tenants; without it the server returns every matching metric.
+
+## Expected output
+
+Hundreds to thousands of `MetricAttribute` descriptors. Sample on a representative tenant:
+
+```
+{
+  "metrics": [
+    { "type": 1025, "attributeName": "...:Average Response Time (ms)", ... },
+    { "type": 1026, "attributeName": "...:Average Response Time (us)", ... },
+    { "type": 1028, "attributeName": "...:Total time (ms)", ... },
+    { "type": 268436481, "attributeName": "...:Average Response Time (ms)", ... }
+  ],
+  ...
+}
+```
+
+Every returned metric will have bit 10 of `type` set. Decode any `type` value back to typeEnum names with `decodeMetricTypeBits(n)` from `@dx-do/client`.
+
+## Two empirical gotchas this query side-steps
+
+1. The `TYPE` op requires its inner `specifier` field on the wire — the schema marks it optional but the server returns 400 without it. We pass `{ op: "ALL" }` as a no-op inner. Full write-up in `cookbooks/gotchas.md`.
+2. The platform doc lists `MONITOR_INT_DURATION` and `MONITOR_LONG_DURATION` but omits `MONITOR_DOUBLE_DURATION` (`type=1028`), which exists on the wire. The bit-10 filter catches it anyway. Same gotcha file documents the broader pattern.
+
+## See also
+
+- `cookbooks/metrics-grounding.md` — bit-region layout and the full typeEnum table
+- `cookbooks/mm-cookbook.md` — full AttributeNameSpecifier vocabulary
+- `cookbooks/gotchas.md` — TYPE-op inner-specifier requirement; undocumented `MONITOR_DOUBLE_*` variants

package/dist-node/40-metadata-filter-by-typeenum.metadata.data-store-b4erpx6h.json5

@@ -0,0 +1,52 @@
+/*
+ * Filter Metrics Metadata by typeEnum — find every duration metric on the
+ * tenant. Useful for "slow / fast" investigations where you only care about
+ * latency-shaped metrics.
+ *
+ * The trick is the bitwise `TYPE` AttributeNameSpecifier: `metric.type` is
+ * a bitwise OR of named typeEnum values, and bit 10 (0x400) is set on every
+ * DURATION variant — MONITOR_INT_DURATION (1025), MONITOR_LONG_DURATION
+ * (1026), and the undocumented-but-real MONITOR_DOUBLE_DURATION (1028).
+ * Filtering on bit 10 alone catches all three and ignores TYPE_INFO_*
+ * flags (FRONTEND / BACKEND / BUSINESS_TRANSACTION) so frontend-tagged
+ * duration metrics are still returned.
+ *
+ * See `cookbooks/metrics-grounding.md` for the full bit-region layout and
+ * the typeEnum value table. To compose a different bitMask programmatically,
+ * use `composeMetricTypeBits([...names])` from `@dx-do/client`.
+ *
+ * Two empirical gotchas this query side-steps (see `cookbooks/gotchas.md`):
+ *  - The TYPE op's nested `specifier` field is required by the server even
+ *    though the schema marks it optional. We pass `{ op: "ALL" }` as a
+ *    no-op inner.
+ *  - Without `clamp`, MM returns every matching metric on the tenant —
+ *    routinely tens of thousands. We cap at 200 for safe browsing.
+ */
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "ALL" },
+    "folderNameSpecifier":  { "op": "ALL" },
+
+    /*
+     * TYPE specifier with bitMask = bitMatch = 0x400 (1024) means:
+     * "match every metric where bit 10 of `metric.type` is set,
+     * regardless of any other bits." That's the DURATION-axis bit.
+     *
+     * For an exact-typeEnum filter instead, set bitMask = bitMatch =
+     * composeMetricTypeBits(['MONITOR_INT_DURATION']) (= 1025) — that
+     * matches only INT_DURATION, not LONG / DOUBLE.
+     *
+     * For "any rate" use 0x200; "any saturation" use 0x4000;
+     * "any percentage" use 0x1000; "any interval counter" use 0x2000.
+     */
+    "attributeNameSpecifier": {
+      "op": "TYPE",
+      "bitMask": 1024,
+      "bitMatch": 1024,
+      "operator": "EQ",
+      "specifier": { "op": "ALL" }
+    }
+  },
+  "clamp": 200
+}

package/dist-node/40-metadata-filter-by-typeenum.metadata.data-store-tmd-3zg3n0j1.json

@@ -0,0 +1,4 @@
+{
+  "description": "Filter MM by typeEnum bitmask — every duration metric on the tenant (bit 10 = DURATION axis)",
+  "tags": ["metadata", "type-enum", "duration"]
+}

package/dist-node/41-metadata-frontend-durations.metadata-n2ba62j7.md

@@ -0,0 +1,50 @@
+# 41-metadata-frontend-durations (Metrics Metadata)
+
+## Purpose
+
+Return every metric that is **both** a duration variant AND tagged as a frontend metric. This is the canonical "slow on the frontend" slice — what an on-call engineer reaches for after a latency alert fires.
+
+Sister recipe to `40-metadata-filter-by-typeenum`. Where 40 demonstrates the single-axis filter, this one shows the **multi-chip composition** pattern: combine an `ANY_*` semantic-class axis with a `TYPE_INFO_*` flag.
+
+## Query construction
+
+The `TYPE` AttributeNameSpecifier matches metrics where `((metric.type & bitMask) == bitMatch)`. To match "any duration that's frontend-tagged", set both fields to the bitwise OR of the DURATION axis bit and the FRONTEND flag bit:
+
+| Component | typeEnum name | Bit | Hex |
+|---|---|---|---|
+| Numeric-info axis | `ANY_DURATION` | 10 | `0x00000400` |
+| Metric-type info flag | `TYPE_INFO_FRONTEND` | 28 | `0x10000000` |
+| Combined | — | 10 + 28 | `0x10000400` (= 268436480) |
+
+In the visual MM editor, pick both chips from the dropdown — `ANY_DURATION` from the "ANY_* (numeric-info axis)" group and `TYPE_INFO_FRONTEND` from the "TYPE_* (flags)" group. The picker auto-fills `bitMask = bitMatch = 268436480`.
+
+To pivot the same shape:
+
+- **Backend durations** — swap `TYPE_INFO_FRONTEND` for `TYPE_INFO_BACKEND` (`0x20000000`). Combined mask: `0x20000400` = 536871424.
+- **Business-transaction durations** — `TYPE_INFO_BUSINESS_TRANSACTION` (`0x40000000`). Combined mask: `0x40000400` = 1073742848.
+- **Frontend rates / counters / saturations** — swap `ANY_DURATION` for `ANY_RATE` (`0x200`), `ANY_COUNTER` (`0x100`), `ANY_SATURATION` (`0x4000`), etc.
+
+## API surface exercised
+
+- **MM `SPEC`** with all three sub-specifier slots filled.
+- **`AttributeNameSpecifier.TYPE`** — bitwise type filter.
+- **Multi-axis bit composition** — DURATION axis OR'd with TYPE_INFO_* flag.
+
+## Expected output
+
+Hundreds of `MetricAttribute` descriptors, all with bits 10 and 28 set in `type`. Sample shapes on a representative tenant:
+
+```
+{
+  "type": 268436481,
+  "attributeName": "By Frontend|Tomcat Manager Application|Health:Average Response Time (ms)"
+}
+```
+
+`decodeMetricTypeBits(268436481)` from `@dx-do/client` returns `{ matched: ['MONITOR_INT_DURATION', 'TYPE_INFO_FRONTEND'], residual: 0 }`.
+
+## See also
+
+- `40-metadata-filter-by-typeenum` — single-axis (ANY_DURATION) filter, no flag scoping.
+- `cookbooks/metrics-grounding.md` — bit-region layout, full typeEnum table, AND-semantics warning when picking multiple MONITOR_* of the same class.
+- `cookbooks/gotchas.md` — TYPE-op inner-specifier requirement.

package/dist-node/41-metadata-frontend-durations.metadata.data-store-kpkhaf6c.json5

@@ -0,0 +1,48 @@
+/*
+ * Filter Metrics Metadata for FRONTEND-tagged duration metrics — the
+ * "slow on the frontend" investigation slice.
+ *
+ * This is the multi-chip composition pattern: combine an `ANY_*` numeric-info
+ * axis (any DURATION, regardless of INT / LONG / DOUBLE underlying type) with
+ * a `TYPE_INFO_*` flag (FRONTEND vs BACKEND vs BUSINESS_TRANSACTION). The
+ * chips picker's "has all selected bits" semantics produces the right mask:
+ *
+ *   composeMetricTypeBits(['ANY_DURATION', 'TYPE_INFO_FRONTEND'])
+ *     = 0x400 | 0x10000000
+ *     = 0x10000400
+ *     = 268436480
+ *
+ * The server then matches every metric where bit 10 AND bit 28 are both set
+ * — i.e. any duration variant flagged as frontend-source.
+ *
+ * To pivot the same shape:
+ *   - Backend durations         → swap TYPE_INFO_FRONTEND for TYPE_INFO_BACKEND
+ *   - Business-transaction      → swap for TYPE_INFO_BUSINESS_TRANSACTION
+ *   - Frontend rates / counters → swap ANY_DURATION for ANY_RATE / ANY_COUNTER
+ *
+ * See `cookbooks/metrics-grounding.md` for the full bit-region map and the
+ * sister example `40-metadata-filter-by-typeenum` for the unscoped axis-only
+ * pattern.
+ */
+{
+  "specifier": {
+    "op": "SPEC",
+    "sourceNameSpecifier": { "op": "ALL" },
+    "folderNameSpecifier":  { "op": "ALL" },
+
+    /*
+     * bitMask = bitMatch = 0x10000400 means: "match every metric where
+     * (type & 0x10000400) == 0x10000400" — i.e. BOTH the DURATION axis
+     * bit AND the TYPE_INFO_FRONTEND flag bit are set. Server-internal
+     * type-property or counter-info bits are ignored.
+     */
+    "attributeNameSpecifier": {
+      "op": "TYPE",
+      "bitMask": 268436480,
+      "bitMatch": 268436480,
+      "operator": "EQ",
+      "specifier": { "op": "ALL" }
+    }
+  },
+  "clamp": 200
+}

package/dist-node/41-metadata-frontend-durations.metadata.data-store-tmd-c685fc9v.json

@@ -0,0 +1,4 @@
+{
+  "description": "Filter MM for frontend-tagged duration metrics — multi-chip composition (ANY_DURATION ∧ TYPE_INFO_FRONTEND, mask 0x10000400)",
+  "tags": ["metadata", "type-enum", "duration", "frontend"]
+}

package/dist-node/42-metadata-metric-id-to-entities.metadata-qg0p7y71.md

@@ -0,0 +1,67 @@
+# 42-metadata-metric-id-to-entities (Metrics Metadata)
+
+## Purpose
+
+Given a metric id, find the topology vertex (or vertices) that the metric is associated with. The canonical pattern when you have a `metric.id` from somewhere (a query result, an alert payload, a customer ticket) and need to know "what entity does this metric belong to?"
+
+The answer is **`metric.attributes.external_ids`** — an array of TAS-compatible vertex externalIds carried on every metric descriptor, populated by the producer-side agent at registration. Those externalIds are directly consumable by `FROM_TOPOLOGY`'s `VERTEX` filter — see the sister query `34-nassql-entity-to-metric-ids` for the inverse direction.
+
+## Query construction
+
+Two-step author flow:
+
+1. Issue an MM `ID` specifier query with the target `metric.id`(s).
+2. Read each returned `MetricAttribute` descriptor's `attributes.external_ids` array.
+
+```json
+{ "specifier": { "op": "ID", "ids": ["<metric-id>"] }, "clamp": 50 }
+```
+
+## API surface exercised
+
+- **MM `ID` op** — pinpoint by metric id; `ids` is required-non-empty.
+- **`MetricAttribute.attributes.external_ids`** — the entity-association field on every descriptor. Always present, sometimes a single externalId, sometimes multiple.
+
+## Sample output (one matched metric, abridged)
+
+```json
+{
+  "metrics": [{
+    "id": "WCUZP-EQ-_5Y-fp0YUJ0B",
+    "sourceName": "SuperDomain|host|process|agent",
+    "attributeName": "Frontends|Apps|...:Average Response Time (ms)",
+    "type": 1028,
+    "attributes": {
+      "external_ids": [
+        "ATC:CTS1A01:GENERICFRONTEND:Apps|...|CTS1A01|SET:source-tail"
+      ],
+      "agent_external_id": "...",
+      "internal::serviceNames": "...",
+      "metric_name": "Average Response Time (ms)"
+    }
+  }]
+}
+```
+
+The `external_ids` value is the exact string format `FROM_TOPOLOGY` accepts in its `VERTEX` filter — copy-paste round-trips work without reformatting.
+
+## The round-trip
+
+| Direction | Query | Field consumed | Field produced |
+|---|---|---|---|
+| metricId → entities | `42-metadata-metric-id-to-entities` (this query) | `metric.id` | `metric.attributes.external_ids[]` |
+| entity → metricIds | `34-nassql-entity-to-metric-ids` | `vertex.externalId` | `metric.id` rows |
+
+A common composite flow: pull the `external_ids` from this query's response, feed each into `34-`'s VERTEX filter to enumerate every metric the entity emits (not just the one you started with).
+
+## When this is useful
+
+- You have a `metric.id` from an alert, a NASSQL pipeline result, or a customer's ticket and need to ground "which entity is producing this?"
+- You need the `external_ids` to feed into a TAS query for entity-context (parents, neighbors, service membership).
+- You're debugging a metric that mysteriously has multiple `external_ids` (multi-entity registration — uncommon but real).
+
+## See also
+
+- `34-nassql-entity-to-metric-ids` — the inverse direction (entity → metric.id list).
+- `cookbooks/metric-source-names.md` — the four-name terminology, now extended to cover `external_ids` as the fifth name.
+- `cookbooks/mm-cookbook.md` — the `ID` specifier in the full top-level ops table.

package/dist-node/42-metadata-metric-id-to-entities.metadata.data-store-tmd-zd99v6pz.json

@@ -0,0 +1,4 @@
+{
+  "description": "metricId → entity(s): MM ID specifier; entity associations live in `metric.attributes.external_ids` (TAS-compatible vertex externalIds)",
+  "tags": ["metadata", "id-lookup", "metric-to-entity", "round-trip"]
+}

package/dist-node/42-metadata-metric-id-to-entities.metadata.data-store-vwv8dq0e.json5

@@ -0,0 +1,52 @@
+/*
+ * metricId → entity(s): given a metric id, find the topology vertices
+ * (entities) it belongs to.
+ *
+ * Shape: MM `ID` specifier, then read `metric.attributes.external_ids`
+ * from each returned descriptor. That field is an array of TAS-compatible
+ * vertex externalIds — typically one entry per associated entity (often
+ * a single vertex, but multi-entity metrics do exist).
+ *
+ * The externalId values returned here are exactly what the sister query
+ * `34-nassql-entity-to-metric-ids` consumes via FROM_TOPOLOGY's `VERTEX`
+ * filter. The two queries form a clean round-trip:
+ *   metricId  → external_ids[]   (this query)
+ *   externalId → [metric.id, ...] (#34)
+ *
+ * To use this against your tenant: replace the placeholder id with a
+ * real metric.id (run any MM or NASSQL query that projects `metric.id`
+ * to grab one). Multiple ids are supported — `ids` is required-non-empty
+ * and the response keeps order.
+ *
+ * Sample shape of the relevant fields in a successful response:
+ *   {
+ *     "metrics": [{
+ *       "id": "<metric-id>",
+ *       "sourceName": "SuperDomain|host|process|agent",
+ *       "attributeName": "Frontends|Apps|...:Average Response Time (ms)",
+ *       "type": 1028,
+ *       "attributes": {
+ *         "external_ids": [
+ *           "SuperDomain:host-001:HOST:Hosts|host-001",
+ *           ...
+ *         ],
+ *         ... // many other producer-supplied attributes
+ *       }
+ *     }]
+ *   }
+ *
+ * Notes:
+ *  - `clamp` here is generous (50) because each ID lookup typically
+ *    returns at most one descriptor; the headroom is for batched calls
+ *    with many ids.
+ *  - The placeholder id below will return zero metrics. That's fine for
+ *    a parse/validate run — substitute a real id before extracting
+ *    entity associations.
+ */
+{
+  "specifier": {
+    "op": "ID",
+    "ids": ["REPLACE-WITH-REAL-METRIC-ID"]
+  },
+  "clamp": 50
+}

package/dist-node/{SKILL-1xn7r9nt.md → SKILL-86r2cm61.md}

@@ -21,13 +21,15 @@ Always in this order:
 
 The full version of step 1–6 lives in `corpus_get('cookbooks', 'investigator-flow')`. **Read it on the first investigative turn of any session**, then reference inline.
 
-## Three load-bearing distinctions
+## Five load-bearing distinctions
 
 These collapse silently into wrong answers. Internalize them:
 
 - **Universe ≠ Service ≠ DXI_SERVICE.** Two kinds of universes (APM + O2). Services are the secondary scoping axis (often hierarchical). DXI_SERVICE is APM-internal and rarely what the user means by "service." See `corpus_get('entities', 'universe')`, `'service'`, `'dxi_service'`.
 - **`FROM_METADATA` vs `FROM`.** Metadata = metric *definitions*; FROM = metric *datapoints* over time. Same metric, totally different rows. See `corpus_get('cookbooks', 'nassql-quickstart')` source-op decision table at the top.
 - **Query vs analysis.** Default to producing a query that returns *raw data*, not analysis. Let the user / ui / analyzer threshold. *"1-of-30 datapoints over 90 vs all-of-30 over 70"* — same dataset, different shapes; a thresholded query silently picks one. See `corpus_get('cookbooks', 'query-vs-analysis-separation')`.
+- **metricId ↔ entity round-trips.** A metric carries its entity associations in `metric.attributes.external_ids` (array of TAS-compatible vertex externalIds). The two directions are dedicated worked examples: `corpus_get('queries', '42-metadata-metric-id-to-entities')` (metricId → external_ids[]) and `corpus_get('queries', '34-nassql-entity-to-metric-ids')` (externalId → metric.id rows, via `FROM_TOPOLOGY(VERTEX) → JOIN_METADATA`). Reach for these whenever the user has one identifier and needs the other — common after alert-followup, ticket triage, or when chaining a TAS result into a metric query.
+- **alarm `status` vs `severity` vs open/closed.** `status` is the lifecycle axis — `NEW` / `UPDATED` / `CLOSED`, UPPERCASE on the wire. `severity` is the criticality axis — `critical` / `major` / `minor` / `information` / `unknown`, lowercase. They are independent: a CLOSED alarm can be critical; an open alarm can be info. "Are there any alarms?" almost always means *open* alarms (`status != CLOSED`), not "any with severity > info". `list_alarms` defaults to open-only — preserve that default unless the user explicitly widens. See `corpus_get('cookbooks', 'alarms-quickstart')`.
 
 ## Schema landmines (memorize)
 
@@ -45,7 +47,14 @@ NASSQL parallels:
 - **`TOP` / `BOTTOM` use `n`, not `count`.**
 - **`vertex.attr.<name>` is the FROM_TOPOLOGY column convention.**
 
-Full list in `corpus_get('cookbooks', 'tas-quickstart')` and `'nassql-quickstart'` (top of each).
+Metrics-Metadata parallels (read before authoring any "slow / fast / noisy / duration / rate / saturation" filter):
+
+- **`metric.type` is a bitmask, not an enum value** — composing or filtering by typeEnum is bitwise. A `type` of 268436481 decodes to `MONITOR_INT_DURATION + TYPE_INFO_FRONTEND`. Full bit-region map + name→value table in `corpus_get('cookbooks', 'metrics-grounding')`.
+- **The `TYPE` AttributeNameSpecifier requires its inner `specifier` field** — schema marks it optional, server returns 400 without it. Pass `{ op: "ALL" }` as a no-op inner.
+- **AND-trap for same-class MONITOR_* names** — picking both `MONITOR_INT_DURATION` and `MONITOR_LONG_DURATION` composes to `bitMask = bitMatch = 0x403`, which requires bits 0 AND 1 simultaneously (mutually exclusive INT/LONG underlying-type bits) → zero results silently. For "any INT or LONG or DOUBLE of this class", use the `ANY_*` axis names instead: `ANY_DURATION` (= `0x400`), `ANY_RATE` (= `0x200`), `ANY_COUNTER` (= `0x100`), `ANY_PERCENTAGE` (= `0x1000`), `ANY_INTERVAL_COUNTER` (= `0x2000`), `ANY_SATURATION` (= `0x4000`).
+- **Worked examples** — `corpus_get('queries', '40-metadata-filter-by-typeenum')` (axis-only, "any duration") and `'41-metadata-frontend-durations'` (multi-chip composition, "any duration AND frontend-flagged").
+
+Full list in `corpus_get('cookbooks', 'tas-quickstart')` and `'nassql-quickstart'` (top of each); MM specifics in `corpus_get('cookbooks', 'mm-quickstart')` and `'metrics-grounding'`.
 
 ## Tool defaults
 
@@ -70,6 +79,18 @@ run_query                                          ← final execution (against
 create_query                                      ← save, then hand off
 ```
 
+When the question is about ALARMS (not topology, not metrics — actual OI alarms: alert breaches, host-down, service-health drops, log conditions, EUM/AXA events):
+
+```
+corpus_get('cookbooks', 'alarms-quickstart')      ← first turn touching alarms in any session
+list_alarms                                        ← the answer (defaults to open-only, 1h window)
+get_alarm / get_alarm_lifecycle /                  ← drilldowns
+  get_related_alarms
+list_alarm_queues                                  ← when the user names a saved filter
+```
+
+Alarms are a separate API — `list_alarms`, not `run_query`. Don't try to author a TAS / NASSQL / MM query "for alarms" — there isn't one. The alarms surface returns its own document shape and has its own vocabulary (`status` UPPERCASE, `severity` lowercase, `external_ids[]` round-trips back to TAS, `services_impacted` only on the lifecycle).
+
 **Don't** guess attribute names, layer names, service names, or vertex types. Always discover. The cost is one tool call; the reward is correctness.
 
 ## Handoff phrasing
@@ -102,3 +123,6 @@ When more clarification is needed before authoring:
 - `corpus_get('cookbooks', 'gotchas')` — empirical surprises across all of the above.
 - `corpus_get('cookbooks', 'run-query-vs-run-partial')` — full vs partial execution choice.
 - `corpus_get('cookbooks', 'tas-quickstart')` / `'nassql-quickstart'` / `'mm-quickstart'` — schema-level details when authoring.
+- `corpus_get('cookbooks', 'metrics-grounding')` — `metric.type` bitmask layout, typeEnum table, `ANY_*` axis names; load before authoring any "slow / fast / noisy / duration / rate" MM filter.
+- `corpus_get('cookbooks', 'alarms-quickstart')` — the "are there any alarms?" entry point; `status` vs `severity` axes; recipes for open/closed/severity/host-scoped/queue-scoped lookups.
+- `corpus_get('cookbooks', 'alarms-cookbook')` — full Alarm document shape, the timestamp map (which fields are populated and which are interface-only), alarm-queue semantics, lifecycle-event taxonomy (including where `services_impacted` actually lives).