@prodisco/prometheus-client

Typed Prometheus client with semantic metric discovery for AI agents. Wraps the prometheus-query library with a clean TypeScript interface.

Table of Contents

• Features
• Installation
• Quick Start
• API Reference
• Types
• Environment Variables
• License

Features

• Semantic Metric Search: Find metrics by natural language queries (e.g., "memory usage")
• Typed Execution: Full TypeScript support for PromQL execution
• Orama Integration: Uses @prodisco/search-libs for fast, indexed metric search

Installation

npm install @prodisco/prometheus-client

Quick Start

import { PrometheusClient, MetricSearchEngine } from '@prodisco/prometheus-client';

// Create client and search engine
const client = new PrometheusClient({ endpoint: 'http://prometheus:9090' });
const search = new MetricSearchEngine(client);

// 1. DISCOVER metrics with semantic search
const memoryMetrics = await search.search('memory usage');
console.log(memoryMetrics);
// [{ name: 'container_memory_working_set_bytes', type: 'gauge', help: 'Current working set in bytes' }, ...]

// 2. EXECUTE PromQL with discovered metric names
const result = await client.executeRange('container_memory_working_set_bytes', {
  start: new Date(Date.now() - 3600000), // 1 hour ago
  end: new Date(),
  step: '5m'
});
console.log(result.data);

API Reference

MetricSearchEngine

Semantic search for discovering available metrics. Use this first before executing queries.

import { PrometheusClient, MetricSearchEngine } from '@prodisco/prometheus-client';

const client = new PrometheusClient({ endpoint: 'http://prometheus:9090' });
const search = new MetricSearchEngine(client);

Methods

search(query: string, options?: MetricSearchOptions): Promise<MetricInfo[]>

Search metrics by natural language. Searches both metric names AND descriptions.

// Find memory-related metrics
const metrics = await search.search('memory usage');

// Find CPU metrics, filter by type
const gauges = await search.search('cpu', { type: 'gauge', limit: 10 });

index(force?: boolean): Promise<number>

Manually index/refresh metrics from Prometheus. Called automatically on first search.

const count = await search.index();
console.log(`Indexed ${count} metrics`);

list(options?: MetricSearchOptions): Promise<MetricInfo[]>

List all indexed metrics.

const allMetrics = await search.list({ limit: 100 });

PrometheusClient

Execute PromQL queries against Prometheus. Note: You should know the metric names first - use MetricSearchEngine.search() to discover them.

import { PrometheusClient } from '@prodisco/prometheus-client';

const client = new PrometheusClient({
  endpoint: 'http://prometheus:9090',
  timeout: 30000, // optional, default 30s
});

Methods

execute(promql: string, time?: Date): Promise<InstantQueryResult>

Execute an instant PromQL query.

// First discover metrics: await search.search('http requests')
// Then execute with known metric name:
const result = await client.execute('http_requests_total');

executeRange(promql: string, range: TimeRange): Promise<RangeQueryResult>

Execute a range PromQL query over a time period.

// First discover metrics: await search.search('memory')
// Then execute with known metric name:
const result = await client.executeRange('node_memory_MemTotal_bytes', {
  start: new Date(Date.now() - 3600000), // 1 hour ago
  end: new Date(),
  step: '5m',
});

result.data.forEach(series => {
  console.log(`Labels: ${JSON.stringify(series.labels)}`);
  series.samples.forEach(s => {
    console.log(`  ${new Date(s.time * 1000)}: ${s.value}`);
  });
});

listMetrics(): Promise<MetricInfo[]>

Get raw metric metadata from Prometheus. For semantic search, use MetricSearchEngine instead.

const metrics = await client.listMetrics();

labelNames(): Promise<string[]>

Get all label names.

labelValues(label: string): Promise<string[]>

Get all values for a specific label.

isHealthy(): Promise<boolean>

Check if Prometheus is reachable.

Helper Function

createMetricSearchEngine(endpoint: string): MetricSearchEngine

Create a MetricSearchEngine directly from an endpoint.

import { createMetricSearchEngine } from '@prodisco/prometheus-client';

const search = createMetricSearchEngine('http://prometheus:9090');
const metrics = await search.search('disk usage');

Types

MetricInfo

interface MetricInfo {
  name: string;      // Metric name (e.g., "http_requests_total")
  type: MetricType;  // 'counter' | 'gauge' | 'histogram' | 'summary' | 'unknown'
  help: string;      // Description
}

MetricSearchOptions

interface MetricSearchOptions {
  limit?: number;    // Max results (default: 20)
  type?: MetricType; // Filter by metric type
}

TimeRange

interface TimeRange {
  start: Date | number;  // Start time
  end: Date | number;    // End time
  step: string;          // Step interval (e.g., "15s", "1m", "5m")
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PROMETHEUS_URL | Prometheus server endpoint | - |

License

MIT