ktm metrics query

Execute a raw InfluxQL query against the operator's metrics database

Usage

ktm metrics query [flags]

Examples

# Discover available measurements
ktm metrics query --operator acme --query "SHOW MEASUREMENTS"

# Explore fields in a measurement
ktm metrics query --operator acme --query "SHOW FIELD KEYS FROM \"test\""

# Success Rate over last 24h grouped by 5 minutes
ktm metrics query --operator acme --query "SELECT sum(\"number_success\")/(sum(\"number_success\")+sum(\"number_failed\"))*100 AS \"Success Rate (%)\" FROM \"test\" WHERE time > now() - 24h GROUP BY time(5m)"

# Platform activity events over last 24h
ktm metrics query --operator acme --query "SELECT * FROM \"event\" WHERE time >= '2026-02-17T00:00:00Z' AND time <= '2026-02-18T00:00:00Z' ORDER BY time DESC LIMIT 50"

Flags

Details

Execute a raw InfluxQL query against the metrics proxy.

Kapptivate monitors generate KPI metrics in InfluxDB. Each monitor run writes data points across multiple measurements depending on the test's action types.

Common measurement patterns (start with SHOW MEASUREMENTS to discover what's available):

• "test" — test-level KPIs: number_success, number_failed, number_total, duration_seconds (always present for any monitored test)
• "action" — per-step execution data, field: duration_seconds (one row per action in a test)
• "event" — platform activity overview: logins, test runs triggered, user actions. Essential for usage reports. Use SHOW FIELD KEYS FROM "event" to discover fields — metadata field may contain JSON.
• "cellular_*" — KPIs from SIM card actions (only tests with SIM action types)
• "smartphone_*" — KPIs from smartphone actions (only tests with smartphone action types)
• "ethernet_*" — KPIs from web agent actions (only tests with ethernet action types)
• "kcollector_*" — passive data collected from customer IT systems

IMPORTANT: Each action-type measurement (cellular_, ethernet_, smartphone_, web_browsing) only contains data from tests that USE that action type. They are NOT infrastructure metrics. For example, ethernet_http_api has data only if a test contains an ETH_HTTP_API action. Before correlating, check which monitors populate a measurement: SHOW TAG VALUES FROM "<measurement>" WITH KEY = "monitoring_name" To investigate a monitor: ktm monitors list → ktm monitors get --id <id> → see test_id, scheduling, variables. If not found → monitor was deleted (data is historical). To see the test definition: ktm tests get --id <test_id> (from the monitor). For filtering queries by monitor: use "monitoring_id" or "monitoring_name" in WHERE clauses.

IMPORTANT: InfluxDB retains data after a test or monitor is deleted. Measurements may contain orphaned data from monitors that no longer exist. Check freshness before analysis: SELECT last(duration_seconds), time FROM "<measurement>"

Exception tables (not generated by monitors):

• "resource_usage" — device utilization (use 'metrics resource-usage' instead)
• "robots_statistics" — internal platform data (can be ignored)
• "sim_card_statistics" — signal level in dBm per SIM resource

A single monitor typically writes to "test" plus one or more action-specific measurements. Use tags (SHOW TAG KEYS) to filter by specific test, product, or monitor.

Schema discovery workflow (FOLLOW THIS ORDER):

1. SHOW MEASUREMENTS → list available tables
2. SHOW FIELD KEYS FROM <measurement> → numeric fields available
3. SHOW TAG VALUES FROM <measurement> WITH KEY = "monitoring_name" → which monitors populate this table
4. SELECT last(<field>), time FROM <measurement> → check freshness (stale = deleted monitor)
5. SHOW TAG KEYS FROM <measurement> → filterable dimensions
6. SHOW TAG VALUES FROM <measurement> WITH KEY = "<tag>" → actual tag values
7. SELECT ... FROM <measurement> WHERE time > now() - 7d GROUP BY time(1h)

Always include a WHERE time clause. Maximum recommended range: 90 days (use GROUP BY time() for wide ranges). Raw selects without aggregation: prefer 30 days max. Queries must complete within 60 seconds — use LIMIT and GROUP BY time() for large datasets.

Output modes:

• Default: raw JSON (for scripting and piping)
• --summary: full statistical analysis (67 metrics per column, EWMA, anomaly detection, trends)
• --executive: compact 1-line-per-series C-level summary with health classification

For reports, use --executive. For raw analysis, use --summary.

Notes

• Raw InfluxQL against monitor KPIs. For SLO compliance use ktm metrics slo; for cross-signal correlation use ktm metrics correlate.

Related

• ktm metrics
• ktm monitors list
• ktm monitors get
• ktm tests get
• ktm metrics resource-usage

What's next?