Efficient Sync Health Monitor

Monitor synchronization pipeline health across GitHub, Linear, and custom integrations with real-time metrics, alerting, and performance diagnostics.

When to Use This Command

Run this command when...

• You need a quick health check of your GitHub-Linear synchronization pipeline before or after a major sync operation
• Webhook delivery failures are suspected and you want to verify event processing rates and latency
• You want to establish baseline performance metrics for your sync infrastructure to detect future degradation

Avoid this command when...

• You need to actively resolve detected conflicts (use Power Sync Conflict Resolver after identifying issues)
• You want to set up continuous monitoring; this command provides point-in-time snapshots rather than persistent alerting

Quick Start

Copy
# .sync-health.yaml
monitors:
  - name: github-api
    check: rate_limit
    warn_threshold: 100
    critical_threshold: 20
  - name: linear-webhook
    check: delivery_rate
    warn_threshold: 0.95
    critical_threshold: 0.80

Copy
claude -p "Check sync health for our GitHub-Linear integration and report any issues"

Expected output:
=== Sync Health Report ===
GitHub API: HEALTHY (4,847/5,000 requests remaining)
Linear Webhook: HEALTHY (99.2% delivery rate, avg 340ms latency)
Last sync: 12 minutes ago (SUCCESS, 47 items processed)
Queue depth: 3 items pending
Errors (24h): 0 critical, 2 warnings (rate limit approach at 14:32)
Overall status: HEALTHY

Core Concepts

Concept	Description
Health Check	Point-in-time probe that tests connectivity, authentication, and response times
Rate Limit Monitoring	Tracks API quota consumption to prevent throttling mid-sync
Delivery Rate	Percentage of webhook events successfully received and processed
Queue Depth	Number of sync items waiting to be processed, indicating backlog pressure
Latency Percentiles	P50, P90, P99 response times revealing tail-latency problems

GitHub API ----[rate check]----> Monitor
Linear API ----[auth check]----> Monitor ----> Health Report
Webhooks   ----[delivery %]----> Monitor        |
Queue      ----[depth check]---> Monitor     [ALERT if
                                              threshold
                                              breached]

Configuration

Parameter	Type	Default	Description	Example
warn_threshold	number	varies	Value that triggers a warning alert	100 (requests remaining)
critical_threshold	number	varies	Value that triggers a critical alert	20
check_interval	string	5m	How often to run health checks	1m
include_latency	boolean	true	Include P50/P90/P99 latency metrics	false
alert_channel	string	stdout	Where to send alerts	slack:#ops

Best Practices

1. Run health checks before major sync operations -- A pre-flight health check catches rate limit exhaustion or authentication expiry before they cause sync failures mid-operation.
2. Set warning thresholds well above critical -- Give yourself time to react; a warning at 100 remaining requests lets you throttle before hitting the critical floor at 20.
3. Track latency trends over time -- A gradual increase in P99 latency often precedes an outage. Export health reports to a time-series store for trend analysis.
4. Include queue depth in dashboards -- A growing queue with stable processing rate means your sync throughput cannot keep up with incoming changes.
5. Correlate health events with deployment timestamps -- Many sync health degradations trace back to recent deployments that changed API call patterns or webhook configurations.

Common Issues

1. GitHub API shows low remaining requests but no sync is running -- Other CI/CD tools or GitHub Actions may share the same API token. Use a dedicated token for sync operations to isolate quota consumption.
2. Webhook delivery rate drops below threshold -- Check whether the webhook endpoint SSL certificate has expired or whether a firewall rule changed. Linear retries failed deliveries, but repeated failures trigger suspension.
3. Health check itself times out -- The monitoring endpoint may be behind a VPN or proxy. Ensure the health check runs from a network location with direct access to both GitHub and Linear APIs.