Skip to content

Commit a7166ea

Browse files
akila-iakila-i
authored
feat: add runtime topology endpoint to metrics adapter API spec (#606)
* feat: add runtime topology endpoint to metrics adapter API spec Signed-off-by: Akila-I <akila.99g@gmail.com> * feat: enhance runtime topology schemas with additional node references and properties Signed-off-by: Akila-I <akila.99g@gmail.com> * refactor: remove unused 'step' parameter from runtime topology Signed-off-by: Akila-I <akila.99g@gmail.com> * refactor: rename metrics fields for clarity in runtime topology response Signed-off-by: Akila-I <akila.99g@gmail.com> * feat: enhance runtime topology schemas with additional component and project fields Signed-off-by: Akila-I <akila.99g@gmail.com> --------- Signed-off-by: Akila-I <akila.99g@gmail.com>
1 parent c0bec3d commit a7166ea

1 file changed

Lines changed: 327 additions & 0 deletions

File tree

‎static/api-specs/observability-metrics-adapter.yaml‎

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,58 @@ paths:
102102
schema:
103103
$ref: "#/components/schemas/ErrorResponse"
104104

105+
# Runtime topology endpoint (for cell diagram with runtime observability)
106+
/api/v1alpha1/metrics/runtime-topology:
107+
post:
108+
tags:
109+
- Metrics
110+
summary: Query runtime topology
111+
description: |
112+
Returns the live HTTP traffic topology for a project in a given environment:
113+
a list of nodes (components, gateways, external endpoints) and a list of edges
114+
(observed source -> target traffic flows), each with aggregated metrics
115+
(request count, error count, latency percentiles) computed over the requested
116+
time window. Identifiers are returned as OpenChoreo UIDs — the caller is
117+
expected to map UIDs back to human-readable names.
118+
operationId: queryRuntimeTopology
119+
requestBody:
120+
required: true
121+
content:
122+
application/json:
123+
schema:
124+
$ref: "#/components/schemas/RuntimeTopologyRequest"
125+
responses:
126+
"200":
127+
description: Runtime topology queried successfully
128+
content:
129+
application/json:
130+
schema:
131+
$ref: "#/components/schemas/RuntimeTopologyResponse"
132+
"400":
133+
description: Invalid request
134+
content:
135+
application/json:
136+
schema:
137+
$ref: "#/components/schemas/ErrorResponse"
138+
"401":
139+
description: Unauthorized
140+
content:
141+
application/json:
142+
schema:
143+
$ref: "#/components/schemas/ErrorResponse"
144+
"403":
145+
description: Forbidden
146+
content:
147+
application/json:
148+
schema:
149+
$ref: "#/components/schemas/ErrorResponse"
150+
"500":
151+
description: Internal Server Error
152+
content:
153+
application/json:
154+
schema:
155+
$ref: "#/components/schemas/ErrorResponse"
156+
105157
/api/v1alpha1/alerts/rules:
106158
post:
107159
tags:
@@ -415,6 +467,281 @@ components:
415467
- $ref: "#/components/schemas/ResourceMetricsTimeSeries"
416468
- $ref: "#/components/schemas/HttpMetricsTimeSeries"
417469

470+
# Runtime topology schemas
471+
RuntimeTopologyRequest:
472+
type: object
473+
description: |
474+
Request body for POST /api/v1alpha1/metrics/runtime-topology.
475+
searchScope must include namespace, projectUid, and environmentUid —
476+
runtime topology is project- and environment-scoped. The optional
477+
componentUid, if set, restricts results to edges that touch that
478+
component.
479+
properties:
480+
searchScope:
481+
$ref: "#/components/schemas/ComponentSearchScope"
482+
startTime:
483+
type: string
484+
description: The start time of the query window
485+
format: date-time
486+
endTime:
487+
type: string
488+
description: The end time of the query window
489+
format: date-time
490+
includeGateways:
491+
type: boolean
492+
description: |
493+
Whether to include gateway -> component edges. Defaults to true.
494+
default: true
495+
includeExternal:
496+
type: boolean
497+
description: |
498+
Whether to include edges to/from components outside the requested
499+
project. Defaults to true.
500+
default: true
501+
required: [searchScope, startTime, endTime]
502+
503+
RuntimeTopologyMetrics:
504+
type: object
505+
description: |
506+
Aggregate HTTP metrics over the requested window. Latency values are
507+
in seconds, matching /api/v1/metrics/query.
508+
properties:
509+
requestCount:
510+
type: number
511+
format: double
512+
unsuccessfulRequestCount:
513+
type: number
514+
format: double
515+
meanLatency:
516+
type: number
517+
format: double
518+
latencyP50:
519+
type: number
520+
format: double
521+
latencyP90:
522+
type: number
523+
format: double
524+
latencyP99:
525+
type: number
526+
format: double
527+
528+
RuntimeTopologyNodeRef:
529+
oneOf:
530+
- $ref: "#/components/schemas/RuntimeTopologyNodeRefComponent"
531+
- $ref: "#/components/schemas/RuntimeTopologyNodeRefGateway"
532+
- $ref: "#/components/schemas/RuntimeTopologyNodeRefExternal"
533+
discriminator:
534+
propertyName: kind
535+
mapping:
536+
component: "#/components/schemas/RuntimeTopologyNodeRefComponent"
537+
gateway: "#/components/schemas/RuntimeTopologyNodeRefGateway"
538+
external: "#/components/schemas/RuntimeTopologyNodeRefExternal"
539+
540+
RuntimeTopologyNodeRefComponent:
541+
type: object
542+
description: |
543+
Reference to a component node in the runtime topology.
544+
properties:
545+
kind:
546+
type: string
547+
enum: [component]
548+
component:
549+
type: string
550+
description: The component name (from pod label).
551+
componentUid:
552+
type: string
553+
description: The component UID (from pod label).
554+
project:
555+
type: string
556+
description: The project name (from pod label).
557+
projectUid:
558+
type: string
559+
description: The project UID.
560+
namespace:
561+
type: string
562+
description: The namespace name (from pod label).
563+
required: [kind, component, componentUid]
564+
565+
RuntimeTopologyNodeRefGateway:
566+
type: object
567+
description: |
568+
Reference to a gateway node in the runtime topology.
569+
properties:
570+
kind:
571+
type: string
572+
enum: [gateway]
573+
gatewayName:
574+
type: string
575+
description: Gateway name (e.g., internet, intranet)
576+
projectUid:
577+
type: string
578+
format: uuid
579+
namespace:
580+
type: string
581+
required: [kind, gatewayName]
582+
583+
RuntimeTopologyNodeRefExternal:
584+
type: object
585+
description: |
586+
Reference to an external node in the runtime topology.
587+
properties:
588+
kind:
589+
type: string
590+
enum: [external]
591+
externalHost:
592+
type: string
593+
component:
594+
type: string
595+
componentUid:
596+
type: string
597+
format: uuid
598+
projectUid:
599+
type: string
600+
format: uuid
601+
description: Included when the source is in a different project
602+
namespace:
603+
type: string
604+
required: [kind]
605+
606+
RuntimeTopologyNode:
607+
oneOf:
608+
- $ref: "#/components/schemas/RuntimeTopologyNodeComponent"
609+
- $ref: "#/components/schemas/RuntimeTopologyNodeGateway"
610+
- $ref: "#/components/schemas/RuntimeTopologyNodeExternal"
611+
discriminator:
612+
propertyName: kind
613+
mapping:
614+
component: "#/components/schemas/RuntimeTopologyNodeComponent"
615+
gateway: "#/components/schemas/RuntimeTopologyNodeGateway"
616+
external: "#/components/schemas/RuntimeTopologyNodeExternal"
617+
618+
RuntimeTopologyNodeComponent:
619+
type: object
620+
description: |
621+
A component node observed in the runtime topology with its aggregated metrics.
622+
properties:
623+
kind:
624+
type: string
625+
enum: [component]
626+
component:
627+
type: string
628+
description: The component name (from pod label).
629+
componentUid:
630+
type: string
631+
description: The component UID (from pod label).
632+
format: uuid
633+
project:
634+
type: string
635+
description: The project name (from pod label).
636+
projectUid:
637+
type: string
638+
description: The project UID.
639+
format: uuid
640+
namespace:
641+
type: string
642+
metrics:
643+
$ref: "#/components/schemas/RuntimeTopologyMetrics"
644+
required: [kind, component, componentUid]
645+
646+
RuntimeTopologyNodeGateway:
647+
type: object
648+
description: |
649+
A gateway node observed in the runtime topology with its aggregated metrics.
650+
properties:
651+
kind:
652+
type: string
653+
enum: [gateway]
654+
gatewayName:
655+
type: string
656+
projectUid:
657+
type: string
658+
format: uuid
659+
namespace:
660+
type: string
661+
metrics:
662+
$ref: "#/components/schemas/RuntimeTopologyMetrics"
663+
required: [kind, gatewayName]
664+
665+
RuntimeTopologyNodeExternal:
666+
type: object
667+
description: |
668+
An external node observed in the runtime topology with its aggregated metrics.
669+
properties:
670+
kind:
671+
type: string
672+
enum: [external]
673+
externalHost:
674+
type: string
675+
component:
676+
type: string
677+
componentUid:
678+
type: string
679+
format: uuid
680+
projectUid:
681+
type: string
682+
format: uuid
683+
namespace:
684+
type: string
685+
metrics:
686+
$ref: "#/components/schemas/RuntimeTopologyMetrics"
687+
required: [kind]
688+
689+
RuntimeTopologyEdge:
690+
type: object
691+
description: An observed traffic flow from a source node to a target node.
692+
properties:
693+
id:
694+
type: string
695+
description: |
696+
Stable identifier for the edge. Convention:
697+
- component->component: `${srcComponentUid}->${dstComponentUid}`
698+
- gateway->component: `gateway:${gatewayName}->${dstComponentUid}`
699+
- component->external: `${srcComponentUid}->external:${externalHost}`
700+
source:
701+
$ref: "#/components/schemas/RuntimeTopologyNodeRef"
702+
target:
703+
$ref: "#/components/schemas/RuntimeTopologyNodeRef"
704+
protocol:
705+
type: string
706+
enum: [http]
707+
metrics:
708+
$ref: "#/components/schemas/RuntimeTopologyMetrics"
709+
required: [id, source, target, protocol]
710+
711+
RuntimeTopologySummary:
712+
type: object
713+
description: Metadata describing the query window.
714+
properties:
715+
startTime:
716+
type: string
717+
format: date-time
718+
endTime:
719+
type: string
720+
format: date-time
721+
generatedAt:
722+
type: string
723+
format: date-time
724+
required: [startTime, endTime, generatedAt]
725+
726+
RuntimeTopologyResponse:
727+
type: object
728+
description: |
729+
Runtime topology response. Nodes and edges only include entities for
730+
which traffic was observed in the window — static topology comes from
731+
a separate source.
732+
properties:
733+
nodes:
734+
type: array
735+
items:
736+
$ref: "#/components/schemas/RuntimeTopologyNode"
737+
edges:
738+
type: array
739+
items:
740+
$ref: "#/components/schemas/RuntimeTopologyEdge"
741+
summary:
742+
$ref: "#/components/schemas/RuntimeTopologySummary"
743+
required: [summary]
744+
418745
# Request schemas for alert rules
419746
AlertRuleRequest:
420747
type: object

0 commit comments

Comments
 (0)