# DbxCentral — API Reference

REST endpoints, WebSocket feeds, and the MCP (Model Context Protocol) server.

## MCP Server NEW

DbxCentral implements the Model Context Protocol (MCP) over HTTP/SSE, enabling AI agents (Claude, Cursor, VS Code Copilot, etc.) to query database performance data directly. The endpoint must be enabled in `DBX_CENTRAL.conf`.

##### POST GET /mcp

POST — JSON-RPC 2.0 endpoint for MCP tool calls.
GET — Server-Sent Events (SSE) stream for alarm push notifications (when `mcp.sseNotificationsEnabled=true`).

###### Authentication

Set `DbxTuneCentral.mcp.apiToken` in `DBX_CENTRAL.conf` and pass it as:
`Authorization: Bearer <token>` or `X-Api-Token: <token>`

###### MCP Client Configuration (Claude Desktop example)

    {
      "mcpServers": {
        "dbxcentral": {
          "url": "http://your-host:8080/mcp",
          "headers": { "Authorization": "Bearer your-secret-token-here" }
        }
      }
    }

###### Available Tools

Tool | Description
--- | ---
list_servers | List all monitored servers currently registered in DbxCentral
list_metrics | List available graph metrics for a server (CmName + graphName)
list_cms | List all Counter Models on the collector with active/data status
get_metric_data | Fetch raw or aggregated time-series data for a specific graph
get_performance_summary | CPU, I/O, memory, connections overview (CmSummary)
get_wait_stats | Top wait types ranked by total time (CmWaitStats)
get_blocking_info | Current and historical blocking chains
get_top_queries | Most expensive queries ranked by CPU, reads, elapsed, or executions
get_active_statements | Live active SQL statements with session context, referenced tables, and execution plans
get_spid_waits | Per-session wait breakdown from the collector
get_memory_analysis | Memory clerk allocations and grant wait analysis
get_io_analysis | Disk I/O activity by database and file
get_tempdb_usage | TempDB space usage by session
get_query_context | Table size, index health, and SQL activity context for a specific table (DSR + live CMs)
get_table_schema | Table/index DDL and statistics from DSR + live collector CMs
get_object_ddl | DDL definitions, table metadata, and execution plans from MonDdlStorage
compare_baseline | Diff performance between two time windows (summary, waits, queries)
list_daily_reports | List available Daily Summary Report (DSR) files
get_daily_report_section | Extract a named section from a DSR as plain text
trigger_query_store_extract | SQL Server: trigger an on-demand Query Store extraction (runs at midnight normally); poll with action=status
get_query_store_databases | SQL Server: list databases with captured Query Store data + health/storage metrics
get_query_store_top_queries | SQL Server: top N queries from Query Store ranked by duration/cpu/reads/executions/memory
get_query_store_query_detail | SQL Server: full detail for a query_id — all plans, wait stats, timeline, plan regression signal
get_active_alarms | Currently active alarms across all or one server
get_alarm_history | Historical alarm events in a time range
get_dbms_config | Full DBMS configuration (gated by `mcp.exposeDbmsConfig=true`)

###### Time range formats (accepted by most tools)

Format | Example | Meaning
--- | --- | ---
Relative | `-1h`, `-30m`, `-7d` | Last N hours/minutes/days from now
Absolute | `2026-04-10 14:30:00` | Exact timestamp
Now | `now` | Current time

###### Key DBX_CENTRAL.conf settings

Property | Default | Description
--- | --- | ---
DbxTuneCentral.mcp.enabled | false | Enable the /mcp endpoint
DbxTuneCentral.mcp.apiToken | (none) | Bearer token for authentication
DbxTuneCentral.mcp.allowedHosts | 127.0.0.1 | Comma-separated IP allowlist
DbxTuneCentral.mcp.maxTimeRangeHours | 168 | Max query window (hours)
DbxTuneCentral.mcp.exposeDbmsConfig | false | Enable get_dbms_config tool
DbxTuneCentral.mcp.sseNotificationsEnabled | false | Push alarm events via SSE GET /mcp

## Collector Proxy APIs NEW

These endpoints proxy requests from DbxCentral to the appropriate collector (DbxTune PCS). All require `srv=SERVERNAME`. The collector must be online and registered.

##### GET /api/cc/mgt/cm/list

List all Counter Models on the collector with their active/data status.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
time | now | Timestamp for hasData window: `now` or `yyyy-MM-dd HH:mm:ss`

##### GET /api/cc/mgt/cm/data

