Query your traces, logs, metrics, and AI events using TQL, a SQL-like query language for filtering and searching the observability data Trasys collects daily.

Trasys Query Language (TQL)

TQL is a query language for searching and filtering the observability data collected by Trasys. The syntax is close to SQL but adapted for trace and event data.

This page covers the core TQL structure. Provider-specific functions, aggregation operators, and advanced query patterns are documented separately in the TQL reference.

Basic structure

SELECT <fields>
FROM   <data_source>
WHERE  <conditions>
LIMIT  <n>

Example queries

Find slow requests:

SELECT trace_id, http.route, http.duration_ms, user_id
FROM   spans
WHERE  http.duration_ms > 2000
  AND  service = 'payment-service'
  AND  time > now() - 1h
LIMIT  100

Find expensive AI calls:

SELECT trace_id, gen_ai.request.model, gen_ai.usage.input_tokens, trasys.ai.cost_usd
FROM   ai_spans
WHERE  trasys.ai.cost_usd > 0.10
  AND  time > now() - 24h
ORDER BY trasys.ai.cost_usd DESC
LIMIT  50

Find errors for a specific user:

SELECT trace_id, http.route, http.status_code, time
FROM   spans
WHERE  user_id = 'usr_abc123'
  AND  http.status_code >= 500
  AND  time > now() - 7d

Data sources

Source	Contains
`spans`	All HTTP, database, gRPC, and queue spans
`ai_spans`	AI provider calls — tokens, cost, model, finish reason
`logs`	Structured log records
`metrics`	Counter, gauge, and histogram data points
`health_checks`	Health check results over time

Filtering (WHERE)

Operator	Description
`=`, `!=`	Exact match
`>`, `>=`, `<`, `<=`	Numeric comparison
`LIKE 'pattern%'`	Prefix or pattern match
`IN ('a', 'b', 'c')`	Set membership
`IS NULL`, `IS NOT NULL`	Presence check
`AND`, `OR`, `NOT`	Boolean logic

Time filtering

WHERE time > now() - 30m      -- last 30 minutes
WHERE time > now() - 6h       -- last 6 hours
WHERE time > now() - 7d       -- last 7 days
WHERE time BETWEEN '2024-01-01' AND '2024-01-31'

Field reference

Spans

Field	Type	Description
`trace_id`	string	W3C trace ID
`span_id`	string	Span ID
`service`	string	Service name
`http.route`	string	Normalized route, e.g. `/users/:id`
`http.method`	string	GET, POST, etc.
`http.status_code`	number	HTTP status code
`http.duration_ms`	number	Request duration in milliseconds
`db.system`	string	`postgresql`, `mongodb`, etc.
`db.statement`	string	Sanitized SQL or query
`db.slow_query`	boolean	`true` when above slow threshold
`user_id`	string	From `trasys.user.id`
`session_id`	string	From `trasys.session.id`
`environment`	string	`production`, `staging`, etc.
`time`	timestamp	Span end time

AI spans

Field	Type	Description
`gen_ai.system`	string	`openai`, `anthropic`, `gemini`, etc.
`gen_ai.request.model`	string	Model name
`gen_ai.usage.input_tokens`	number	Prompt token count
`gen_ai.usage.output_tokens`	number	Completion token count
`gen_ai.response.finish_reasons`	string	`stop`, `length`, `tool_calls`
`trasys.ai.cost_usd`	number	Estimated cost in USD

Logs

Field	Type	Description
`message`	string	Log message
`severity`	string	`debug`, `info`, `warn`, `error`, `fatal`
`trace_id`	string	Correlated trace
`user_id`	string	Correlated user
`error.type`	string	Error class name
`error.message`	string	Error message

Aggregations

SELECT
  http.route,
  COUNT(*)                         AS request_count,
  AVG(http.duration_ms)            AS avg_latency,
  PERCENTILE(http.duration_ms, 95) AS p95_latency,
  SUM(CASE WHEN http.status_code >= 500 THEN 1 ELSE 0 END) AS errors
FROM   spans
WHERE  service = 'api-gateway'
  AND  time > now() - 1h
GROUP BY http.route
ORDER BY errors DESC

Saved queries

Queries can be saved in the dashboard and referenced in alert conditions by their slug:

error_rate("payment-service") > 0.05

This references the built-in error_rate aggregation function. Custom saved queries can be referenced similarly once defined.

The full TQL reference — all built-in functions, aggregation operators, and provider-specific fields — is maintained separately and will be expanded as TQL evolves.

Trasys Query Language (TQL)

On this page