Performance Analytics with Pulse: Tracing, Metrics & Monitoring

What is Observability?

Observability is the ability to understand what your application is doing internally by examining its external outputs. In production, you cannot attach a debugger or add print statements. You need systems that continuously collect and present data about your application's behavior.

Observability rests on three pillars:

Most observability solutions (Datadog, New Relic, Grafana Cloud) are external services that cost money and send your data to third-party servers. Pulse is different — it's built into your Grit application and runs locally. Your data stays with you.

What is Pulse?

Pulse is Grit's built-in observability SDK. It's embedded directly in your API as middleware and provides a dashboard at /pulse/ui. No external services, no API keys, no monthly bills — just start your Grit API and open the dashboard.

What Pulse provides:

• • Request tracing — every API request timed and recorded with endpoint, method, status, and duration
• • Database monitoring — SQL query tracking, duration, and connection pool status
• • Runtime metrics — goroutine count, memory usage, garbage collection stats
• • Error tracking — automatic error capture with stack traces and frequency
• • Health checks — GET /pulse/health for load balancers and uptime monitoring
• • Prometheus export — /pulse/metrics for integration with Grafana

Request Tracing

Every HTTP request to your API is automatically traced by Pulse. For each request, Pulse records:

• • Endpoint — the URL path (e.g., /api/users)
• • Method — GET, POST, PUT, DELETE
• • Status code — 200, 201, 400, 401, 404, 500
• • Duration — how long the request took in milliseconds
• • Timestamp — when the request was made
• • Client IP — the origin of the request

The dashboard displays this data in a table, sorted by most recent. You can filter by endpoint, status code, or time range. The most useful view is sorting by duration — this instantly reveals your slowest endpoints.

┌─────────┬───────────────────┬────────┬──────────┬─────────────────┐
│ Method  │ Endpoint          │ Status │ Duration │ Timestamp       │
├─────────┼───────────────────┼────────┼──────────┼─────────────────┤
│ POST    │ /api/auth/login   │ 200    │ 142ms    │ 10:03:22.481    │
│ GET     │ /api/users        │ 200    │ 23ms     │ 10:03:21.102    │
│ GET     │ /api/products     │ 200    │ 89ms     │ 10:03:20.847    │
│ POST    │ /api/products     │ 201    │ 31ms     │ 10:03:19.223    │
│ GET     │ /api/users/5      │ 404    │ 4ms      │ 10:03:18.991    │
│ DELETE  │ /api/products/3   │ 200    │ 12ms     │ 10:03:17.445    │
└─────────┴───────────────────┴────────┴──────────┴─────────────────┘

Database Monitoring

Most API performance issues are database issues. A single N+1 query can turn a 10ms endpoint into a 2-second endpoint. Pulse tracks every SQL query executed by GORM:

• • Query text — the actual SQL that was executed
• • Duration — how long the query took
• • Rows affected — how many rows were returned or modified
• • Frequency — how many times this query pattern was executed

Pulse also shows your connection pool status:

Database Connection Pool
─────────────────────────
Idle connections:    5
Active connections:  2
Max connections:     25
Wait count:          0     ← requests waiting for a connection
Max idle time:       10m

If "Wait count" is greater than zero, your pool is too small — requests are waiting for an available database connection. If "Idle connections" is consistently at max, your pool is too large — those connections consume memory on the database server.

Runtime Metrics

Go provides rich runtime information through its runtime package. Pulse collects and displays these metrics so you can understand how your application is using system resources.

Key runtime metrics Pulse tracks:

Error Tracking

When your API returns a 4xx or 5xx status code, Pulse captures the error automatically. For each error, it records:

• • Error message — what went wrong
• • Stack trace — where in the code the error occurred
• • Endpoint — which URL triggered the error
• • Frequency — how many times this error has occurred
• • Last occurrence — when it happened most recently

Errors are grouped by type and endpoint. If the same validation error occurs 500 times on the registration endpoint, it shows as one entry with a count of 500 — not 500 separate entries. This makes it easy to prioritize: fix the most frequent errors first.

┌───────────────────────────┬──────────┬───────┬───────────────────┐
│ Error                     │ Endpoint │ Count │ Last Seen         │
├───────────────────────────┼──────────┼───────┼───────────────────┤
│ record not found          │ GET /api │ 23    │ 2 minutes ago     │
│                           │ /users/  │       │                   │
│ validation: email required│ POST /api│ 8     │ 15 minutes ago    │
│                           │ /auth/   │       │                   │
│ duplicate key: email      │ POST /api│ 3     │ 1 hour ago        │
│                           │ /auth/   │       │                   │
└───────────────────────────┴──────────┴───────┴───────────────────┘

Health Checks

The health check endpoint at GET /pulse/health returns the current status of your API and its dependencies. This endpoint is used by:

• • Load balancers — to route traffic only to healthy instances
• • Kubernetes — as a liveness probe to restart unhealthy pods
• • Uptime monitors — services like UptimeRobot or Pingdom that alert you when your API goes down
• • Deployment scripts — to verify a new deployment is healthy before switching traffic

GET /pulse/health

{
  "status": "healthy",
  "uptime": "4h 23m 12s",
  "checks": {
    "database": "connected",
    "redis": "connected",
    "storage": "connected"
  },
  "version": "1.0.0"
}

If any dependency is unhealthy (database disconnected, Redis unreachable), the status changes to "degraded" or "unhealthy" and the HTTP status code changes from 200 to 503 (Service Unavailable).

Prometheus Export

Pulse exposes a /pulse/metrics endpoint in Prometheus format. This is a plain-text format that Prometheus understands:

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",endpoint="/api/users",status="200"} 142
http_requests_total{method="POST",endpoint="/api/auth/login",status="200"} 38
http_requests_total{method="GET",endpoint="/api/products",status="200"} 67

# HELP http_request_duration_seconds HTTP request duration in seconds
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{endpoint="/api/users",le="0.01"} 120
http_request_duration_seconds_bucket{endpoint="/api/users",le="0.05"} 138
http_request_duration_seconds_bucket{endpoint="/api/users",le="0.1"} 141

# HELP go_goroutines Number of goroutines
# TYPE go_goroutines gauge
go_goroutines 42

# HELP go_memstats_alloc_bytes Number of bytes allocated
# TYPE go_memstats_alloc_bytes gauge
go_memstats_alloc_bytes 2.4813e+07

To use this with Grafana, add a Prometheus data source pointing at http://your-api:8080/pulse/metrics and build dashboards with panels for request rate, error rate, response time percentiles, and resource usage.

Configuration

Pulse is configured through environment variables in your .env file:

# Pulse Configuration
PULSE_ENABLED=true
PULSE_USERNAME=admin
PULSE_PASSWORD=your-secure-password-here

Summary

Let's review what Pulse provides: