Skip to main content
A BackendEvent is the fundamental unit of observability in OTAS. Each time your backend middleware or an agent logs an API call, OTAS creates one BackendEvent record. These records are the raw material for dashboards, latency analysis, error tracking, and session replay.

​
Event fields

​
Identity and timing

​
event_id
UUID
Auto-generated UUID primary key for the event.
​
event_time
datetime
The timestamp of the API call. Defaults to the time OTAS receives the log request. You can override this to preserve the original call time.
​
event_date
date
Auto-derived from event_time. Used to partition and index events efficiently for date-range queries.

​
Context

​
project_id
string
required
UUID of the project this event belongs to. Resolved automatically from the SDK key or agent key used to log it.
​
agent_id
string
UUID of the agent that made the call. Optional when logging via the Backend SDK without a specific agent context.
​
agent_session_id
string
UUID of the session this event belongs to. Provide this to group all calls from one agent task or run together.

​
Request

​
path
string
required
The URL path of the API call, e.g., /v1/messages or https://api.openai.com/v1/chat/completions.
​
method
string
required
HTTP method: GET, POST, PUT, PATCH, DELETE, etc.
​
status_code
integer
required
HTTP status code returned by the upstream API, e.g., 200, 429, 500.
​
request_headers
string
Serialized request headers. Omit or redact authorization headers before logging.
​
request_body
string
Raw request body as a string.
​
query_params
string
URL query parameters as a serialized string.
​
post_data
string
Form-encoded POST data, when applicable.
​
request_content_type
string
Value of the request Content-Type header, e.g., application/json.
​
request_size_bytes
integer
Size of the request body in bytes. Defaults to 0.

​
Response

​
response_headers
string
Serialized response headers.
​
response_body
string
Raw response body as a string.
​
response_content_type
string
Value of the response Content-Type header.
​
response_size_bytes
integer
Size of the response body in bytes. Defaults to 0.

​
Performance and diagnostics

​
latency_ms
float
required
End-to-end latency in milliseconds from when your agent sent the request to when it received the response.
​
error
string
A non-null value marks this event as an error. Set this to any error message, exception type, or structured string when the call fails or your agent raises an exception.
​
metadata
JSON
Arbitrary JSON for any structured context you want to attach to the event that doesn’t fit another field.
​
custom_properties
JSON
Additional key-value pairs for filtering and grouping events in the dashboard, e.g., { "model": "claude-3-5-sonnet", "temperature": 0.7 }.

​
Required vs. optional fields

Required when logging an event:
  • project_id
  • path
  • method
  • status_code
  • latency_ms
Everything else is optional, though providing agent_id, agent_session_id, request_body, response_body, and error gives you the most complete observability picture.

​
Two sources of events

Server-side middleware authenticates with X-OTAS-SDK-KEY and logs events on behalf of agents. The project is resolved from the key. Use this approach when you have a proxy or middleware layer that intercepts all outbound API calls from your service.
POST http://localhost:8002/api/v1/backend/log/sdk/
X-OTAS-SDK-KEY: otas_<prefix>_<secret>
X-OTAS-AGENT-SESSION-TOKEN: <session-jwt>

{
  "project_id": "<project-uuid>",
  "agent_id": "<agent-uuid>",
  "path": "/v1/messages",
  "method": "POST",
  "status_code": 200,
  "latency_ms": 843.2
}

​
Error detection

OTAS treats an event as an error when the error field is non-null and non-empty. You control what counts as an error: set this field to the exception message, an error code, or any descriptive string when a call fails or your agent catches an exception.
Log errors even when the HTTP status code is 200. Some LLM APIs return 200 with an error payload inside the response body. Use the error field to capture these cases explicitly.

Build docs developers (and LLMs) love

Get started for freeTalk to us