From b1bd9cdc0be98aa1b7a3b9ff61c49899a9efee3e Mon Sep 17 00:00:00 2001 From: Sai Soundararaj Date: Tue, 1 Jul 2025 17:36:28 -0700 Subject: [PATCH] a --- api_update_plan.md | 4 +- docs/_static/llama-stack-spec.html | 314 ++++++++++++++++-------- docs/_static/llama-stack-spec.yaml | 186 +++++++++++++- llama_stack/apis/inspect/inspect.py | 28 ++- llama_stack/apis/telemetry/telemetry.py | 163 ++++++++++++ 5 files changed, 574 insertions(+), 121 deletions(-) diff --git a/api_update_plan.md b/api_update_plan.md index cef3c470d..a0dd7b95a 100644 --- a/api_update_plan.md +++ b/api_update_plan.md @@ -239,8 +239,8 @@ Before finalizing documentation, verify: [x] 18. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/batch_inference/batch_inference.py` - Batch inference operations [x] 19. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/synthetic_data_generation/synthetic_data_generation.py` - Data generation [x] 20. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/providers/providers.py` - Provider management -21. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/inspect/inspect.py` - System inspection -22. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/telemetry/telemetry.py` - Telemetry and monitoring +[x] 21. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/inspect/inspect.py` - System inspection +[x] 22. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/telemetry/telemetry.py` - Telemetry and monitoring **Step 1: Existing Documentation Assessment** - **Priority**: Review all @json_schema_type classes and @webmethod functions for docstring completeness diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 7f1610ff4..6419d369a 100644 --- a/docs/_static/llama-stack-spec.html +++ b/docs/_static/llama-stack-spec.html @@ -1922,7 +1922,7 @@ "get": { "responses": { "200": { - "description": "A HealthInfo.", + "description": "Health information indicating if the service is operational.", "content": { "application/json": { "schema": { @@ -1947,7 +1947,7 @@ "tags": [ "Inspect" ], - "description": "Get the health of the service.", + "description": "Get the current health status of the service.", "parameters": [] } }, @@ -2839,7 +2839,7 @@ "get": { "responses": { "200": { - "description": "A ListRoutesResponse.", + "description": "Response containing information about all available routes.", "content": { "application/json": { "schema": { @@ -2864,7 +2864,7 @@ "tags": [ "Inspect" ], - "description": "List all routes.", + "description": "List all available API routes with their methods and implementing providers.", "parameters": [] } }, @@ -4955,7 +4955,7 @@ "get": { "responses": { "200": { - "description": "A VersionInfo.", + "description": "Version information containing the service version number.", "content": { "application/json": { "schema": { @@ -5840,7 +5840,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "completion_message": { "$ref": "#/components/schemas/CompletionMessage", @@ -5865,7 +5866,8 @@ "type": "object", "properties": { "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric" }, "value": { "oneOf": [ @@ -5875,10 +5877,12 @@ { "type": "number" } - ] + ], + "description": "The numeric value of the metric" }, "unit": { - "type": "string" + "type": "string", + "description": "(Optional) The unit of measurement for the metric value" } }, "additionalProperties": false, @@ -5886,7 +5890,8 @@ "metric", "value" ], - "title": "MetricInResponse" + "title": "MetricInResponse", + "description": "A metric value included in API responses." }, "TokenLogProbs": { "type": "object", @@ -5973,7 +5978,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "content": { "type": "string", @@ -6141,7 +6147,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "event": { "$ref": "#/components/schemas/ChatCompletionResponseEvent", @@ -6302,7 +6309,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "delta": { "type": "string", @@ -10932,24 +10940,30 @@ "type": "object", "properties": { "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span" }, "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this span belongs to" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the operation began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the operation finished, if completed" }, "attributes": { "type": "object", @@ -10974,7 +10988,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the span" } }, "additionalProperties": false, @@ -10984,7 +10999,8 @@ "name", "start_time" ], - "title": "Span" + "title": "Span", + "description": "A span representing a single operation within a trace." }, "GetSpanTreeRequest": { "type": "object", @@ -11010,30 +11026,37 @@ "ok", "error" ], - "title": "SpanStatus" + "title": "SpanStatus", + "description": "The status of a span indicating whether it completed successfully or with an error." }, "SpanWithStatus": { "type": "object", "properties": { "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span" }, "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this span belongs to" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the operation began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the operation finished, if completed" }, "attributes": { "type": "object", @@ -11058,10 +11081,12 @@ "type": "object" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the span" }, "status": { - "$ref": "#/components/schemas/SpanStatus" + "$ref": "#/components/schemas/SpanStatus", + "description": "(Optional) The current status of the span" } }, "additionalProperties": false, @@ -11071,7 +11096,8 @@ "name", "start_time" ], - "title": "SpanWithStatus" + "title": "SpanWithStatus", + "description": "A span that includes status information." }, "QuerySpanTreeResponse": { "type": "object", @@ -11080,14 +11106,16 @@ "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SpanWithStatus" - } + }, + "description": "Dictionary mapping span IDs to spans with status information" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QuerySpanTreeResponse" + "title": "QuerySpanTreeResponse", + "description": "Response containing a tree structure of spans." }, "Tool": { "type": "object", @@ -11243,18 +11271,22 @@ "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace" }, "root_span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the root span that started this trace" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the trace began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the trace finished, if completed" } }, "additionalProperties": false, @@ -11263,7 +11295,8 @@ "root_span_id", "start_time" ], - "title": "Trace" + "title": "Trace", + "description": "A trace representing the complete execution path of a request across multiple operations." }, "Checkpoint": { "description": "Checkpoint created during training runs", @@ -11452,14 +11485,15 @@ "Error", "Not Implemented" ], - "title": "HealthStatus" + "description": "Current health status of the service" } }, "additionalProperties": false, "required": [ "status" ], - "title": "HealthInfo" + "title": "HealthInfo", + "description": "Health status information for the service." }, "RAGDocument": { "type": "object", @@ -12221,16 +12255,19 @@ "type": "object", "properties": { "route": { - "type": "string" + "type": "string", + "description": "The API endpoint path" }, "method": { - "type": "string" + "type": "string", + "description": "HTTP method for the route" }, "provider_types": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of provider types that implement this route" } }, "additionalProperties": false, @@ -12239,7 +12276,8 @@ "method", "provider_types" ], - "title": "RouteInfo" + "title": "RouteInfo", + "description": "Information about an API route including its path, method, and implementing providers." }, "ListRoutesResponse": { "type": "object", @@ -12248,14 +12286,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/RouteInfo" - } + }, + "description": "List of available route information objects" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListRoutesResponse" + "title": "ListRoutesResponse", + "description": "Response containing a list of all available API routes." }, "ListToolDefsResponse": { "type": "object", @@ -12389,7 +12429,8 @@ "structured_log", "metric" ], - "title": "EventType" + "title": "EventType", + "description": "The type of telemetry event being logged." }, "LogSeverity": { "type": "string", @@ -12401,20 +12442,24 @@ "error", "critical" ], - "title": "LogSeverity" + "title": "LogSeverity", + "description": "The severity level of a log message." }, "MetricEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12436,15 +12481,18 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "metric", - "default": "metric" + "default": "metric", + "description": "Event type identifier set to METRIC" }, "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric being measured" }, "value": { "oneOf": [ @@ -12454,10 +12502,12 @@ { "type": "number" } - ] + ], + "description": "The numeric value of the metric measurement" }, "unit": { - "type": "string" + "type": "string", + "description": "The unit of measurement for the metric value" } }, "additionalProperties": false, @@ -12470,7 +12520,8 @@ "value", "unit" ], - "title": "MetricEvent" + "title": "MetricEvent", + "description": "A metric event containing a measured value." }, "SpanEndPayload": { "type": "object", @@ -12478,10 +12529,12 @@ "type": { "$ref": "#/components/schemas/StructuredLogType", "const": "span_end", - "default": "span_end" + "default": "span_end", + "description": "Payload type identifier set to SPAN_END" }, "status": { - "$ref": "#/components/schemas/SpanStatus" + "$ref": "#/components/schemas/SpanStatus", + "description": "The final status of the span indicating success or failure" } }, "additionalProperties": false, @@ -12489,7 +12542,8 @@ "type", "status" ], - "title": "SpanEndPayload" + "title": "SpanEndPayload", + "description": "Payload for a span end event." }, "SpanStartPayload": { "type": "object", @@ -12497,13 +12551,16 @@ "type": { "$ref": "#/components/schemas/StructuredLogType", "const": "span_start", - "default": "span_start" + "default": "span_start", + "description": "Payload type identifier set to SPAN_START" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" } }, "additionalProperties": false, @@ -12511,20 +12568,24 @@ "type", "name" ], - "title": "SpanStartPayload" + "title": "SpanStartPayload", + "description": "Payload for a span start event." }, "StructuredLogEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12546,15 +12607,18 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "structured_log", - "default": "structured_log" + "default": "structured_log", + "description": "Event type identifier set to STRUCTURED_LOG" }, "payload": { - "$ref": "#/components/schemas/StructuredLogPayload" + "$ref": "#/components/schemas/StructuredLogPayload", + "description": "The structured payload data for the log event" } }, "additionalProperties": false, @@ -12565,7 +12629,8 @@ "type", "payload" ], - "title": "StructuredLogEvent" + "title": "StructuredLogEvent", + "description": "A structured log event containing typed payload data." }, "StructuredLogPayload": { "oneOf": [ @@ -12590,20 +12655,24 @@ "span_start", "span_end" ], - "title": "StructuredLogType" + "title": "StructuredLogType", + "description": "The type of structured log event payload." }, "UnstructuredLogEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12625,18 +12694,22 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "unstructured_log", - "default": "unstructured_log" + "default": "unstructured_log", + "description": "Event type identifier set to UNSTRUCTURED_LOG" }, "message": { - "type": "string" + "type": "string", + "description": "The log message text" }, "severity": { - "$ref": "#/components/schemas/LogSeverity" + "$ref": "#/components/schemas/LogSeverity", + "description": "The severity level of the log message" } }, "additionalProperties": false, @@ -12648,7 +12721,8 @@ "message", "severity" ], - "title": "UnstructuredLogEvent" + "title": "UnstructuredLogEvent", + "description": "An unstructured log event containing a simple text message." }, "LogEventRequest": { "type": "object", @@ -15311,10 +15385,12 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the label to match" }, "value": { - "type": "string" + "type": "string", + "description": "The value to match against" }, "operator": { "type": "string", @@ -15324,7 +15400,7 @@ "=~", "!~" ], - "title": "MetricLabelOperator", + "description": "The comparison operator to use for matching", "default": "=" } }, @@ -15334,7 +15410,8 @@ "value", "operator" ], - "title": "MetricLabelMatcher" + "title": "MetricLabelMatcher", + "description": "A matcher for filtering metrics by label values." }, "description": "The label matchers to apply to the metric." } @@ -15350,10 +15427,12 @@ "type": "object", "properties": { "timestamp": { - "type": "integer" + "type": "integer", + "description": "Unix timestamp when the metric value was recorded" }, "value": { - "type": "number" + "type": "number", + "description": "The numeric value of the metric at this timestamp" } }, "additionalProperties": false, @@ -15361,16 +15440,19 @@ "timestamp", "value" ], - "title": "MetricDataPoint" + "title": "MetricDataPoint", + "description": "A single data point in a metric time series." }, "MetricLabel": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the label" }, "value": { - "type": "string" + "type": "string", + "description": "The value of the label" } }, "additionalProperties": false, @@ -15378,25 +15460,29 @@ "name", "value" ], - "title": "MetricLabel" + "title": "MetricLabel", + "description": "A label associated with a metric." }, "MetricSeries": { "type": "object", "properties": { "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/MetricLabel" - } + }, + "description": "List of labels associated with this metric series" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/MetricDataPoint" - } + }, + "description": "List of data points in chronological order" } }, "additionalProperties": false, @@ -15405,7 +15491,8 @@ "labels", "values" ], - "title": "MetricSeries" + "title": "MetricSeries", + "description": "A time series of metric data points." }, "QueryMetricsResponse": { "type": "object", @@ -15414,23 +15501,27 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" - } + }, + "description": "List of metric series matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QueryMetricsResponse" + "title": "QueryMetricsResponse", + "description": "Response containing metric time series data." }, "QueryCondition": { "type": "object", "properties": { "key": { - "type": "string" + "type": "string", + "description": "The attribute key to filter on" }, "op": { - "$ref": "#/components/schemas/QueryConditionOp" + "$ref": "#/components/schemas/QueryConditionOp", + "description": "The comparison operator to apply" }, "value": { "oneOf": [ @@ -15452,7 +15543,8 @@ { "type": "object" } - ] + ], + "description": "The value to compare against" } }, "additionalProperties": false, @@ -15461,7 +15553,8 @@ "op", "value" ], - "title": "QueryCondition" + "title": "QueryCondition", + "description": "A condition for filtering query results." }, "QueryConditionOp": { "type": "string", @@ -15471,7 +15564,8 @@ "gt", "lt" ], - "title": "QueryConditionOp" + "title": "QueryConditionOp", + "description": "Comparison operators for query conditions." }, "QuerySpansRequest": { "type": "object", @@ -15509,14 +15603,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Span" - } + }, + "description": "List of spans matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QuerySpansResponse" + "title": "QuerySpansResponse", + "description": "Response containing a list of spans." }, "QueryTracesRequest": { "type": "object", @@ -15554,14 +15650,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Trace" - } + }, + "description": "List of traces matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QueryTracesResponse" + "title": "QueryTracesResponse", + "description": "Response containing a list of traces." }, "RegisterBenchmarkRequest": { "type": "object", @@ -16440,14 +16538,16 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Version number of the service" } }, "additionalProperties": false, "required": [ "version" ], - "title": "VersionInfo" + "title": "VersionInfo", + "description": "Version information for the service." } }, "responses": { diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 5fddd1449..564ea3bbc 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/docs/_static/llama-stack-spec.yaml @@ -1323,7 +1323,8 @@ paths: get: responses: '200': - description: A HealthInfo. + description: >- + Health information indicating if the service is operational. content: application/json: schema: @@ -1340,7 +1341,8 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Inspect - description: Get the health of the service. + description: >- + Get the current health status of the service. parameters: [] /v1/tool-runtime/rag-tool/insert: post: @@ -1984,7 +1986,8 @@ paths: get: responses: '200': - description: A ListRoutesResponse. + description: >- + Response containing information about all available routes. content: application/json: schema: @@ -2001,7 +2004,8 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Inspect - description: List all routes. + description: >- + List all available API routes with their methods and implementing providers. parameters: [] /v1/tool-runtime/list-tools: get: @@ -3506,7 +3510,8 @@ paths: get: responses: '200': - description: A VersionInfo. + description: >- + Version information containing the service version number. content: application/json: schema: @@ -4164,6 +4169,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response completion_message: $ref: '#/components/schemas/CompletionMessage' description: The complete response message @@ -4183,17 +4190,23 @@ components: properties: metric: type: string + description: The name of the metric value: oneOf: - type: integer - type: number + description: The numeric value of the metric unit: type: string + description: >- + (Optional) The unit of measurement for the metric value additionalProperties: false required: - metric - value title: MetricInResponse + description: >- + A metric value included in API responses. TokenLogProbs: type: object properties: @@ -4268,6 +4281,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response content: type: string description: The generated completion text @@ -4421,6 +4436,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response event: $ref: '#/components/schemas/ChatCompletionResponseEvent' description: The event containing the new content @@ -4544,6 +4561,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response delta: type: string description: >- @@ -7881,18 +7900,28 @@ components: properties: span_id: type: string + description: Unique identifier for the span trace_id: type: string + description: >- + Unique identifier for the trace this span belongs to parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span name: type: string + description: >- + Human-readable name describing the operation this span represents start_time: type: string format: date-time + description: Timestamp when the operation began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the operation finished, if completed attributes: type: object additionalProperties: @@ -7903,6 +7932,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Key-value pairs containing additional metadata about the span additionalProperties: false required: - span_id @@ -7910,6 +7941,8 @@ components: - name - start_time title: Span + description: >- + A span representing a single operation within a trace. GetSpanTreeRequest: type: object properties: @@ -7929,23 +7962,36 @@ components: - ok - error title: SpanStatus + description: >- + The status of a span indicating whether it completed successfully or with + an error. SpanWithStatus: type: object properties: span_id: type: string + description: Unique identifier for the span trace_id: type: string + description: >- + Unique identifier for the trace this span belongs to parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span name: type: string + description: >- + Human-readable name describing the operation this span represents start_time: type: string format: date-time + description: Timestamp when the operation began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the operation finished, if completed attributes: type: object additionalProperties: @@ -7956,8 +8002,12 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Key-value pairs containing additional metadata about the span status: $ref: '#/components/schemas/SpanStatus' + description: >- + (Optional) The current status of the span additionalProperties: false required: - span_id @@ -7965,6 +8015,7 @@ components: - name - start_time title: SpanWithStatus + description: A span that includes status information. QuerySpanTreeResponse: type: object properties: @@ -7972,10 +8023,14 @@ components: type: object additionalProperties: $ref: '#/components/schemas/SpanWithStatus' + description: >- + Dictionary mapping span IDs to spans with status information additionalProperties: false required: - data title: QuerySpanTreeResponse + description: >- + Response containing a tree structure of spans. Tool: type: object properties: @@ -8086,20 +8141,29 @@ components: properties: trace_id: type: string + description: Unique identifier for the trace root_span_id: type: string + description: >- + Unique identifier for the root span that started this trace start_time: type: string format: date-time + description: Timestamp when the trace began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the trace finished, if completed additionalProperties: false required: - trace_id - root_span_id - start_time title: Trace + description: >- + A trace representing the complete execution path of a request across multiple + operations. Checkpoint: description: Checkpoint created during training runs title: Checkpoint @@ -8245,11 +8309,13 @@ components: - OK - Error - Not Implemented - title: HealthStatus + description: Current health status of the service additionalProperties: false required: - status title: HealthInfo + description: >- + Health status information for the service. RAGDocument: type: object properties: @@ -8808,18 +8874,25 @@ components: properties: route: type: string + description: The API endpoint path method: type: string + description: HTTP method for the route provider_types: type: array items: type: string + description: >- + List of provider types that implement this route additionalProperties: false required: - route - method - provider_types title: RouteInfo + description: >- + Information about an API route including its path, method, and implementing + providers. ListRoutesResponse: type: object properties: @@ -8827,10 +8900,14 @@ components: type: array items: $ref: '#/components/schemas/RouteInfo' + description: >- + List of available route information objects additionalProperties: false required: - data title: ListRoutesResponse + description: >- + Response containing a list of all available API routes. ListToolDefsResponse: type: object properties: @@ -8925,6 +9002,8 @@ components: - structured_log - metric title: EventType + description: >- + The type of telemetry event being logged. LogSeverity: type: string enum: @@ -8935,16 +9014,22 @@ components: - error - critical title: LogSeverity + description: The severity level of a log message. MetricEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -8954,18 +9039,26 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: metric default: metric + description: Event type identifier set to METRIC metric: type: string + description: The name of the metric being measured value: oneOf: - type: integer - type: number + description: >- + The numeric value of the metric measurement unit: type: string + description: >- + The unit of measurement for the metric value additionalProperties: false required: - trace_id @@ -8976,6 +9069,8 @@ components: - value - unit title: MetricEvent + description: >- + A metric event containing a measured value. SpanEndPayload: type: object properties: @@ -8983,13 +9078,17 @@ components: $ref: '#/components/schemas/StructuredLogType' const: span_end default: span_end + description: Payload type identifier set to SPAN_END status: $ref: '#/components/schemas/SpanStatus' + description: >- + The final status of the span indicating success or failure additionalProperties: false required: - type - status title: SpanEndPayload + description: Payload for a span end event. SpanStartPayload: type: object properties: @@ -8997,25 +9096,37 @@ components: $ref: '#/components/schemas/StructuredLogType' const: span_start default: span_start + description: >- + Payload type identifier set to SPAN_START name: type: string + description: >- + Human-readable name describing the operation this span represents parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span additionalProperties: false required: - type - name title: SpanStartPayload + description: Payload for a span start event. StructuredLogEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -9025,12 +9136,18 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: structured_log default: structured_log + description: >- + Event type identifier set to STRUCTURED_LOG payload: $ref: '#/components/schemas/StructuredLogPayload' + description: >- + The structured payload data for the log event additionalProperties: false required: - trace_id @@ -9039,6 +9156,8 @@ components: - type - payload title: StructuredLogEvent + description: >- + A structured log event containing typed payload data. StructuredLogPayload: oneOf: - $ref: '#/components/schemas/SpanStartPayload' @@ -9054,16 +9173,23 @@ components: - span_start - span_end title: StructuredLogType + description: >- + The type of structured log event payload. UnstructuredLogEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -9073,14 +9199,20 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: unstructured_log default: unstructured_log + description: >- + Event type identifier set to UNSTRUCTURED_LOG message: type: string + description: The log message text severity: $ref: '#/components/schemas/LogSeverity' + description: The severity level of the log message additionalProperties: false required: - trace_id @@ -9090,6 +9222,8 @@ components: - message - severity title: UnstructuredLogEvent + description: >- + An unstructured log event containing a simple text message. LogEventRequest: type: object properties: @@ -11065,8 +11199,10 @@ components: properties: name: type: string + description: The name of the label to match value: type: string + description: The value to match against operator: type: string enum: @@ -11074,7 +11210,8 @@ components: - '!=' - =~ - '!~' - title: MetricLabelOperator + description: >- + The comparison operator to use for matching default: '=' additionalProperties: false required: @@ -11082,6 +11219,8 @@ components: - value - operator title: MetricLabelMatcher + description: >- + A matcher for filtering metrics by label values. description: >- The label matchers to apply to the metric. additionalProperties: false @@ -11094,44 +11233,59 @@ components: properties: timestamp: type: integer + description: >- + Unix timestamp when the metric value was recorded value: type: number + description: >- + The numeric value of the metric at this timestamp additionalProperties: false required: - timestamp - value title: MetricDataPoint + description: >- + A single data point in a metric time series. MetricLabel: type: object properties: name: type: string + description: The name of the label value: type: string + description: The value of the label additionalProperties: false required: - name - value title: MetricLabel + description: A label associated with a metric. MetricSeries: type: object properties: metric: type: string + description: The name of the metric labels: type: array items: $ref: '#/components/schemas/MetricLabel' + description: >- + List of labels associated with this metric series values: type: array items: $ref: '#/components/schemas/MetricDataPoint' + description: >- + List of data points in chronological order additionalProperties: false required: - metric - labels - values title: MetricSeries + description: A time series of metric data points. QueryMetricsResponse: type: object properties: @@ -11139,17 +11293,23 @@ components: type: array items: $ref: '#/components/schemas/MetricSeries' + description: >- + List of metric series matching the query criteria additionalProperties: false required: - data title: QueryMetricsResponse + description: >- + Response containing metric time series data. QueryCondition: type: object properties: key: type: string + description: The attribute key to filter on op: $ref: '#/components/schemas/QueryConditionOp' + description: The comparison operator to apply value: oneOf: - type: 'null' @@ -11158,12 +11318,14 @@ components: - type: string - type: array - type: object + description: The value to compare against additionalProperties: false required: - key - op - value title: QueryCondition + description: A condition for filtering query results. QueryConditionOp: type: string enum: @@ -11172,6 +11334,8 @@ components: - gt - lt title: QueryConditionOp + description: >- + Comparison operators for query conditions. QuerySpansRequest: type: object properties: @@ -11201,10 +11365,13 @@ components: type: array items: $ref: '#/components/schemas/Span' + description: >- + List of spans matching the query criteria additionalProperties: false required: - data title: QuerySpansResponse + description: Response containing a list of spans. QueryTracesRequest: type: object properties: @@ -11234,10 +11401,13 @@ components: type: array items: $ref: '#/components/schemas/Trace' + description: >- + List of traces matching the query criteria additionalProperties: false required: - data title: QueryTracesResponse + description: Response containing a list of traces. RegisterBenchmarkRequest: type: object properties: @@ -11858,10 +12028,12 @@ components: properties: version: type: string + description: Version number of the service additionalProperties: false required: - version title: VersionInfo + description: Version information for the service. responses: BadRequest400: description: The request was invalid or malformed diff --git a/llama_stack/apis/inspect/inspect.py b/llama_stack/apis/inspect/inspect.py index 44a5e95b2..3a7dc607c 100644 --- a/llama_stack/apis/inspect/inspect.py +++ b/llama_stack/apis/inspect/inspect.py @@ -14,6 +14,12 @@ from llama_stack.schema_utils import json_schema_type, webmethod @json_schema_type class RouteInfo(BaseModel): + """Information about an API route including its path, method, and implementing providers. + + :param route: The API endpoint path + :param method: HTTP method for the route + :param provider_types: List of provider types that implement this route + """ route: str method: str provider_types: list[str] @@ -21,15 +27,27 @@ class RouteInfo(BaseModel): @json_schema_type class HealthInfo(BaseModel): + """Health status information for the service. + + :param status: Current health status of the service + """ status: HealthStatus @json_schema_type class VersionInfo(BaseModel): + """Version information for the service. + + :param version: Version number of the service + """ version: str class ListRoutesResponse(BaseModel): + """Response containing a list of all available API routes. + + :param data: List of available route information objects + """ data: list[RouteInfo] @@ -37,17 +55,17 @@ class ListRoutesResponse(BaseModel): class Inspect(Protocol): @webmethod(route="/inspect/routes", method="GET") async def list_routes(self) -> ListRoutesResponse: - """List all routes. + """List all available API routes with their methods and implementing providers. - :returns: A ListRoutesResponse. + :returns: Response containing information about all available routes. """ ... @webmethod(route="/health", method="GET") async def health(self) -> HealthInfo: - """Get the health of the service. + """Get the current health status of the service. - :returns: A HealthInfo. + :returns: Health information indicating if the service is operational. """ ... @@ -55,6 +73,6 @@ class Inspect(Protocol): async def version(self) -> VersionInfo: """Get the version of the service. - :returns: A VersionInfo. + :returns: Version information containing the service version number. """ ... diff --git a/llama_stack/apis/telemetry/telemetry.py b/llama_stack/apis/telemetry/telemetry.py index 0eb53f397..78f4213bf 100644 --- a/llama_stack/apis/telemetry/telemetry.py +++ b/llama_stack/apis/telemetry/telemetry.py @@ -25,12 +25,27 @@ DEFAULT_TTL_DAYS = 7 @json_schema_type class SpanStatus(Enum): + """The status of a span indicating whether it completed successfully or with an error. + + :cvar OK: Span completed successfully without errors + :cvar ERROR: Span completed with an error or failure + """ OK = "ok" ERROR = "error" @json_schema_type class Span(BaseModel): + """A span representing a single operation within a trace. + + :param span_id: Unique identifier for the span + :param trace_id: Unique identifier for the trace this span belongs to + :param parent_span_id: (Optional) Unique identifier for the parent span, if this is a child span + :param name: Human-readable name describing the operation this span represents + :param start_time: Timestamp when the operation began + :param end_time: (Optional) Timestamp when the operation finished, if completed + :param attributes: (Optional) Key-value pairs containing additional metadata about the span + """ span_id: str trace_id: str parent_span_id: str | None = None @@ -47,6 +62,13 @@ class Span(BaseModel): @json_schema_type class Trace(BaseModel): + """A trace representing the complete execution path of a request across multiple operations. + + :param trace_id: Unique identifier for the trace + :param root_span_id: Unique identifier for the root span that started this trace + :param start_time: Timestamp when the trace began + :param end_time: (Optional) Timestamp when the trace finished, if completed + """ trace_id: str root_span_id: str start_time: datetime @@ -55,6 +77,12 @@ class Trace(BaseModel): @json_schema_type class EventType(Enum): + """The type of telemetry event being logged. + + :cvar UNSTRUCTURED_LOG: A simple log message with severity level + :cvar STRUCTURED_LOG: A structured log event with typed payload data + :cvar METRIC: A metric measurement with value and unit + """ UNSTRUCTURED_LOG = "unstructured_log" STRUCTURED_LOG = "structured_log" METRIC = "metric" @@ -62,6 +90,15 @@ class EventType(Enum): @json_schema_type class LogSeverity(Enum): + """The severity level of a log message. + + :cvar VERBOSE: Detailed diagnostic information for troubleshooting + :cvar DEBUG: Debug information useful during development + :cvar INFO: General informational messages about normal operation + :cvar WARN: Warning messages about potentially problematic situations + :cvar ERROR: Error messages indicating failures that don't stop execution + :cvar CRITICAL: Critical error messages indicating severe failures + """ VERBOSE = "verbose" DEBUG = "debug" INFO = "info" @@ -71,6 +108,13 @@ class LogSeverity(Enum): class EventCommon(BaseModel): + """Common fields shared by all telemetry events. + + :param trace_id: Unique identifier for the trace this event belongs to + :param span_id: Unique identifier for the span this event belongs to + :param timestamp: Timestamp when the event occurred + :param attributes: (Optional) Key-value pairs containing additional metadata about the event + """ trace_id: str span_id: str timestamp: datetime @@ -79,6 +123,12 @@ class EventCommon(BaseModel): @json_schema_type class UnstructuredLogEvent(EventCommon): + """An unstructured log event containing a simple text message. + + :param type: Event type identifier set to UNSTRUCTURED_LOG + :param message: The log message text + :param severity: The severity level of the log message + """ type: Literal[EventType.UNSTRUCTURED_LOG] = EventType.UNSTRUCTURED_LOG message: str severity: LogSeverity @@ -86,6 +136,13 @@ class UnstructuredLogEvent(EventCommon): @json_schema_type class MetricEvent(EventCommon): + """A metric event containing a measured value. + + :param type: Event type identifier set to METRIC + :param metric: The name of the metric being measured + :param value: The numeric value of the metric measurement + :param unit: The unit of measurement for the metric value + """ type: Literal[EventType.METRIC] = EventType.METRIC metric: str # this would be an enum value: int | float @@ -94,6 +151,12 @@ class MetricEvent(EventCommon): @json_schema_type class MetricInResponse(BaseModel): + """A metric value included in API responses. + + :param metric: The name of the metric + :param value: The numeric value of the metric + :param unit: (Optional) The unit of measurement for the metric value + """ metric: str value: int | float unit: str | None = None @@ -120,17 +183,32 @@ class MetricInResponse(BaseModel): class MetricResponseMixin(BaseModel): + """Mixin class for API responses that can include metrics. + + :param metrics: (Optional) List of metrics associated with the API response + """ metrics: list[MetricInResponse] | None = None @json_schema_type class StructuredLogType(Enum): + """The type of structured log event payload. + + :cvar SPAN_START: Event indicating the start of a new span + :cvar SPAN_END: Event indicating the completion of a span + """ SPAN_START = "span_start" SPAN_END = "span_end" @json_schema_type class SpanStartPayload(BaseModel): + """Payload for a span start event. + + :param type: Payload type identifier set to SPAN_START + :param name: Human-readable name describing the operation this span represents + :param parent_span_id: (Optional) Unique identifier for the parent span, if this is a child span + """ type: Literal[StructuredLogType.SPAN_START] = StructuredLogType.SPAN_START name: str parent_span_id: str | None = None @@ -138,6 +216,11 @@ class SpanStartPayload(BaseModel): @json_schema_type class SpanEndPayload(BaseModel): + """Payload for a span end event. + + :param type: Payload type identifier set to SPAN_END + :param status: The final status of the span indicating success or failure + """ type: Literal[StructuredLogType.SPAN_END] = StructuredLogType.SPAN_END status: SpanStatus @@ -151,6 +234,11 @@ register_schema(StructuredLogPayload, name="StructuredLogPayload") @json_schema_type class StructuredLogEvent(EventCommon): + """A structured log event containing typed payload data. + + :param type: Event type identifier set to STRUCTURED_LOG + :param payload: The structured payload data for the log event + """ type: Literal[EventType.STRUCTURED_LOG] = EventType.STRUCTURED_LOG payload: StructuredLogPayload @@ -164,6 +252,14 @@ register_schema(Event, name="Event") @json_schema_type class EvalTrace(BaseModel): + """A trace record for evaluation purposes. + + :param session_id: Unique identifier for the evaluation session + :param step: The evaluation step or phase identifier + :param input: The input data for the evaluation + :param output: The actual output produced during evaluation + :param expected_output: The expected output for comparison during evaluation + """ session_id: str step: str input: str @@ -173,11 +269,22 @@ class EvalTrace(BaseModel): @json_schema_type class SpanWithStatus(Span): + """A span that includes status information. + + :param status: (Optional) The current status of the span + """ status: SpanStatus | None = None @json_schema_type class QueryConditionOp(Enum): + """Comparison operators for query conditions. + + :cvar EQ: Equal to comparison + :cvar NE: Not equal to comparison + :cvar GT: Greater than comparison + :cvar LT: Less than comparison + """ EQ = "eq" NE = "ne" GT = "gt" @@ -186,29 +293,59 @@ class QueryConditionOp(Enum): @json_schema_type class QueryCondition(BaseModel): + """A condition for filtering query results. + + :param key: The attribute key to filter on + :param op: The comparison operator to apply + :param value: The value to compare against + """ key: str op: QueryConditionOp value: Any class QueryTracesResponse(BaseModel): + """Response containing a list of traces. + + :param data: List of traces matching the query criteria + """ data: list[Trace] class QuerySpansResponse(BaseModel): + """Response containing a list of spans. + + :param data: List of spans matching the query criteria + """ data: list[Span] class QuerySpanTreeResponse(BaseModel): + """Response containing a tree structure of spans. + + :param data: Dictionary mapping span IDs to spans with status information + """ data: dict[str, SpanWithStatus] class MetricQueryType(Enum): + """The type of metric query to perform. + + :cvar RANGE: Query metrics over a time range + :cvar INSTANT: Query metrics at a specific point in time + """ RANGE = "range" INSTANT = "instant" class MetricLabelOperator(Enum): + """Operators for matching metric labels. + + :cvar EQUALS: Label value must equal the specified value + :cvar NOT_EQUALS: Label value must not equal the specified value + :cvar REGEX_MATCH: Label value must match the specified regular expression + :cvar REGEX_NOT_MATCH: Label value must not match the specified regular expression + """ EQUALS = "=" NOT_EQUALS = "!=" REGEX_MATCH = "=~" @@ -216,6 +353,12 @@ class MetricLabelOperator(Enum): class MetricLabelMatcher(BaseModel): + """A matcher for filtering metrics by label values. + + :param name: The name of the label to match + :param value: The value to match against + :param operator: The comparison operator to use for matching + """ name: str value: str operator: MetricLabelOperator = MetricLabelOperator.EQUALS @@ -223,24 +366,44 @@ class MetricLabelMatcher(BaseModel): @json_schema_type class MetricLabel(BaseModel): + """A label associated with a metric. + + :param name: The name of the label + :param value: The value of the label + """ name: str value: str @json_schema_type class MetricDataPoint(BaseModel): + """A single data point in a metric time series. + + :param timestamp: Unix timestamp when the metric value was recorded + :param value: The numeric value of the metric at this timestamp + """ timestamp: int value: float @json_schema_type class MetricSeries(BaseModel): + """A time series of metric data points. + + :param metric: The name of the metric + :param labels: List of labels associated with this metric series + :param values: List of data points in chronological order + """ metric: str labels: list[MetricLabel] values: list[MetricDataPoint] class QueryMetricsResponse(BaseModel): + """Response containing metric time series data. + + :param data: List of metric series matching the query criteria + """ data: list[MetricSeries]