Integration health metrics: errors, latency, and churn signals

An integration can be "up" and still be dying. Calls return 200. The listing still shows installed. The customer stopped trusting the sync two weeks ago and will disconnect at renewal. The signals were in error class, latency, and records that never moved. Nobody had a threshold that meant "this connection is about to churn."

Health metrics sit between integration monitoring and integration adoption metrics. Health is quality of use, and bad health leads disconnects. Google's monitoring distributed systems and Prometheus alerting apply directly: alert on symptoms the user feels, and keep the page channel trustworthy.

The 60-second version

• Health is quality of a live connection, not uptime and not installs. A green ping with a growing sync gap is unhealthy.
• Watch four churn-leading families: error rate and class, latency (including sync lag), reconciliation gaps, and dead auth or dead webhooks.
• Thresholds come from the workflow, not from a copied SLA. A daily sync and a checkout-path call cannot share one number.
• Alert on symptoms and duration, not on a single slow request. Pages that cry wolf train people to ignore churn warnings too.
• Broken connections are not the same as unused ones. Instrument auth failures and delivery stops separately from inactivity, or you will misread both.
• Health without an owner is a dashboard. Every integration needs a person who gets the yellow state and a play for it.
• Tie health to retention. Connections that sit red for a defined period should trigger a save path, not only an incident channel.
• Adoption tells you if they tried. Health tells you if they will stay. You need both.

Health is not uptime, and it is not installs

Uptime asks whether the endpoint answers. Adoption asks whether a customer connected and came back. Health asks whether the connection is producing the outcome the customer bought: contacts that match, orders that land on time, events that arrive, a workflow that still feels faster than the spreadsheet.

Those three diverge on purpose.

A customer who churns an integration often did not see a public outage. They saw duplicates, missing rows, a lag that made the dashboard useless, or a reconnect loop after a token expired. Those are health failures. If your only scoreboard is "is the job running," you will report green through the entire slide into disconnect.

Google's SRE chapter on monitoring distributed systems draws the same line as symptom versus cause. The symptom here is "the customer's records are late or wrong." CPU on your worker is a cause. Page on the symptom. Debug on the cause.

Error rate and error class

Raw error count is a weak churn signal. A traffic spike creates errors. A single noisy endpoint can drown a quiet, fatal one. What predicts "I am going to disconnect this" is persistent, user-visible failure on the path they care about.

Split errors so the class tells you the save action:

Track rate per connection and per endpoint, not a global pile. A 2 percent error rate company-wide can hide one customer at 80 percent, and that one customer is the churn. Also track consecutive failure time per connection. A connection that has not succeeded in N hours is a different object from a connection with occasional 500s.

Do not treat all 4xx as the customer's fault. A 401 after you failed to refresh a token is yours. A 422 after the partner tightened validation is a versioning event and a health event at once.

Latency, lag, and "feels broken"

Latency is how long a call takes. Lag is how late the data is relative to when the customer needed it. Churn cares about lag. A p50 of 200 milliseconds on a webhook you process six hours later is a healthy call and an unhealthy integration.

Measure both:

• Call latency as a distribution (p50, p95, p99) at the boundary you control, including retries. This is the monitoring view.
• Sync lag as time from source change to destination apply, per connection. This is the health view.

Thresholds have to match the job. A notification integration that is "real time" in the listing cannot sit at twenty minutes of lag without becoming a lie. A nightly finance export can. Write the promise you already made in the docs, then put the threshold there. Do not copy a 300-millisecond API SLA onto a batch sync.

Lag that creeps is more useful than lag that spikes once. A connection whose lag has risen every day for a week is a customer who is about to build a workaround. Workarounds are the step before disconnect. Alert on the trend, not only on a cliff.

Sync gaps: the silent churn driver

The highest-value health metric is still reconciliation: what should have moved versus what did. Integration monitoring covers how to build that check. Here the point is why it predicts churn better than errors.

Customers forgive an outage they can see. They do not forgive a CRM that is missing 40 of 1,000 contacts with no error. They find it in a meeting, they lose trust, and they turn the integration off "until we have time to look," which is a polite disconnect.

Health metrics to keep on the reconciliation:

• Gap count and gap rate per connection (missing, extra, mismatched on a key field).
• Gap age: how long the oldest missing record has been missing.
• Direction: source-to-you versus you-to-partner, because blame and the fix differ.

A growing gap with a green error rate is the classic silent failure: webhooks stopped, a filter dropped a type, a partial batch, a clock skew. Treat gap growth as a page-level symptom for high-value connections, and as a same-day ticket for the rest.

Dead connections: auth, webhooks, and "active" that is not

Adoption metrics warn you not to confuse a broken connection with churn. Health metrics are how you stop confusing them.

