photoncloud-monorepo/nightlight/crates/nightlight-api/proto/admin.proto

// Nightlight Admin API
//
// Provides health checks, statistics, and administrative operations.

syntax = "proto3";

package nightlight;

// Admin service provides operational and monitoring endpoints.
service Admin {
  // Health check endpoint
  rpc Health(HealthRequest) returns (HealthResponse);

  // Get storage and query statistics
  rpc Stats(StatsRequest) returns (StatsResponse);

  // Get build information
  rpc BuildInfo(BuildInfoRequest) returns (BuildInfoResponse);
}

// HealthRequest is empty (health check has no parameters).
message HealthRequest {}

// HealthResponse indicates server health status.
message HealthResponse {
  // Status: "ok", "degraded", "error"
  string status = 1;

  // Human-readable status message
  string message = 2;

  // Component-level health checks
  repeated ComponentHealth components = 3;
}

// ComponentHealth represents the health of a single component.
message ComponentHealth {
  // Component name (e.g., "storage", "query_engine", "ingestion")
  string name = 1;

  // Status: "ok", "degraded", "error"
  string status = 2;

  // Optional details or error message
  string message = 3;
}

// StatsRequest is empty (stats have no parameters).
message StatsRequest {}

// StatsResponse provides storage and operational statistics.
message StatsResponse {
  // Storage statistics
  StorageStats storage = 1;

  // Ingestion statistics
  IngestionStats ingestion = 2;

  // Query statistics
  QueryStats query = 3;

  // Server uptime in seconds
  uint64 uptime_seconds = 4;
}

// StorageStats provides time-series database statistics.
message StorageStats {
  // Number of active time series (in-memory head)
  uint64 active_series = 1;

  // Total number of samples stored
  uint64 total_samples = 2;

  // Number of storage blocks (on-disk chunks)
  uint64 blocks_count = 3;

  // Number of samples in the head block (in-memory)
  uint64 head_samples = 4;

  // Total disk space used (bytes)
  uint64 disk_bytes_used = 5;

  // Oldest sample timestamp (milliseconds since epoch)
  int64 oldest_sample_time = 6;

  // Newest sample timestamp (milliseconds since epoch)
  int64 newest_sample_time = 7;
}

// IngestionStats provides write/ingestion statistics.
message IngestionStats {
  // Total samples ingested since server start
  uint64 samples_ingested_total = 1;

  // Total write requests received
  uint64 write_requests_total = 2;

  // Failed write requests
  uint64 write_requests_failed = 3;

  // Current samples per second (recent average)
  double samples_per_second = 4;

  // Samples currently in the write buffer
  uint64 buffer_samples = 5;
}

// QueryStats provides query execution statistics.
message QueryStats {
  // Total queries executed since server start
  uint64 queries_total = 1;

  // Failed queries
  uint64 queries_failed = 2;

  // Active queries (currently executing)
  uint64 queries_active = 3;

  // Query duration p50 (milliseconds)
  double query_duration_p50 = 4;

  // Query duration p95 (milliseconds)
  double query_duration_p95 = 5;

  // Query duration p99 (milliseconds)
  double query_duration_p99 = 6;
}

// BuildInfoRequest is empty (build info has no parameters).
message BuildInfoRequest {}

// BuildInfoResponse provides server build and version information.
message BuildInfoResponse {
  // Server version (e.g., "0.1.0")
  string version = 1;

  // Git commit hash
  string commit = 2;

  // Build timestamp (ISO 8601 format)
  string build_time = 3;

  // Rust compiler version
  string rust_version = 4;

  // Target platform (e.g., "x86_64-unknown-linux-gnu")
  string target = 5;
}