Quickstart

Prom2json Plugin Quickstart

Overview

Prom2json is a Prometheus tool that scrapes metrics endpoints and converts them from text or protocol buffer format to JSON. The supercli prom2json plugin provides convenient commands for converting Prometheus metrics to structured JSON, making it ideal for parsing and processing in scripts.

Installation

The prom2json binary must be installed on your system:

# Via Go
go install github.com/prometheus/prom2json/cmd/prom2json@latest

# Or download from releases
# https://github.com/prometheus/prom2json/releases

Available Commands

Convert Metrics URL to JSON

sc prom2json convert http://localhost:9090/metrics

Scrapes a Prometheus metrics endpoint and converts to JSON format.

Convert Metrics File to JSON

sc prom2json convert-file /path/to/metrics.prom

Converts a Prometheus metrics file to JSON format.

Convert from Stdin

curl http://localhost:9090/metrics | sc prom2json convert-stdin

Converts Prometheus metrics piped from stdin to JSON format.

Convert with TLS Client Authentication

sc prom2json convert-tls --cert /path/to/cert.pem --key /path/to/key.pem https://metrics.example.com/metrics

Converts HTTPS metrics endpoint using TLS client authentication.

Convert without TLS Validation (Testing Only)

sc prom2json convert-insecure https://metrics.example.com/metrics

Converts HTTPS metrics endpoint without TLS validation (for testing only).

Convert with UTF-8 Escaping

sc prom2json convert-utf8 http://localhost:9090/metrics

Converts metrics with UTF-8 character escaping scheme.

Output Format

All commands return structured JSON output:

[
  {
    "name": "http_requests_total",
    "help": "Total number of HTTP requests",
    "type": "counter",
    "metrics": [
      {
        "labels": {
          "method": "GET",
          "status": "200"
        },
        "value": "1024"
      }
    ]
  }
]

Use Cases

• Metrics parsing: Convert Prometheus metrics to JSON for easier processing
• Monitoring scripts: Integrate metrics collection into monitoring systems
• Data analysis: Parse and analyze Prometheus metrics data
• Automation: Process metrics in CI/CD pipelines
• API integration: Convert metrics for consumption by other tools

Caveats & Pitfalls

• Network connectivity: Requires network access to metrics endpoints
• TLS security: Avoid using --accept-invalid-cert in production
• Large metrics sets: Large metrics endpoints may produce significant JSON output
• Metrics format: Input must be valid Prometheus metrics format
• Rate limiting: Some metrics endpoints may rate limit frequent requests

Examples

Scrape local Prometheus metrics

sc prom2json convert http://localhost:9090/metrics

Convert metrics file

sc prom2json convert-file /var/lib/prometheus/metrics.prom

Pipe from curl

curl http://localhost:9090/metrics | sc prom2json convert-stdin

Convert HTTPS metrics with authentication

sc prom2json convert-tls --cert /etc/ssl/certs/client.pem --key /etc/ssl/private/client.key https://secure-metrics.example.com/metrics

Process metrics with jq

sc prom2json convert http://localhost:9090/metrics | jq '.[] | select(.name == "http_requests_total")'

Filter specific metric

sc prom2json convert http://localhost:9090/metrics | jq '.[] | select(.name | contains("cpu"))'