# How to Integrate Easegress with Prometheus and Grafana for Full Observability

> Integrate Easegress with Prometheus and Grafana for full observability. Expose Prometheus-formatted metrics via a /metrics endpoint for seamless scraping and visualization.

- Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/easegress-io/easegress/blob/main/pkg/api/prometheus.go), the API server registers a dedicated HTTP handler that serves the Prometheus exposition format:

```go
// 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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/prometheus.yml) configuration file:

```yaml
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:

```json
{
  "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`](https://github.com/easegress-io/easegress/blob/main/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:

```go
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`](https://github.com/easegress-io/easegress/blob/main/pkg/api/prometheus.go) using `promhttp.Handler()`.
- **Automatic instrumentation**: The HTTP server runtime in [`pkg/object/httpserver/runtime.go`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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`](https://github.com/easegress-io/easegress/blob/main/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.