cubeapm-mcp 1.2.0 → 1.3.1

package/README.md

@@ -207,7 +207,7 @@ Readable resources exposing CubeAPM data and configuration:
 
 ## CubeAPM Query Patterns
 
-### Metrics Naming Conventions
+### Metrics (PromQL / MetricsQL)
 
 CubeAPM uses specific naming conventions that differ from standard OpenTelemetry:
 
@@ -217,7 +217,7 @@ CubeAPM uses specific naming conventions that differ from standard OpenTelemetry
 | Service label | `service` (NOT `server` or `service_name`) |
 | Common labels | `env`, `service`, `span_kind`, `status_code`, `http_code` |
 
-### Histogram Queries (P50, P90, P95, P99)
+#### Histogram Queries (P50, P90, P95, P99)
 
 CubeAPM uses **VictoriaMetrics-style histograms** with `vmrange` labels instead of Prometheus `le` buckets:
 
@@ -233,7 +233,9 @@ histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))
 
 > **Note:** Latency values are returned in **seconds** (0.05 = 50ms)
 
-### Logs Label Discovery
+### Logs (LogsQL)
+
+#### Stream Selectors
 
 Log labels vary by source. Use `*` query first to discover available labels:
 
@@ -249,17 +251,92 @@ Log labels vary by source. Use `*` query first to discover available labels:
 # Lambda function logs
 {faas.name="my-lambda-prod"}
 
