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

shopify-observability