Seleção de traces e logs com OQL

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. Casos de uso

Executar a mesma seleção pela API, pela CLI e pelo AI Studio.
Combinar várias condições em uma única expressão em vez de montar um array filters.
Repassar uma investigação salva a um colega como uma única linha de texto.

Visão geral

OQL é uma linguagem de pipeline para selecionar Traces e Logs. Uma consulta nomeia o sinal e depois adiciona estágios separados por |:

fetch <signal> | filter <expr> | sort <field> <order> | limit <n>

fetch vem primeiro e é obrigatório. filter pode se repetir, e todos os filtros são combinados com and. Um estágio sort ou limit repetido usa o último valor. A OQL é compilada no mesmo planejador e registro de campos que o array estruturado filters, então um campo ou operador que funciona ali também funciona na OQL. Não há estágio de agregação: linhas calculadas e séries temporais vêm da Telemetry API.

Início rápido

Execute uma consulta de traces em uma janela de tempo. A API aceita somente timestamps RFC 3339.

curl -X POST https://router.toqan.ai/eu/v3/traces/query \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-02T00:00:00Z",
    "oql": "fetch traces | filter status == \"error\" | limit 20"
  }'

Os resultados ficam em search.data. Use os exemplos abaixo no campo oql do SDK ou no corpo da requisição. Os intervalos da API usam timestamps RFC 3339.

Estágios

Estágio	Forma	Regras
`fetch`	`fetch traces`, `fetch logs`	Obrigatório e primeiro. Qualquer outro início é rejeitado.
`filter`	`filter <field> <operator> <value>`	Opcional e repetível. Todos os filtros são combinados com `and`, então filtros contraditórios não retornam linhas.
`sort`	`sort <field> <asc\|desc>`	Opcional e repetível. Cada sinal fixa o campo que aceita, e um estágio repetido usa o último valor.
`limit`	`limit <n>`	Opcional e repetível. Usa o último valor e substitui o campo `limit` da solicitação.

Expressões de filtro

Duas formas são interpretadas como o mesmo filtro. A forma com símbolos cobre igualdade e ordenação:

Escrito	Operador	Exemplo
`A == B`	`eq`	`status == "error"`
`A != B`	`neq`	`status != "error"`
`A > B`	`gt`	`tokens.total > 100`
`A >= B`	`gte`	`tokens.total >= 100`
`A < B`	`lt`	`tokens.total < 100`
`A <= B`	`lte`	`tokens.total <= 100`

A forma com palavras cobre os operadores que precisam de sintaxe própria:

Escrito	Exemplo
`A contains B`	`name contains "responses"`
`A in (B, C)`	`status in ("error", "success")`
`A not_in (B, C)`	`status not_in ("error")`
`A between (B, C)`	`start_time between ("2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z")`
`A exists`	`tokens.total exists`

As listas usam parênteses ou colchetes e são separadas por vírgulas. Os valores podem ser colocados entre " ou ', o que permite que um valor contenha espaços; uma aspa dentro de um valor exige o outro caractere de aspas. Os operadores aceitos por um campo dependem do seu tipo, e não do parser. Uma expressão válida no tipo de campo errado ainda é rejeitada:

{ "code": 3, "message": "invalid filter: operator \"exists\" is not allowed for \"status\"", "details": [] }

A tabela de tipos e operadores está em Gramática de filtros; os campos aceitos e seus operadores vêm de GET /v3/traces/fields para traces e de GET /v3/logs/fields para logs. Os filtros de status usam a grafia success e error; Valores de status de trace relaciona esses valores aos da Telemetry API e de Reporting.

Regras por sinal

	Traces	Logs
Início	`fetch traces`	`fetch logs`
Endpoint	`POST /v3/traces/query`	`POST /v3/logs/query`
Ordenação	Somente `sort end_time desc`	Somente `sort timestamp desc`
`limit` do pipeline	Até 200	Até 1000
Timestamps	RFC 3339 no corpo da solicitação, valores relativos pela CLI	igual
Campos seletores	Somente `oql`; `filters` e `query` são rejeitados como campos desconhecidos	Somente `oql`; `filters` e `query` são aceitos, mas ignorados, então uma solicitação que os envia os descarta silenciosamente

