Merge pull request #374 from Entropy-Xu/codex/provider-performance-stats

feat(stats): 添加 Provider 性能统计分析

apps/aether-gateway/src/control/route/admin/observability_families.rs

@@ -495,6 +495,19 @@ pub(super) fn classify_admin_observability_family_route(
             "admin:stats",
             false,
         ))
+    } else if method == http::Method::GET
+        && matches!(
+            normalized_path,
+            "/api/admin/stats/performance/providers" | "/api/admin/stats/performance/providers/"
+        )
+    {
+        Some(classified(
+            "admin_proxy",
+            "stats_manage",
+            "provider_performance",
+            "admin:stats",
+            false,
+        ))
     } else if method == http::Method::GET
         && matches!(
             normalized_path,

apps/aether-gateway/src/control/tests/admin_stats.rs

@@ -81,6 +81,25 @@ fn classifies_admin_stats_performance_percentiles_as_admin_proxy_route() {
     assert!(!decision.is_execution_runtime_candidate());
 }
 
+#[test]
+fn classifies_admin_stats_provider_performance_as_admin_proxy_route() {
+    let headers = headers(&[]);
+    let uri: Uri = "/api/admin/stats/performance/providers"
+        .parse()
+        .expect("uri should parse");
+    let decision =
+        classify_control_route(&http::Method::GET, &uri, &headers).expect("route should classify");
+
+    assert_eq!(decision.route_class.as_deref(), Some("admin_proxy"));
+    assert_eq!(decision.route_family.as_deref(), Some("stats_manage"));
+    assert_eq!(decision.route_kind.as_deref(), Some("provider_performance"));
+    assert_eq!(
+        decision.auth_endpoint_signature.as_deref(),
+        Some("admin:stats")
+    );
+    assert!(!decision.is_execution_runtime_candidate());
+}
+
 #[test]
 fn classifies_admin_stats_cost_forecast_as_admin_proxy_route() {
     let headers = headers(&[]);

apps/aether-gateway/src/data/state/runtime.rs

@@ -1029,6 +1029,21 @@ impl GatewayDataState {
         }
     }
 
+    pub(crate) async fn summarize_usage_provider_performance(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageProviderPerformanceQuery,
+    ) -> Result<
+        aether_data_contracts::repository::usage::StoredUsageProviderPerformance,
+        DataLayerError,
+    > {
+        match &self.usage_reader {
+            Some(repository) => repository.summarize_usage_provider_performance(query).await,
+            None => Ok(
+                aether_data_contracts::repository::usage::StoredUsageProviderPerformance::default(),
+            ),
+        }
+    }
+
     pub(crate) async fn summarize_usage_cost_savings(
         &self,
         query: &aether_data_contracts::repository::usage::UsageCostSavingsSummaryQuery,

apps/aether-gateway/src/handlers/admin/observability/stats/analytics_routes.rs

@@ -1,4 +1,4 @@
-use super::range::build_comparison_range;
+use super::range::{build_comparison_range, parse_bounded_u32};
 use super::resolve_admin_usage_time_range;
 use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::query_param_value;
@@ -6,16 +6,18 @@ use crate::GatewayError;
 use aether_admin::observability::stats::{
     admin_stats_bad_request_response, admin_stats_comparison_empty_response,
     admin_stats_error_distribution_empty_response,
-    admin_stats_performance_percentiles_empty_response, admin_stats_time_series_empty_response,
+    admin_stats_performance_percentiles_empty_response,
+    admin_stats_provider_performance_empty_response, admin_stats_time_series_empty_response,
     build_admin_stats_comparison_response_from_aggregates,
     build_admin_stats_error_distribution_response_from_summaries,
     build_admin_stats_performance_percentiles_response_from_summaries,
+    build_admin_stats_provider_performance_response,
     build_admin_stats_time_series_response_from_summaries, AdminStatsAggregate,
     AdminStatsComparisonType, AdminStatsGranularity, AdminStatsTimeRange, AdminStatsUsageFilter,
 };
 use aether_data_contracts::repository::usage::{
     UsageAuditSummaryQuery, UsageErrorDistributionQuery, UsagePerformancePercentilesQuery,
-    UsageTimeSeriesGranularity, UsageTimeSeriesQuery,
+    UsageProviderPerformanceQuery, UsageTimeSeriesGranularity, UsageTimeSeriesQuery,
 };
 use axum::{body::Body, http, response::Response};
 
@@ -173,6 +175,56 @@ pub(super) async fn maybe_build_local_admin_stats_analytics_response(
         ));
     }
 
