Health Check
Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.
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
Client initialization and authentication:
Available only on the server and Console sides: Requires Server SDK
Client(setEndpoint,setProject,setKey; the API Key must have thehealth.readscope) or Console SDK (management plane Session / short-lived JWT).Client / Web SDK unavailable: To prevent exposing the underlying infrastructure topology and internal queue watermarks, the browser-side Web SDK does not provide the
Healthservice.
Usage workflow
Initialize the client and the
Healthservice: LoadAPPBASE_ENDPOINT,APPBASE_PROJECT_ID, and aAPPBASE_API_KEYwith thehealth.readscope in the inspection process or release pipeline.Run gateway and core component liveness checks: Call
health.get()to check the HTTP service overview, and callgetDB(),getCache(),getPubSub(),getStorage(),getStorageLocal()to verify connectivity of core storage and the message bus as well aspinglatency (milliseconds).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 callgetCertificate({ domain })to check the remaining validity of the TLS certificate for the site or custom domain.Monitor asynchronous queue backlog and failed tasks: Call
getQueue*({ threshold })(e.g.getQueueWebhooks,getQueueBuilds,getQueueDatabases) to monitor pending queue lengths, and callgetFailedJobs({ 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 Method | Go Method | REST Endpoint | Parameters | Return Model | Description |
|---|---|---|---|---|---|---|
get() | get() | Get() | GET /v1/health | None | HealthStatus | Check the HTTP service overview status (name, ping, status: pass / fail). |
getDB() | get_db() | GetDB() | GET /v1/health/db | None | HealthStatusList | Check connectivity and latency of the underlying database instance (total + statuses[]). |
getCache() | get_cache() | GetCache() | GET /v1/health/cache | None | HealthStatusList | Check connectivity and response latency of the cache layer (Redis). |
getPubSub() | get_pub_sub() | GetPubSub() | GET /v1/health/pubsub | None | HealthStatusList | Check the status of realtime subscriptions and the internal event Pub/Sub channel. |
getStorage() | get_storage() | GetStorage() | GET /v1/health/storage | None | HealthStatus | Check read/write status of the currently configured primary storage device. |
getStorageLocal() | get_storage_local() | GetStorageLocal() | GET /v1/health/storage/local | None | HealthStatus | Check writability and status of the local file system storage volume. |
getAntivirus() | get_antivirus() | GetAntivirus() | GET /v1/health/anti-virus | None | HealthAntivirus | Check the antivirus engine version (version) and online status (status). |
getCertificate({ domain }) (domain optional) | get_certificate(domain=...) | GetCertificate(...) | GET /v1/health/certificate | domain?: string | HealthCertificate | Check the TLS certificate issuer, subject, and expiration timestamp of the specified domain (or the primary endpoint domain). |
getTime() | get_time() | GetTime() | GET /v1/health/time | None | HealthTime | Returns 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 Method | REST Endpoint | Optional Parameters | Return Model |
|---|---|---|---|---|
getQueueBuilds({ threshold }) (threshold optional) | get_queue_builds(threshold=...) | GET /v1/health/queue/builds | threshold?: number (backlog alert threshold) | HealthQueue ({ size: number }) |
getQueueCertificates({ threshold }) (threshold optional) | get_queue_certificates(threshold=...) | GET /v1/health/queue/certificates | threshold?: number | HealthQueue |
getQueueDatabases({ name, threshold }) (both name and threshold optional) | get_queue_databases(...) | GET /v1/health/queue/databases | name?: string, threshold?: number | HealthQueue |
getQueueDeletes({ threshold }) (threshold optional) | get_queue_deletes(threshold=...) | GET /v1/health/queue/deletes | threshold?: number | HealthQueue |
getQueueFunctions({ threshold }) (threshold optional) | get_queue_functions(threshold=...) | GET /v1/health/queue/functions | threshold?: number | HealthQueue |
getQueueLogs({ threshold }) (threshold optional) | get_queue_logs(threshold=...) | GET /v1/health/queue/logs | threshold?: number | HealthQueue |
getQueueMails({ threshold }) (threshold optional) | get_queue_mails(threshold=...) | GET /v1/health/queue/mails | threshold?: number | HealthQueue |
getQueueMessaging({ threshold }) (threshold optional) | get_queue_messaging(threshold=...) | GET /v1/health/queue/messaging | threshold?: number | HealthQueue |
getQueueMigrations({ threshold }) (threshold optional) | get_queue_migrations(threshold=...) | GET /v1/health/queue/migrations | threshold?: number | HealthQueue |
getQueueStatsResources({ threshold }) (threshold optional) | get_queue_stats_resources(...) | GET /v1/health/queue/stats-resources | threshold?: number | HealthQueue |
getQueueUsage({ threshold }) (threshold optional) | get_queue_usage(threshold=...) | GET /v1/health/queue/usage | threshold?: number | HealthQueue |
getQueueUsageDump({ threshold }) (threshold optional) | get_queue_usage_dump(threshold=...) | GET /v1/health/queue/usage-dump | threshold?: number | HealthQueue |
getQueueWebhooks({ threshold }) (threshold optional) | get_queue_webhooks(threshold=...) | GET /v1/health/queue/webhooks | threshold?: number | HealthQueue |
getFailedJobs({ name, threshold }) (threshold optional) | get_failed_jobs(name, threshold=...) | GET /v1/health/queue/failed/{name} | name (required queue enum), threshold?: number | HealthQueue |
Errors and boundaries
A single subsystem failure does not block overall availability: For example, when ClamAV is not enabled,
getAntivirus()may returndisabled/offlineor an exception, but this does not affect normal service of TablesDB, the knowledge base, or the model gateway; production inspection scripts should set alert severity levels according to the subsystems the business actually depends on.Queue threshold (
threshold) exceeded semantics: When callinggetQueue*({ threshold: 500 })orgetFailedJobs({ name: 'webhooks', threshold: 10 }), if the current queuesizeexceeds the passedthreshold, the server returns an error status code (making it easy to integrate HTTP status code-based external monitoring probes); if you only need to collect numeric metrics for writing to Prometheus, it is recommended not to passthreshold(or passnull) and read the returnedsizefield directly.Permission isolation: If the API Key lacks the
health.readscope, all/v1/health/*endpoints will return401 general_unauthorized_scope.
SDK Category Differences
| SDK category | Coverage | Authentication method | Typical scenarios |
|---|---|---|---|
| Server SDK (Node.js / Java / Python / Go) | Full subsystem health checks and queue monitoring | Project 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 getConsolePausing | Management plane Session / short-lived JWT | Health 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.
- Node.js (Server)
- Java
- Python
- Go
- REST (curl)
import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
.setProject(process.env.APPBASE_PROJECT_ID ?? '<APPBASE_PROJECT_ID>')
.setKey(process.env.APPBASE_API_KEY!);
{
const prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
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;
}import io.agentbase.Client;
import io.agentbase.services.Health;
import io.agentbase.exceptions.AppBaseException;
Client client = new Client()
.setEndpoint("<APPBASE_ENDPOINT_WITH_V1>")
.setProject("<APPBASE_PROJECT_ID>")
.setKey(System.getenv("APPBASE_API_KEY"));
client.setHttpClient(new okhttp3.OkHttpClient.Builder()
.followRedirects(false).followSslRedirects(false).build());
Health health = new Health(client);
try {
var overall = health.get(); // Overview
var db = health.getDB(); // Subsystems: getCache / getPubSub / getStorage / getStorageLocal / getAntivirus / getCertificate / getTime
var cache = health.getCache();
var whQueue = health.getQueueWebhooks(1000L); // Queue backlog: getQueue* series (builds / mails / messaging / webhooks / usage / migrations, etc.)
System.out.println("Status=" + overall.getStatus() + ", db=" + db.getTotal() + ", cache=" + cache.getTotal() + ", whQueue=" + whQueue.getSize());
} catch (AppBaseException e) {
System.err.println("Health check alert: HTTP " + e.getCode() + " type=" + e.getType());
}The Python Server SDK 2.12.0 default transport may forward the project API key on redirects. Use the REST tab in this section.
package main
import (
"errors"
"net/http"
"fmt"
"os"
"agentbase-go-sdk/agentbase"
)
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"),
agentbase.WithProject("<APPBASE_PROJECT_ID>"),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}
health := agentbase.NewHealth(cl)
status, _ := health.Get() // Overview
db, _ := health.GetDB() // Subsystems: GetCache / GetPubSub / GetStorage / GetStorageLocal / GetAntivirus / GetCertificate / GetTime / GetFailedJobs
whQueue, _ := health.GetQueueWebhooks(health.WithGetQueueWebhooksThreshold(1000))
fmt.Println(status.Status, db.Total, whQueue.Size)
}(
set +x
set -e -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. HTTP gateway, database, cache and storage health checks
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/health" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/health/db" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/health/cache" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
# 2. Check queue backlog and failed job water levels (builds / mails / webhooks / migrations / databases, etc.)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/health/queue/webhooks?threshold=1000" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/health/queue/failed/webhooks?threshold=50" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
)Example Guide
JavaScript / TypeScript full example: ../examples/javascript.md
Python full example: ../examples/python.md
Java full example: ../examples/java.md
Go full example: ../examples/go.md