using System;

namespace Svrnty.CQRS.Events.Abstractions.Streaming;

/// <summary>
/// Metrics collection interface for event streaming operations.
/// Provides observability into stream performance, consumer behavior, and error rates.
/// </summary>
/// <remarks>
/// <para>
/// <strong>Phase 6 Feature:</strong>
/// This interface enables monitoring and observability for event streaming.
/// Implementations should integrate with telemetry systems like OpenTelemetry, Prometheus, etc.
/// </para>
/// <para>
/// <strong>Key Metrics Categories:</strong>
/// - Throughput: Events published/consumed per second
/// - Lag: Consumer offset delta from stream head
/// - Latency: Time from event publish to acknowledgment
/// - Errors: Failed operations and retry counts
/// </para>
/// </remarks>
public interface IEventStreamMetrics
{
    /// <summary>
    /// Records an event being published to a stream.
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="eventType">Type name of the event.</param>
    void RecordEventPublished(string streamName, string eventType);

    /// <summary>
    /// Records an event being consumed from a subscription.
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription.</param>
    /// <param name="eventType">Type name of the event.</param>
    void RecordEventConsumed(string streamName, string subscriptionId, string eventType);

    /// <summary>
    /// Records the processing latency for an event (time from publish to acknowledgment).
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription.</param>
    /// <param name="latency">Processing duration.</param>
    void RecordProcessingLatency(string streamName, string subscriptionId, TimeSpan latency);

    /// <summary>
    /// Records consumer lag (offset delta from stream head).
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription.</param>
    /// <param name="lag">Number of events the consumer is behind.</param>
    void RecordConsumerLag(string streamName, string subscriptionId, long lag);

    /// <summary>
    /// Records an error during event processing.
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription (or null for publish errors).</param>
    /// <param name="errorType">Type or category of error.</param>
    void RecordError(string streamName, string? subscriptionId, string errorType);

    /// <summary>
    /// Records a retry attempt for failed event processing.
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription.</param>
    /// <param name="attemptNumber">Retry attempt number (1-based).</param>
    void RecordRetry(string streamName, string subscriptionId, int attemptNumber);

    /// <summary>
    /// Records the current stream length (total events).
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="length">Current length of the stream.</param>
    void RecordStreamLength(string streamName, long length);

    /// <summary>
    /// Records the number of active consumers for a subscription.
    /// </summary>
    /// <param name="streamName">Name of the stream.</param>
    /// <param name="subscriptionId">ID of the subscription.</param>
    /// <param name="consumerCount">Number of active consumers.</param>
    void RecordActiveConsumers(string streamName, string subscriptionId, int consumerCount);
}