How to Integrate Easegress with Prometheus and Grafana for Full Observability

Yes, Easegress integrates natively with Prometheus and Grafana by exposing a /metrics endpoint that outputs Prometheus-formatted metrics, which can be scraped by Prometheus and visualized in Grafana without requiring custom plugins.

The easegress-io/easegress repository ships with built-in observability support that automatically registers HTTP handlers and exposes runtime statistics. This native integration eliminates the need for sidecar exporters or additional instrumentation layers when connecting to modern observability stacks.

Native Prometheus Support in Easegress

Easegress embeds Prometheus client libraries directly into its core architecture, creating a seamless observability integration that starts automatically when the server boots.

The /metrics Endpoint

In pkg/api/prometheus.go, the API server registers a dedicated HTTP handler that serves the Prometheus exposition format:

// Path: "/metrics"
// Method: "GET"
// Handler: promhttp.Handler()

This endpoint becomes available on the admin port immediately after startup, requiring no additional configuration to activate. The handler uses the standard promhttp.Handler() from the Prometheus Go client to serialize registered metrics.

Built-in Runtime Metrics

The HTTP server implementation in pkg/object/httpserver/runtime.go defines concrete metric vectors that track traffic health and performance. These include gauges for latency percentiles (P95, P99), request/response sizes, and health status, all prefixed with easegress_.

Each incoming request updates these vectors automatically, generating time-series data like easegress_httpserver_p95 that represents the 95th percentile latency in milliseconds.

Configuring Prometheus Scraping

To collect Easegress metrics, add a scrape job to your prometheus.yml configuration file:

scrape_configs:
  - job_name: 'easegress'
    static_configs:
      - targets: ['<EASEGRESS_HOST>:<ADMIN_PORT>']   # e.g. 127.0.0.1:2381

    metrics_path: /metrics
    scheme: http

Replace <EASEGRESS_HOST> and <ADMIN_PORT> with the actual host and administrative port where your Easegress instance runs. Prometheus will begin scraping the endpoint immediately, storing metrics with the easegress_* namespace.

Visualizing Metrics in Grafana

Grafana integration requires no special datasource plugin—simply add your Prometheus server as a data source and query the exposed metrics.

Building Latency Dashboards

To display P95 latency across your Easegress cluster, configure a graph panel with the following query:

{
  "type": "graph",
  "title": "Easegress P95 Latency (ms)",
  "targets": [
    {
      "expr": "easegress_httpserver_p95",
      "legendFormat": "{{instance}}"
    }
  ],
  "yAxis": {
    "format": "short",
    "label": "ms"
  }
}

This queries the easegress_httpserver_p95 gauge defined in the runtime package, visualizing latency percentiles per instance.

Creating Custom Metrics with Prometheus Helper

For custom filters requiring specialized telemetry, Easegress provides a utility package in pkg/util/prometheushelper/helper.go that standardizes metric creation and registration.

The helper exposes functions like NewCounter(), NewGauge(), and NewHistogram() that validate metric names and register them with the global Prometheus registry.

Example: Custom Request Counter

Implement custom instrumentation in your filter using the helper:

import "github.com/easegress-io/easegress/pkg/util/prometheushelper"

var myCounter = prometheushelper.NewCounter(
    "my_custom_requests_total",
    "Total number of custom requests processed",
    []string{"status"},
)

func (f *MyFilter) handleRequest(ctx context.Context) {
    // … processing …
    myCounter.WithLabelValues("success").Inc()
}

Once deployed, my_custom_requests_total appears automatically on the /metrics endpoint alongside built-in statistics, making it immediately available to Prometheus and Grafana.

Summary

• Native endpoint: Easegress exposes Prometheus metrics at /metrics via pkg/api/prometheus.go using promhttp.Handler().
• Automatic instrumentation: The HTTP server runtime in pkg/object/httpserver/runtime.go tracks latency percentiles, traffic volume, and health status without manual configuration.
• Zero-plugin Grafana: Connect Grafana to your Prometheus data source to visualize easegress_* metrics using standard PromQL queries.
• Extensible metrics: Use pkg/util/prometheushelper/helper.go to add custom counters and gauges that inherit the same scraping infrastructure.

Frequently Asked Questions

Does Easegress require a plugin to support Prometheus?

No. Prometheus support is compiled into the core binary. The pkg/api/prometheus.go file registers the /metrics handler during server initialization, exposing all registered metrics automatically without external dependencies or plugin installation.

What metrics does Easegress expose by default?

The default instrumentation includes latency percentiles (P95, P99), request and response byte sizes, health status indicators, and request counts. These metrics use the easegress_httpserver_* prefix and are defined in pkg/object/httpserver/runtime.go.

Can I create custom metrics for my Easegress filters?

Yes. Import github.com/easegress-io/easegress/pkg/util/prometheushelper and use helper functions like NewCounter() or NewGauge() to define custom metric vectors. These appear on the /metrics endpoint immediately after registration and follow the same scraping lifecycle as built-in metrics.

How do I secure the /metrics endpoint?

The metrics endpoint runs on the admin server port, which should be restricted to internal networks or protected via reverse proxy authentication. Easegress does not expose the endpoint on public-facing HTTP ports by default, reducing the attack surface for unauthorized metric scraping.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}