Instrument your Shopify app to track GraphQL query cost, rate limit consumption, webhook delivery success, and API latency. Shopify-specific metrics that generic monitoring misses.
Define Prometheus counters, histograms, and gauges for query cost, rate limit headroom, REST bucket state, API duration, webhook processing, and error classification.
See Shopify Metrics Definitions for the complete metric registrations.
Wrap the Shopify GraphQL client to automatically record query cost from extensions.cost, update rate limit gauges, and classify errors (throttled, auth, API error).
See Instrumented GraphQL Client for the complete implementation.
Parse X-Shopify-Shop-Api-Call-Limit headers (e.g., "32/40") from REST responses to track leaky bucket fill level. Warn when bucket exceeds 80% capacity.
function trackRestHeaders(shop: string, headers: Record<string, string>): void {
const callLimit = headers["x-shopify-shop-api-call-limit"];
if (callLimit) {
const [used, max] = callLimit.split("/").map(Number);
restBucketGauge.set({ shop }, used);
if (used > max * 0.8) {
console.warn(`[shopify] REST bucket at ${used}/${max} for ${shop}`);
}
}
}
Track HMAC validation results, processing success/failure, and duration for all incoming webhooks.
See Webhook Observability for the complete Express middleware.
Pino-based logger with automatic PII redaction and Shopify-specific context fields (query cost, available points, operation name).
See Structured Logging for the complete implementation.
Prometheus alert rules for low rate limits, high query cost (P95 > 500), webhook failures (> 10%), and API latency (P95 > 3s).
See Alert Rules for the complete Prometheus configuration.
| Issue | Cause | Solution |
|---|---|---|
| Missing cost data | Query error before response | Check error handling wraps correctly |
| High cardinality | Per-shop labels | Aggregate by plan tier instead |
| Alert storms | Aggressive thresholds | Tune based on baseline traffic |
| Webhook metrics missing | Not instrumented | Add counter to webhook handler |
app.get("/metrics", async (req, res) => {
res.set("Content-Type", registry.contentType);
res.send(await registry.metrics());
});