Implementation:SeleniumHQ Selenium Grid Status Endpoint

Knowledge Sources	Selenium
Domains	Distributed_Testing, Observability, Selenium_Grid
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for monitoring Grid health through HTTP endpoints provided by the Selenium Grid Router and supporting handler classes.

Description

GridStatusHandler implements HttpHandler and powers the /status endpoint. It queries Distributor.getStatus() via a cached thread pool executor with a 2-second timeout. The response includes ready (true if any node has Availability.UP and hasCapacity()), a message string, and a nodes array with fields: id, uri, maxSessions, sessionTimeout, osInfo, heartbeatPeriod, availability, version, and slots. On timeout or error, it returns {"ready": false, "message": "Unable to read distributor status."}.

GraphqlHandler implements HttpHandler and AutoCloseable, serving the /graphql endpoint. It parses the GraphQL schema from selenium-grid-schema.graphqls (classpath resource), uses RuntimeWiring with GridData and SessionData data fetchers, and caches parsed query documents using a Caffeine cache (weighted at 5% of heap memory, 30-minute TTL, 1MB max query size bypass).

GridUiRoute implements Routable and serves the React-based Grid UI from classpath resources at /ui. It also handles /grid/console redirect and root path redirect to the UI. Both Standalone and Hub support disabling the UI via RouterOptions.disableUi().

Usage

Query /status for automated health checks. Access /ui in a browser for visual monitoring. Use /graphql for programmatic monitoring dashboards. Use /readyz for Kubernetes liveness probes.

Code Reference

Source Location

• Repository: Selenium
• File: java/src/org/openqa/selenium/grid/router/GridStatusHandler.java (L50-167)
• File: java/src/org/openqa/selenium/grid/graphql/GraphqlHandler.java (L66-274)
• File: java/src/org/openqa/selenium/grid/web/GridUiRoute.java (L37-101)
• File: java/src/org/openqa/selenium/grid/router/Router.java (L62-68)

Signature

class GridStatusHandler implements HttpHandler {
    GridStatusHandler(Tracer tracer, Distributor distributor);
    public HttpResponse execute(HttpRequest req);
    // Queries Distributor.getStatus() with 2-second timeout
    // Returns JSON: { "value": { "ready": boolean, "message": string, "nodes": [...] } }
}

public class GraphqlHandler implements HttpHandler, AutoCloseable {
    public GraphqlHandler(Tracer tracer, Distributor distributor,
                          NewSessionQueue newSessionQueue, URI publicUri, String version);
    public HttpResponse execute(HttpRequest req);
    public void close();
    // Serves GraphQL queries against selenium-grid-schema.graphqls
}

public class GridUiRoute implements Routable {
    public GridUiRoute(String prefix);
    public boolean matches(HttpRequest req);
    public HttpResponse execute(HttpRequest req);
    // Serves React UI from classpath resources at /ui
}

Import

N/A - Accessed via HTTP endpoints, not Java imports

I/O Contract

Inputs

Name	Type	Required	Description
HTTP GET /status	HTTP Request	-	Simple health check; no body required
HTTP POST /graphql	HTTP Request (JSON)	-	JSON body with "query" (String) and optional "variables" (Map)
HTTP GET /ui	HTTP Request	-	Serves Grid web UI static assets
HTTP GET /readyz	HTTP Request	-	Kubernetes liveness probe; bypasses authentication

Outputs

Name	Type	Description
/status	JSON	{ "value": { "ready": boolean, "message": string, "nodes": [ { "id", "uri", "maxSessions", "sessionTimeout", "osInfo", "heartbeatPeriod", "availability", "version", "slots" } ] } }
/graphql	JSON	GraphQL response with grid, nodes, sessions data per schema
/ui	HTML	React web application for visual monitoring
/readyz	Text	"Standalone is true/false" or "Router is true/false"

Usage Examples

Health Check

# Simple readiness check
curl http://localhost:4444/status

# Expected response (when Grid is ready with nodes)
# { "value": { "ready": true, "message": "Selenium Grid ready.", "nodes": [...] } }

# Kubernetes liveness probe (bypasses authentication)
curl http://localhost:4444/readyz

GraphQL Query

# Query grid overview
curl -X POST http://localhost:4444/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ grid { uri totalSlots usedSlots sessionCount maxSession nodeCount } }"}'

# Query node details
curl -X POST http://localhost:4444/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ nodesInfo { nodes { uri status sessions { id capabilities } } } }"}'

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_Grid_Health_Monitoring

Requires Environment

• Environment:SeleniumHQ_Selenium_Grid_Deployment_Environment