// SPDX-License-Identifier: Apache-2.0
// Performance metrics and usage (decision L-81, docs/control-plane/METRICS.md): the same
// operations as REST /v1/metrics/* and /v1/usage.
syntax = "proto3";

package kyvernon.v1;

import "kyvernon/v1/common.proto";

// Performance counters, samples and the usage ledger.
service MetricsService {
  // The counter catalogue.
  rpc ListCounters(Empty) returns (ListCountersResponse);
  // Counters and instances with data for an entity at an interval.
  rpc ListAvailableMetrics(ListAvailableMetricsRequest) returns (ListAvailableMetricsResponse);
  // Samples by entity, counter, interval and time range.
  rpc QueryMetrics(QueryMetricsRequest) returns (QueryMetricsResponse);
  // The usage ledger (needs Kyvernon.Usage.Read on the root).
  rpc QueryUsage(QueryUsageRequest) returns (QueryUsageResponse);
}

// A performance counter of the catalogue.
message PerfCounter {
  // Stable id (vCenter's where one exists; 900000 and up otherwise).
  int32 id = 1;
  // group.name.rollup
  string name = 2;
  // Counter group (`cpu`, `mem`, `net`, ...).
  string group = 3;
  // Short name to show.
  string label = 4;
  // What the counter measures.
  string summary = 5;
  // How samples are combined over time (`average`, `maximum`, ...).
  string rollup = 6;
  // Unit of the values.
  string unit = 7;
  // Kind of statistic (`absolute`, `delta`, `rate`).
  string stats_type = 8;
  // Collection level of the aggregate.
  uint32 level = 9;
  // Collection level of the per-device instances.
  uint32 per_device_level = 10;
  // Name of the Prometheus metric with the same values.
  string metric = 11;
  // The counter has per-instance values only, no aggregate.
  bool instances_only = 12;
}

// The counter catalogue.
message ListCountersResponse {
  // Every counter.
  repeated PerfCounter counters = 1;
}

// Asks which counters have data for an object.
message ListAvailableMetricsRequest {
  // Id of the object.
  string entity = 1;
  // 0 = 20 for hosts and VMs, 300 for datastores.
  uint32 interval = 2;
}

// A counter with data for the object.
message AvailableMetric {
  // Id of the counter.
  int32 counter_id = 1;
  // Name of the counter.
  string counter = 2;
  // Instance (device); empty for the aggregate.
  string instance = 3;
}

// Counters with data.
message ListAvailableMetricsResponse {
  // Sampling period in seconds the list is for.
  uint32 interval = 1;
  // Counters and instances with data.
  repeated AvailableMetric metrics = 2;
}

// Queries samples.
message QueryMetricsRequest {
  // Ids of the objects.
  repeated string entities = 1;
  // Counter names or ids.
  repeated string counters = 2;
  // 0 = default (20 for hosts and VMs, 300 for datastores).
  uint32 interval = 3;
  // RFC 3339; empty = as far back as kept / now.
  string start = 4;
  // RFC 3339; empty = now.
  string end = 5;
  // "" aggregate, "*" all instances and the aggregate, or one instance.
  string instance = 6;
  // 0 = no limit.
  uint32 max_samples = 7;
}

// Samples of one counter and instance of one object.
message MetricSeries {
  // Id of the object.
  string entity = 1;
  // Id of the counter.
  int32 counter_id = 2;
  // Name of the counter.
  string counter = 3;
  // Instance; empty for the aggregate.
  string instance = 4;
  // Unit of the values.
  string unit = 5;
  // Sampling period in seconds.
  uint32 interval = 6;
  // Interval end times (Unix seconds) and values; percent values are 0..100.
  repeated int64 timestamps = 7;
  // Values in the order of `timestamps`.
  repeated double values = 8;
}

// The samples.
message QueryMetricsResponse {
  // One series per object, counter and instance.
  repeated MetricSeries series = 1;
}

// Queries the usage ledger.
message QueryUsageRequest {
  // YYYY-MM-DD, inclusive.
  string from = 1;
  // YYYY-MM-DD, inclusive.
  string to = 2;
  // vm (default), tenant, resourcePool, folder, host.
  string group_by = 3;
  // day (default), month, total.
  string period = 4;
}

// Usage of one group in one period.
message UsageLine {
  // The day, month or total the line covers.
  string period = 1;
  // Id of the group (virtual machine, tenant, resource group, folder or host).
  string key = 2;
  // Name of the group.
  string name = 3;
  // Virtual machines counted.
  uint32 vms = 4;
  // Hours powered on.
  double powered_on_hours = 5;
  // vCPU hours.
  double vcpu_hours = 6;
  // Memory in GiB hours.
  double ram_gib_hours = 7;
  // Provisioned disk in GiB hours.
  double provisioned_gib_hours = 8;
  // Used disk in GiB hours.
  double used_gib_hours = 9;
  // Received network traffic in GiB.
  double net_rx_gib = 10;
  // Sent network traffic in GiB.
  double net_tx_gib = 11;
  // Received network traffic in bytes.
  uint64 net_rx_bytes = 12;
  // Sent network traffic in bytes.
  uint64 net_tx_bytes = 13;
}

// Usage lines.
message QueryUsageResponse {
  // One line per group and period.
  repeated UsageLine lines = 1;
}