-# Search with text filter
-{faas.name=~".*-prod"} AND "error"
+# Regex match
+{faas.name=~".*-prod"}
+
+# Text filter with boolean operators
+{faas.name=~".*"} AND "error" AND NOT "retry"
+```
+
+#### Pipe Operators
+
+Chain after any query with `|`:
+
+| Pipe | Syntax | Description |
+|------|--------|-------------|
+| `copy` | `\| copy src AS dst` | Copy field value |
+| `drop` | `\| drop field1, field2` | Remove fields from output |
+| `extract_regexp` | `\| extract_regexp "(?P<name>re)"` | Extract via named capture groups |
+| `join` | `\| join by (field) (...subquery...)` | Join with subquery results |
+| `keep` | `\| keep field1, field2` | Keep only specified fields |
+| `limit` | `\| limit N` | Return at most N results |
+| `math` | `\| math result = f1 + f2` | Arithmetic (+, -, *, /, %) |
+| `rename` | `\| rename src AS dst` | Rename a field |
+| `replace` | `\| replace (field, "old", "new")` | Substring replacement |
+| `replace_regexp` | `\| replace_regexp (field, "re", "repl")` | Regex replacement |
+| `sort` | `\| sort by (field) [asc\|desc]` | Sort results |
+| `stats` | `\| stats <func> as alias [by (fields)]` | Aggregate results |
+| `unpack_json` | `\| unpack_json` | Extract fields from JSON body |
+
+#### Stats Functions
+
+Used with the `| stats` pipe:
+
+| Function | Description |
+|----------|-------------|
+| `avg(field)` | Arithmetic mean |
+| `count()` | Total matching entries |
+| `count_empty(field)` | Entries where field is empty |
+| `count_uniq(field)` | Distinct values |
+| `max(field)` | Maximum value |
+| `median(field)` | Median (50th percentile) |
+| `min(field)` | Minimum value |
+| `quantile(p, field)` | p-th quantile (e.g., `quantile(0.95, duration)`) |
+| `sum(field)` | Sum of values |
+
+#### Example Log Queries
+
+```logsql
+# Count errors per Lambda function
+{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)
+
+# Top 10 slowest requests
+{service_name="my-service"} | sort by (duration) desc | limit 10
+
+# Extract and aggregate from JSON logs
+{service_name="api"} | unpack_json | stats avg(response_time) as avg_rt by (endpoint)
+```
+
+### Traces
+
+Trace queries use the same pipe syntax as logs: `{stream_selector} | pipe1 | pipe2`
+
+**Important notes:**
+- `query`, `env`, `service` are REQUIRED parameters
+- Duration is in **milliseconds** (not seconds like metrics)
+- `p95` is NOT a valid stats function — use `quantile(0.95, duration)`
+- Service names are case-sensitive (e.g., `"Kratos-Prod"` not `"kratos"`)
+
+#### Example Trace Queries
+
+```
+# P95 latency for a service
+{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms
+
+# Error count by endpoint
+{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)
+
+# Slowest spans
+{service="Kratos-Prod"} | sort by (duration) desc | limit 20
 ```
 
-## Example Queries
+## Example Natural Language Queries
 
 ### Logs
 ```
 "Show me logs from webhook-lambda-prod"
 "Find all logs containing 'timeout' in the last hour"
-"Query logs from Lambda functions in production"
+"Count errors per Lambda function in the last 24h"
 ```
 
 ### Metrics
@@ -271,7 +348,7 @@ Log labels vary by source. Use `*` query first to discover available labels:
 
 ### Traces
 ```
-"Find slow traces (>2s) from the order-service"
+"Find the P95 latency for Kratos-Prod using trace stats"
 "Show me traces with errors in the production environment"
 "Get the full waterfall for trace ID abc123"
 ```

package/dist/index.js

@@ -25,6 +25,90 @@ const server = new McpServer({
 // ============================================
 // LOGS APIs
 // ============================================
+// Convert RFC3339 string or Unix timestamp (s/ms/μs/ns) to nanoseconds.
+// CubeAPM's prod UI embeds time in queries as `_time:[ns_start, ns_end)`,
+// so we mirror that wire format rather than relying on start/end form params.
+function toNanoseconds(t) {
+    if (/^\d+$/.test(t)) {
+        const n = BigInt(t);
+        if (n < 10000000000n)
+            return (n * 1000000000n).toString(); // seconds
+        if (n < 10000000000000n)
+            return (n * 1000000n).toString(); // milliseconds
+        if (n < 10000000000000000n)
+            return (n * 1000n).toString(); // microseconds
+        return n.toString(); // nanoseconds
+    }
+    const ms = new Date(t).getTime();
+    if (Number.isNaN(ms))
+        throw new Error(`Invalid timestamp: ${t}`);
+    return (BigInt(ms) * 1000000n).toString();
+}
+// Find the index of the first top-level pipe operator in a LogsQL query,
+// ignoring `|` inside quoted strings (regex alternation like `=~"a|b"`),
+// brace groups `{...}`, or parens `(...)`. Returns -1 if no pipe found.
+function findFirstTopLevelPipe(query) {
+    let inDouble = false;
+    let inSingle = false;
+    let braceDepth = 0;
+    let parenDepth = 0;
+    for (let i = 0; i < query.length; i++) {
+        const c = query[i];
+        const prev = i > 0 ? query[i - 1] : "";
+        // Honour backslash escapes inside strings (e.g. `"shopify\\-prod"`).
+        if (prev === "\\")
+            continue;
+        if (inDouble) {
+            if (c === '"')
+                inDouble = false;
+            continue;
+        }
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (c === "{") {
+            braceDepth++;
+            continue;
+        }
+        if (c === "}") {
+            braceDepth--;
+            continue;
+        }
+        if (c === "(") {
+            parenDepth++;
+            continue;
+        }
+        if (c === ")") {
+            parenDepth--;
+            continue;
+        }
+        if (c === "|" && braceDepth === 0 && parenDepth === 0)
+            return i;
+    }
+    return -1;
+}
+// Inject `_time:[start_ns,end_ns)` before the first top-level pipe operator
+// (or at end if none). Quote/brace/paren aware to handle regex alternations
+// like `=~"shopify-latest|shopify-prod"` without splitting mid-string.
+function injectTimeFilter(query, startNs, endNs) {
+    const timeFilter = `_time:[${startNs},${endNs})`;
+    const pipeIdx = findFirstTopLevelPipe(query);
+    if (pipeIdx === -1)
+        return `${query.trim()} ${timeFilter}`.trim();
+    const head = query.slice(0, pipeIdx).trim();
+    const tail = query.slice(pipeIdx);
+    return `${head} ${timeFilter} ${tail}`;
+}
 server.tool("query_logs", `Query logs from CubeAPM using LogsQL syntax (VictoriaLogs compatible). Returns log entries matching the query.
 
 IMPORTANT - Log Label Discovery:
@@ -41,20 +125,49 @@ LogsQL Query Syntax:
 - Negation: {faas.name!="unwanted-service"}
 - Combine filters: {env="UNSET", faas.name=~".*-lambda.*"}
 
+PIPE OPERATORS — chain after query with "|":
+  | copy src_field AS dst_field       — copy field value
+  | drop field1, field2               — remove fields from output
+  | extract_regexp "(?P<name>regex)"  — extract fields via named capture groups
+  | join by (field) (...subquery...)   — join with subquery results
+  | keep field1, field2               — keep only specified fields
+  | limit N                           — return at most N results
+  | math result = field1 + field2     — compute derived fields (+, -, *, /, %)
+  | rename src AS dst                 — rename a field
+  | replace (field, "old", "new")     — replace substring in field
+  | replace_regexp (field, "re", "replacement") — regex replacement
+  | sort by (field) [asc|desc]        — sort results
+  | stats <func> as alias [by (group_fields)] — aggregate results
+  | unpack_json                       — extract fields from JSON log body
+
+STATS FUNCTIONS (use with | stats pipe):
+  avg(field)            — arithmetic mean
+  count()               — total number of matching entries
+  count_empty(field)    — count entries where field is empty
+  count_uniq(field)     — count distinct values
+  max(field)            — maximum value
+  median(field)         — median (50th percentile)
+  min(field)            — minimum value
+  quantile(p, field)    — p-th quantile (e.g., quantile(0.95, duration))
+  sum(field)            — sum of values
+
 Example queries:
 - All logs (discover structure): *
 - Lambda logs: {faas.name="webhook-lambda-prod"}
 - Search errors: {faas.name=~".*"} AND "error"
-- By environment: {env="production"}`, {
+- By environment: {env="production"}
+- Count errors per function: {faas.name=~".*"} AND "error" | stats count() as error_count by (faas.name)
+- Top 10 slowest: {service_name="my-service"} | sort by (duration) desc | limit 10`, {
     query: z.string().describe("The log search query including stream filters (LogsQL syntax)"),
     start: z.string().describe("Start time in RFC3339 format (e.g., 2024-01-01T00:00:00Z) or Unix timestamp in seconds"),
     end: z.string().describe("End time in RFC3339 format or Unix timestamp in seconds"),
     limit: z.number().optional().default(100).describe("Maximum log entries to return (default: 100)"),
 }, async ({ query, start, end, limit }) => {
+    const startNs = toNanoseconds(start);
+    const endNs = toNanoseconds(end);
+    const finalQuery = injectTimeFilter(query, startNs, endNs);
     const params = new URLSearchParams({
-        query,
-        start,
-        end,
+        query: finalQuery,
         limit: String(limit),
     });
     const response = await fetch(`${queryBaseUrl}/api/logs/select/logsql/query`, {
@@ -206,15 +319,45 @@ IMPORTANT - Required Parameters:
 - Use env="UNSET" if environment is not configured
 - Service names are case-sensitive (e.g., "Kratos-Prod" not "kratos")
 
-Optional filters:
+TRACE QUERY SYNTAX:
+The query parameter supports pipe syntax similar to LogsQL:
+  {stream_selector} | pipe1 | pipe2
+
+Stream selectors filter spans:
+  {service="Kratos-Prod"}
+  {service="Kratos-Prod", span_kind="server"}
+  {http_code=~"5.."}
+
+PIPE OPERATORS — same as LogsQL pipes:
+  | copy, | drop, | extract_regexp, | join, | keep, | limit,
+  | math, | rename, | replace, | replace_regexp, | sort,
+  | stats <func> as alias [by (group_fields)], | unpack_json
+
+STATS FUNCTIONS (for aggregate trace analysis):
+  avg(field)            — arithmetic mean
+  count()               — total matching spans
+  count_uniq(field)     — distinct values
+  max(field)            — maximum value
+  median(field)         — median value
+  min(field)            — minimum value
+  quantile(p, field)    — p-th quantile (e.g., quantile(0.95, duration))
+  sum(field)            — sum of values
+
+IMPORTANT: Duration in traces is in MILLISECONDS.
+IMPORTANT: "p95" is NOT a valid function — use quantile(0.95, duration).
+
+Example queries:
+  Wildcard: query="*"
+  P95 latency: query='{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_latency'
+  Error count by endpoint: query='{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)'
+  Slow spans: query='{service="Kratos-Prod"} | sort by (duration) desc | limit 20'
+
+Optional filters (applied in addition to query):
 - spanKind: server, client, consumer, producer
 - sortBy: duration (to find slow traces)
 
 To discover available service names, first query metrics:
-count by (service) (cube_apm_calls_total{env="UNSET"})
-
-Example: Find slow server spans in Shopify-Prod
-  query="*", env="UNSET", service="Shopify-Prod", spanKind="server", sortBy="duration"`, {
+count by (service) (cube_apm_calls_total{env="UNSET"})`, {
     query: z.string().default("*").describe("The traces search query (use * for wildcard)"),
     env: z.string().default("UNSET").describe("Environment name (use UNSET if not configured)"),
     service: z.string().describe("Service name to filter by (REQUIRED, case-sensitive)"),
@@ -224,13 +367,16 @@ Example: Find slow server spans in Shopify-Prod
     spanKind: z.string().optional().describe("Filter by span kind: server, client, consumer, producer"),
     sortBy: z.string().optional().describe("Sort results by: duration"),
 }, async ({ query, env, service, start, end, limit, spanKind, sortBy }) => {
+    // Generate a random index value for the API call
+    const index = Math.random().toString(36).substring(2, 15);
     const params = new URLSearchParams({
         query,
         env,
         service,
         start,
         end,
-        limit: String(limit)
+        limit: String(limit),
+        index
     });
     if (spanKind)
         params.append("spanKind", spanKind);
@@ -446,34 +592,122 @@ server.resource("query-patterns", "cubeapm://query-patterns", {
             {
                 uri: "cubeapm://query-patterns",
                 mimeType: "text/markdown",
-                text: `# CubeAPM Query Patterns
+                text: `# CubeAPM Query Patterns — Full Reference
 
-## Metrics Naming Conventions
+## Metrics (PromQL / MetricsQL)
+
+### Naming Conventions
 - Prefix: \`cube_apm_*\` (e.g., cube_apm_calls_total, cube_apm_latency_bucket)
 - Service label: \`service\` (NOT "server" or "service_name")
 - Common labels: env, service, span_kind, status_code, http_code
 
-## Histogram Queries (Percentiles)
-CubeAPM uses VictoriaMetrics-style histograms with \`vmrange\` label:
+### Histogram Queries (Percentiles)
+CubeAPM uses VictoriaMetrics-style histograms with \`vmrange\` label (NOT Prometheus \`le\` buckets):
 
 \`\`\`promql
-# P95 Latency
+# ✅ Correct — use histogram_quantiles() with vmrange
 histogram_quantiles("phi", 0.95, sum by (vmrange, service) (
   increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])
 ))
+
+# ❌ Wrong — standard Prometheus syntax won't work
+histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))
 \`\`\`
 
-Note: Latency values are in SECONDS (0.05 = 50ms)
+Latency values are in SECONDS (0.05 = 50ms).
+
+---
 
 ## Logs (LogsQL)
-- Use \`*\` to discover available labels
-- Lambda logs: \`{faas.name="my-function"}\`
-- Service logs: \`{service_name="my-service"}\`
+
+### Stream Selectors
+- \`*\` — wildcard, discover all labels
+- \`{faas.name="my-function"}\` — exact match
+- \`{faas.name=~".*-prod"}\` — regex match
+- \`{faas.name!="unwanted"}\` — negation
+- \`{env="production", faas.name=~".*"}\` — combine filters
+
+### Text Filters
+- \`{stream} AND "error"\` — text search
+- \`{stream} AND "timeout" AND NOT "retry"\` — boolean operators
+
+### Pipe Operators
+Chain after query with \`|\`:
+
+| Pipe | Syntax | Description |
+|------|--------|-------------|
+| copy | \`copy src AS dst\` | Copy field value |
+| drop | \`drop field1, field2\` | Remove fields from output |
+| extract_regexp | \`extract_regexp "(?P<name>re)"\` | Extract via named capture groups |
+| join | \`join by (field) (...subquery...)\` | Join with subquery |
+| keep | \`keep field1, field2\` | Keep only specified fields |
+| limit | \`limit N\` | Return at most N results |
+| math | \`math result = f1 + f2\` | Arithmetic (+, -, *, /, %) |
+| rename | \`rename src AS dst\` | Rename a field |
+| replace | \`replace (field, "old", "new")\` | Substring replacement |
+| replace_regexp | \`replace_regexp (field, "re", "repl")\` | Regex replacement |
+| sort | \`sort by (field) [asc/desc]\` | Sort results |
+| stats | \`stats <func> as alias [by (fields)]\` | Aggregate results |
+| unpack_json | \`unpack_json\` | Extract fields from JSON body |
+
+### Stats Functions
+Used with \`| stats\` pipe:
+
+| Function | Description |
+|----------|-------------|
+| \`avg(field)\` | Arithmetic mean |
+| \`count()\` | Total matching entries |
+| \`count_empty(field)\` | Entries where field is empty |
+| \`count_uniq(field)\` | Distinct values |
+| \`max(field)\` | Maximum value |
+| \`median(field)\` | Median (50th percentile) |
+| \`min(field)\` | Minimum value |
+| \`quantile(p, field)\` | p-th quantile (e.g., quantile(0.95, duration)) |
+| \`sum(field)\` | Sum of values |
+
+### Example Log Queries
+\`\`\`logsql
+# Discover labels
+*
+
+# Count errors per Lambda function
+{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)
+
+# Top 10 slowest requests
+{service_name="my-service"} | sort by (duration) desc | limit 10
+\`\`\`
+
+---
 
 ## Traces
+
+### Query Syntax
+Trace queries use the same pipe syntax:
+\`{stream_selector} | pipe1 | pipe2\`
+
+### Stream Selectors
+- \`{service="Kratos-Prod"}\`
+- \`{service="Kratos-Prod", span_kind="server"}\`
+- \`{http_code=~"5.."}\`
+
+### Important Notes
 - query, env, service are REQUIRED parameters
-- Use \`sortBy=duration\` to find slow traces
+- Duration is in MILLISECONDS (not seconds like metrics)
+- \`p95\` is NOT a valid function — use \`quantile(0.95, duration)\`
+- Use \`sortBy=duration\` param to find slow traces
 - Filter by spanKind: server, client, consumer, producer
+
+### Example Trace Queries
+\`\`\`
+# P95 latency for a service
+{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms
+
+# Error count by endpoint
+{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)
+
+# Slowest spans
+{service="Kratos-Prod"} | sort by (duration) desc | limit 20
+\`\`\`
 `,
             },
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeapm-mcp",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "MCP server for CubeAPM - Query traces, metrics, and logs from your observability platform using AI assistants",
   "type": "module",
   "main": "dist/index.js",