Method-Level Granularity

By default, a single circuit breaker protects all methods on an integration. This is the recommended setup for most projects — it is simpler, uses less memory, and works well when all endpoints share the same backend reliability profile.

If a single endpoint starts failing (for whatever reason — flaky third-party dependency, slow database query, intermittent timeout), the default behavior opens the breaker and blocks every method, including healthy ones. In that specific scenario, method-level granularity isolates breakers per API method so a failing getReviews does not block getProduct.

When to use

Enable method-level granularity only when all of these are true:

1. You have identified a specific endpoint that fails independently of the rest of the integration.
2. The default integration-level breaker is blocking healthy methods because of that single endpoint.
3. You have confirmed the issue cannot be resolved at the source (e.g., fixing the flaky endpoint, adding a dedicated timeout, or splitting the integration).

For most integrations — especially those with few methods or a single backend — the default integration-level granularity is sufficient.

Enable in config

integrations: {
  commerce: {
    location: "./integrations/commerce/index.server.ts",
    configuration: { /* ... */ },
    circuitBreaker: {
      preset: "BALANCED",
      granularity: "method",   // last resort — see "When to use" above
      methods: ["getReviews", "getRecommendations"], // optional — only these get own breakers
    },
  },
}

When methods is omitted, all methods get their own breaker. When provided, only the listed methods get method-level breakers — unlisted methods share the integration-level breaker.

Enable via environment variable

# All integrations
CB_GRANULARITY=method

# Single integration
CB_COMMERCE_GRANULARITY=method

# Selective methods (comma-separated)
CB_COMMERCE_METHODS=getReviews,getRecommendations

# Global methods override
CB_METHODS=getReviews,getRecommendations

Environment variables override the config value.

Diagnostic workflow

Method-level granularity is most useful as a temporary diagnostic tool. Follow this workflow:

1. Enable method granularity — set granularity: "method" (or CB_<INTEGRATION>_GRANULARITY=method via env var) when the integration-level breaker keeps tripping and you need to identify which endpoint is the root cause.
2. Identify the failing methods — monitor logs and metrics to find which specific method(s) are causing the circuit breaker to open.
3. Handle errors more gracefully — once the problematic methods are identified, check if their errors can be handled at the application level (e.g., fallback responses, retries, dedicated timeouts, or fixing the upstream issue).
4. Switch back to the default granularity — after resolving the underlying issue, remove the granularity: "method" setting to return to integration-level circuit breaking.

If the issue is permanent (e.g., a chronically unreliable third-party endpoint), you can use selective method granularity to isolate only those endpoints:

circuitBreaker: {
  preset: "BALANCED",
  granularity: "method",
  methods: ["getReviews", "getRecommendations"], // only these get own breakers
}

Trade-offs

• More isolation — a single flaky endpoint no longer takes down the whole integration.
• More memory — each unique method gets its own circuit breaker (stat buckets, timers, listeners). The total number of breakers is bounded by the number of real API methods in your project.
• More complexity — monitoring and debugging become harder because you now have many breakers per integration instead of one.