Fetch the latest snapshot for a single Counter Model from the collector. Returns `{ "columns": [...], "rows": [[...], ...] }`.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
cm | mandatory | CM name, e.g. `CmWaitStats`, `CmActiveStatements`
time | now | Sample timestamp
type | abs | `abs`, `diff`, or `rate`

##### GET /api/cc/mgt/ddl-storage

Retrieve DDL definitions, table/index metadata, and execution plans from MonDdlStorage on the collector. MonDdlStorage is automatically populated during monitoring with CREATE statements, table size info, optimizer diagnostics, and captured execution plans.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
objectName | (all) | Case-insensitive partial match on object name
dbname | (all) | Database name filter. Use `statement_cache` for execution plans
type | (all) | Comma-separated type codes: `U`=Table, `V`=View, `P`=Proc/Func, `TR`=Trigger, `SS`=Execution plan
includeText | true | `true/false` — include DDL text blobs (objectText, extraInfoText, etc.)
ts | now | Timestamp for H2 date-rolling: selects the correct historical database file
limit | 200 | Max items returned

##### GET /api/cc/mgt/query-store

SQL Server Query Store data captured nightly by the collector into H2 schemas named `qs:<DatabaseName>`. Extraction runs automatically at midnight (`doLastRecordingActionBeforeDatabaseRollover`). Use `ts` to select data from a specific day's H2 recording.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
action | mandatory | GET actions (read-only): `listDatabases` — all databases with QS data + health info `topQueries` — top N queries ranked by cost metric `queryDetail` — full detail for a specific query_id `extractStatus` — poll the status of a running/completed extraction POST actions (write): `extract` — trigger an on-demand extraction (async, returns immediately)
dbname | (all) | Database name. Required for topQueries/queryDetail.
queryId |  | Required for queryDetail: the query_id to inspect
rankBy | duration | topQueries ranking: `duration` | `cpu` | `reads` | `executions` | `memory`
topN | 25 | Max queries returned (topQueries)
minExecutions | 2 | Minimum execution count filter (noise reduction)
includePlan | false | queryDetail: include XML execution plan text (can be large)
type | QUERY_STORE | extract/extractStatus: `QUERY_STORE` | `DEADLOCK` | `JOB_SCHEDULER` | `BACKUP_HISTORY`
ts | now | Timestamp for H2 date-rolling (selects the correct historical DB file)

On-demand extraction pattern: `POST ?action=extract&type=QUERY_STORE` → returns `{"status":"started",...}` → poll `GET ?action=extractStatus&type=QUERY_STORE` until `lastStatus="ok"` → then call `topQueries` or `queryDetail` for today's data. Extraction typically takes 1–3 minutes.

##### GET /api/cc/mgt/dbms-config

Full DBMS configuration captured at collector startup: sp_configure values, database options, trace flags, and detected configuration issues.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
ts | (latest) | Timestamp to find the closest session start

## Sessions & Servers

##### GET /api/sessions

Available sessions and basic information about each.

Parameter | Default | Description
--- | --- | ---
type | last | `last` — last available session; `all` — all recordings
graphs | false | Include available graphs for each session
status | all | Filter by session status

##### GET /api/server-layout

Server list and layout configuration for the landing page. No parameters.

##### GET /api/healthcheck

Health status for one or all collectors.

Parameter | Default | Description
--- | --- | ---
srv | (all) | Server name to check
age | sampleInterval×20 | Minutes without data before marking unhealthy. `<0` = skip data-received check; `0` = auto (interval×20); `>0` = explicit minutes
srvInfo | true | Include server info in response
result | array | `array` or `map`

## Graph Data

##### GET /api/graphs

Available graphs for a server or profile.

Parameter | Default | Description
--- | --- | ---
sessionName | mandatory | Server/session/profile name
sessionStartTime | (last session) | Specific session start time

##### GET /api/graph/data

Time-series graph data for a specific CM and graph.

Parameter | Default | Description
--- | --- | ---
sessionName | mandatory | Server name
cmName |  | Counter Model name (e.g. `CmSummary`, `CmWaitStats`)
graphName |  | Graph name within the CM
startTime | -2h | Start time: `-Nm`, `-Nh`, `-Nd`, or `yyyy-MM-dd HH:mm:ss`
endTime | (now) | End time, same formats as startTime
sampleType | AUTO | `ALL` — every data point `AUTO` — automatic downsampling when >360 points `MAX_OVER_SAMPLES`, `MIN_OVER_SAMPLES` — peak/min per N samples `MAX_OVER_MINUTES`, `MIN_OVER_MINUTES`, `AVG_OVER_MINUTES`, `SUM_OVER_MINUTES` — bucketed by time
sampleValue |  | N for non-ALL/AUTO sample types
autoOverflow | 360 | Point threshold before AUTO switches to downsampling

