golang-api-metrics

golang-api-metrics

A small, importable Go library that registers Prometheus metrics, health/readiness, build info, optional pprof, and a DB diagnostics framework under:

/aem/...

Designed to be embedded into Gin-based APIs while remaining lightweight and extensible across services in the organization.

This library intentionally avoids heavy external SDK dependencies. Additional systems (Redis, Kafka, S3, Elasticsearch, Snowflake, BigQuery, etc.) are supported via pluggable providers implemented inside each service.

Endpoints

All are mounted under /aem:

Endpoint Purpose

GET /aem/metrics Prometheus scrape endpoint GET /aem/health summarized health GET /aem/health/live liveness GET /aem/health/ready readiness (DB + custom checks) GET /aem/buildinfo version/build metadata POST /aem/db dependency diagnostics GET /aem/ index of available routes /aem/debug/pprof/** optional pprof (disabled by default)

Installation

go get github.com/api-essentials/golang-api-metrics@latest

Quick start (Gin)

import (
    "database/sql"
    diagnostic "github.com/api-essentials/golang-api-metrics/v2/diagnostic"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.New()

    var pg *sql.DB
    var ch *sql.DB

    cfg := diagnostic.Config{
        ServiceName: "service-name",
        Version:     "1.2.3",
        Commit:      "abcdef1",
        BuildTime:   "2026-02-20T00:00:00Z",

        Postgres:   pg,
        ClickHouse: ch,

        Queryable: false,
        EnablePprof:  false,
    }

    diagnostic.RegisterGin(r, cfg)

    r.Use(diagnostic.GinHTTPMetricsMiddleware(
        diagnostic.HTTPMetricsOptions{ServiceName: cfg.ServiceName},
    ))

    _ = r.Run(":8080")
}

DB Diagnostics

Connectivity check

POST /aem/db
(empty body)

Returns connectivity status for configured dependencies.

Query Execution (Disabled by Default)

Queries only run when:

Queryable == true

If a payload is supplied while Queryable == false the endpoint returns HTTP 404.

Mandatory aem: Prefix

All SQL queries must begin with:

aem:

Example:

{ "target": "postgres", "query": "aem:SELECT now()" }

The prefix is removed before validation and execution.

If a query does not start with aem: HTTP 404 is returned.

Read-Only Enforcement

When Queryable == true:

Only read-only statements are permitted.

Any mutating or multi-statement query returns HTTP 404.

404 Behaviour

The endpoint returns HTTP 404 when:

• Queryable == false and payload supplied
• Query missing aem: prefix
• Query appears mutating
• Query attempts multi-statement execution
• Target DB not configured
• Query execution errors
• Query returns zero rows
• Provider returns empty result

License

MIT