Shopify Observability

Overview

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.

Prerequisites

• Prometheus or compatible metrics backend
• pino or similar structured logger
• Shopify API client with response interception

Instructions

Step 1: Shopify-Specific Metrics

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.

Step 2: Instrumented GraphQL Client

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.

Step 3: REST API Header Tracking

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}`);
    }
  }
}

Step 4: Webhook Observability

Track HMAC validation results, processing success/failure, and duration for all incoming webhooks.

See Webhook Observability for the complete Express middleware.

Step 5: Structured Logging

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.

Step 6: Alert Rules

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.

Output

• GraphQL query cost tracking with per-operation metrics
• Rate limit monitoring for both REST and GraphQL
• Webhook delivery and processing metrics
• Structured logs with automatic PII redaction
• Alert rules for critical Shopify-specific conditions

Error Handling

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

Examples

Metrics Endpoint

app.get("/metrics", async (req, res) => {
  res.set("Content-Type", registry.contentType);
  res.send(await registry.metrics());
});

Resources

• Shopify Rate Limit Headers
• Prometheus Best Practices
• OpenTelemetry Node.js