Prometheus datasource for QuickStat
npm install @quickstat/prometheusThe QuickStat Prometheus DataSource provides seamless integration for collecting and exporting metrics to Prometheus. It supports multiple strategies including scraping, push gateway, and remote write, enabling flexible metric collection patterns for different deployment scenarios.
If you are new to QuickStat and its components, feel free to check the official documentation for a detailed breakdown.
Install the QuickStat core package and the Prometheus datasource:
``bash`
npm install @quickstat/core
npm install @quickstat/prometheus
QuickStat offers a range of examples to help you get started with monitoring your metrics. These examples cover various use cases and demonstrate how to integrate QuickStat with different libraries and frameworks.
- Node.js Plugin Example
- PM2 Plugin Example
- REST Plugin Example
- Express.js Plugin Example
- Fastify Plugin Example
- Koa Plugin Example
The Prometheus DataSource can be used with any QuickStat plugin or custom metrics. It offers three different strategies for metric collection:
1. ScrapeStrategy: Exposes metrics on an HTTP endpoint for Prometheus to scrape (pull model)
2. PushGatewayStrategy: Pushes metrics to a Prometheus Push Gateway (push model)
3. RemoteWriteStrategy: Sends metrics using Prometheus remote write protocol (push model)
The most common approach is using the scrape strategy where Prometheus pulls metrics from your application:
`typescript
import { Client as QuickStatClient } from '@quickstat/core'
import { PrometheusDataSource, ScrapeStrategy } from '@quickstat/prometheus'
import http from 'http'
// Create QuickStat Client with Prometheus DataSource
const quickStatClient = new QuickStatClient
metrics: [
// Add your custom metrics here
],
plugins: [
// Add your plugins here (e.g., ExpressPlugin, NodeJSPlugin, etc.)
],
dataSource: new PrometheusDataSource({
strategy: new ScrapeStrategy(),
}),
})
// Expose metrics endpoint for Prometheus scraping
// WARNING: On production, properly secure this endpoint
http.createServer(async (req, res) => {
const response = await quickStatClient.dataSource?.strategy?.getResponse()
if (response) {
res.writeHead(200, response.headers)
res.end(response.file)
}
}).listen(9090, () => {
console.log('Metrics available at http://localhost:9090')
})
`
For batch jobs or applications behind firewalls, use the Push Gateway strategy:
`typescript
import { Client as QuickStatClient } from '@quickstat/core'
import { PrometheusDataSource, PushGatewayStrategy } from '@quickstat/prometheus'
const quickStatClient = new QuickStatClient
metrics: [
// Add your custom metrics here
],
plugins: [
// Add your plugins here
],
dataSource: new PrometheusDataSource({
strategy: new PushGatewayStrategy({
url: 'http://localhost:9091', // Your Push Gateway URL
auto: {
pushInterval: 10000, // Push every 10 seconds
jobName: 'my-application',
},
}),
}),
})
// Manually push metrics
await quickStatClient.dataSource?.strategy?.push('my-job')
// Or push with custom groupings
await quickStatClient.dataSource?.strategy?.push('my-job', {
instance: 'server-1',
environment: 'production',
})
`
For direct integration with Prometheus remote write endpoints:
`typescript
import { Client as QuickStatClient } from '@quickstat/core'
import { PrometheusDataSource, RemoteWriteStrategy } from '@quickstat/prometheus'
const quickStatClient = new QuickStatClient
metrics: [
// Add your custom metrics here
],
plugins: [
// Add your plugins here
],
dataSource: new PrometheusDataSource({
strategy: new RemoteWriteStrategy({
// Remote write configuration
}),
}),
})
`
The ScrapeStrategy accepts minimal configuration as it simply exposes metrics for scraping:
`typescript`
new ScrapeStrategy({
// Currently no specific options available
})
The PushGatewayStrategy supports comprehensive configuration for push gateway integration:
`typescript`
new PushGatewayStrategy({
url: 'http://localhost:9091', // Required: Push Gateway URL
requestOptions: { // Optional: HTTP request options
timeout: 5000,
headers: {
'Authorization': 'Bearer token',
},
},
auto: { // Optional: Auto-push configuration
pushInterval: 10000, // Push interval in milliseconds
jobName: 'my-application', // Job name for metrics
},
})
The RemoteWriteStrategy is currently in development. Configuration options will be documented when available.
- Use Case: Traditional Prometheus deployments where Prometheus scrapes metrics
- Advantages: Simple setup, Prometheus controls scraping frequency, no additional infrastructure needed
- Considerations: Requires your application to be accessible by Prometheus
- Use Case: Batch jobs, applications behind firewalls, or when scraping is not feasible
- Advantages: Works with short-lived processes, can push on-demand, supports custom groupings
- Considerations: Requires Push Gateway deployment, manual lifecycle management of metrics
- Use Case: Direct integration with Prometheus remote write endpoints
- Advantages: Direct integration, suitable for high-volume metrics
- Considerations: Currently in development
When using the ScrapeStrategy, configure Prometheus to scrape your application:
`yaml`prometheus.yml
scrape_configs:
- job_name: 'quickstat-app'
static_configs:
- targets: ['localhost:9090']
scrape_interval: 15s
When using PushGatewayStrategy, configure Prometheus to scrape the Push Gateway:
`yaml`prometheus.yml
scrape_configs:
- job_name: 'pushgateway'
static_configs:
- targets: ['localhost:9091']
honor_labels: true
The Prometheus DataSource automatically converts QuickStat metrics to Prometheus format:
- Counters: Exported with _total suffix_bucket
- Gauges: Exported with current value
- Histograms: Exported with , _count, and _sum metrics
Example output:
`HELP http_requests_total Total number of HTTP requests
TYPE http_requests_total counter
http_requests_total{method="GET",status="200"} 1234
Integration with QuickStat Plugins
The Prometheus DataSource works seamlessly with all QuickStat plugins:
typescript
import { ExpressPlugin } from '@quickstat/expressjs'
import { NodeJSPlugin } from '@quickstat/nodejs'
import { PM2Plugin } from '@quickstat/pm2'const quickStatClient = new QuickStatClient>({
metrics: [],
plugins: [
new ExpressPlugin({ app }),
new NodeJSPlugin(),
new PM2Plugin(),
],
dataSource: new PrometheusDataSource({
strategy: new ScrapeStrategy(),
}),
})
``For issues or feature requests, feel free to open an issue on the GitHub repository.