The RED method for integrations

The RED method gives you three numbers for every integration:

• Rate: How many requests per second are you making to this partner?
• Errors: What percentage of those requests are failing?
• Duration: How long are those requests taking?

If you monitor only these three things per partner, you will catch 90% of integration issues before your users report them.

import { Registry, Counter, Histogram } from 'prom-client';

const register = new Registry();

// Rate + Errors: a single counter with status labels
const integrationRequests = new Counter({
  name: 'integration_requests_total',
  help: 'Total number of external API requests',
  labelNames: ['partner', 'endpoint', 'method', 'status'],
  registers: [register],
});

// Duration: histogram for response time distribution
const integrationDuration = new Histogram({
  name: 'integration_request_duration_seconds',
  help: 'External API request duration in seconds',
  labelNames: ['partner', 'endpoint', 'method'],
  // Buckets tuned for typical API latencies
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  registers: [register],
});

Instrumenting an integration call

Wrap every external APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more call with metric recording:

async function callExternalAPI(
  partner: string,
  endpoint: string,
  method: string,
  options: RequestInit
): Promise<Response> {
  const timer = integrationDuration.startTimer({
    partner,
    endpoint,
    method,
  });

  try {
    const response = await fetch(endpoint, { method, ...options });

    // Record the request with its status category
    const status = response.ok ? 'success' : `error_${response.status}`;
    integrationRequests.inc({ partner, endpoint, method, status });

    timer(); // Records duration
    return response;
  } catch (error) {
    // Network errors, timeouts, DNS failures
    integrationRequests.inc({
      partner,
      endpoint,
      method,
      status: 'network_error',
    });
    timer();
    throw error;
  }
}

Now every external call automatically tracks rate, errors, and duration. You do not need to remember to add metrics, the wrapper handles it.

Essential integration metrics

Beyond RED, there are integration-specific metrics that catch problems logs alone cannot:

Per-partner vs. global metrics

This is the key difference between integration observability and general application monitoring. A global error rate of 2% might look fine, but if 100% of your Stripe calls are failing and 0% of everything else is, that 2% global rate hides a complete payment outage.

// Bad: global metric hides partner-specific issues
const apiErrors = new Counter({
  name: 'api_errors_total',
  help: 'Total API errors',
  registers: [register],
});

// Good: per-partner metric reveals exactly who is failing
const integrationErrors = new Counter({
  name: 'integration_errors_total',
  help: 'Integration errors by partner',
  labelNames: ['partner', 'error_type'],
  registers: [register],
});

Always label by partner. The extra cardinality is worth it, integration debugging without partner-level granularity is guesswork.

Prometheus histogram buckets

Default histogram buckets are designed for general HTTPWhat is http?The protocol browsers and servers use to exchange web pages, API data, and other resources, defining how requests and responses are formatted. Ask AI for more servers. Integration calls have different latencyWhat is latency?The time delay between sending a request and receiving the first byte of the response, usually measured in milliseconds. Ask AI for more profiles, an internal microservice responds in 5ms, but a payment APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more might take 2 seconds. Choose buckets that match your SLO targets:

// For fast internal APIs (< 100ms expected)
const internalBuckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5];

// For typical external APIs (100ms - 2s expected)
const externalBuckets = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];

// For slow external APIs (payment, KYC verification)
const slowExternalBuckets = [0.5, 1, 2.5, 5, 10, 15, 30, 60];

If your SLO says "99% of Stripe calls must complete in under 2 seconds", you need buckets around that 2-second mark to calculate the actual percentile accurately. Buckets that jump from 1s to 5s will not give you useful data at the 2-second boundary.

Dashboard design for integration health

A good integration dashboard is not a wall of graphs, it is a decision-making tool. Design it to answer specific questions in a specific order.

The integration health dashboard layout

PromQL examples for integration dashboards

# Error rate per partner (as percentage)
100 * (
  rate(integration_requests_total{status=~"error.*"}[5m])
  / rate(integration_requests_total[5m])
)

# p99 latency per partner
histogram_quantile(0.99,
  rate(integration_request_duration_seconds_bucket[5m])
)

# Requests per second to each partner
sum by (partner) (rate(integration_requests_total[5m]))

# Retry ratio (retries / total requests)
rate(integration_retries_total[5m])
  / rate(integration_requests_total[5m])

Avoiding high-cardinality explosions

Prometheus stores every unique combination of labels as a separate time series. Adding a userId label to your integration metrics creates one time series per user per partner per endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. Ask AI for more, millions of series that will crash your Prometheus server.

Group status codes into buckets (success, client_error, server_error, timeout) rather than tracking each individual code. Use logs for the per-request detail, metrics are for aggregates.

Exposing the metrics endpointWhat is endpoint?A specific URL path on a server that handles a particular type of request, like GET /api/users. Ask AI for more

Wire up the Prometheus metrics endpoint so your Prometheus server can scrape it:

import express from 'express';
import { register } from './metrics';

const app = express();

// Prometheus scrape endpoint
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

In production, protect this endpoint, it should not be publicly accessible. Use a separate internal port or restrict access by IP.

Quick reference