Skip to content

health

Package health provides a client for the Memory Health and Metrics APIs.

The health client is a non-context client — it requires no org or project context. It is used for infrastructure health checks (Kubernetes liveness/readiness probes), runtime diagnostics, and job queue metrics.

import "github.com/emergent-company/emergent.memory/apps/server/pkg/sdk/health"
type Client struct { /* unexported */ }

Obtained via sdk.Client.Health. No SetContext call is needed or available.

No authentication required for the health/ready/healthz endpoints. Authentication is required for Debug, JobMetrics, and SchedulerStatus.


func (c *Client) Health(ctx context.Context) (*HealthResponse, error)

Returns the overall service health including individual subsystem check results. A 503 Service Unavailable response is decoded normally (not treated as an error) since it represents the “unhealthy” state.

Endpoint: GET /health


func (c *Client) APIHealth(ctx context.Context) (*HealthResponse, error)

Same as Health but accessed via the API path (useful when the server is behind an API gateway that strips the root path).

Endpoint: GET /api/health


func (c *Client) Ready(ctx context.Context) (*ReadyResponse, error)

Returns the readiness state. A 503 response is still decoded (represents “not ready”). Use for Kubernetes readiness probes and load-balancer health checks.

Endpoint: GET /ready


func (c *Client) IsReady(ctx context.Context) (bool, error)

Convenience wrapper around Ready that returns true only when status == "ready".


func (c *Client) Healthz(ctx context.Context) error

Simple liveness check. Returns nil on 200 OK, an error otherwise. Use for Kubernetes liveness probes.

Endpoint: GET /healthz


func (c *Client) Debug(ctx context.Context) (*DebugResponse, error)

Returns runtime debug info: Go version, goroutine count, memory stats, and database pool stats.

Note: This endpoint is only available in non-production environments.

Endpoint: GET /debug


func (c *Client) JobMetrics(ctx context.Context, projectID string) (*AllJobMetrics, error)

Returns per-queue job metrics. Pass projectID to scope metrics to a single project, or "" for global metrics.

Endpoint: GET /api/metrics/jobs


func (c *Client) SchedulerStatus(ctx context.Context) (*SchedulerMetrics, error)

Returns scheduled task metrics.

Endpoint: GET /api/metrics/scheduler


type HealthResponse struct {
Status string `json:"status"`
Timestamp string `json:"timestamp"`
Uptime string `json:"uptime"`
Version string `json:"version"`
Checks map[string]Check `json:"checks"`
}

Status is "healthy" or "unhealthy". Checks maps subsystem names to their individual Check results.

type Check struct {
Status string `json:"status"`
Message string `json:"message,omitempty"`
}

type ReadyResponse struct {
Status string `json:"status"` // "ready" or "not_ready"
Message string `json:"message,omitempty"`
}

type DebugResponse struct {
Environment string `json:"environment"`
Debug bool `json:"debug"`
GoVersion string `json:"go_version"`
Goroutines int `json:"goroutines"`
Memory DebugMemory `json:"memory"`
Database DebugDatabase `json:"database"`
}
type DebugMemory struct {
AllocMB uint64 `json:"alloc_mb"`
TotalAllocMB uint64 `json:"total_alloc_mb"`
SysMB uint64 `json:"sys_mb"`
NumGC uint32 `json:"num_gc"`
}
type DebugDatabase struct {
Host string `json:"host"`
Port int `json:"port"`
Database string `json:"database"`
PoolTotal int32 `json:"pool_total"`
PoolIdle int32 `json:"pool_idle"`
PoolInUse int32 `json:"pool_in_use"`
}

type JobQueueMetrics struct {
Queue string `json:"queue"`
Pending int64 `json:"pending"`
Processing int64 `json:"processing"`
Completed int64 `json:"completed"`
Failed int64 `json:"failed"`
Total int64 `json:"total"`
LastHour int64 `json:"last_hour"`
Last24Hours int64 `json:"last_24_hours"`
}
type AllJobMetrics struct {
Queues []JobQueueMetrics `json:"queues"`
Timestamp string `json:"timestamp"`
}

type SchedulerMetrics struct {
Message string `json:"message,omitempty"`
}

// Kubernetes readiness probe
ok, err := client.Health.IsReady(ctx)
if err != nil || !ok {
// service is not ready
}
// Check detailed health
h, err := client.Health.Health(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Status: %s (uptime: %s)\n", h.Status, h.Uptime)
for name, check := range h.Checks {
fmt.Printf(" %s: %s\n", name, check.Status)
}
// Check job queue backlog
metrics, err := client.Health.JobMetrics(ctx, "")
if err != nil {
log.Fatal(err)
}
for _, q := range metrics.Queues {
fmt.Printf("Queue %s: %d pending, %d failed\n", q.Queue, q.Pending, q.Failed)
}