cubeapm-mcp 1.0.0 → 1.1.0

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": {
@@ -160,20 +176,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

@@ -3,11 +3,20 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 // Configuration from environment variables
+// CUBEAPM_URL takes precedence - use full URL like https://prod-cube.example.com
+// Falls back to building URL from CUBEAPM_HOST + ports for backward compatibility
+const CUBEAPM_URL = process.env.CUBEAPM_URL;
 const CUBEAPM_HOST = process.env.CUBEAPM_HOST || "localhost";
 const CUBEAPM_QUERY_PORT = process.env.CUBEAPM_QUERY_PORT || "3140";
 const CUBEAPM_INGEST_PORT = process.env.CUBEAPM_INGEST_PORT || "3130";
-const queryBaseUrl = `http://${CUBEAPM_HOST}:${CUBEAPM_QUERY_PORT}`;
-const ingestBaseUrl = `http://${CUBEAPM_HOST}:${CUBEAPM_INGEST_PORT}`;
+// If CUBEAPM_URL is provided, use it directly (removes trailing slash if present)
+// Otherwise build from host:port
+const queryBaseUrl = CUBEAPM_URL
+    ? CUBEAPM_URL.replace(/\/$/, '')
+    : `http://${CUBEAPM_HOST}:${CUBEAPM_QUERY_PORT}`;
+const ingestBaseUrl = CUBEAPM_URL
+    ? CUBEAPM_URL.replace(/\/$/, '')
+    : `http://${CUBEAPM_HOST}:${CUBEAPM_INGEST_PORT}`;
 // Create the MCP server
 const server = new McpServer({
     name: "cubeapm-mcp",
@@ -16,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"),
@@ -59,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"),
@@ -95,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"),
@@ -138,7 +198,16 @@ 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.", {
+server.tool("search_traces", `Search for traces in CubeAPM matching the specified criteria. Returns trace snippets with key spans.
+
+Tips for effective trace searches:
+- Service names are case-sensitive (e.g., "Kratos-Prod" not "kratos")
+- Use the service parameter to filter by service name
+- Use the env parameter to filter by environment
+- Time range is required (start/end in RFC3339 or Unix timestamp)
+
+To discover available service names, first query metrics:
+count by (service) (cube_apm_calls_total{env="UNSET"})`, {
     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"),

package/package.json

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