Extend tracing proto: GetTraceSummary, GetTraceSpanTotals, SpanFilter extensions

[rowan-stein]

Summary

Extend tracing/v1/tracing.proto with two new RPCs and filter extensions to support the tracing-app wiring. Update gateway/v1/tracing.proto to proxy the new RPCs.

User Request

The tracing-app needs server-side aggregation (summary + filtered totals with token usage) and multi-value filtering on ListSpans. These cannot be computed client-side due to pagination.

Specification

Files to modify

• proto/agynio/api/tracing/v1/tracing.proto
• proto/agynio/api/gateway/v1/tracing.proto

1. New enums

Add to tracing/v1/tracing.proto:

// Derived status for a span, computed from OTel status_code + end_time.
enum SpanStatus {
  SPAN_STATUS_UNSPECIFIED = 0;
  SPAN_STATUS_RUNNING = 1;     // end_time = 0, status_code != ERROR
  SPAN_STATUS_OK = 2;          // end_time > 0, status_code != ERROR
  SPAN_STATUS_ERROR = 3;       // status_code = ERROR (regardless of end_time)
}

// Trace-level status derived from constituent span statuses.
enum TraceStatus {
  TRACE_STATUS_UNSPECIFIED = 0;
  TRACE_STATUS_RUNNING = 1;    // At least one span is RUNNING
  TRACE_STATUS_COMPLETED = 2;  // All spans ended, none with ERROR
  TRACE_STATUS_ERROR = 3;      // All spans ended, at least one ERROR
}

2. New messages

// ---------- GetTraceSummary ----------

message GetTraceSummaryRequest {
  bytes trace_id = 1; // 16 bytes, required
}

message GetTraceSummaryResponse {
  bytes trace_id = 1;
  TraceStatus status = 2;
  fixed64 first_span_start_time = 3;  // earliest start_time_unix_nano
  fixed64 last_span_start_time = 4;   // latest start_time_unix_nano
  fixed64 last_span_end_time = 5;     // latest end_time_unix_nano (0 if none completed)
  map<string, int64> counts_by_name = 6;   // key = span name, value = count
  map<string, int64> counts_by_status = 7; // key = SpanStatus enum name, value = count
  int64 total_spans = 8;
}

// ---------- GetTraceSpanTotals ----------

message GetTraceSpanTotalsRequest {
  bytes trace_id = 1; // 16 bytes, required
  repeated string names = 2;           // span names to include (empty = all)
  repeated SpanStatus statuses = 3;    // derived statuses to include (empty = all)
}

message GetTraceSpanTotalsResponse {
  int64 span_count = 1;
  TokenUsageTotals token_usage = 2;
}

message TokenUsageTotals {
  int64 input_tokens = 1;
  int64 output_tokens = 2;
  int64 cache_read_input_tokens = 3;
  int64 reasoning_tokens = 4;
  int64 total_tokens = 5; // server-computed: input + output
}

3. SpanFilter extensions

Add two new fields to the existing SpanFilter message:

message SpanFilter {
  // ... existing fields 1-7 unchanged ...
  repeated string names = 8;             // multiple span names, OR-combined
  repeated SpanStatus statuses = 9;      // derived statuses, OR-combined
}

Semantics:

• names takes precedence over name if both are set.
• statuses takes precedence over in_progress if both are set.
• All filter fields remain AND-combined. Within names and statuses, values are OR-combined.

4. New RPCs on TracingService

Add to the existing TracingService:

rpc GetTraceSummary(GetTraceSummaryRequest) returns (GetTraceSummaryResponse);
rpc GetTraceSpanTotals(GetTraceSpanTotalsRequest) returns (GetTraceSpanTotalsResponse);

5. Gateway proxy additions

Add to the existing TracingGateway in gateway/v1/tracing.proto:

rpc GetTraceSummary(agynio.api.tracing.v1.GetTraceSummaryRequest) returns (agynio.api.tracing.v1.GetTraceSummaryResponse);
rpc GetTraceSpanTotals(agynio.api.tracing.v1.GetTraceSpanTotalsRequest) returns (agynio.api.tracing.v1.GetTraceSpanTotalsResponse);

6. Validation

• buf lint
• buf build
• buf breaking --against '.git#branch=main' (these are additive changes — should pass)