cubeapm-mcp 1.0.1 → 1.1.1

package/README.md

@@ -68,7 +68,8 @@ You can now ask Claude questions like:
 
 | Environment Variable | Default | Description |
 |---------------------|---------|-------------|
-| `CUBEAPM_HOST` | `localhost` | CubeAPM server hostname or IP |
+| `CUBEAPM_URL` | - | Full URL to CubeAPM (e.g., `https://cube.example.com`). Takes precedence over HOST/PORT settings. |
+| `CUBEAPM_HOST` | `localhost` | CubeAPM server hostname or IP (used if CUBEAPM_URL not set) |
 | `CUBEAPM_QUERY_PORT` | `3140` | Port for querying APIs (traces, metrics, logs) |
 | `CUBEAPM_INGEST_PORT` | `3130` | Port for ingestion APIs |
 
@@ -89,7 +90,22 @@ You can now ask Claude questions like:
 }
 ```
 
-**Production:**
+**Production (with full URL):**
+```json
+{
+  "mcpServers": {
+    "cubeapm": {
+      "command": "npx",
+      "args": ["-y", "cubeapm-mcp"],
+      "env": {
+        "CUBEAPM_URL": "https://cubeapm.internal.company.com"
+      }
+    }
+  }
+}
+```
+
+**Production (with host/port):**
 ```json
 {
   "mcpServers": {
@@ -143,12 +159,16 @@ You can now ask Claude questions like:
 | `search_traces` | Search traces by service, environment, or custom query |
 | `get_trace` | Fetch complete trace details by trace ID |
 
-**Search Parameters:**
-- `query` - Optional search query
-- `env` - Environment filter (e.g., `production`)
-- `service` - Service name filter
-- `start` / `end` - Time range
+**Search Parameters (Required):**
+- `query` - Search query (default: `*` for wildcard)
+- `env` - Environment filter (default: `UNSET`)
+- `service` - Service name filter (**required**, case-sensitive)
+- `start` / `end` - Time range (RFC3339 or Unix timestamp)
+
+**Search Parameters (Optional):**
 - `limit` - Maximum results (default: 20)
+- `spanKind` - Filter by span type: `server`, `client`, `consumer`, `producer`
+- `sortBy` - Sort by: `duration` (useful for finding slow traces)
 
 **Get Trace Parameters:**
 - `trace_id` - Hex-encoded trace ID
@@ -160,20 +180,68 @@ You can now ask Claude questions like:
 |------|-------------|
 | `ingest_metrics_prometheus` | Send metrics in Prometheus text exposition format |
 
+## CubeAPM Query Patterns
+
+### Metrics Naming Conventions
+
+CubeAPM uses specific naming conventions that differ from standard OpenTelemetry:
+
+| What | CubeAPM Convention |
+|------|-------------------|
+| Metric 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 (P50, P90, P95, P99)
+
+CubeAPM uses **VictoriaMetrics-style histograms** with `vmrange` labels instead of Prometheus `le` buckets:
+
+```promql
+# ✅ 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 returned in **seconds** (0.05 = 50ms)
+
+### Logs Label Discovery
+
+Log labels vary by source. Use `*` query first to discover available labels:
+
+| Source | Common Labels |
+|--------|---------------|
+| Lambda functions | `faas.name`, `faas.arn`, `env`, `aws.lambda_request_id` |
+| Services | `service_name`, `level`, `host` |
+
+```logsql
+# Discover all labels
+*
+
+# Lambda function logs
+{faas.name="my-lambda-prod"}
+
+# Search with text filter
+{faas.name=~".*-prod"} AND "error"
+```
+
 ## Example Queries
 
 ### Logs
 ```
-"Find all ERROR logs from auth-service in the last 30 minutes"
-"Show me logs containing 'connection refused' from the database service"
-"Query logs where trace_id matches xyz123"
+"Show me logs from webhook-lambda-prod"
+"Find all logs containing 'timeout' in the last hour"
+"Query logs from Lambda functions in production"
 ```
 
 ### Metrics
 ```
-"What's the average request duration for the API gateway?"
-"Show me CPU usage for all services over the last 6 hours"
-"Graph the error rate for checkout-service with 1-minute resolution"
+"What's the P95 latency for Kratos-Prod service?"
+"Show me error rate for all services"
+"List all available services in CubeAPM"
 ```
 
 ### Traces

package/dist/index.js

@@ -25,7 +25,27 @@ const server = new McpServer({
 // ============================================
 // LOGS APIs
 // ============================================
-server.tool("query_logs", "Query logs from CubeAPM using LogsQL syntax. Returns log entries matching the query.", {
+server.tool("query_logs", `Query logs from CubeAPM using LogsQL syntax (VictoriaLogs compatible). Returns log entries matching the query.
+
+IMPORTANT - Log Label Discovery:
+- Labels vary by source! Use "*" query first to discover available labels
+- Lambda logs use: faas.name, faas.arn, env, aws.lambda_request_id
+- Service logs may use: service_name, level, host
+- NOT all sources have "service_name" - check the _stream field in results
+
+LogsQL Query Syntax:
+- Wildcard (discover labels): *
+- Stream filters: {faas.name="my-lambda-prod"}
+- Text search: {faas.name="webhook-lambda-prod"} AND "error"
+- Regex match: {faas.name=~".*-prod"}
+- Negation: {faas.name!="unwanted-service"}
+- Combine filters: {env="UNSET", faas.name=~".*-lambda.*"}
+
+Example queries:
+- All logs (discover structure): *
+- Lambda logs: {faas.name="webhook-lambda-prod"}
+- Search errors: {faas.name=~".*"} AND "error"
+- By environment: {env="production"}`, {
     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"),
@@ -68,7 +88,24 @@ server.tool("query_logs", "Query logs from CubeAPM using LogsQL syntax. Returns
 // ============================================
 // METRICS APIs
 // ============================================
-server.tool("query_metrics_instant", "Execute an instant query against CubeAPM metrics at a single point in time. Uses PromQL-compatible syntax.", {
+server.tool("query_metrics_instant", `Execute an instant query against CubeAPM metrics at a single point in time. Uses PromQL-compatible syntax (VictoriaMetrics flavor).
+
+IMPORTANT - CubeAPM Metric Naming Conventions:
+- Metrics use "cube_apm_" prefix (e.g., cube_apm_calls_total, cube_apm_latency_bucket)
+- Service label is "service" (NOT "server" or "service_name")
+- Common labels: env, service, span_kind (server|client|consumer|producer), status_code, http_code
+
+HISTOGRAM QUERIES (P50, P90, P95, P99):
+- CubeAPM uses VictoriaMetrics-style histograms with "vmrange" label (NOT Prometheus "le" buckets)
+- Use histogram_quantiles() function instead of histogram_quantile()
+- Syntax: histogram_quantiles("phi", 0.95, sum by (vmrange) (increase(cube_apm_latency_bucket{...}[5m])))
+- Latency values are returned in SECONDS (0.05 = 50ms)
+
+Example queries:
+- P95 latency: histogram_quantiles("phi", 0.95, sum by (vmrange, service) (increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])))
+- Error rate: sum by (service) (increase(cube_apm_calls_total{status_code="ERROR"}[1h])) / sum by (service) (increase(cube_apm_calls_total[1h])) * 100
+- List services: count by (service) (cube_apm_calls_total{env="UNSET"})
+- Request count: sum by (service) (increase(cube_apm_calls_total{span_kind=~"server|consumer"}[1h]))`, {
     query: z.string().describe("The metrics query expression (PromQL syntax)"),
     time: z.string().describe("Evaluation timestamp in RFC3339 format or Unix timestamp in seconds"),
     step: z.number().optional().describe("Time window in seconds for processing data"),
@@ -104,7 +141,21 @@ server.tool("query_metrics_instant", "Execute an instant query against CubeAPM m
         ],
     };
 });
-server.tool("query_metrics_range", "Execute a range query against CubeAPM metrics over a time range. Returns time series data.", {
+server.tool("query_metrics_range", `Execute a range query against CubeAPM metrics over a time range. Returns time series data. Uses PromQL-compatible syntax (VictoriaMetrics flavor).
+
+IMPORTANT - CubeAPM Metric Naming Conventions:
+- Metrics use "cube_apm_" prefix (e.g., cube_apm_calls_total, cube_apm_latency_bucket)
+- Service label is "service" (NOT "server" or "service_name")
+- Common labels: env, service, span_kind (server|client|consumer|producer), status_code, http_code
+
+HISTOGRAM QUERIES (P50, P90, P95, P99):
+- CubeAPM uses VictoriaMetrics-style histograms with "vmrange" label (NOT Prometheus "le" buckets)
+- Use histogram_quantiles() function instead of histogram_quantile()
+- Syntax: histogram_quantiles("phi", 0.95, sum by (vmrange, service) (increase(cube_apm_latency_bucket{...}[5m])))
+- Latency values are returned in SECONDS (0.05 = 50ms)
+
+Example range query for P95 over time:
+histogram_quantiles("phi", 0.95, sum by (vmrange, service) (increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])))`, {
     query: z.string().describe("The metrics query expression (PromQL syntax)"),
     start: z.string().describe("Start timestamp in RFC3339 format or Unix timestamp"),
     end: z.string().describe("End timestamp in RFC3339 format or Unix timestamp"),
@@ -147,21 +198,44 @@ server.tool("query_metrics_range", "Execute a range query against CubeAPM metric
 // ============================================
 // TRACES APIs
 // ============================================
-server.tool("search_traces", "Search for traces in CubeAPM matching the specified criteria. Returns trace snippets with key spans.", {
-    query: z.string().optional().describe("The traces search query"),
-    env: z.string().optional().describe("Environment name to filter by"),
-    service: z.string().optional().describe("Service name to filter by"),
+server.tool("search_traces", `Search for traces in CubeAPM matching the specified criteria. Returns trace snippets with key spans.
+
+IMPORTANT - Required Parameters:
+- query, env, service, start, end are ALL REQUIRED by CubeAPM API
+- Use query="*" for wildcard search
+- Use env="UNSET" if environment is not configured
+- Service names are case-sensitive (e.g., "Kratos-Prod" not "kratos")
+
+Optional filters:
+- 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"`, {
+    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)"),
     start: z.string().describe("Start timestamp in RFC3339 format or Unix seconds"),
     end: z.string().describe("End timestamp in RFC3339 format or Unix seconds"),
     limit: z.number().optional().default(20).describe("Maximum number of traces to return"),
-}, async ({ query, env, service, start, end, limit }) => {
-    const params = new URLSearchParams({ start, end, limit: String(limit) });
-    if (query)
-        params.append("query", query);
-    if (env)
-        params.append("env", env);
-    if (service)
-        params.append("service", service);
+    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 }) => {
+    const params = new URLSearchParams({
+        query,
+        env,
+        service,
+        start,
+        end,
+        limit: String(limit)
+    });
+    if (spanKind)
+        params.append("spanKind", spanKind);
+    if (sortBy)
+        params.append("sortBy", sortBy);
     const response = await fetch(`${queryBaseUrl}/api/traces/api/v1/search?${params.toString()}`, { method: "GET" });
     if (!response.ok) {
         return {

package/package.json

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