Trace management endpoints. A Trace provides a mechanism similar to OpenTelemetry for tracking the execution flow of a task. It allows you to monitor and analyze the sequence of operations, their timings, and other related metrics. Tracing is essential for performance monitoring and debugging.
openapi: 3.2.0
info:
title: PhariaStudio Traces API
version: 0.1.0
description: Trace management endpoints. A Trace provides a mechanism similar to OpenTelemetry for tracking the execution flow of a task. It allows you to monitor and analyze the sequence of operations, their timings, and other related metrics. Tracing is essential for performance monitoring and debugging.
servers:
- url: '{host}/v1/studio'
variables:
host:
default: https://api.pharia.example.com
security:
- BearerAuth: []
tags:
- name: Traces
description: Trace management endpoints. A Trace provides a mechanism similar to OpenTelemetry for tracking the execution flow of a task. It allows you to monitor and analyze the sequence of operations, their timings, and other related metrics. Tracing is essential for performance monitoring and debugging.
paths:
/projects/{project_id}/traces:
post:
tags:
- Traces
summary: Create Trace
description: Create a new `Trace`. All submitted spans must have the same trace id.
operationId: create_trace_projects__project_id__traces_post
parameters:
- name: project_id
in: path
required: true
schema:
type: string
format: uuid
title: Project Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SingularTraceSpanList'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: string
format: uuid
title: Response Create Trace Projects Project Id Traces Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- Traces
summary: Get Many Traces
description: List paginated `Traces`.
operationId: get_many_traces_projects__project_id__traces_get
parameters:
- name: project_id
in: path
required: true
schema:
type: string
format: uuid
title: Project Id
- name: page
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: The page number to retrieve. Starts at 1.
default: 1
title: Page
description: The page number to retrieve. Starts at 1.
- name: size
in: query
required: false
schema:
type: integer
maximum: 100
exclusiveMinimum: 0
description: The number of items per page.
default: 25
title: Size
description: The number of items per page.
- name: only_root
in: query
required: false
schema:
type: boolean
description: Return only the root span instead of all spans
default: false
title: Only Root
description: Return only the root span instead of all spans
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PagedResponse_TraceResponse_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/projects/{project_id}/traces/{trace_id}:
get:
tags:
- Traces
summary: Get Trace
description: Get a `Trace` by its id.
operationId: get_trace_projects__project_id__traces__trace_id__get
parameters:
- name: project_id
in: path
required: true
schema:
type: string
format: uuid
title: Project Id
- name: trace_id
in: path
required: true
schema:
type: string
format: uuid
title: Trace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TraceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TraceResponse:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The timestamp when this resource was created in UTC.
created_by:
type: string
title: Created By
description: The ID of the user that created the resource.
examples:
- '12345'
id:
type: string
format: uuid
title: Id
description: A unique id for the opened `Trace`.
examples:
- 123e4567-e89b-12d3-a456-426614174000
spans:
items:
$ref: '#/components/schemas/SpanResponse-Output'
type: array
title: Spans
type: object
required:
- created_at
- created_by
- id
- spans
title: TraceResponse
description: A trace represents a single tree of spans.
SpanResponse-Output:
properties:
created_at:
type: string
format: date-time
title: Created At
description: The timestamp when this resource was created in UTC.
created_by:
type: string
title: Created By
description: The ID of the user that created the resource.
examples:
- '12345'
id:
type: string
format: uuid
title: Id
description: The unique id of the span.
examples:
- 123e4567-e89b-12d3-a456-426614174000
parent_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Parent Id
description: The unique id of the parent element of the span.
examples:
- 123e4567-e89b-12d3-a456-426614174000
name:
type: string
title: Name
description: The name of the span.
examples:
- Span
start_time:
type: string
format: date-time
title: Start Time
description: The timestamp when this span was started.
examples:
- '2024-01-01 12:34:56.123456+00:00'
end_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: End Time
description: The timestamp when this span was ended.
examples:
- '2024-01-01 12:34:56.123456+00:00'
status:
$ref: '#/components/schemas/SpanStatus'
description: The status code of the span.
examples:
- OK
type:
$ref: '#/components/schemas/SpanType'
description: The type of the span.
examples:
- TaskSpan
attributes:
additionalProperties:
$ref: '#/components/schemas/JsonSerializable-Output'
type: object
title: Attributes
description: The `Attributes` of the `Span`.
examples:
- key: value
type: object
required:
- created_at
- created_by
- id
- parent_id
- name
- start_time
- end_time
- status
- type
- attributes
title: SpanResponse
Context:
properties:
trace_id:
type: string
format: uuid
title: Trace Id
span_id:
type: string
format: uuid
title: Span Id
type: object
required:
- trace_id
- span_id
title: Context
SpanRequest:
properties:
context:
$ref: '#/components/schemas/Context'
name:
anyOf:
- type: string
- type: 'null'
title: Name
parent_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Parent Id
start_time:
type: string
format: date-time
title: Start Time
end_time:
type: string
format: date-time
title: End Time
attributes:
oneOf:
- $ref: '#/components/schemas/SpanAttributes'
- $ref: '#/components/schemas/TaskSpanAttributes'
title: Attributes
discriminator:
propertyName: type
mapping:
SPAN: '#/components/schemas/SpanAttributes'
TASK_SPAN: '#/components/schemas/TaskSpanAttributes'
events:
items:
$ref: '#/components/schemas/Event'
type: array
title: Events
status:
$ref: '#/components/schemas/SpanStatus'
type: object
required:
- context
- name
- parent_id
- start_time
- end_time
- attributes
- events
- status
title: SpanRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
SpanType:
type: string
enum:
- SPAN
- TASK_SPAN
title: SpanType
TaskSpanAttributes:
properties:
type:
type: string
const: TASK_SPAN
title: Type
default: TASK_SPAN
input:
$ref: '#/components/schemas/JsonSerializable-Input'
output:
$ref: '#/components/schemas/JsonSerializable-Input'
type: object
required:
- input
- output
title: TaskSpanAttributes
SpanAttributes:
properties:
type:
type: string
const: SPAN
title: Type
default: SPAN
type: object
title: SpanAttributes
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SingularTraceSpanList:
items:
$ref: '#/components/schemas/SpanRequest'
type: array
title: SingularTraceSpanList
PagedResponse_TraceResponse_:
properties:
total:
type: integer
title: Total
page:
type: integer
title: Page
size:
type: integer
title: Size
num_pages:
type: integer
title: Num Pages
items:
items:
$ref: '#/components/schemas/TraceResponse'
type: array
title: Items
default: []
type: object
required:
- total
- page
- size
- num_pages
title: PagedResponse[TraceResponse]
Event:
properties:
name:
type: string
title: Name
message:
type: string
title: Message
body:
$ref: '#/components/schemas/JsonSerializable-Input'
timestamp:
type: string
format: date-time
title: Timestamp
type: object
required:
- name
- message
- body
title: Event
JsonSerializable-Input:
anyOf:
- type: integer
- type: number
- type: string
- type: boolean
- items:
$ref: '#/components/schemas/JsonSerializable-Input'
type: array
- additionalProperties:
$ref: '#/components/schemas/JsonSerializable-Input'
type: object
- type: 'null'
JsonSerializable-Output:
anyOf:
- type: integer
- type: number
- type: string
- type: boolean
- items:
$ref: '#/components/schemas/JsonSerializable-Output'
type: array
- additionalProperties:
$ref: '#/components/schemas/JsonSerializable-Output'
type: object
- type: 'null'
SpanStatus:
type: string
enum:
- ERROR
- OK
- ACTIVE
title: SpanStatus
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT