tlbmc/edge_filtering.proto

edition = "2023";

package milotic_hft;

// EdgeFilter describes a per-identifier edge-side operation that
// the HFT server applies to that identifier's sample stream.
// If the server does not recognize the configured
// variant, the subscription is rejected.
message EdgeFilter {
  oneof filter {
    OnChangeFilter on_change = 1;
    SdtFilter sdt = 2;
  }
}

// OnChangeFilter emits a sample only when its value differs from the most
// recently emitted sample beyond a threshold, with an optional heartbeat
// to assert liveness when the value is steady.
message OnChangeFilter {
  // Absolute delta threshold: a sample passes the filter when
  // |current - last_emitted| > float_epsilon. 0 means emit on any change.
  // For uint64 `count` readings the threshold is float_epsilon rounded to the
  // nearest whole count.
  float float_epsilon = 1;

  // Maximum interval between emissions for this identifier when the
  // value is unchanged. 0 disables the heartbeat. Effective resolution
  // is rounded up to a multiple of export_interval_ms.
  //
  // The same cadence also re-asserts an unchanged non-OK status
  // (STALE/MISSING): with a heartbeat configured, a persistent stall
  // marker is re-emitted once per heartbeat interval instead of only
  // once on the status transition.
  int32 heartbeat_interval_ms = 2;
}

// SdtFilter (Swinging Door Trending) compresses a time-series stream by
// discarding points that fall within a corridor around the line connecting
// the last emitted point to the current point.  Not yet implemented.
message SdtFilter {
  // Half-width of the compression corridor.  A sample is emitted when it
  // deviates from the interpolated line by more than this value.
  float compression_deviation = 1;

  // Maximum interval between emissions when the signal stays within the
  // corridor. 0 disables the heartbeat. Effective resolution is rounded
  // up to a multiple of export_interval_ms (same semantics as
  // OnChangeFilter.heartbeat_interval_ms).
  int32 heartbeat_interval_ms = 2;

  // When true, the point immediately preceding a new hinge (the last
  // point that was still inside the corridor) is emitted alongside the
  // hinge point itself, preserving the shape of the original signal at
  // transitions.  When false, only the hinge point is emitted.
  bool emit_preceding_point = 3;
}