> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Record Trace Log
> Log a (LLM) span to visualize inference results, or chains.
```bash Regular Log theme={null}
curl --location 'https://parea-ai-backend-us-9ac16cdbc7a7b006.onporter.run/api/parea/v1/trace_log' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <>' \
--data '{
"trace_id": "<>",
"root_trace_id": "<>",
"parent_trace_id": "<>",
"trace_name":"test",
"project_name":"default",
"inputs": {
"x": "Golang",
"y": "Fiber"
},
"start_timestamp":"2024-05-30 13:48:34",
"end_timestamp":"2024-05-30 13:48:35",
"status": "success",
"output": "Some logged output",
"metadata": {"purpose": "testing"}
}'
```
```bash LLM Log theme={null}
curl --location 'https://parea-ai-backend-us-9ac16cdbc7a7b006.onporter.run/api/parea/v1/trace_log' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <>' \
--data '{
"trace_id": "<>",
"root_trace_id": "<>",
"parent_trace_id": "<>",
"trace_name": "LLM",
"project_name": "default",
"inputs": {
"promptTemplateVar1": "value",
"promptTemplateVar2": "some other value"
},
"output": "LLM repsonse",
"configuration": {
"model": "gpt-4o",
"provider": "openai",
"messages": [
{
"role": "user",
"content": "Some prompt"
}
]
},
"start_timestamp": "2024-05-30 13:48:34",
"end_timestamp": "2024-05-30 13:48:35",
"status": "success",
"metadata": {"purpose": "testing"}
}'
```
## OpenAPI
````yaml post /api/parea/v1/trace_log
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers: []
security: []
paths:
/api/parea/v1/trace_log:
post:
summary: Record Trace Log
description: Log a (LLM) span to visualize inference results, or chains.
operationId: record_trace_log_api_parea_v1_trace_log_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TraceLogSchema'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- APIKeyHeader: []
- APIKeyHeader: []
components:
schemas:
TraceLogSchema:
properties:
configuration:
allOf:
- $ref: '#/components/schemas/InputsSchema-Input'
description: >-
If this log was a LLM call, this will contain the configuration used
for the call.
default: {}
inputs:
anyOf:
- type: object
- type: 'null'
title: Inputs
description: >-
Key-value pair inputs of this trace. Note, there is a special field
to capture messages in LLM calls. You can still use it in the case
of LLM calls to track the key-value pairs for prompt templates.
output:
anyOf:
- type: string
- type: 'null'
title: Output
description: >-
Response of this step/log/function. If response isn’t a string, it
needs to be serialized to a string.
target:
anyOf:
- type: string
- type: 'null'
title: Target
description: "The target or “gold standardâ€\x9D response for the inputs of this log."
latency:
anyOf:
- type: number
- type: 'null'
title: Latency
description: Latency of this log in seconds.
default: 0
time_to_first_token:
anyOf:
- type: number
- type: 'null'
title: Time To First Token
description: >-
If this was a LLM call, this will contain the time taken to generate
the first token.
input_tokens:
anyOf:
- type: integer
- type: 'null'
title: Input Tokens
description: >-
If this was a LLM call, this will contain the number of tokens in
the input.
default: 0
output_tokens:
anyOf:
- type: integer
- type: 'null'
title: Output Tokens
description: >-
If this was a LLM call, this will contain the number of tokens in
the output.
default: 0
total_tokens:
anyOf:
- type: integer
- type: 'null'
title: Total Tokens
description: >-
If this was a LLM call, this will contain the total number of tokens
in the input and output.
default: 0
cost:
anyOf:
- type: number
- type: 'null'
title: Cost
description: If this was a LLM call, this will contain the cost of the call.
default: 0
trace_id:
type: string
title: Trace Id
description: 'UUID of the trace log. Ex: e3267953-a16f-47f5-b37e-622dbb29d730'
start_timestamp:
type: string
title: Start Timestamp
description: Start timestamp
parent_trace_id:
anyOf:
- type: string
- type: 'null'
title: Parent Trace Id
description: >-
If given, current trace will be a child of this trace. If current
child is not a child, `parent_trace_id` should be equal to
`trace_id`
root_trace_id:
anyOf:
- type: string
- type: 'null'
title: Root Trace Id
description: >-
This is the UUID of the root trace/span of this trace. If current
trace is the root trace, `root_trace_id` must be equal to `trace_id`
project_name:
anyOf:
- type: string
- type: 'null'
title: Project Name
description: >-
Name of the project with which the trace/log should be associated
with. Must be provided if `project_uuid` is not provided
status:
anyOf:
- type: string
- type: 'null'
title: Status
description: If the trace was a `success` or `error`
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: >-
If `status=error`, this should contain any additional information
such as the stacktrace
output_for_eval_metrics:
anyOf:
- type: string
- type: 'null'
title: Output For Eval Metrics
description: >-
If provided, will be used as output for any specified evaluation
metric.
evaluation_metric_names:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Evaluation Metric Names
description: >-
Names of evaluation metrics deployed on Parea which should be
applied to this log.
scores:
anyOf:
- items:
$ref: '#/components/schemas/EvaluationScoreSchema'
type: array
- type: 'null'
title: Scores
description: Any scores/eval results associated with this log.
feedback_score:
anyOf:
- type: number
- type: 'null'
title: Feedback Score
description: Any captured (user) feedback on this log
apply_eval_frac:
anyOf:
- type: number
- type: 'null'
title: Apply Eval Frac
description: >-
If specified, evals given with `evaluation_metric_names` will be
applied to this log with this fraction.
default: 1
log_sample_rate:
anyOf:
- type: number
maximum: 1
minimum: 0
- type: 'null'
title: Log Sample Rate
description: >-
If specified, this log and its entire associated trace will logged
with this probability. Must be between 0 and 1 (incl.). Defaults to
1.0 (i.e., keeping all logs)
default: 1
deployment_id:
anyOf:
- type: string
- type: 'null'
title: Deployment Id
description: Optionally, provide the ID of the used deployed prompt in this log.
cache_hit:
type: boolean
title: Cache Hit
description: If the cache was hit for this log.
default: false
trace_name:
anyOf:
- type: string
- type: 'null'
title: Trace Name
description: The name of this span.
children:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Children
description: UUIDs of any children.
children_ids:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Children Ids
description: IDs of any children. Will be automatically populated.
end_timestamp:
anyOf:
- type: string
- type: 'null'
title: End Timestamp
description: End timestamp of span.
end_user_identifier:
anyOf:
- type: string
- type: 'null'
title: End User Identifier
description: Unique identifier for a end-user.
session_id:
anyOf:
- type: string
- type: 'null'
title: Session Id
description: >-
Unique identifier for a session. Can you be used to associated
multiple logs in e.g. chat applications.
metadata:
anyOf:
- type: object
- type: 'null'
title: Metadata
description: >-
Any additional key-value pairs which provide context or are useful
for filtering.
tags:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Tags
description: >-
List of tags which provide additional context or are useful for
filtering.
experiment_uuid:
anyOf:
- type: string
- type: 'null'
title: Experiment Uuid
description: If given, will be used to associate this log with an experiment.
images:
anyOf:
- items:
$ref: '#/components/schemas/TraceLogImage'
type: array
- type: 'null'
title: Images
description: Any images associated with trace.
comments:
anyOf:
- items:
$ref: '#/components/schemas/TraceLogCommentSchema'
type: array
- type: 'null'
title: Comments
description: Any comments on log which were collected on Parea frontend.
annotations:
anyOf:
- additionalProperties:
additionalProperties:
$ref: '#/components/schemas/TraceLogAnnotationSchema'
type: object
type: object
- type: 'null'
title: Annotations
description: >-
Any annotations on log which were collected on Parea frontend. It
maps annoation criterion ID to a dictionary mapping user_id (Parea
user ID) to annotation.
depth:
type: integer
title: Depth
description: >-
Depth/level of nestedness of span in overall trace. Root-level trace
is 0 and it always increments by 1.
default: 0
execution_order:
type: integer
title: Execution Order
description: >-
The execution number of span in trace. It starts with 0 and
increments by 1 with every span.
default: 0
evaluation_metric_ids:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Evaluation Metric Ids
description: Deprecated
fill_children:
type: boolean
title: Fill Children
description: Deprecated
default: false
project_uuid:
anyOf:
- type: string
- type: 'null'
title: Project Uuid
description: >-
UUID of project with which this log is associated. Will be
automatically filled-in by SDKs
organization_id:
anyOf:
- type: string
- type: 'null'
title: Organization Id
description: >-
Organization ID associated with Parea API key. Will be automatically
determined from API key
type: object
required:
- trace_id
- start_timestamp
title: TraceLogSchema
examples:
- depth: 0
end_timestamp: '2024-05-30 13:48:35'
execution_order: 0
inputs:
x: Golang
'y': Fiber
metadata:
purpose: testing
output: Some logged output
parent_trace_id: <>
project_name: default
root_trace_id: <>
start_timestamp: '2024-05-30 13:48:34'
status: success
trace_id: <>
trace_name: test
- configuration:
messages:
- content: Some prompt
role: user
model: gpt-4o
provider: openai
depth: 0
end_timestamp: '2024-05-30 13:48:35'
execution_order: 0
inputs:
promptTemplateVar1: value
promptTemplateVar2: some other value
metadata:
purpose: testing
output: LLM response
parent_trace_id: <>
project_name: default
root_trace_id: <>
start_timestamp: '2024-05-30 13:48:34'
status: success
trace_id: <>
trace_name: LLM
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
InputsSchema-Input:
properties:
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: Model name
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
description: Provider name
model_params:
anyOf:
- $ref: '#/components/schemas/ParamsSchema'
- type: 'null'
description: Parameters such as temperature.
messages:
anyOf:
- items:
$ref: '#/components/schemas/MessageSchema'
type: array
- type: 'null'
title: Messages
description: Messages to LLM
functions:
anyOf:
- items: {}
type: array
- type: 'null'
title: Functions
description: >-
A list of functions the model may generate JSON inputs for. Assumes
every item in list has key 'name', 'description' and 'parameters'
function_call:
anyOf:
- type: string
- type: object
- type: 'null'
title: Function Call
description: "Controls how the model responds to function calls. “autoâ€\x9D means the model can pick between an end-user or calling a function. To specifying a particular function name use a dictionary with key=“nameâ€\x9D and value=“my_functionâ€\x9D. This will force the model to call that function."
type: object
title: InputsSchema
description: >-
Inputs for LLM inference such as messages, functions and additional
parameters.
EvaluationScoreSchema:
properties:
name:
type: string
title: Name
description: Name of the score / evaluation
score:
type: number
title: Score
description: Value of the score
evaluation_metric_id:
anyOf:
- type: integer
- type: 'null'
title: Evaluation Metric Id
description: >-
Will be automatically populated if this score was from a deployed
evaluation metric.
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: Reason for this score
type: object
required:
- name
- score
title: EvaluationScoreSchema
examples:
- name: Answer Matches Target
reason: The answer is mostly correct but lacks aspect A & B.
score: 0.8
TraceLogImage:
properties:
url:
type: string
title: Url
description: URL of image
caption:
anyOf:
- type: string
- type: 'null'
title: Caption
description: Caption of image
type: object
required:
- url
title: TraceLogImage
TraceLogCommentSchema:
properties:
trace_id:
type: string
title: Trace Id
description: Trace ID
comment:
type: string
title: Comment
description: Comment
id:
anyOf:
- type: string
- type: integer
title: Id
description: Comment ID
user_id:
type: string
title: User Id
description: User ID
user_email_address:
anyOf:
- type: string
- type: 'null'
title: User Email Address
description: User email address
created_at:
type: string
title: Created At
description: Comment creation timestamp
type: object
required:
- trace_id
- comment
- id
- user_id
- created_at
title: TraceLogCommentSchema
TraceLogAnnotationSchema:
properties:
trace_id:
type: string
title: Trace Id
description: UUID of associated trace
defined_annotation_id:
type: integer
title: Defined Annotation Id
description: Annotation criterion ID
score:
anyOf:
- type: number
- type: 'null'
title: Score
description: Annotation score
value:
anyOf:
- type: string
- type: 'null'
title: Value
description: Annotation value
id:
anyOf:
- type: string
- type: integer
- type: 'null'
title: Id
description: Annotation ID
created_at:
type: string
title: Created At
description: Annotation creation timestamp
user_id:
type: string
title: User Id
description: Parea user ID
user_email_address:
anyOf:
- type: string
- type: 'null'
title: User Email Address
description: User email address
annotation_name:
anyOf:
- type: string
- type: 'null'
title: Annotation Name
description: Annotation name
type: object
required:
- trace_id
- defined_annotation_id
- created_at
- user_id
title: TraceLogAnnotationSchema
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ParamsSchema:
properties:
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: Model name
temp:
anyOf:
- type: number
- type: 'null'
title: Temp
description: Temperature
top_p:
anyOf:
- type: number
- type: 'null'
title: Top P
description: Top p
frequency_penalty:
anyOf:
- type: number
- type: 'null'
title: Frequency Penalty
description: Frequency penalty
presence_penalty:
anyOf:
- type: number
- type: 'null'
title: Presence Penalty
description: Presence penalty
max_length:
anyOf:
- type: integer
- type: 'null'
title: Max Length
description: Max. number of completion tokens
response_format:
anyOf:
- type: object
- type: 'null'
title: Response Format
description: Response format. See OpenAI docs for definition
safe_prompt:
anyOf:
- type: boolean
- type: 'null'
title: Safe Prompt
description: Used for Mistral.
type: object
title: ParamsSchema
description: >-
Additional parameters to run inference of LLMs, such as temperature,
top_p, etc.
Following the OpenAI API format.
MessageSchema:
properties:
content:
anyOf:
- type: string
- items: {}
type: array
- type: 'null'
title: Content
description: Message content
default: ''
role:
allOf:
- $ref: '#/components/schemas/Role'
description: Message role
default: user
type: object
title: MessageSchema
Role:
type: string
enum:
- user
- assistant
- system
- user
- assistant
- function
- tool
title: Role
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-user-id
````