Exemplos

Traces com falha no último dia

OQL

fetch traces | filter status == "error" | sort end_time desc | limit 50

Traces cujo nome corresponde a um deployment, pelo nome do trace

OQL

fetch traces | filter name contains "responses" | limit 20

Traces em qualquer um de dois estados

OQL

fetch traces | filter status in ("error", "success") | limit 20

Logs de erro, dos mais recentes para os mais antigos

OQL

fetch logs | filter severity_text == "ERROR" | sort timestamp desc | limit 100

Traces caros, combinando dois filtros

OQL

fetch traces | filter tokens.total > 1000 | filter status == "success" | limit 20

Logs de erro pelo SDK, com o cliente do Início rápido A OQL escrita no AI Studio chega ao mesmo endpoint, então as regras acima continuam valendo. A barra de consulta em Traces e Logs alterna entre um construtor e a OQL, e o formulário de relatório do Insights aceita o mesmo dialeto somente para estágios filter: sort e limit são rejeitados ali. As sugestões de campos vêm do registro de campos do workspace.

Erros

Mensagem	Causa
`invalid oql: query must start with fetch traces`	Início ausente ou que nomeia outro sinal; a mensagem repete o início esperado pelo sinal, então uma consulta de logs mostra `fetch logs`
`invalid oql: unsupported command "..."`	Um estágio diferente de `filter`, `sort` e `limit`
`invalid oql: unterminated quote`	Um `"` ou `'` que é aberto e nunca fechado
`invalid oql: malformed list`	Uma lista sem o `)` ou `]` de fechamento
`invalid oql: between expects exactly two values`	`between` com um ou três valores
`invalid oql: limit cannot exceed 200`	Uma consulta de traces acima do limite do pipeline
`validation error: limit: must be greater than or equal to 1 and less than or equal to 1000`	Uma consulta de logs acima do limite do pipeline
`invalid sort: only end_time desc is supported`	Qualquer outra ordenação de traces
`invalid sort: only timestamp desc is supported`	Qualquer outra ordenação de logs
`invalid filter: unknown field "..."`	Uma consulta de traces que nomeia um campo desconhecido pelo registro. Uma consulta de logs responde `filter[0]: unknown field "..."`
`invalid filter: operator "..." is not allowed for "..."`	Uma consulta de traces que aplica um operador fora da lista do campo, publicada por `GET /v3/traces/fields`

Uma consulta malformada é rejeitada antes que o planejador seja executado, então uma solicitação inválida nunca retorna linhas parciais.

Limitações

Limitação	Impacto	Alternativa
Sem agregação	`summarize`, `group by` e contagens não fazem parte da linguagem	Use a Telemetry API
Um campo de ordenação	Cada sinal aceita um campo de ordenação: `end_time desc` para traces, `timestamp desc` para logs	Escolha a ordenação que importa
Os campos vêm do registro	Um atributo de span personalizado só existe depois que o workspace o registra	Confira a lista de campos antes de escrever a consulta
Traces não aceitam seletor estruturado	`filters` e `query` são campos desconhecidos em `/v3/traces/query`	Expresse cada condição como um estágio `filter`
O texto do pipeline não diferencia maiúsculas de minúsculas nos comandos	`FETCH` e `fetch` são iguais	Escolha uma grafia por consulta para facilitar a leitura

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Visão geral

Início rápido

Estágios

Expressões de filtro

Regras por sinal

Exemplos

Erros

Limitações

​Visão geral

​Início rápido

​Estágios

​Expressões de filtro

​Regras por sinal

​Exemplos

​Erros

​Limitações

Visão geral

Início rápido

Estágios

Expressões de filtro

Regras por sinal

Exemplos

Erros

Limitações