Key Takeaways (BLUF)
Bottom Line Up Front (BLUF): You cannot monitor a **GraphQL endpoint** the same way you monitor a REST API. By design, GraphQL servers will return an HTTP 200 OK status code even if the underlying database completely crashed and the query failed. To monitor GraphQL effectively, your synthetic probe must send a strictly formatted HTTP POST request containing a raw GraphQL query, and then explicitly assert that the `errors` array in the JSON response is null or undefined.
Why GraphQL Breaks Legacy Monitors
In a traditional REST architecture, routing is handled at the HTTP layer. If you request `/api/users/123` and the user does not exist, the server returns a `404 Not Found`. If the database is offline, it returns a `500 Internal Server Error`. Legacy monitoring tools rely entirely on these HTTP status codes.
GraphQL routes everything through a single endpoint, usually `/graphql`, via an HTTP POST request. The GraphQL engine parses the request, executes resolvers, and packages the result into a JSON response. Even if every single resolver throws a fatal exception, the HTTP layer still successfully processed the request, so it returns a 200 OK.
- The 200 OK Trap: A Pingdom or UptimeRobot basic tier will report 100% uptime for a GraphQL server that is completely broken.
- The Partial Failure: GraphQL can return partial data. If a user query succeeds but the nested posts query fails, the response will contain both `data` and `errors`.
- The Payload Requirement: You cannot just GET a GraphQL endpoint. You must send a highly specific JSON payload containing the `query` string and `variables` object.
Competitor Information Gap: The Correct cURL Command
Many DevOps engineers struggle to configure their synthetic monitors because they format the GraphQL payload incorrectly. A GraphQL request is just a standard JSON POST request with a specific schema.
Here is the exact cURL syntax your synthetic monitor uses behind the scenes to execute a GraphQL health query:
# The correct way to POST a GraphQL query
# Notice how the entire GraphQL query is escaped into a single JSON string
curl -X POST https://api.yourdomain.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"query": "query HealthCheck { systemHealth { database cache version } }",
"variables": {}
}'
# A FAILED GraphQL response still returns HTTP 200!
# We must use JSONPath to assert that $.errors IS_EMPTY
# {
# "data": { "systemHealth": null },
# "errors": [
# {
# "message": "Redis cache connection refused",
# "locations": [{ "line": 1, "column": 23 }]
# }
# ]
# }Asserting the GraphQL Response
Once your synthetic monitor is successfully executing the POST request, you must configure two specific JSON assertions.
First, assert that `$.errors` does not exist or is empty. Second, assert that `$.data.systemHealth.database` equals `"connected"`.
By crafting a specific `HealthCheck` GraphQL query that touches your most critical resolvers, you can verify your entire microservice architecture with a single 15-second synthetic probe.
Frequently Asked Questions
Should I monitor GraphQL Mutations?
Usually, no. Monitoring queries (reads) is safe. Monitoring mutations (writes) in production will fill your database with junk data every 15 seconds. If you must monitor a mutation, ensure it is a dedicated `syntheticPing` mutation that does not write to the primary tables.
How do I pass GraphQL variables in a synthetic monitor?
When configuring the POST body in your monitor, provide the standard JSON payload: `{"query": "...", "variables": {"userId": "123"}}`. Ensure the entire payload is valid JSON.
Does Introspection need to be enabled for monitoring?
No. Synthetic monitors do not need to download your GraphQL schema. They simply send a hardcoded query string. You should leave introspection disabled in production for security reasons.
Conclusion
If you are running a GraphQL API, basic HTTP monitoring is not just inadequate—it is actively lying to you. You must deploy synthetic monitors that can POST raw **GraphQL queries** and parse the resulting JSON payload for the dreaded `errors` array. WakeMetrics was built specifically for modern APIs, with native support for GraphQL payloads and deep JSON assertions. Start monitoring your GraphQL endpoints today.