dsh-prometheus-plugin
A DeepSeek Harness (dsh) plugin that exposes the
Prometheus HTTP API as a set of tools an LLM agent can call. Built on the
Cordis framework and
@deepseek-ai/dsh-tools.
Features
- 30 tools covering the full Prometheus HTTP API: instant / range queries, metadata & series discovery, targets, rules / alerts / alertmanagers, server status, the experimental Search API, and the admin TSDB endpoints.
- A single shared HTTP client (
src/client.ts) with consistent error formatting and a configurable request timeout (AbortController, default 30s). - Declarative tool definitions via
@deepseek-ai/dsh-tools, friendly for agent use.
Prerequisites
- A running Prometheus instance reachable over HTTP.
- Some endpoints require extra Prometheus launch flags:
- Admin tools (
admin-snapshot,admin-delete-series,admin-clean-tombstones) require--web.enable-admin-api. - Search tools (
search-metric-names,search-label-names,search-label-values) require--enable-feature=search-api. - Some endpoints are only available in newer Prometheus versions
(
format-query,parse-query,query-exemplars,status-tsdb(3.6.0+),status-self-metrics,features, …). Pointing a tool at an older server returns an HTTP error from Prometheus itself.
- Admin tools (
Usage
Install the bundle into your dsh profile:
git clone https://github.com/HuckOps/dsh-prometheus-plugin
# In dsh (agent or Plugin Manager), install the bundle:
# plugin_manager install_bundle /path/to/dsh-prometheus-plugin
The bundle declares cordis.patch.yml, which registers the promql-plugin
entry with the package @local/dsh-prometheus-plugin (resolved via the
dsh.bundle.patch field in package.json). No manual cordis.yml editing is
needed.
The patch ships a default config:
- insert:
- id: promql-plugin
name: '@local/dsh-prometheus-plugin'
config:
prometheusEndpoint: http://127.0.0.1:9090
Edit the patch (or override the entry's config) to point at your Prometheus
instance. prometheusEndpoint defaults to http://127.0.0.1:9090 when omitted.
To build from source:
npm install # postinstall runs tsc, output to lib/
Note: runtime dependencies (
@deepseek-ai/dsh-tools,@deepseek-ai/cordis,@deepseek-ai/schemastery) are declared as peer dependencies matching the DSH host runtime; they are not bundled into the plugin.
Tools
All tools are registered with the promql- prefix.
Query
| Tool | Prometheus endpoint |
|---|---|
promql-query |
GET /api/v1/query |
promql-query-range |
GET /api/v1/query_range |
promql-format-query |
GET /api/v1/format_query |
promql-parse-query |
GET /api/v1/parse_query |
promql-query-exemplars |
GET /api/v1/query_exemplars |
Metadata & series
| Tool | Prometheus endpoint |
|---|---|
promql-series |
GET /api/v1/series |
promql-labels |
GET /api/v1/labels |
promql-label-values |
GET /api/v1/label/{name}/values |
promql-metadata |
GET /api/v1/metadata |
Targets
| Tool | Prometheus endpoint |
|---|---|
promql-targets |
GET /api/v1/targets |
promql-targets-metadata |
GET /api/v1/targets/metadata |
promql-scrape-pools |
GET /api/v1/scrape_pools |
Rules / alerts / alertmanagers
| Tool | Prometheus endpoint |
|---|---|
promql-rules |
GET /api/v1/rules |
promql-alerts |
GET /api/v1/alerts |
promql-alertmanagers |
GET /api/v1/alertmanagers |
Status
| Tool | Prometheus endpoint |
|---|---|
promql-status-config |
GET /api/v1/status/config |
promql-status-flags |
GET /api/v1/status/flags |
promql-status-runtimeinfo |
GET /api/v1/status/runtimeinfo |
promql-status-buildinfo |
GET /api/v1/status/buildinfo |
promql-status-tsdb |
GET /api/v1/status/tsdb (3.6.0+) |
promql-status-tsdb-blocks |
GET /api/v1/status/tsdb/blocks |
promql-status-walreplay |
GET /api/v1/status/walreplay |
promql-status-self-metrics |
GET /api/v1/status/self_metrics |
promql-features |
GET /api/v1/features |
Search (experimental, requires --enable-feature=search-api)
| Tool | Prometheus endpoint |
|---|---|
promql-search-metric-names |
GET /api/v1/search/metric_names |
promql-search-label-names |
GET /api/v1/search/label_names |
promql-search-label-values |
GET /api/v1/search/label_values |
Admin (requires --web.enable-admin-api)
| Tool | Prometheus endpoint |
|---|---|
promql-admin-snapshot |
POST /api/v1/admin/tsdb/snapshot |
promql-admin-delete-series |
POST /api/v1/admin/tsdb/delete_series |
promql-admin-clean-tombstones |
POST /api/v1/admin/tsdb/clean_tombstones |
Project layout
.
├── cordis.patch.yml # dsh bundle patch: registers the promql-plugin entry
├── package.json # bundle manifest (dsh.bundle.patch) + peer deps
├── icon.svg # bundle display icon
├── locale/
│ ├── en.json
│ └── zh.json
├── tsconfig.json
├── README.md
├── LICENSE
└── src/
├── index.ts # package entry: re-exports apply/inject/Config
├── client.ts # shared HTTP client + error handling + timeout
├── query.ts # query / query_range / format_query / parse_query / query_exemplars
├── metadata.ts # series / labels / label_values / metadata
├── targets.ts # targets / targets_metadata / scrape_pools
├── rules.ts # rules / alerts / alertmanagers
├── status.ts # config / flags / runtimeinfo / buildinfo / tsdb / tsdb_blocks / walreplay / self_metrics / features
├── search.ts # search/metric_names / search/label_names / search/label_values
├── admin.ts # admin/tsdb/snapshot / delete_series / clean_tombstones
└── plugin.ts # entry: imports and registers all tools
License
MIT © 2026 HuckOps
No comments yet. Be the first to write one.