Monitoring & Observability
Relevant source files
The following files were used as context for generating this wiki page:The email-platform project incorporates a robust monitoring and observability stack using Prometheus and Grafana. This system is designed to provide insights into the application's performance, health, and operational metrics. The entire stack is containerized and managed via Docker Compose, allowing for easy deployment in both development and production environments.
The core of the system involves the API service exposing metrics in a Prometheus-compatible format, which are then scraped by a Prometheus server. Grafana is used for visualizing these metrics through a pre-configured "Email Operations Dashboard," offering real-time views of request rates and latencies. Health check endpoints are also provided to allow for automated readiness and liveness probes.
Sources: README.md:21-22, blueprint.md:16, deployment_guide.md:65-69
Architecture
The monitoring architecture consists of three main services orchestrated by Docker: the api service, prometheus, and grafana. The api service exposes application metrics, prometheus scrapes and stores these metrics, and grafana queries Prometheus to display the data on dashboards.
Sources: README.md:21-22, deployment_guide.md:65-69
Component Overview
The following diagram illustrates the relationship between the monitoring components.
This diagram shows the data flow from the API service to Prometheus for scraping and then to Grafana for visualization.
Sources: README.md:21-22, services/observability/prometheus.yml:9-13
Service Configuration
The monitoring services are defined in the development deployment guide. The production guide also mentions Grafana and Prometheus URLs.
| Service | Description |
|---|---|
prometheus | Scrapes and stores time-series metrics from the API service. |
grafana | Visualizes metrics collected by Prometheus. Accessible at https://grafana.yourdomain.com. |
Sources: deployment_guide.md:65-69, README.md:21-22
Prometheus
Prometheus is configured to scrape metrics from the API service. The configuration specifies the scrape interval and the target endpoint.
Sources: services/observability/prometheus.yml
Scrape Configuration
The Prometheus server is configured to poll the api service every 15 seconds on port 3001 at the /metrics endpoint.
# services/observability/prometheus.yml:9-13
scrape_configs:
- job_name: "api"
static_configs:
- targets: ["api:3001"]
This configuration ensures that Prometheus continuously collects metrics from the running API container.
Sources: services/observability/prometheusyml:9-13
Metrics Exposition
The API service exposes key operational metrics via a dedicated /metrics endpoint. This is implemented using the prom-client library.
Sources: services/api/src/routes/health.ts:18-24, README.md:100
Health & Metrics Endpoints
The system provides several endpoints for health checks and metrics scraping.
| Endpoint | Method | Description | Source File |
|---|---|---|---|
/health | GET | A simple liveness probe that returns the service status. | services/api/src/routes/health.ts |
/ready | GET | A readiness probe that checks the database connection. | services/api/src/routes/health.ts |
/metrics | GET | Exposes application metrics in Prometheus format. | services/api/src/routes/health.ts |
The /metrics endpoint is set up to serve the collected metrics.
// services/api/src/routes/health.ts:18-24
app.get("/metrics", async (request, reply) => {
const metrics = await client.register.metrics();
reply.header("Content-Type", client.register.contentType);
return metrics;
});
This endpoint is the target for the Prometheus scrape job.
Sources: services/api/src/routes/health.ts:18-24, README.md:100
Grafana Dashboard
The project includes a pre-built Grafana dashboard named "Email Operations Dashboard" for visualizing the most critical API metrics.
Sources: services/observability/grafana/dashboards/email_service.json
Dashboard Panels
The dashboard provides at-a-glance information about the API's performance.
The following diagram shows the metrics scraping and visualization flow.
The dashboard contains the following key panels:
| Panel Title | Description | PromQL Query |
|---|---|---|
| Request Rate (RPS) | Shows the number of HTTP requests per second. | rate(http_request_duration_seconds_count[1m]) |
| P95 Latency (s) | Displays the 95th percentile of request latency in seconds. | histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[1m])) by (le)) |
These panels help operators quickly identify performance issues or changes in traffic patterns.
Sources: services/observability/grafana/dashboards/email_service.json:59-81, services/observability/grafana/dashboards/email_service.json:133-155
A sample panel configuration for "Request Rate (RPS)" is shown below:
// services/observability/grafana/dashboards/email_service.json:73-80
"targets": [
{
"datasource": { "type": "prometheus", "uid": "Prometheus" },
"editorMode": "code",
"expr": "rate(http_request_duration_seconds_count[1m])",
"legendFormat": "{{route}} ({{method}})",
"range": true,
"refId": "A"
}
],
Sources: services/observability/grafana/dashboards/email_service.json:73-80
Summary
The monitoring and observability stack is a critical part of the email-platform, providing essential visibility into the system's health and performance. By leveraging industry-standard tools like Prometheus and Grafana, developers and operators can effectively monitor the API, diagnose issues, and ensure service reliability. The setup is fully containerized and pre-configured, making it easy to deploy and use out of the box.
Sources: README.md:100-103, deployment_guide.md:65-69, blueprint.md:16