shopify-observability

name	shopify-observability
description	Set up observability for Shopify app integrations with query cost tracking, rate limit monitoring, webhook delivery metrics, and structured logging. Use when instrumenting a Shopify app for production monitoring, setting up Prometheus metrics for API health, or configuring alerts for rate limit issues. Trigger with phrases like "shopify monitoring", "shopify metrics", "shopify observability", "monitor shopify API", "shopify alerts", "shopify dashboard".
allowed-tools	Read, Write, Edit
version	2.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","ecommerce","shopify"]
compatibility	Designed for Claude Code

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