Course outline

01 · Introduction to the Meridian Platform3/3

02 · Workspace Layout, Design Principles, and the Platform Library5/5

03 · The Data Layer4/4

04 · Identity Service: HTTP API Layer4/4

05 · Authentication and Authorization4/4

06 · The Gateway Service2/2

07 · Testing Strategy5/5

08 · Caching and Rate Limiting3/3

09 · Background Processing3/3

10 · File Storage2/2

11 · Event-Driven Communication3/3

12 · Resilience Patterns2/2

13 · Observability3/3

14 · Advanced PostgreSQL3/3

15 · API Versioning and the Platform Contract2/2

16 · Containerization and Deployment4/4

17 · CI/CD Pipeline2/2

18 · Security Hardening2/2

19 · Capstone: System Integration2/2

20 · Retrospective2/2

Stage 7 · Master

Observability

Prometheus Metrics and Health Checks

Every Meridian service already exposes /healthz. This chapter distinguishes that implemented liveness baseline from the planned metrics, readiness, and dependency health surface needed once real tenant-scoped traffic and PostgreSQL arrive.

15 min readMeridian: A Multi-Tenant Go PlatformMaster

Implemented Health Baseline

The repository already exposes one health endpoint in every service: GET /healthz returns { service, status }. This is enough for the current scaffolding phase because there are no downstream dependencies, no Postgres pool, no Redis, and no reverse-proxy routes. A passing /healthz today therefore means exactly one thing: the process started and can answer a trivial HTTP request.

Goapps/gateway/internal/router/router.go-—-current-health-route.go

5 linesLn 1, Col 1Go

The same pattern exists in the three internal services. No readiness probe or Prometheus endpoint exists yet.

Liveness versus Readiness

Endpoint	What it should answer	Current status
/healthz or /livez	Is the process alive enough to keep running?	Implemented as /healthz in every service
/readyz	Can this instance safely receive production traffic?	Planned for the phase that adds downstream dependencies
/metrics	What is the numeric behavior of this process over time?	Planned; not implemented

Once the gateway proxies to internal services and each service owns real storage, readiness must become stricter than liveness. A billing-service process may be alive while its database pool is exhausted; a gateway process may be alive while all downstream identity requests are failing. Those are readiness failures, not liveness failures. Conflating the two would cause Kubernetes to keep routing traffic to an instance that is running but not useful.

Metrics and readiness are future-phase design

No Prometheus client library, ServiceMonitor, or readiness code is present in meridian today. The remaining sections define the intended surface so the eventual implementation stays aligned with the current service boundaries and Platform Contract.

Planned Metrics Surface

Files in this step— Planned additions once real handlers and dependencies exist.

apps/gateway/internal/metrics/metrics.gocreate

Responsibility: Register HTTP request duration and dependency outcome metrics for the only public entrypoint.

Why now: The gateway is the correct place to observe public latency and status distribution.

Connects to: Pairs with versioned routes in apps/gateway/internal/router/router.go.

apps/identity-service/internal/health/readiness.gocreate

Responsibility: Report readiness based on future database and auth-dependency state rather than on process life alone.

Why now: identity-service will eventually own tenant lookup and membership data, so readiness must reflect that critical path.

Connects to: Complements the existing /healthz handler in cmd/identity-service/main.go.

apps/billing-service/internal/metrics/metrics.gocreate

Responsibility: Expose counters and histograms for invoice and payment operations without embedding tenant identifiers in labels.

Why now: Financial traffic needs error-rate and latency visibility, but label cardinality must stay bounded.

Connects to: Will back the future /metrics endpoint for billing-service.

Terminal — planned metrics and readiness scaffolding

$mkdir -p apps/gateway/internal/metrics

// Create the gateway metrics package where public request instrumentation will be registered.

$touch apps/gateway/internal/metrics/metrics.go

// Add the planned metrics file for gateway latency and dependency outcome metrics.

$mkdir -p apps/identity-service/internal/health

// Create the identity-service health package for readiness-specific checks.

$touch apps/identity-service/internal/health/readiness.go

// Add the planned readiness handler that can later gate traffic on dependency state.

$mkdir -p apps/billing-service/internal/metrics

// Create the billing-service metrics package for bounded financial counters and histograms.

$touch apps/billing-service/internal/metrics/metrics.go

// Add the planned billing metrics file without introducing tenant-level label cardinality.

Goplanned-readiness-sketch.go

9 linesLn 1, Col 1Go

The exact checks will depend on future dependencies, but readiness must answer whether the instance can serve useful work right now.

Label Discipline

Keep labels low-cardinality: service, route template, status class, dependency name, method.
Do not label metrics with tenant slug, tenant UUID, resident ID, unit ID, invoice ID, or user email.
Record tenant-specific investigations in logs or traces, not in unbounded Prometheus label sets.

The Decision

Meridian keeps the current /healthz handlers as simple liveness checks during scaffolding, then adds /readyz and /metrics only when real dependencies justify them. The observability model is therefore staged: basic process health now, dependency-aware readiness and bounded Prometheus instrumentation later.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.