telemetry

func GetMetrics ¶

func GetMetrics() map[string]any

GetMetrics returns a snapshot of metrics for dashboard consumption.

func LatencyMiddleware ¶

func LatencyMiddleware(latencyMs int) func(echo.HandlerFunc) echo.HandlerFunc

LatencyMiddleware returns a middleware that injects a random sleep of [0, latencyMs) milliseconds before each request, simulating real-world network latency. This helps surface timeout bugs, race conditions, and missing retry logic. If latencyMs is zero or negative, the middleware is a no-op. The sleep is context-aware: it is interrupted immediately when the request context is cancelled (e.g. client disconnect, server shutdown).

func MemoryStatsMiddleware ¶

func MemoryStatsMiddleware(next echo.HandlerFunc) echo.HandlerFunc

MemoryStatsMiddleware injects the X-Gopherstack-Memory-Stats header into all responses. The header contains Alloc, TotalAlloc, Sys, and NumGC stats from runtime.MemStats. This allows long-term monitoring of the Gopherstack container's memory health.

func RecordDeleteQueueDepth ¶

func RecordDeleteQueueDepth(service string, depth int)

RecordDeleteQueueDepth updates the live delete-queue depth gauge for a service. service should be "s3" or "dynamodb".

func RecordLockDuration ¶

func RecordLockDuration(lockType string, durationSeconds float64)

RecordLockDuration records lock hold time.

func RecordOperation ¶

func RecordOperation(operation, _ string, durationSeconds float64, status string)

RecordOperation records an operation latency and status. operation: name of the operation (e.g., "GetItem", "PutObject") resource: name of the resource (ignored for Prometheus metrics to reduce cardinality) durationSeconds: how long the operation took status: "success" or "error"

func RecordStreamEvents ¶

func RecordStreamEvents(service string, count int)

RecordStreamEvents records the number of stream records delivered via GetRecords.

func RecordTTLEvictions ¶

func RecordTTLEvictions(service string, count int)

RecordTTLEvictions records that count items were evicted via background TTL sweep.

func RecordWorkerItems ¶

func RecordWorkerItems(service, worker string, count int)

RecordWorkerItems records the number of items processed by a background worker.

func RecordWorkerQueueDepth ¶

func RecordWorkerQueueDepth(service, worker string, depth int)

RecordWorkerQueueDepth updates the current queue depth for a background worker.

func RecordWorkerTask ¶

func RecordWorkerTask(service, worker, status string)

RecordWorkerTask records that a background worker has processed a task. service: e.g., "dynamodb", "s3" worker: e.g., "TableCleaner", "TTLSweeper" status: "success" or "error"

func SetServiceCount ¶

func SetServiceCount(n int)

SetServiceCount records the number of registered services. Call this once at startup after all services have been initialised. The value is exposed via the "gopherstack_registered_services" Prometheus gauge and included in the RuntimeMetrics.NumServices field returned by CollectMetrics.

func WrapEchoHandler ¶

func WrapEchoHandler(
	serviceName string,
	handler echo.HandlerFunc,
	observer ObservabilityObserver,
) echo.HandlerFunc

WrapEchoHandler wraps an Echo handler with automated metrics and logging. The wrapper extracts operation and resource names via the observer, times the handler execution, records metrics, and logs the result.

Per request, it enriches the request context logger with a "service" attribute so that all downstream log lines are automatically tagged. The logger is pulled from the request context via pkglogger.Load; callers are expected to inject a logger into the context before requests arrive (e.g. via pkglogger.EchoMiddleware).

This eliminates boilerplate from service handlers—they focus on business logic while observability is handled automatically.