package com.cameleer.server.core.storage.model;

import java.time.Instant;
import java.util.List;
import java.util.Map;

/**
 * Request contract for the generic server-metrics time-series query.
 *
 * <p>{@code aggregation} controls how multiple samples within a bucket
 * collapse: {@code avg|sum|max|min|latest}. {@code mode} controls counter
 * handling: {@code raw} returns values as stored (cumulative for counters),
 * {@code delta} returns per-bucket positive-clipped differences computed
 * per {@code server_instance_id}.
 *
 * <p>{@code statistic} filters which Micrometer sub-measurement to read
 * ({@code value} / {@code count} / {@code total_time} / {@code total} /
 * {@code max} / {@code mean}). {@code mean} is a derived statistic for
 * timers: {@code sum(total_time|total) / sum(count)} per bucket.
 *
 * <p>{@code groupByTags} splits the output into one series per unique tag
 * combination. {@code filterTags} narrows the input to samples whose tag
 * map matches every entry.
 *
 * <p>{@code serverInstanceIds} is an optional allow-list. When null or
 * empty all instances observed in the window are included.
 */
public record ServerMetricQueryRequest(
        String metric,
        String statistic,
        Instant from,
        Instant to,
        Integer stepSeconds,
        List<String> groupByTags,
        Map<String, String> filterTags,
        String aggregation,
        String mode,
        List<String> serverInstanceIds
) {
}
