123eworld Knowledge Hub → SMS API → Page 311
SMS API Health Monitoring: Metrics, Alerts, SLOs and Operational Dashboards
A practical developer reference designed to solve real implementation and production problems around sms api health monitoring: metrics, alerts, slos and operational dashboards.
What to monitor
Monitor API latency, error rate, queue age, worker throughput, provider response time, delivery rate, failure rate, webhook success and database health.
SLIs and SLOs
Define service-level indicators that represent customer experience. Examples include successful API acceptance rate, queue processing latency and webhook delivery latency.
Golden signals
Latency, traffic, errors and saturation are useful foundations, but messaging platforms also need delivery and queue-specific indicators.
Queue age
Queue age is often more informative than queue depth alone. A queue with many fast-processing messages may be healthy, while a small queue with very old messages may indicate a serious problem.
Provider health
Track providers separately by destination and route. Aggregate provider health can hide a country-specific outage.
Alert design
Alert on sustained conditions and meaningful thresholds. Avoid creating an alert for every individual provider rejection.
Dashboards
Create executive, operations and engineering views with appropriate levels of detail.
Tenant impact
Where appropriate, identify which tenants or applications are affected without exposing sensitive customer data.
Incident correlation
Use common request, message and attempt IDs to connect metrics, logs and traces.
Capacity signals
Monitor worker saturation, database connections, queue throughput and provider limits.
Review cadence
Review SLO breaches and near misses to improve thresholds and architecture.
Operational checklist
Metrics → thresholds → alerts → runbooks → incident review → improvement.
Practical implementation guidance
Design the public API around a stable logical message ID and keep provider-specific complexity behind internal adapters. Every asynchronous step should be durable, observable and safe to retry.
Security and privacy
Treat phone numbers, message content, credentials and delivery evidence as sensitive. Apply tenant authorization before data access and avoid unnecessary values in logs, traces and reports.
Developer-first principle
A useful reference page should tell developers not only what a feature is, but how to implement it safely, how to troubleshoot it and what failure cases to expect.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related API, routing, reliability and developer guides.
Metrics hierarchy
Start with service-wide metrics, then drill down by tenant, provider, country, route and application. Avoid dashboards with hundreds of undifferentiated graphs. Each metric should answer an operational question.
API acceptance SLO
Measure the percentage of valid API requests accepted within the target latency. Exclude invalid customer requests from availability calculations where that matches the documented SLO.
Queue processing SLO
Track the time from queue admission to worker processing. Long queue age can indicate worker saturation, provider throttling or downstream database contention.
Delivery SLO
A delivery SLO must define the eligible population and time window. Pending traffic should not be treated as failed merely because its receipt has not yet arrived.
Webhook SLO
Measure successful webhook acknowledgement and delivery latency separately from SMS delivery. A perfectly delivered SMS can still have a failed customer webhook.
Saturation
Monitor worker concurrency, database connections, queue capacity and provider throughput. Saturation often predicts incidents before error rates rise.
Alert severity
Use different severities for customer-impacting failures, capacity warnings and data-quality anomalies. This keeps on-call attention focused.
Dashboards by role
An executive dashboard can show availability and delivery trends; an operations dashboard should show queue and provider health; an engineering dashboard should expose latency and dependency detail.
Alert runbooks
Every important alert should link conceptually to a runbook describing investigation and mitigation steps.
SLO review
Review SLO performance monthly and after incidents. Adjust only when the change reflects better understanding or a deliberate product decision, not to make the dashboard look healthier.
Anomaly detection
Static thresholds are useful, but baseline-aware detection can identify unusual delivery or latency changes. Compare current traffic with historical patterns for the same hour, country and provider where data volume supports it.
Metric cardinality
Do not create unrestricted metrics for phone number or message ID. High-cardinality telemetry can become more expensive and less useful than logs or traces. Aggregate on controlled dimensions.
Alert fatigue
Review alerts that rarely lead to action. An alert that is always ignored is not protecting the system. Combine related symptoms into an incident-level alert where practical.
Operational ownership
Every critical metric should have an owner responsible for reviewing it and maintaining its threshold or runbook. Monitoring without ownership becomes stale.
Burn-rate thinking
For important SLOs, track how quickly the error or latency budget is being consumed. A short incident may be acceptable while a persistent small degradation can become more damaging over the month.
Provider dashboards
Give each provider a dedicated health view showing request success, throttling, latency, destination distribution and delivery outcomes. Compare it with the overall platform view.
Queue dashboards
Show oldest message age, percentile age, throughput and retry volume. Queue depth alone can be misleading during variable traffic.
Capacity alerts
Alert before hard limits are reached. Database connection utilization, worker saturation and provider throughput should have warning thresholds that leave time for intervention.
Monitoring review checklist
For each alert, ask: who receives it, what customer impact does it represent, what metric proves it, what runbook applies and what mitigation is available? Remove alerts that cannot lead to action.
Reference principle
Monitoring should reduce time to detect and time to recover, not simply increase the number of dashboards.
Advanced production guidance
Monitoring should connect symptoms to likely causes. For example, rising queue age combined with normal API latency and increased provider throttling suggests downstream capacity pressure, while rising API latency with normal provider performance may indicate application or database saturation. Dashboards should therefore show related signals together rather than isolating every metric on a separate screen. During an incident, the operator should be able to move from a customer-impacting symptom to the dependency that is likely responsible. After recovery, the same dashboard should help verify that queue age, provider performance and delivery outcomes have returned to normal. This closes the loop between detection and recovery.
Reference architecture detail
Operational dashboards should make the relationship between queue health and delivery health visible. If queue age increases while provider performance remains normal, the worker layer may be saturated. If queue age is normal but delivery latency rises after submission, the provider or carrier route may be responsible. These distinctions help operators avoid changing the wrong component during an incident. Dashboard design should therefore group metrics around the message lifecycle rather than around infrastructure teams alone. This produces a clearer operational picture and shortens the path from symptom to corrective action.
Final production checklist
Monitoring should be reviewed after every significant architecture change. New queues, providers, database replicas or reporting pipelines can introduce failure modes that existing dashboards do not capture. Add the minimum metrics needed to prove the new component is healthy and connected to the customer-visible message lifecycle.
Advanced reference note
An operational dashboard should also display configuration changes that may explain sudden metric movement. A new provider weight, sender profile, rate limit or worker deployment can change traffic behaviour even when no infrastructure is technically unhealthy. Where practical, place deployment and configuration markers on time-series charts. This gives incident responders immediate context and reduces the need to search several unrelated systems for the reason a metric changed.
Final reference guidance
Keep operational dashboards readable on an incident screen. The most important customer-impacting signals should be visible without opening many panels. Detailed provider, route and tenant drill-downs can remain one level deeper.
Implementation safeguard
Alert thresholds should be based on customer impact and system capacity. For example, queue age can be tied to the maximum acceptable processing delay, while provider throttling can be compared with available alternate capacity. This makes alerts meaningful instead of arbitrary.
Operational control
Finally, monitoring data should itself be versioned when definitions change. If a queue-age metric changes from oldest item to p95 age, record the change so historical comparisons remain meaningful. Stable definitions make operational reviews much more trustworthy.
Final control
Keep alert ownership explicit so every critical notification has a responsible response team.