Add observability and metrics interface for monitoring

[coolguy1771]

Proposal

The library currently lacks internal visibility, making it difficult to monitor production health or debug API-level issues. I propose introducing a Metrics interface to allow users to hook into the session lifecycle and API performance data (e.g., for Prometheus or Datadog).

Proposed Interface

This interface covers session management, message throughput, and raw API performance:

type Metrics interface {
    RecordSessionCreated(scaleSetID int)
    RecordSessionRefreshed(scaleSetID int)
    RecordSessionClosed(scaleSetID int, err error)
    RecordMessageReceived(scaleSetID, messageID int)
    RecordMessageDeleted(scaleSetID, messageID int)
    RecordScaleEvent(scaleSetID, desired, actual int)
    RecordAPICall(method, path string, duration time.Duration, statusCode int, err error)
}

Integration Plan

1. Functional Options: Add WithMetrics(Metrics) to HTTPOption to allow optional injection.
2. Default No-op: Provide a noopMetrics implementation to avoid nil checks throughout the codebase.
3. Instrumentation Points:
   • Sessions: Track creation, refresh, and termination.
   • Messages: Track Get and Delete success/failure rates.
   • Transport: Wrap the HTTP client to record latency and status codes for all outbound requests.

func WithMetrics(metrics Metrics) HTTPOption {
    return func(c *httpClientOption) {
        c.metrics = metrics
    }
}

Benefits

• Observability: Users can alert on high error rates or session stalls.
• Cost Tracking: Provides visibility into API usage patterns.
• Performance: Latency tracking for scaling operations.