##### GET /api/graph/profiles

Details for a named graph profile.

Parameter | Default | Description
--- | --- | ---
name | mandatory | Profile name
user |  | User-specific profile
dbxTypeName |  | Product name (SqlServerTune, AseTune, PostgresTune, …)

##### WS /api/chart/broadcast-ws

WebSocket subscription for live graph data push.

Parameter | Default | Description
--- | --- | ---
serverList | mandatory | Comma-separated server names
graphList |  | Comma-separated graph names to subscribe to

##### GET /api/last-sample

Latest counter snapshot for a specific CM (raw counters format with absCounters/diffCounters/rateCounters).

Parameter | Default | Description
--- | --- | ---
srv | (all) | Server name
cm | mandatory | CM name (e.g. `CmActiveStatements`)

##### GET /api/space/forecast

Space usage forecast for OS disk, data files, or WAL/log.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name
type | os | `os`, `data`, or `wal`
days | 30 | Number of history days to use for the forecast
period | 60 | Sample aggregation period in minutes
outType | html-page | `html-page`, `html-table`, or `json`

## Alarms

##### GET /api/alarm/active

Currently active alarms. Returns an empty array if none.

Parameter | Default | Description
--- | --- | ---
srv | (all) | Filter by server name

##### GET /api/alarm/history

Historical alarm events (RAISE, RE-RAISE, CANCEL).

Parameter | Default | Description
--- | --- | ---
srv | (all) | Filter by server name
age |  | Time window, e.g. `-24h` or `-7d`
type |  | Filter by event type: `RAISE`, `RE-RAISE`, `CANCEL`
category |  | Filter by alarm category: `CPU`, `DISK`, etc.

## Reports & Logs

##### GET /report

Access Daily Summary Report (DSR) HTML files.

Parameter | Default | Description
--- | --- | ---
name | mandatory | Server name, or full report filename (`SRVNAME.2026-04-10_0003.html`)
op | mandatory | `viewLatest`, `view`, or `remove`

##### GET /alarmLog

Retrieve an alarm log file.

Parameter | Default | Description
--- | --- | ---
name | mandatory | Filename only (not full path)
type |  | `RAISE`, `CANCEL`
method | html | `pcs`, `json`, `html`
age |  | For `pcs`: `-10l` (last 10 rows), `-10m` (last 10 min), `-10h`, `-10d`, or `yyyy-MM-dd HH:mm:ss`

##### GET /log

Retrieve a log file.

Parameter | Default | Description
--- | --- | ---
name | mandatory | Filename only (not full path)
method | plain | `plain`, `json`, `html`
discard |  | RegEx for lines to exclude (plain mode only)
tail |  | Number of lines to tail (plain mode only)

##### WS /logtail

WebSocket feeder for live log tail (`tail -f` style). Used internally by the log viewer.

##### GET /h2ws

H2 writer statistics chart (internal storage performance).

Parameter | Default | Description
--- | --- | ---
filename | mandatory | Log filename (typically `DBX_CENTRAL_H2WriterStatCronTask.log`)
startDate | mandatory | RFC 3339: `yyyy-MM-ddThh:mm`
endDate | mandatory | RFC 3339: `yyyy-MM-ddThh:mm`

## Admin & Misc

##### POST /api/pcs/receiver

Inbound data receiver — this is where DbxTune collectors push monitoring data to DbxCentral. Not intended for direct external use.

##### GET /api/pcs/queueInfo

Inbound PCS queue depth — how many entries are waiting to be written to persistent storage.

##### GET /api/collector-refresh

Send a configuration refresh request to a collector.

Parameter | Default | Description
--- | --- | ---
srv | mandatory | Server name

##### GET /conf

Retrieve a configuration file by name.

Parameter | Default | Description
--- | --- | ---
name | mandatory | Configuration filename

##### GET /overview

Overview page with all managed servers and their current status.

##### GET /download-local-dbxtune

Download the latest local DbxTune ZIP package from the DbxCentral server. May be a newer version than the public release.

##### GET /admin

Admin panel with internal management commands.

##### GET /admin/shutdown

Shutdown or restart DbxCentral.

##### GET /login-check

Check whether the current browser session is authenticated.

##### GET /logout

Log out and invalidate the current session.
DbxCentral API Reference — kept in `resources/WebContent/api/index.html`