Instrument, separately:

• Token expiry and refresh failure. The connection will look idle if you only count successful syncs.
• Webhook delivery stop. No events is not the same as no business events. Heartbeats or an expected-volume check distinguish "quiet day" from "partner stopped calling."
• User-disabled versus system-broken. A customer who toggles off is adoption/churn. A customer who would still be on if the OAuth had refreshed is a health miss you can still save.

A dead connection that you report as "inactive, probably churned" never gets the reconnect email, and then it does churn. The save path is mechanical: in-app reconnect, email to the admin who installed, a banner on the next login. The metric is time in broken-auth state. The target is hours, not a weekly digest.

Rate limits belong here too. A connection that lives on 429s is not down, but it is late, and late is the lag problem above. Persistent 429s on one tenant are a health ticket (batching, quota, or a runaway loop), not a shrug.

Thresholds, alerting, and who acts

A threshold is a promise about when a human will look. Copying someone else's p99 number is how you either page all night or never page. Set them from the workflow and from what you already told the customer.

Method, without fake universal SLAs:

1. Write the user-visible promise. "Contacts within X minutes," "nightly by 07:00," "errors surfaced in the UI."
2. Pick a symptom metric that is that promise: lag, gap, consecutive auth failure, error rate on that path.
3. Add duration. Prometheus's alerting practices are blunt: alerts should be for things that are real, urgent, and actionable, and they should not flap. "Gap rate above your line for 15 minutes" is an alert. One failed call is not.
4. Severity matches the save path. Page now if the connection is dead for a high-value tenant. Ticket today if p95 is over budget. Weekly review if a deprecation header appeared.
5. Name the owner. Health alerts that land in a shared channel nobody owns are how yellow becomes a surprise disconnect.

You need one written promise, two or three symptom alerts with duration, and a person. Expand after the first incident.

Tie each symptom to a save path. Broken auth gets a reconnect campaign. A growing gap gets a visible pause or a fix: hidden wrong data is worse than a pause. Chronic lag means you change the listing promise or you fix the queue. Connections that stay red go to a QBR list and to partnership metrics. If most disconnects were red first, you have a health problem. If they were green, you have an adoption problem. Chronically red integrations are sunset candidates, not only an on-call tax.

Common mistakes, and the fix

Watching uptime and calling it health. The fix: add lag, gap, and auth-state. A ping does not tell you whether records moved.

One global error rate. The fix: per connection and per endpoint, plus consecutive failure time. Averages hide the customer who is already gone.

Alerting on every 500. The fix: symptoms, thresholds, duration. Follow the SRE and Prometheus alerting idea: pages must be actionable or they will be ignored, including the ones that were real.

Treating dead auth as churn. The fix: a broken-connection state, a reconnect path, and time-in-broken as a metric. Save them before you count them as lost.

No owner for yellow. The fix: named owner per integration, same as in integration monitoring. A dashboard without a route is a slide.

Ignoring health in adoption reports. The fix: report retained usage and health together. A retained-but-red connection is a churn warning, not a success.

FAQ

What are the most important integration health metrics? Per-connection error rate by class, sync lag against the promised freshness, reconciliation gap, and time in broken-auth or stopped-webhook state.

How do I set thresholds if I do not have SLO history? Start from the promise in your docs, add a duration so a blip does not page, and tighten after the first incident. Do not paste a public cloud SLA onto a batch sync.

How is this different from integration monitoring? Monitoring is the system: collect, alert, on-call, partner API change. This post is which signals mean a customer is about to leave, and the save path.

How is this different from adoption metrics? Adoption is install, active, retained. Health is whether the active connection is correct and timely. Read them together.

Should we show health to the customer? Yes, for states they can fix or should know: reconnect, paused, delayed. Show last successful sync and action required, not a p99 chart.

When is an integration unhealthy enough to sunset? When it stays red across many tenants, the partner API is a moving target, and adoption does not justify the maintenance. Keeping it for the listing is a support tax.

The short version

Integration health is the quality of a live connection: errors by class, latency and lag, sync gaps, and dead auth. Uptime and installs will not warn you before a customer leaves. Set thresholds from the promise you already made, alert on symptoms with duration, and give yellow a named owner and a save path. Broken is not unused. Wrong data is worse than a visible pause.

Adoption says whether they tried. Health says whether they will still be there at renewal. Measure both.

If you want a clear picture of which integrations are worth keeping healthy, and which to build next, that is exactly what a Partner Audit is for. We review your product, API, and partner potential, then define what to build, who to approach, and how to ship it.

Further reading

• Google SRE: monitoring distributed systems
• Prometheus: alerting practices
• Google SRE: service level objectives