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

​
UUID
Auto-generated UUID primary key for the event.
​
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.
​
date
Auto-derived from event_time. Used to partition and index events efficiently for date-range queries.

​
Context

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

​
Request

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

​
Response

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

​
Performance and diagnostics

​
float
required
End-to-end latency in milliseconds from when your agent sent the request to when it received the response.
​
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.
​
JSON
Arbitrary JSON for any structured context you want to attach to the event that doesn’t fit another field.
​
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.

​
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.