phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-07-29 15:23:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

a

Browse source
This commit is contained in:
Sai Soundararaj 2025-07-01 17:36:28 -07:00
parent 20c527eded
commit b1bd9cdc0b
5 changed files with 574 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

4
api_update_plan.md
View file

@ -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] 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] 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 [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 [x] 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] 22. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/telemetry/telemetry.py` - Telemetry and monitoring
**Step 1: Existing Documentation Assessment** **Step 1: Existing Documentation Assessment**
- **Priority**: Review all @json_schema_type classes and @webmethod functions for docstring completeness - **Priority**: Review all @json_schema_type classes and @webmethod functions for docstring completeness

314
docs/_static/llama-stack-spec.html vendored
View file

@ -1922,7 +1922,7 @@
"get": { "get": {
"responses": { "responses": {
"200": { "200": {
"description": "A HealthInfo.", "description": "Health information indicating if the service is operational.",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -1947,7 +1947,7 @@
"tags": [ "tags": [
"Inspect" "Inspect"
], ],
"description": "Get the health of the service.", "description": "Get the current health status of the service.",
"parameters": [] "parameters": []
} }
}, },
@ -2839,7 +2839,7 @@
"get": { "get": {
"responses": { "responses": {
"200": { "200": {
"description": "A ListRoutesResponse.", "description": "Response containing information about all available routes.",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -2864,7 +2864,7 @@
"tags": [ "tags": [
"Inspect" "Inspect"
], ],
"description": "List all routes.", "description": "List all available API routes with their methods and implementing providers.",
"parameters": [] "parameters": []
} }
}, },
@ -4955,7 +4955,7 @@
"get": { "get": {
"responses": { "responses": {
"200": { "200": {
"description": "A VersionInfo.", "description": "Version information containing the service version number.",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -5840,7 +5840,8 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricInResponse" "$ref": "#/components/schemas/MetricInResponse"
} },
"description": "(Optional) List of metrics associated with the API response"
}, },
"completion_message": { "completion_message": {
"$ref": "#/components/schemas/CompletionMessage", "$ref": "#/components/schemas/CompletionMessage",
@ -5865,7 +5866,8 @@
"type": "object", "type": "object",
"properties": { "properties": {
"metric": { "metric": {
"type": "string" "type": "string",
"description": "The name of the metric"
}, },
"value": { "value": {
"oneOf": [ "oneOf": [
@ -5875,10 +5877,12 @@
{ {
"type": "number" "type": "number"
} }
] ],
"description": "The numeric value of the metric"
}, },
"unit": { "unit": {
"type": "string" "type": "string",
"description": "(Optional) The unit of measurement for the metric value"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -5886,7 +5890,8 @@
"metric", "metric",
"value" "value"
], ],
"title": "MetricInResponse" "title": "MetricInResponse",
"description": "A metric value included in API responses."
}, },
"TokenLogProbs": { "TokenLogProbs": {
"type": "object", "type": "object",
@ -5973,7 +5978,8 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricInResponse" "$ref": "#/components/schemas/MetricInResponse"
} },
"description": "(Optional) List of metrics associated with the API response"
}, },
"content": { "content": {
"type": "string", "type": "string",
@ -6141,7 +6147,8 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricInResponse" "$ref": "#/components/schemas/MetricInResponse"
} },
"description": "(Optional) List of metrics associated with the API response"
}, },
"event": { "event": {
"$ref": "#/components/schemas/ChatCompletionResponseEvent", "$ref": "#/components/schemas/ChatCompletionResponseEvent",
@ -6302,7 +6309,8 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricInResponse" "$ref": "#/components/schemas/MetricInResponse"
} },
"description": "(Optional) List of metrics associated with the API response"
}, },
"delta": { "delta": {
"type": "string", "type": "string",
@ -10932,24 +10940,30 @@
"type": "object", "type": "object",
"properties": { "properties": {
"span_id": { "span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the span"
}, },
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace this span belongs to"
}, },
"parent_span_id": { "parent_span_id": {
"type": "string" "type": "string",
"description": "(Optional) Unique identifier for the parent span, if this is a child span"
}, },
"name": { "name": {
"type": "string" "type": "string",
"description": "Human-readable name describing the operation this span represents"
}, },
"start_time": { "start_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the operation began"
}, },
"end_time": { "end_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "(Optional) Timestamp when the operation finished, if completed"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -10974,7 +10988,8 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "(Optional) Key-value pairs containing additional metadata about the span"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -10984,7 +10999,8 @@
"name", "name",
"start_time" "start_time"
], ],
"title": "Span" "title": "Span",
"description": "A span representing a single operation within a trace."
}, },
"GetSpanTreeRequest": { "GetSpanTreeRequest": {
"type": "object", "type": "object",
@ -11010,30 +11026,37 @@
"ok", "ok",
"error" "error"
], ],
"title": "SpanStatus" "title": "SpanStatus",
"description": "The status of a span indicating whether it completed successfully or with an error."
}, },
"SpanWithStatus": { "SpanWithStatus": {
"type": "object", "type": "object",
"properties": { "properties": {
"span_id": { "span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the span"
}, },
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace this span belongs to"
}, },
"parent_span_id": { "parent_span_id": {
"type": "string" "type": "string",
"description": "(Optional) Unique identifier for the parent span, if this is a child span"
}, },
"name": { "name": {
"type": "string" "type": "string",
"description": "Human-readable name describing the operation this span represents"
}, },
"start_time": { "start_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the operation began"
}, },
"end_time": { "end_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "(Optional) Timestamp when the operation finished, if completed"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -11058,10 +11081,12 @@
"type": "object" "type": "object"
} }
] ]
} },
"description": "(Optional) Key-value pairs containing additional metadata about the span"
}, },
"status": { "status": {
"$ref": "#/components/schemas/SpanStatus" "$ref": "#/components/schemas/SpanStatus",
"description": "(Optional) The current status of the span"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -11071,7 +11096,8 @@
"name", "name",
"start_time" "start_time"
], ],
"title": "SpanWithStatus" "title": "SpanWithStatus",
"description": "A span that includes status information."
}, },
"QuerySpanTreeResponse": { "QuerySpanTreeResponse": {
"type": "object", "type": "object",
@ -11080,14 +11106,16 @@
"type": "object", "type": "object",
"additionalProperties": { "additionalProperties": {
"$ref": "#/components/schemas/SpanWithStatus" "$ref": "#/components/schemas/SpanWithStatus"
} },
"description": "Dictionary mapping span IDs to spans with status information"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"data" "data"
], ],
"title": "QuerySpanTreeResponse" "title": "QuerySpanTreeResponse",
"description": "Response containing a tree structure of spans."
}, },
"Tool": { "Tool": {
"type": "object", "type": "object",
@ -11243,18 +11271,22 @@
"type": "object", "type": "object",
"properties": { "properties": {
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace"
}, },
"root_span_id": { "root_span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the root span that started this trace"
}, },
"start_time": { "start_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the trace began"
}, },
"end_time": { "end_time": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "(Optional) Timestamp when the trace finished, if completed"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -11263,7 +11295,8 @@
"root_span_id", "root_span_id",
"start_time" "start_time"
], ],
"title": "Trace" "title": "Trace",
"description": "A trace representing the complete execution path of a request across multiple operations."
}, },
"Checkpoint": { "Checkpoint": {
"description": "Checkpoint created during training runs", "description": "Checkpoint created during training runs",
@ -11452,14 +11485,15 @@
"Error", "Error",
"Not Implemented" "Not Implemented"
], ],
"title": "HealthStatus" "description": "Current health status of the service"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"status" "status"
], ],
"title": "HealthInfo" "title": "HealthInfo",
"description": "Health status information for the service."
}, },
"RAGDocument": { "RAGDocument": {
"type": "object", "type": "object",
@ -12221,16 +12255,19 @@
"type": "object", "type": "object",
"properties": { "properties": {
"route": { "route": {
"type": "string" "type": "string",
"description": "The API endpoint path"
}, },
"method": { "method": {
"type": "string" "type": "string",
"description": "HTTP method for the route"
}, },
"provider_types": { "provider_types": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"description": "List of provider types that implement this route"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12239,7 +12276,8 @@
"method", "method",
"provider_types" "provider_types"
], ],
"title": "RouteInfo" "title": "RouteInfo",
"description": "Information about an API route including its path, method, and implementing providers."
}, },
"ListRoutesResponse": { "ListRoutesResponse": {
"type": "object", "type": "object",
@ -12248,14 +12286,16 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/RouteInfo" "$ref": "#/components/schemas/RouteInfo"
} },
"description": "List of available route information objects"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"data" "data"
], ],
"title": "ListRoutesResponse" "title": "ListRoutesResponse",
"description": "Response containing a list of all available API routes."
}, },
"ListToolDefsResponse": { "ListToolDefsResponse": {
"type": "object", "type": "object",
@ -12389,7 +12429,8 @@
"structured_log", "structured_log",
"metric" "metric"
], ],
"title": "EventType" "title": "EventType",
"description": "The type of telemetry event being logged."
}, },
"LogSeverity": { "LogSeverity": {
"type": "string", "type": "string",
@ -12401,20 +12442,24 @@
"error", "error",
"critical" "critical"
], ],
"title": "LogSeverity" "title": "LogSeverity",
"description": "The severity level of a log message."
}, },
"MetricEvent": { "MetricEvent": {
"type": "object", "type": "object",
"properties": { "properties": {
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace this event belongs to"
}, },
"span_id": { "span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the span this event belongs to"
}, },
"timestamp": { "timestamp": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the event occurred"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -12436,15 +12481,18 @@
"type": "null" "type": "null"
} }
] ]
} },
"description": "(Optional) Key-value pairs containing additional metadata about the event"
}, },
"type": { "type": {
"$ref": "#/components/schemas/EventType", "$ref": "#/components/schemas/EventType",
"const": "metric", "const": "metric",
"default": "metric" "default": "metric",
"description": "Event type identifier set to METRIC"
}, },
"metric": { "metric": {
"type": "string" "type": "string",
"description": "The name of the metric being measured"
}, },
"value": { "value": {
"oneOf": [ "oneOf": [
@ -12454,10 +12502,12 @@
{ {
"type": "number" "type": "number"
} }
] ],
"description": "The numeric value of the metric measurement"
}, },
"unit": { "unit": {
"type": "string" "type": "string",
"description": "The unit of measurement for the metric value"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12470,7 +12520,8 @@
"value", "value",
"unit" "unit"
], ],
"title": "MetricEvent" "title": "MetricEvent",
"description": "A metric event containing a measured value."
}, },
"SpanEndPayload": { "SpanEndPayload": {
"type": "object", "type": "object",
@ -12478,10 +12529,12 @@
"type": { "type": {
"$ref": "#/components/schemas/StructuredLogType", "$ref": "#/components/schemas/StructuredLogType",
"const": "span_end", "const": "span_end",
"default": "span_end" "default": "span_end",
"description": "Payload type identifier set to SPAN_END"
}, },
"status": { "status": {
"$ref": "#/components/schemas/SpanStatus" "$ref": "#/components/schemas/SpanStatus",
"description": "The final status of the span indicating success or failure"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12489,7 +12542,8 @@
"type", "type",
"status" "status"
], ],
"title": "SpanEndPayload" "title": "SpanEndPayload",
"description": "Payload for a span end event."
}, },
"SpanStartPayload": { "SpanStartPayload": {
"type": "object", "type": "object",
@ -12497,13 +12551,16 @@
"type": { "type": {
"$ref": "#/components/schemas/StructuredLogType", "$ref": "#/components/schemas/StructuredLogType",
"const": "span_start", "const": "span_start",
"default": "span_start" "default": "span_start",
"description": "Payload type identifier set to SPAN_START"
}, },
"name": { "name": {
"type": "string" "type": "string",
"description": "Human-readable name describing the operation this span represents"
}, },
"parent_span_id": { "parent_span_id": {
"type": "string" "type": "string",
"description": "(Optional) Unique identifier for the parent span, if this is a child span"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12511,20 +12568,24 @@
"type", "type",
"name" "name"
], ],
"title": "SpanStartPayload" "title": "SpanStartPayload",
"description": "Payload for a span start event."
}, },
"StructuredLogEvent": { "StructuredLogEvent": {
"type": "object", "type": "object",
"properties": { "properties": {
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace this event belongs to"
}, },
"span_id": { "span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the span this event belongs to"
}, },
"timestamp": { "timestamp": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the event occurred"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -12546,15 +12607,18 @@
"type": "null" "type": "null"
} }
] ]
} },
"description": "(Optional) Key-value pairs containing additional metadata about the event"
}, },
"type": { "type": {
"$ref": "#/components/schemas/EventType", "$ref": "#/components/schemas/EventType",
"const": "structured_log", "const": "structured_log",
"default": "structured_log" "default": "structured_log",
"description": "Event type identifier set to STRUCTURED_LOG"
}, },
"payload": { "payload": {
"$ref": "#/components/schemas/StructuredLogPayload" "$ref": "#/components/schemas/StructuredLogPayload",
"description": "The structured payload data for the log event"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12565,7 +12629,8 @@
"type", "type",
"payload" "payload"
], ],
"title": "StructuredLogEvent" "title": "StructuredLogEvent",
"description": "A structured log event containing typed payload data."
}, },
"StructuredLogPayload": { "StructuredLogPayload": {
"oneOf": [ "oneOf": [
@ -12590,20 +12655,24 @@
"span_start", "span_start",
"span_end" "span_end"
], ],
"title": "StructuredLogType" "title": "StructuredLogType",
"description": "The type of structured log event payload."
}, },
"UnstructuredLogEvent": { "UnstructuredLogEvent": {
"type": "object", "type": "object",
"properties": { "properties": {
"trace_id": { "trace_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the trace this event belongs to"
}, },
"span_id": { "span_id": {
"type": "string" "type": "string",
"description": "Unique identifier for the span this event belongs to"
}, },
"timestamp": { "timestamp": {
"type": "string", "type": "string",
"format": "date-time" "format": "date-time",
"description": "Timestamp when the event occurred"
}, },
"attributes": { "attributes": {
"type": "object", "type": "object",
@ -12625,18 +12694,22 @@
"type": "null" "type": "null"
} }
] ]
} },
"description": "(Optional) Key-value pairs containing additional metadata about the event"
}, },
"type": { "type": {
"$ref": "#/components/schemas/EventType", "$ref": "#/components/schemas/EventType",
"const": "unstructured_log", "const": "unstructured_log",
"default": "unstructured_log" "default": "unstructured_log",
"description": "Event type identifier set to UNSTRUCTURED_LOG"
}, },
"message": { "message": {
"type": "string" "type": "string",
"description": "The log message text"
}, },
"severity": { "severity": {
"$ref": "#/components/schemas/LogSeverity" "$ref": "#/components/schemas/LogSeverity",
"description": "The severity level of the log message"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -12648,7 +12721,8 @@
"message", "message",
"severity" "severity"
], ],
"title": "UnstructuredLogEvent" "title": "UnstructuredLogEvent",
"description": "An unstructured log event containing a simple text message."
}, },
"LogEventRequest": { "LogEventRequest": {
"type": "object", "type": "object",
@ -15311,10 +15385,12 @@
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string" "type": "string",
"description": "The name of the label to match"
}, },
"value": { "value": {
"type": "string" "type": "string",
"description": "The value to match against"
}, },
"operator": { "operator": {
"type": "string", "type": "string",
@ -15324,7 +15400,7 @@
"=~", "=~",
"!~" "!~"
], ],
"title": "MetricLabelOperator", "description": "The comparison operator to use for matching",
"default": "=" "default": "="
} }
}, },
@ -15334,7 +15410,8 @@
"value", "value",
"operator" "operator"
], ],
"title": "MetricLabelMatcher" "title": "MetricLabelMatcher",
"description": "A matcher for filtering metrics by label values."
}, },
"description": "The label matchers to apply to the metric." "description": "The label matchers to apply to the metric."
} }
@ -15350,10 +15427,12 @@
"type": "object", "type": "object",
"properties": { "properties": {
"timestamp": { "timestamp": {
"type": "integer" "type": "integer",
"description": "Unix timestamp when the metric value was recorded"
}, },
"value": { "value": {
"type": "number" "type": "number",
"description": "The numeric value of the metric at this timestamp"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -15361,16 +15440,19 @@
"timestamp", "timestamp",
"value" "value"
], ],
"title": "MetricDataPoint" "title": "MetricDataPoint",
"description": "A single data point in a metric time series."
}, },
"MetricLabel": { "MetricLabel": {
"type": "object", "type": "object",
"properties": { "properties": {
"name": { "name": {
"type": "string" "type": "string",
"description": "The name of the label"
}, },
"value": { "value": {
"type": "string" "type": "string",
"description": "The value of the label"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -15378,25 +15460,29 @@
"name", "name",
"value" "value"
], ],
"title": "MetricLabel" "title": "MetricLabel",
"description": "A label associated with a metric."
}, },
"MetricSeries": { "MetricSeries": {
"type": "object", "type": "object",
"properties": { "properties": {
"metric": { "metric": {
"type": "string" "type": "string",
"description": "The name of the metric"
}, },
"labels": { "labels": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricLabel" "$ref": "#/components/schemas/MetricLabel"
} },
"description": "List of labels associated with this metric series"
}, },
"values": { "values": {
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricDataPoint" "$ref": "#/components/schemas/MetricDataPoint"
} },
"description": "List of data points in chronological order"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -15405,7 +15491,8 @@
"labels", "labels",
"values" "values"
], ],
"title": "MetricSeries" "title": "MetricSeries",
"description": "A time series of metric data points."
}, },
"QueryMetricsResponse": { "QueryMetricsResponse": {
"type": "object", "type": "object",
@ -15414,23 +15501,27 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/MetricSeries" "$ref": "#/components/schemas/MetricSeries"
} },
"description": "List of metric series matching the query criteria"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"data" "data"
], ],
"title": "QueryMetricsResponse" "title": "QueryMetricsResponse",
"description": "Response containing metric time series data."
}, },
"QueryCondition": { "QueryCondition": {
"type": "object", "type": "object",
"properties": { "properties": {
"key": { "key": {
"type": "string" "type": "string",
"description": "The attribute key to filter on"
}, },
"op": { "op": {
"$ref": "#/components/schemas/QueryConditionOp" "$ref": "#/components/schemas/QueryConditionOp",
"description": "The comparison operator to apply"
}, },
"value": { "value": {
"oneOf": [ "oneOf": [
@ -15452,7 +15543,8 @@
{ {
"type": "object" "type": "object"
} }
] ],
"description": "The value to compare against"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
@ -15461,7 +15553,8 @@
"op", "op",
"value" "value"
], ],
"title": "QueryCondition" "title": "QueryCondition",
"description": "A condition for filtering query results."
}, },
"QueryConditionOp": { "QueryConditionOp": {
"type": "string", "type": "string",
@ -15471,7 +15564,8 @@
"gt", "gt",
"lt" "lt"
], ],
"title": "QueryConditionOp" "title": "QueryConditionOp",
"description": "Comparison operators for query conditions."
}, },
"QuerySpansRequest": { "QuerySpansRequest": {
"type": "object", "type": "object",
@ -15509,14 +15603,16 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/Span" "$ref": "#/components/schemas/Span"
} },
"description": "List of spans matching the query criteria"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"data" "data"
], ],
"title": "QuerySpansResponse" "title": "QuerySpansResponse",
"description": "Response containing a list of spans."
}, },
"QueryTracesRequest": { "QueryTracesRequest": {
"type": "object", "type": "object",
@ -15554,14 +15650,16 @@
"type": "array", "type": "array",
"items": { "items": {
"$ref": "#/components/schemas/Trace" "$ref": "#/components/schemas/Trace"
} },
"description": "List of traces matching the query criteria"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"data" "data"
], ],
"title": "QueryTracesResponse" "title": "QueryTracesResponse",
"description": "Response containing a list of traces."
}, },
"RegisterBenchmarkRequest": { "RegisterBenchmarkRequest": {
"type": "object", "type": "object",
@ -16440,14 +16538,16 @@
"type": "object", "type": "object",
"properties": { "properties": {
"version": { "version": {
"type": "string" "type": "string",
"description": "Version number of the service"
} }
}, },
"additionalProperties": false, "additionalProperties": false,
"required": [ "required": [
"version" "version"
], ],
"title": "VersionInfo" "title": "VersionInfo",
"description": "Version information for the service."
} }
}, },
"responses": { "responses": {

186
docs/_static/llama-stack-spec.yaml vendored
View file

@ -1323,7 +1323,8 @@ paths:
get: get:
responses: responses:
'200': '200':
description: A HealthInfo. description: >-
Health information indicating if the service is operational.
content: content:
application/json: application/json:
schema: schema:
@ -1340,7 +1341,8 @@ paths:
$ref: '#/components/responses/DefaultError' $ref: '#/components/responses/DefaultError'
tags: tags:
- Inspect - Inspect
description: Get the health of the service. description: >-
Get the current health status of the service.
parameters: [] parameters: []
/v1/tool-runtime/rag-tool/insert: /v1/tool-runtime/rag-tool/insert:
post: post:
@ -1984,7 +1986,8 @@ paths:
get: get:
responses: responses:
'200': '200':
description: A ListRoutesResponse. description: >-
Response containing information about all available routes.
content: content:
application/json: application/json:
schema: schema:
@ -2001,7 +2004,8 @@ paths:
$ref: '#/components/responses/DefaultError' $ref: '#/components/responses/DefaultError'
tags: tags:
- Inspect - Inspect
description: List all routes. description: >-
List all available API routes with their methods and implementing providers.
parameters: [] parameters: []
/v1/tool-runtime/list-tools: /v1/tool-runtime/list-tools:
get: get:
@ -3506,7 +3510,8 @@ paths:
get: get:
responses: responses:
'200': '200':
description: A VersionInfo. description: >-
Version information containing the service version number.
content: content:
application/json: application/json:
schema: schema:
@ -4164,6 +4169,8 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricInResponse' $ref: '#/components/schemas/MetricInResponse'
description: >-
(Optional) List of metrics associated with the API response
completion_message: completion_message:
$ref: '#/components/schemas/CompletionMessage' $ref: '#/components/schemas/CompletionMessage'
description: The complete response message description: The complete response message
@ -4183,17 +4190,23 @@ components:
properties: properties:
metric: metric:
type: string type: string
description: The name of the metric
value: value:
oneOf: oneOf:
- type: integer - type: integer
- type: number - type: number
description: The numeric value of the metric
unit: unit:
type: string type: string
description: >-
(Optional) The unit of measurement for the metric value
additionalProperties: false additionalProperties: false
required: required:
- metric - metric
- value - value
title: MetricInResponse title: MetricInResponse
description: >-
A metric value included in API responses.
TokenLogProbs: TokenLogProbs:
type: object type: object
properties: properties:
@ -4268,6 +4281,8 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricInResponse' $ref: '#/components/schemas/MetricInResponse'
description: >-
(Optional) List of metrics associated with the API response
content: content:
type: string type: string
description: The generated completion text description: The generated completion text
@ -4421,6 +4436,8 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricInResponse' $ref: '#/components/schemas/MetricInResponse'
description: >-
(Optional) List of metrics associated with the API response
event: event:
$ref: '#/components/schemas/ChatCompletionResponseEvent' $ref: '#/components/schemas/ChatCompletionResponseEvent'
description: The event containing the new content description: The event containing the new content
@ -4544,6 +4561,8 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricInResponse' $ref: '#/components/schemas/MetricInResponse'
description: >-
(Optional) List of metrics associated with the API response
delta: delta:
type: string type: string
description: >- description: >-
@ -7881,18 +7900,28 @@ components:
properties: properties:
span_id: span_id:
type: string type: string
description: Unique identifier for the span
trace_id: trace_id:
type: string type: string
description: >-
Unique identifier for the trace this span belongs to
parent_span_id: parent_span_id:
type: string type: string
description: >-
(Optional) Unique identifier for the parent span, if this is a child span
name: name:
type: string type: string
description: >-
Human-readable name describing the operation this span represents
start_time: start_time:
type: string type: string
format: date-time format: date-time
description: Timestamp when the operation began
end_time: end_time:
type: string type: string
format: date-time format: date-time
description: >-
(Optional) Timestamp when the operation finished, if completed
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -7903,6 +7932,8 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
(Optional) Key-value pairs containing additional metadata about the span
additionalProperties: false additionalProperties: false
required: required:
- span_id - span_id
@ -7910,6 +7941,8 @@ components:
- name - name
- start_time - start_time
title: Span title: Span
description: >-
A span representing a single operation within a trace.
GetSpanTreeRequest: GetSpanTreeRequest:
type: object type: object
properties: properties:
@ -7929,23 +7962,36 @@ components:
- ok - ok
- error - error
title: SpanStatus title: SpanStatus
description: >-
The status of a span indicating whether it completed successfully or with
an error.
SpanWithStatus: SpanWithStatus:
type: object type: object
properties: properties:
span_id: span_id:
type: string type: string
description: Unique identifier for the span
trace_id: trace_id:
type: string type: string
description: >-
Unique identifier for the trace this span belongs to
parent_span_id: parent_span_id:
type: string type: string
description: >-
(Optional) Unique identifier for the parent span, if this is a child span
name: name:
type: string type: string
description: >-
Human-readable name describing the operation this span represents
start_time: start_time:
type: string type: string
format: date-time format: date-time
description: Timestamp when the operation began
end_time: end_time:
type: string type: string
format: date-time format: date-time
description: >-
(Optional) Timestamp when the operation finished, if completed
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -7956,8 +8002,12 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: >-
(Optional) Key-value pairs containing additional metadata about the span
status: status:
$ref: '#/components/schemas/SpanStatus' $ref: '#/components/schemas/SpanStatus'
description: >-
(Optional) The current status of the span
additionalProperties: false additionalProperties: false
required: required:
- span_id - span_id
@ -7965,6 +8015,7 @@ components:
- name - name
- start_time - start_time
title: SpanWithStatus title: SpanWithStatus
description: A span that includes status information.
QuerySpanTreeResponse: QuerySpanTreeResponse:
type: object type: object
properties: properties:
@ -7972,10 +8023,14 @@ components:
type: object type: object
additionalProperties: additionalProperties:
$ref: '#/components/schemas/SpanWithStatus' $ref: '#/components/schemas/SpanWithStatus'
description: >-
Dictionary mapping span IDs to spans with status information
additionalProperties: false additionalProperties: false
required: required:
- data - data
title: QuerySpanTreeResponse title: QuerySpanTreeResponse
description: >-
Response containing a tree structure of spans.
Tool: Tool:
type: object type: object
properties: properties:
@ -8086,20 +8141,29 @@ components:
properties: properties:
trace_id: trace_id:
type: string type: string
description: Unique identifier for the trace
root_span_id: root_span_id:
type: string type: string
description: >-
Unique identifier for the root span that started this trace
start_time: start_time:
type: string type: string
format: date-time format: date-time
description: Timestamp when the trace began
end_time: end_time:
type: string type: string
format: date-time format: date-time
description: >-
(Optional) Timestamp when the trace finished, if completed
additionalProperties: false additionalProperties: false
required: required:
- trace_id - trace_id
- root_span_id - root_span_id
- start_time - start_time
title: Trace title: Trace
description: >-
A trace representing the complete execution path of a request across multiple
operations.
Checkpoint: Checkpoint:
description: Checkpoint created during training runs description: Checkpoint created during training runs
title: Checkpoint title: Checkpoint
@ -8245,11 +8309,13 @@ components:
- OK - OK
- Error - Error
- Not Implemented - Not Implemented
title: HealthStatus description: Current health status of the service
additionalProperties: false additionalProperties: false
required: required:
- status - status
title: HealthInfo title: HealthInfo
description: >-
Health status information for the service.
RAGDocument: RAGDocument:
type: object type: object
properties: properties:
@ -8808,18 +8874,25 @@ components:
properties: properties:
route: route:
type: string type: string
description: The API endpoint path
method: method:
type: string type: string
description: HTTP method for the route
provider_types: provider_types:
type: array type: array
items: items:
type: string type: string
description: >-
List of provider types that implement this route
additionalProperties: false additionalProperties: false
required: required:
- route - route
- method - method
- provider_types - provider_types
title: RouteInfo title: RouteInfo
description: >-
Information about an API route including its path, method, and implementing
providers.
ListRoutesResponse: ListRoutesResponse:
type: object type: object
properties: properties:
@ -8827,10 +8900,14 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/RouteInfo' $ref: '#/components/schemas/RouteInfo'
description: >-
List of available route information objects
additionalProperties: false additionalProperties: false
required: required:
- data - data
title: ListRoutesResponse title: ListRoutesResponse
description: >-
Response containing a list of all available API routes.
ListToolDefsResponse: ListToolDefsResponse:
type: object type: object
properties: properties:
@ -8925,6 +9002,8 @@ components:
- structured_log - structured_log
- metric - metric
title: EventType title: EventType
description: >-
The type of telemetry event being logged.
LogSeverity: LogSeverity:
type: string type: string
enum: enum:
@ -8935,16 +9014,22 @@ components:
- error - error
- critical - critical
title: LogSeverity title: LogSeverity
description: The severity level of a log message.
MetricEvent: MetricEvent:
type: object type: object
properties: properties:
trace_id: trace_id:
type: string type: string
description: >-
Unique identifier for the trace this event belongs to
span_id: span_id:
type: string type: string
description: >-
Unique identifier for the span this event belongs to
timestamp: timestamp:
type: string type: string
format: date-time format: date-time
description: Timestamp when the event occurred
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -8954,18 +9039,26 @@ components:
- type: number - type: number
- type: boolean - type: boolean
- type: 'null' - type: 'null'
description: >-
(Optional) Key-value pairs containing additional metadata about the event
type: type:
$ref: '#/components/schemas/EventType' $ref: '#/components/schemas/EventType'
const: metric const: metric
default: metric default: metric
description: Event type identifier set to METRIC
metric: metric:
type: string type: string
description: The name of the metric being measured
value: value:
oneOf: oneOf:
- type: integer - type: integer
- type: number - type: number
description: >-
The numeric value of the metric measurement
unit: unit:
type: string type: string
description: >-
The unit of measurement for the metric value
additionalProperties: false additionalProperties: false
required: required:
- trace_id - trace_id
@ -8976,6 +9069,8 @@ components:
- value - value
- unit - unit
title: MetricEvent title: MetricEvent
description: >-
A metric event containing a measured value.
SpanEndPayload: SpanEndPayload:
type: object type: object
properties: properties:
@ -8983,13 +9078,17 @@ components:
$ref: '#/components/schemas/StructuredLogType' $ref: '#/components/schemas/StructuredLogType'
const: span_end const: span_end
default: span_end default: span_end
description: Payload type identifier set to SPAN_END
status: status:
$ref: '#/components/schemas/SpanStatus' $ref: '#/components/schemas/SpanStatus'
description: >-
The final status of the span indicating success or failure
additionalProperties: false additionalProperties: false
required: required:
- type - type
- status - status
title: SpanEndPayload title: SpanEndPayload
description: Payload for a span end event.
SpanStartPayload: SpanStartPayload:
type: object type: object
properties: properties:
@ -8997,25 +9096,37 @@ components:
$ref: '#/components/schemas/StructuredLogType' $ref: '#/components/schemas/StructuredLogType'
const: span_start const: span_start
default: span_start default: span_start
description: >-
Payload type identifier set to SPAN_START
name: name:
type: string type: string
description: >-
Human-readable name describing the operation this span represents
parent_span_id: parent_span_id:
type: string type: string
description: >-
(Optional) Unique identifier for the parent span, if this is a child span
additionalProperties: false additionalProperties: false
required: required:
- type - type
- name - name
title: SpanStartPayload title: SpanStartPayload
description: Payload for a span start event.
StructuredLogEvent: StructuredLogEvent:
type: object type: object
properties: properties:
trace_id: trace_id:
type: string type: string
description: >-
Unique identifier for the trace this event belongs to
span_id: span_id:
type: string type: string
description: >-
Unique identifier for the span this event belongs to
timestamp: timestamp:
type: string type: string
format: date-time format: date-time
description: Timestamp when the event occurred
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -9025,12 +9136,18 @@ components:
- type: number - type: number
- type: boolean - type: boolean
- type: 'null' - type: 'null'
description: >-
(Optional) Key-value pairs containing additional metadata about the event
type: type:
$ref: '#/components/schemas/EventType' $ref: '#/components/schemas/EventType'
const: structured_log const: structured_log
default: structured_log default: structured_log
description: >-
Event type identifier set to STRUCTURED_LOG
payload: payload:
$ref: '#/components/schemas/StructuredLogPayload' $ref: '#/components/schemas/StructuredLogPayload'
description: >-
The structured payload data for the log event
additionalProperties: false additionalProperties: false
required: required:
- trace_id - trace_id
@ -9039,6 +9156,8 @@ components:
- type - type
- payload - payload
title: StructuredLogEvent title: StructuredLogEvent
description: >-
A structured log event containing typed payload data.
StructuredLogPayload: StructuredLogPayload:
oneOf: oneOf:
- $ref: '#/components/schemas/SpanStartPayload' - $ref: '#/components/schemas/SpanStartPayload'
@ -9054,16 +9173,23 @@ components:
- span_start - span_start
- span_end - span_end
title: StructuredLogType title: StructuredLogType
description: >-
The type of structured log event payload.
UnstructuredLogEvent: UnstructuredLogEvent:
type: object type: object
properties: properties:
trace_id: trace_id:
type: string type: string
description: >-
Unique identifier for the trace this event belongs to
span_id: span_id:
type: string type: string
description: >-
Unique identifier for the span this event belongs to
timestamp: timestamp:
type: string type: string
format: date-time format: date-time
description: Timestamp when the event occurred
attributes: attributes:
type: object type: object
additionalProperties: additionalProperties:
@ -9073,14 +9199,20 @@ components:
- type: number - type: number
- type: boolean - type: boolean
- type: 'null' - type: 'null'
description: >-
(Optional) Key-value pairs containing additional metadata about the event
type: type:
$ref: '#/components/schemas/EventType' $ref: '#/components/schemas/EventType'
const: unstructured_log const: unstructured_log
default: unstructured_log default: unstructured_log
description: >-
Event type identifier set to UNSTRUCTURED_LOG
message: message:
type: string type: string
description: The log message text
severity: severity:
$ref: '#/components/schemas/LogSeverity' $ref: '#/components/schemas/LogSeverity'
description: The severity level of the log message
additionalProperties: false additionalProperties: false
required: required:
- trace_id - trace_id
@ -9090,6 +9222,8 @@ components:
- message - message
- severity - severity
title: UnstructuredLogEvent title: UnstructuredLogEvent
description: >-
An unstructured log event containing a simple text message.
LogEventRequest: LogEventRequest:
type: object type: object
properties: properties:
@ -11065,8 +11199,10 @@ components:
properties: properties:
name: name:
type: string type: string
description: The name of the label to match
value: value:
type: string type: string
description: The value to match against
operator: operator:
type: string type: string
enum: enum:
@ -11074,7 +11210,8 @@ components:
- '!=' - '!='
- =~ - =~
- '!~' - '!~'
title: MetricLabelOperator description: >-
The comparison operator to use for matching
default: '=' default: '='
additionalProperties: false additionalProperties: false
required: required:
@ -11082,6 +11219,8 @@ components:
- value - value
- operator - operator
title: MetricLabelMatcher title: MetricLabelMatcher
description: >-
A matcher for filtering metrics by label values.
description: >- description: >-
The label matchers to apply to the metric. The label matchers to apply to the metric.
additionalProperties: false additionalProperties: false
@ -11094,44 +11233,59 @@ components:
properties: properties:
timestamp: timestamp:
type: integer type: integer
description: >-
Unix timestamp when the metric value was recorded
value: value:
type: number type: number
description: >-
The numeric value of the metric at this timestamp
additionalProperties: false additionalProperties: false
required: required:
- timestamp - timestamp
- value - value
title: MetricDataPoint title: MetricDataPoint
description: >-
A single data point in a metric time series.
MetricLabel: MetricLabel:
type: object type: object
properties: properties:
name: name:
type: string type: string
description: The name of the label
value: value:
type: string type: string
description: The value of the label
additionalProperties: false additionalProperties: false
required: required:
- name - name
- value - value
title: MetricLabel title: MetricLabel
description: A label associated with a metric.
MetricSeries: MetricSeries:
type: object type: object
properties: properties:
metric: metric:
type: string type: string
description: The name of the metric
labels: labels:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricLabel' $ref: '#/components/schemas/MetricLabel'
description: >-
List of labels associated with this metric series
values: values:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricDataPoint' $ref: '#/components/schemas/MetricDataPoint'
description: >-
List of data points in chronological order
additionalProperties: false additionalProperties: false
required: required:
- metric - metric
- labels - labels
- values - values
title: MetricSeries title: MetricSeries
description: A time series of metric data points.
QueryMetricsResponse: QueryMetricsResponse:
type: object type: object
properties: properties:
@ -11139,17 +11293,23 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/MetricSeries' $ref: '#/components/schemas/MetricSeries'
description: >-
List of metric series matching the query criteria
additionalProperties: false additionalProperties: false
required: required:
- data - data
title: QueryMetricsResponse title: QueryMetricsResponse
description: >-
Response containing metric time series data.
QueryCondition: QueryCondition:
type: object type: object
properties: properties:
key: key:
type: string type: string
description: The attribute key to filter on
op: op:
$ref: '#/components/schemas/QueryConditionOp' $ref: '#/components/schemas/QueryConditionOp'
description: The comparison operator to apply
value: value:
oneOf: oneOf:
- type: 'null' - type: 'null'
@ -11158,12 +11318,14 @@ components:
- type: string - type: string
- type: array - type: array
- type: object - type: object
description: The value to compare against
additionalProperties: false additionalProperties: false
required: required:
- key - key
- op - op
- value - value
title: QueryCondition title: QueryCondition
description: A condition for filtering query results.
QueryConditionOp: QueryConditionOp:
type: string type: string
enum: enum:
@ -11172,6 +11334,8 @@ components:
- gt - gt
- lt - lt
title: QueryConditionOp title: QueryConditionOp
description: >-
Comparison operators for query conditions.
QuerySpansRequest: QuerySpansRequest:
type: object type: object
properties: properties:
@ -11201,10 +11365,13 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/Span' $ref: '#/components/schemas/Span'
description: >-
List of spans matching the query criteria
additionalProperties: false additionalProperties: false
required: required:
- data - data
title: QuerySpansResponse title: QuerySpansResponse
description: Response containing a list of spans.
QueryTracesRequest: QueryTracesRequest:
type: object type: object
properties: properties:
@ -11234,10 +11401,13 @@ components:
type: array type: array
items: items:
$ref: '#/components/schemas/Trace' $ref: '#/components/schemas/Trace'
description: >-
List of traces matching the query criteria
additionalProperties: false additionalProperties: false
required: required:
- data - data
title: QueryTracesResponse title: QueryTracesResponse
description: Response containing a list of traces.
RegisterBenchmarkRequest: RegisterBenchmarkRequest:
type: object type: object
properties: properties:
@ -11858,10 +12028,12 @@ components:
properties: properties:
version: version:
type: string type: string
description: Version number of the service
additionalProperties: false additionalProperties: false
required: required:
- version - version
title: VersionInfo title: VersionInfo
description: Version information for the service.
responses: responses:
BadRequest400: BadRequest400:
description: The request was invalid or malformed description: The request was invalid or malformed

28
llama_stack/apis/inspect/inspect.py
View file

@ -14,6 +14,12 @@ from llama_stack.schema_utils import json_schema_type, webmethod
@json_schema_type @json_schema_type
class RouteInfo(BaseModel): 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 route: str
method: str method: str
provider_types: list[str] provider_types: list[str]
@ -21,15 +27,27 @@ class RouteInfo(BaseModel):
@json_schema_type @json_schema_type
class HealthInfo(BaseModel): class HealthInfo(BaseModel):
"""Health status information for the service.
:param status: Current health status of the service
"""
status: HealthStatus status: HealthStatus
@json_schema_type @json_schema_type
class VersionInfo(BaseModel): class VersionInfo(BaseModel):
"""Version information for the service.
:param version: Version number of the service
"""
version: str version: str
class ListRoutesResponse(BaseModel): class ListRoutesResponse(BaseModel):
"""Response containing a list of all available API routes.
:param data: List of available route information objects
"""
data: list[RouteInfo] data: list[RouteInfo]
@ -37,17 +55,17 @@ class ListRoutesResponse(BaseModel):
class Inspect(Protocol): class Inspect(Protocol):
@webmethod(route="/inspect/routes", method="GET") @webmethod(route="/inspect/routes", method="GET")
async def list_routes(self) -> ListRoutesResponse: 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") @webmethod(route="/health", method="GET")
async def health(self) -> HealthInfo: 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: async def version(self) -> VersionInfo:
"""Get the version of the service. """Get the version of the service.
:returns: A VersionInfo. :returns: Version information containing the service version number.
""" """
... ...

163
llama_stack/apis/telemetry/telemetry.py
View file

@ -25,12 +25,27 @@ DEFAULT_TTL_DAYS = 7
@json_schema_type @json_schema_type
class SpanStatus(Enum): 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" OK = "ok"
ERROR = "error" ERROR = "error"
@json_schema_type @json_schema_type
class Span(BaseModel): 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 span_id: str
trace_id: str trace_id: str
parent_span_id: str | None = None parent_span_id: str | None = None
@ -47,6 +62,13 @@ class Span(BaseModel):
@json_schema_type @json_schema_type
class Trace(BaseModel): 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 trace_id: str
root_span_id: str root_span_id: str
start_time: datetime start_time: datetime
@ -55,6 +77,12 @@ class Trace(BaseModel):
@json_schema_type @json_schema_type
class EventType(Enum): 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" UNSTRUCTURED_LOG = "unstructured_log"
STRUCTURED_LOG = "structured_log" STRUCTURED_LOG = "structured_log"
METRIC = "metric" METRIC = "metric"
@ -62,6 +90,15 @@ class EventType(Enum):
@json_schema_type @json_schema_type
class LogSeverity(Enum): 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" VERBOSE = "verbose"
DEBUG = "debug" DEBUG = "debug"
INFO = "info" INFO = "info"
@ -71,6 +108,13 @@ class LogSeverity(Enum):
class EventCommon(BaseModel): 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 trace_id: str
span_id: str span_id: str
timestamp: datetime timestamp: datetime
@ -79,6 +123,12 @@ class EventCommon(BaseModel):
@json_schema_type @json_schema_type
class UnstructuredLogEvent(EventCommon): 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 type: Literal[EventType.UNSTRUCTURED_LOG] = EventType.UNSTRUCTURED_LOG
message: str message: str
severity: LogSeverity severity: LogSeverity
@ -86,6 +136,13 @@ class UnstructuredLogEvent(EventCommon):
@json_schema_type @json_schema_type
class MetricEvent(EventCommon): 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 type: Literal[EventType.METRIC] = EventType.METRIC
metric: str # this would be an enum metric: str # this would be an enum
value: int | float value: int | float
@ -94,6 +151,12 @@ class MetricEvent(EventCommon):
@json_schema_type @json_schema_type
class MetricInResponse(BaseModel): 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 metric: str
value: int | float value: int | float
unit: str | None = None unit: str | None = None
@ -120,17 +183,32 @@ class MetricInResponse(BaseModel):
class MetricResponseMixin(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 metrics: list[MetricInResponse] | None = None
@json_schema_type @json_schema_type
class StructuredLogType(Enum): 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_START = "span_start"
SPAN_END = "span_end" SPAN_END = "span_end"
@json_schema_type @json_schema_type
class SpanStartPayload(BaseModel): 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 type: Literal[StructuredLogType.SPAN_START] = StructuredLogType.SPAN_START
name: str name: str
parent_span_id: str | None = None parent_span_id: str | None = None
@ -138,6 +216,11 @@ class SpanStartPayload(BaseModel):
@json_schema_type @json_schema_type
class SpanEndPayload(BaseModel): 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 type: Literal[StructuredLogType.SPAN_END] = StructuredLogType.SPAN_END
status: SpanStatus status: SpanStatus
@ -151,6 +234,11 @@ register_schema(StructuredLogPayload, name="StructuredLogPayload")
@json_schema_type @json_schema_type
class StructuredLogEvent(EventCommon): 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 type: Literal[EventType.STRUCTURED_LOG] = EventType.STRUCTURED_LOG
payload: StructuredLogPayload payload: StructuredLogPayload
@ -164,6 +252,14 @@ register_schema(Event, name="Event")
@json_schema_type @json_schema_type
class EvalTrace(BaseModel): 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 session_id: str
step: str step: str
input: str input: str
@ -173,11 +269,22 @@ class EvalTrace(BaseModel):
@json_schema_type @json_schema_type
class SpanWithStatus(Span): class SpanWithStatus(Span):
"""A span that includes status information.
:param status: (Optional) The current status of the span
"""
status: SpanStatus | None = None status: SpanStatus | None = None
@json_schema_type @json_schema_type
class QueryConditionOp(Enum): 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" EQ = "eq"
NE = "ne" NE = "ne"
GT = "gt" GT = "gt"
@ -186,29 +293,59 @@ class QueryConditionOp(Enum):
@json_schema_type @json_schema_type
class QueryCondition(BaseModel): 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 key: str
op: QueryConditionOp op: QueryConditionOp
value: Any value: Any
class QueryTracesResponse(BaseModel): class QueryTracesResponse(BaseModel):
"""Response containing a list of traces.
:param data: List of traces matching the query criteria
"""
data: list[Trace] data: list[Trace]
class QuerySpansResponse(BaseModel): class QuerySpansResponse(BaseModel):
"""Response containing a list of spans.
:param data: List of spans matching the query criteria
"""
data: list[Span] data: list[Span]
class QuerySpanTreeResponse(BaseModel): 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] data: dict[str, SpanWithStatus]
class MetricQueryType(Enum): 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" RANGE = "range"
INSTANT = "instant" INSTANT = "instant"
class MetricLabelOperator(Enum): 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 = "=" EQUALS = "="
NOT_EQUALS = "!=" NOT_EQUALS = "!="
REGEX_MATCH = "=~" REGEX_MATCH = "=~"
@ -216,6 +353,12 @@ class MetricLabelOperator(Enum):
class MetricLabelMatcher(BaseModel): 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 name: str
value: str value: str
operator: MetricLabelOperator = MetricLabelOperator.EQUALS operator: MetricLabelOperator = MetricLabelOperator.EQUALS
@ -223,24 +366,44 @@ class MetricLabelMatcher(BaseModel):
@json_schema_type @json_schema_type
class MetricLabel(BaseModel): 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 name: str
value: str value: str
@json_schema_type @json_schema_type
class MetricDataPoint(BaseModel): 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 timestamp: int
value: float value: float
@json_schema_type @json_schema_type
class MetricSeries(BaseModel): 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 metric: str
labels: list[MetricLabel] labels: list[MetricLabel]
values: list[MetricDataPoint] values: list[MetricDataPoint]
class QueryMetricsResponse(BaseModel): class QueryMetricsResponse(BaseModel):
"""Response containing metric time series data.
:param data: List of metric series matching the query criteria
"""
data: list[MetricSeries] data: list[MetricSeries]