Docs
Contents

Health Check

Overview and use cases

Health The service targets server-side monitoring probes, SRE inspection scripts, and platform operations automation, providing real-time health liveness checks for instances and core subsystems as well as queue watermark queries: including HTTP gateway liveness, OceanBase database connection pool, Redis cache and Pub/Sub channels, object storage and local mounted volumes, the ClamAV antivirus engine, TLS certificate validity, NTP clock offset, and pending backlog (size) and failed job counts of background asynchronous Worker queues (build, database, mail, messaging, webhook, migration, usage aggregation, etc.).

Prerequisites

Usage workflow

  1. Initialize the client and the Health service: Load APPBASE_ENDPOINT, APPBASE_PROJECT_ID, and a APPBASE_API_KEY with the health.read scope in the inspection process or release pipeline.

  2. Run gateway and core component liveness checks: Call health.get() to check the HTTP service overview, and call getDB(), getCache(), getPubSub(), getStorage(), getStorageLocal() to verify connectivity of core storage and the message bus as well as ping latency (milliseconds).

  3. Check security and environment status: As needed, call getTime() to verify server clock offset against internet NTP time (preventing JWT/OAuth signature failures due to clock drift), and call getCertificate({ domain }) to check the remaining validity of the TLS certificate for the site or custom domain.

  4. Monitor asynchronous queue backlog and failed tasks: Call getQueue*({ threshold }) (e.g. getQueueWebhooks, getQueueBuilds, getQueueDatabases) to monitor pending queue lengths, and call getFailedJobs({ name, threshold }) to monitor the dead-letter/failed job watermark of each queue.

Key parameters and returns

Subsystem and Environment Check Method List

SDK Method (Node / Java)Python MethodGo MethodREST EndpointParametersReturn ModelDescription
get()get()Get()GET /v1/healthNoneHealthStatusCheck the HTTP service overview status (name, ping, status: pass / fail).
getDB()get_db()GetDB()GET /v1/health/dbNoneHealthStatusListCheck connectivity and latency of the underlying database instance (total + statuses[]).
getCache()get_cache()GetCache()GET /v1/health/cacheNoneHealthStatusListCheck connectivity and response latency of the cache layer (Redis).
getPubSub()get_pub_sub()GetPubSub()GET /v1/health/pubsubNoneHealthStatusListCheck the status of realtime subscriptions and the internal event Pub/Sub channel.
getStorage()get_storage()GetStorage()GET /v1/health/storageNoneHealthStatusCheck read/write status of the currently configured primary storage device.
getStorageLocal()get_storage_local()GetStorageLocal()GET /v1/health/storage/localNoneHealthStatusCheck writability and status of the local file system storage volume.
getAntivirus()get_antivirus()GetAntivirus()GET /v1/health/anti-virusNoneHealthAntivirusCheck the antivirus engine version (version) and online status (status).
getCertificate({ domain }) (domain optional)get_certificate(domain=...)GetCertificate(...)GET /v1/health/certificatedomain?: stringHealthCertificateCheck the TLS certificate issuer, subject, and expiration timestamp of the specified domain (or the primary endpoint domain).
getTime()get_time()GetTime()GET /v1/health/timeNoneHealthTimeReturns the remote NTP time (remoteTime), local time (localTime), and the difference in seconds (diff).

Asynchronous Queue Backlog and Failed Task Check Method List

SDK Method (Node / Java)Python MethodREST EndpointOptional ParametersReturn Model
getQueueBuilds({ threshold }) (threshold optional)get_queue_builds(threshold=...)GET /v1/health/queue/buildsthreshold?: number (backlog alert threshold)HealthQueue ({ size: number })
getQueueCertificates({ threshold }) (threshold optional)get_queue_certificates(threshold=...)GET /v1/health/queue/certificatesthreshold?: numberHealthQueue
getQueueDatabases({ name, threshold }) (both name and threshold optional)get_queue_databases(...)GET /v1/health/queue/databasesname?: string, threshold?: numberHealthQueue
getQueueDeletes({ threshold }) (threshold optional)get_queue_deletes(threshold=...)GET /v1/health/queue/deletesthreshold?: numberHealthQueue
getQueueFunctions({ threshold }) (threshold optional)get_queue_functions(threshold=...)GET /v1/health/queue/functionsthreshold?: numberHealthQueue
getQueueLogs({ threshold }) (threshold optional)get_queue_logs(threshold=...)GET /v1/health/queue/logsthreshold?: numberHealthQueue
getQueueMails({ threshold }) (threshold optional)get_queue_mails(threshold=...)GET /v1/health/queue/mailsthreshold?: numberHealthQueue
getQueueMessaging({ threshold }) (threshold optional)get_queue_messaging(threshold=...)GET /v1/health/queue/messagingthreshold?: numberHealthQueue
getQueueMigrations({ threshold }) (threshold optional)get_queue_migrations(threshold=...)GET /v1/health/queue/migrationsthreshold?: numberHealthQueue
getQueueStatsResources({ threshold }) (threshold optional)get_queue_stats_resources(...)GET /v1/health/queue/stats-resourcesthreshold?: numberHealthQueue
getQueueUsage({ threshold }) (threshold optional)get_queue_usage(threshold=...)GET /v1/health/queue/usagethreshold?: numberHealthQueue
getQueueUsageDump({ threshold }) (threshold optional)get_queue_usage_dump(threshold=...)GET /v1/health/queue/usage-dumpthreshold?: numberHealthQueue
getQueueWebhooks({ threshold }) (threshold optional)get_queue_webhooks(threshold=...)GET /v1/health/queue/webhooksthreshold?: numberHealthQueue
getFailedJobs({ name, threshold }) (threshold optional)get_failed_jobs(name, threshold=...)GET /v1/health/queue/failed/{name}name (required queue enum), threshold?: numberHealthQueue

Errors and boundaries

SDK Category Differences

SDK categoryCoverageAuthentication methodTypical scenarios
Server SDK (Node.js / Java / Python / Go)Full subsystem health checks and queue monitoringProject API Key (health.read)Backend readiness probes, Worker backlog inspection, pre-release environment self-checks
Console SDK (Node.js / Java / Python / Go)Full + management plane extensions such as getConsolePausingManagement plane Session / short-lived JWTHealth dashboard of the platform operations Console
Client / Web SDK (Web)No Health service—Health checks cannot be called from the browser

Examples by language

Server / Console side perspective (no Web tab); failure of a single subsystem does not mean overall unavailability.

import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
    .setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY!);

const health = new Health(client);

try {
    // 1. Overview and core storage/cache health checks
    const httpStatus = await health.get();
    const dbStatus = await health.getDB();
    const cacheStatus = await health.getCache();
    const storageStatus = await health.getStorage();
    console.log('HTTP:', httpStatus.status, 'DB count:', dbStatus.total, 'Cache count:', cacheStatus.total, 'Storage:', storageStatus.status);

    // 2. Clock skew and queue backlog monitoring
    const clock = await health.getTime();
    const webhookQueue = await health.getQueueWebhooks({ threshold: 1000 });
    const buildQueue = await health.getQueueBuilds({ threshold: 200 });
    console.log(`NTP diff=${clock.diff}s, webhookQueue=${webhookQueue.size}, buildQueue=${buildQueue.size}`);
} catch (err) {
    if (err instanceof AgentbaseException) {
        console.error(`健康检查告警 [${err.code} ${err.type}]: ${err.message}`);
    }
    throw err;
}

Example Guide