+    if request_context.route_kind() == Some("provider_performance")
+        && request_context.method() == http::Method::GET
+        && matches!(
+            request_context.path(),
+            "/api/admin/stats/performance/providers" | "/api/admin/stats/performance/providers/"
+        )
+    {
+        let time_range = match resolve_admin_usage_time_range(request_context.query_string()) {
+            Ok(value) => value,
+            Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
+        };
+        let granularity =
+            match query_param_value(request_context.query_string(), "granularity").as_deref() {
+                None | Some("day") => UsageTimeSeriesGranularity::Day,
+                Some("hour") => UsageTimeSeriesGranularity::Hour,
+                Some(_) => {
+                    return Ok(Some(admin_stats_bad_request_response(
+                        "granularity must be one of: day, hour".to_string(),
+                    )));
+                }
+            };
+        let limit = match query_param_value(request_context.query_string(), "limit")
+            .map(|value| parse_bounded_u32("limit", &value, 1, 20))
+            .transpose()
+        {
+            Ok(value) => value.unwrap_or(8) as usize,
+            Err(detail) => return Ok(Some(admin_stats_bad_request_response(detail))),
+        };
+        if !state.has_usage_data_reader() {
+            return Ok(Some(admin_stats_provider_performance_empty_response()));
+        }
+
+        let Some((created_from_unix_secs, created_until_unix_secs)) = time_range.to_unix_bounds()
+        else {
+            return Ok(Some(admin_stats_provider_performance_empty_response()));
+        };
+        let performance = state
+            .summarize_usage_provider_performance(&UsageProviderPerformanceQuery {
+                created_from_unix_secs,
+                created_until_unix_secs,
+                granularity,
+                tz_offset_minutes: time_range.tz_offset_minutes,
+                limit,
+            })
+            .await?;
+        return Ok(Some(build_admin_stats_provider_performance_response(
+            &performance,
+        )));
+    }
+
     if request_context.route_kind() == Some("time_series")
         && request_context.method() == http::Method::GET
         && matches!(

apps/aether-gateway/src/handlers/admin/request/observability.rs

@@ -168,6 +168,16 @@ impl<'a> AdminAppState<'a> {
             .await
     }
 
+    pub(crate) async fn summarize_usage_provider_performance(
+        &self,
+        query: &aether_data_contracts::repository::usage::UsageProviderPerformanceQuery,
+    ) -> Result<
+        aether_data_contracts::repository::usage::StoredUsageProviderPerformance,
+        GatewayError,
+    > {
+        self.app.summarize_usage_provider_performance(query).await
+    }
+
     pub(crate) async fn summarize_usage_cost_savings(
         &self,
         query: &aether_data_contracts::repository::usage::UsageCostSavingsSummaryQuery,

apps/aether-gateway/src/state/runtime/usage_queries.rs

@@ -251,6 +251,16 @@ impl AppState {
             .map_err(|err| GatewayError::Internal(err.to_string()))
     }
 
+    pub(crate) async fn summarize_usage_provider_performance(
+        &self,
+        query: &usage::UsageProviderPerformanceQuery,
+    ) -> Result<usage::StoredUsageProviderPerformance, GatewayError> {
+        self.data
+            .summarize_usage_provider_performance(query)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
     pub(crate) async fn summarize_usage_cost_savings(
         &self,
         query: &usage::UsageCostSavingsSummaryQuery,

apps/aether-gateway/src/tests/control/admin/stats.rs

@@ -853,6 +853,187 @@ async fn gateway_handles_admin_stats_performance_percentiles_locally_without_usa
     upstream_handle.abort();
 }
 
+#[tokio::test]
+async fn gateway_handles_admin_stats_provider_performance_locally_with_trusted_admin_principal() {
+    let (_upstream_url, upstream_hits, upstream_handle) =
+        start_stats_upstream("/api/admin/stats/performance/providers").await;
+
+    let mut usage = (1..=10)
+        .map(|index| {
+            let mut row = sample_usage_row(
+                &format!("usage-provider-perf-a-{index}"),
+                &format!("req-provider-perf-a-{index}"),
+                Some("user-1"),
+                Some("key-1"),
+                Some("primary"),
+                "OpenAI",
+                "gpt-5",
+                10,
+                10,
+                0.01,
+                0.01,
+                DAY_1_UNIX_SECS + i64::from(index),
+            );
+            row.response_time_ms = Some((index * 100) as u64);
+            row.first_byte_time_ms = Some((index * 10) as u64);
+            row
+        })
+        .collect::<Vec<_>>();
+    let mut failed = sample_usage_row(
+        "usage-provider-perf-failed",
+        "req-provider-perf-failed",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "OpenAI",
+        "gpt-5",
+        10,
+        99,
+        0.01,
+        0.01,
+        DAY_1_UNIX_SECS + 20,
+    );
+    failed.status = "failed".to_string();
+    failed.status_code = Some(500);
+    failed.error_message = Some("upstream failed".to_string());
+    usage.push(failed);
+
+    let mut provider_b = sample_usage_row(
+        "usage-provider-perf-b",
+        "req-provider-perf-b",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "Anthropic",
+        "claude-sonnet",
+        10,
+        20,
+        0.01,
+        0.01,
+        DAY_1_UNIX_SECS + 30,
+    );
+    provider_b.provider_id = Some("provider-2".to_string());
+    provider_b.response_time_ms = Some(1000);
+    provider_b.first_byte_time_ms = None;
+    usage.push(provider_b);
+
+    let mut unknown_provider = sample_usage_row(
+        "usage-provider-perf-unknown",
+        "req-provider-perf-unknown",
+        Some("user-1"),
+        Some("key-1"),
+        Some("primary"),
+        "unknown",
+        "gpt-5",
+        10,
+        999,
+        0.01,
+        0.01,
+        DAY_1_UNIX_SECS + 40,
+    );
+    unknown_provider.provider_id = None;
+    usage.push(unknown_provider);
+
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(usage));
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(GatewayDataState::with_usage_reader_for_tests(
+                usage_repository,
+            )),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(reqwest::Client::new().get(format!(
+        "{gateway_url}/api/admin/stats/performance/providers?start_date=2024-03-21&end_date=2024-03-21&granularity=hour&limit=2&tz_offset_minutes=0"
+    )))
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["summary"]["request_count"], 12);
+    assert_eq!(payload["summary"]["success_rate"], 91.67);
+    assert_eq!(payload["summary"]["avg_output_tps"], 18.46);
+    assert_eq!(payload["summary"]["avg_first_byte_time_ms"], 55.0);
+    assert_eq!(payload["summary"]["avg_response_time_ms"], 590.91);
+
+    assert_eq!(payload["providers"].as_array().map(Vec::len), Some(2));
+    assert_eq!(payload["providers"][0]["provider_id"], "provider-1");
+    assert_eq!(payload["providers"][0]["provider"], "OpenAI");
+    assert_eq!(payload["providers"][0]["request_count"], 11);
+    assert_eq!(payload["providers"][0]["success_count"], 10);
+    assert_eq!(payload["providers"][0]["error_count"], 1);
+    assert_eq!(payload["providers"][0]["success_rate"], 90.91);
+    assert_eq!(payload["providers"][0]["output_tokens"], 199);
+    assert_eq!(payload["providers"][0]["avg_output_tps"], 18.18);
+    assert_eq!(payload["providers"][0]["avg_first_byte_time_ms"], 55.0);
+    assert_eq!(payload["providers"][0]["avg_response_time_ms"], 550.0);
+    assert_eq!(payload["providers"][0]["p90_response_time_ms"], 910);
+    assert_eq!(payload["providers"][0]["p90_first_byte_time_ms"], 91);
+    assert_eq!(payload["providers"][0]["tps_sample_count"], 10);
+    assert_eq!(payload["providers"][0]["first_byte_sample_count"], 10);
+
+    assert_eq!(payload["providers"][1]["provider_id"], "provider-2");
+    assert_eq!(payload["providers"][1]["provider"], "Anthropic");
+    assert_eq!(payload["providers"][1]["avg_output_tps"], 20.0);
+    assert_eq!(
+        payload["providers"][1]["avg_first_byte_time_ms"],
+        serde_json::Value::Null
+    );
+    assert_eq!(
+        payload["providers"][1]["p90_response_time_ms"],
+        serde_json::Value::Null
+    );
+
+    assert_eq!(payload["timeline"].as_array().map(Vec::len), Some(2));
+    assert_eq!(payload["timeline"][0]["date"], "2024-03-21T05:00:00+00:00");
+    assert_eq!(payload["timeline"][0]["provider_id"], "provider-1");
+    assert_eq!(payload["timeline"][0]["avg_output_tps"], 18.18);
+    assert_eq!(payload["timeline"][0]["success_rate"], 90.91);
+    assert_eq!(payload["timeline"][1]["provider_id"], "provider-2");
+    assert_eq!(
+        payload["timeline"][1]["avg_first_byte_time_ms"],
+        serde_json::Value::Null
+    );
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
+#[tokio::test]
+async fn gateway_returns_empty_admin_stats_provider_performance_without_usage_reader() {
+    let (_upstream_url, upstream_hits, upstream_handle) =
+        start_stats_upstream("/api/admin/stats/performance/providers").await;
+
+    let gateway = build_router_with_state(AppState::new().expect("gateway should build"));
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(reqwest::Client::new().get(format!(
+        "{gateway_url}/api/admin/stats/performance/providers?start_date=2024-03-21&end_date=2024-03-21&limit=2"
+    )))
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["summary"]["request_count"], 0);
+    assert_eq!(payload["summary"]["success_rate"], 0.0);
+    assert_eq!(
+        payload["summary"]["avg_output_tps"],
+        serde_json::Value::Null
+    );
+    assert_eq!(payload["providers"].as_array().map(Vec::len), Some(0));
+    assert_eq!(payload["timeline"].as_array().map(Vec::len), Some(0));
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_stats_time_series_locally_with_trusted_admin_principal() {
     let (upstream_url, upstream_hits, upstream_handle) =