Monitors

O que são Monitors

Um Monitor é um dashboard personalizado composto por widgets. Cada widget representa em gráfico uma consulta sobre Traces, Metrics ou Logs, para que uma equipe possa manter em uma única página os números que importam: custo por modelo, latência p95, taxa de aprovação dos evaluators e muito mais. Todo Monitor tem um escopo:

Workspace: representa dados de todos os Projects do workspace. Somente administradores do workspace podem criar, editar ou excluir Monitors de workspace.
Project: representa dados de um único Project.

O escopo é definido na criação e não pode ser alterado depois.

Criar um Monitor

AI Studio
API e SDK

Abra Monitors

Abra Monitors na seção Observability da barra lateral e escolha + Monitor.

Dê um nome ao monitor

Insira um Name e uma Description opcional do que o Monitor acompanha.

Escolha o escopo

Selecione Workspace (all projects) ou um Project. A caixa de diálogo abre no projeto ativo. Os demais membros só veem os Projects aos quais têm acesso.

Escolha um modelo

Em Start from template, mantenha Blank monitor ou comece a partir de um dashboard pronto. Consulte Modelos.

Defina o intervalo padrão

Default range é a janela de tempo com a qual o dashboard é aberto. Automatic usa o intervalo padrão. Intervalos além da retenção de dados do plano não são oferecidos.

Crie

Na caixa de diálogo New monitor, escolha Create. O dashboard é aberto imediatamente.

Toda solicitação é autenticada com uma chave de API.

cURL

curl -X POST "https://router.toqan.ai/eu/v2/monitors" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Production cost",
    "description": "Cost tracking for production",
    "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    "default_range": "1d",
    "widgets": [
      {
        "widget_id": "total-cost",
        "type": "bignumber",
        "title": "Total cost",
        "queries": [{ "metric": "genai.cost" }],
        "layout": { "x": 0, "y": 0, "w": 4, "h": 3 }
      }
    ]
  }'

{
  "monitor": {
    "monitor_id": "monitor_01m4cy71kr64ayad4gvmgqtgeg",
    "display_name": "Production cost",
    "description": "Cost tracking for production",
    "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    "widgets": [
      {
        "widget_id": "total-cost",
        "type": "bignumber",
        "title": "Total cost",
        "queries": [
          {
            "source": "MONITOR_TELEMETRY_SOURCE_TRACES",
            "metric": "genai.cost",
            "operation": "sum",
            "group_by": [],
            "filters": []
          }
        ],
        "display": null,
        "layout": { "x": 0, "y": 0, "w": 4, "h": 3 }
      }
    ],
    "default_range": "1d",
    "preset_key": "",
    "workspace_id": "ws_01JQ8Z0MB5W1YTVN3GCK7B0EXA",
    "created_at": "2026-10-08T05:01:43.928Z",
    "updated_at": "2026-10-08T05:01:43.928Z",
    "created_by_id": "01JQ8Z1TF7QK9D2RH4NMV6PY3C",
    "updated_by_id": "01JQ8Z1TF7QK9D2RH4NMV6PY3C"
  }
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`display_name`	string	Sim	Nome único no workspace, com até 255 caracteres.
`description`	string	Não	Resumo do que o Monitor acompanha, com até 1024 caracteres.
`project_id`	string	Não	Project proprietário. Se omitido, cria um Monitor para todo o workspace, o que exige acesso de administrador do workspace. Imutável após a criação.
`widgets`	array	Não	Widgets a serem exibidos, até 30. Se omitido, cria um Monitor em branco.
`default_range`	enum	Não	`5m`, `15m`, `30m`, `1h`, `6h`, `12h`, `1d`, `7d`, `14d`, `30d`, `60d` ou `90d`.

Um widget contém um type igual a timeseries, toplist, table ou bignumber, exatamente uma entrada em queries e uma posição na grade em layout (x, y, w, h). Uma consulta nomeia a metric e pode adicionar group_by, filters, grain, limit, source e operation. Para uma métrica de trace genai.*, o servidor preenche source e operation quando omitidos; outros datasets exigem ambos explicitamente.

Modelos

Modelo	O que mostra	Intervalo padrão
GenAI overview	Total de solicitações, custo, tokens e erros, solicitações ao longo do tempo por modelo, latência p95 e custo e erros por modelo.	Último dia
Cost analysis	Custo total, solicitações e tokens, custo ao longo do tempo por modelo e custo por modelo e por Project.	Últimos 7 dias
Latency	Latência p50, p95 e p99 ao longo do tempo e os modelos e provedores mais lentos no p95.	Último dia
Evaluator quality	Execuções de evaluators, taxa de aprovação, guardrails acionados, taxa de aprovação e pontuação média ao longo do tempo e taxa de bloqueio de guardrails por evaluator.	Últimos 7 dias

Todo widget criado a partir de um modelo pode ser editado, movido ou excluído como qualquer outro.

Usar o dashboard

O cabeçalho do dashboard contém os controles de todo o Monitor:

Intervalo de tempo: escolha um intervalo predefinido ou personalizado. O intervalo se aplica a todos os widgets e é mantido na URL da página, então um link para o dashboard abre a mesma janela. Os intervalos são limitados à retenção de dados do plano.
Refresh: recarrega todos os widgets.
+ Widget: abre o editor de widgets. Consulte Adicionar um widget.
Ações do monitor: Settings, Duplicate e Delete.

Arraste um widget pelo cabeçalho para movê-lo ou arraste sua borda para redimensioná-lo. Depois que o layout mudar, escolha Save layout para mantê-lo ou Cancel para descartá-lo. Abra o menu de um widget para:

Edit: reabrir o widget no editor.
Duplicate: adicionar uma cópia ao mesmo Monitor.
Create alert: abrir o formulário de Alerts com a métrica, os filtros e o Project do widget já preenchidos. A linha de meta do widget se torna o limite do alerta. Disponível para métricas GenAI de Traces. Os alertas não têm divisão, então Split results by não é transferido, e um Monitor de workspace exige que um Project seja escolhido no formulário. Os Notifiers do alerta são selecionados nesse formulário.
Delete: remover o widget.

Widgets de série temporal desenhados como linhas ou barras também mostram um botão no cabeçalho para alternar entre gráfico de linhas e gráfico de barras. O editor de widgets tem a configuração na parte superior e uma Preview ao vivo do widget abaixo, usando o intervalo de tempo atual do dashboard.

Escolha os dados

Dataset: Traces, Metrics ou Logs. Somente os datasets disponíveis para o workspace são listados.
Measure: a métrica a ser representada, por exemplo Requests, LLM cost, Latency p95 ou Evaluator pass rate. Consulte Medidas.
Aggregate: como os valores são combinados, como contagem, soma, média ou um percentil. As opções dependem da medida.
Interval: o tamanho do bucket para séries temporais, Auto, Minute, Hour ou Day.

Filtre os dados

Em Where, escolha + Filter para restringir a consulta, por exemplo a um modelo, provedor ou Deployment. Até 20 filtros por widget.

Divida os resultados

Em Split results by, selecione uma ou mais dimensões, como Model, Provider, Project, Agent ou Tool, para obter uma série ou linha por valor. Deixe vazio para representar todos os resultados juntos.

Dê um nome e escolha a visualização

Insira um Title e escolha uma Visualization. Somente as visualizações adequadas à consulta são listadas:

Visualização	Quando está disponível
Line chart, Bar chart, Area chart	Valores ao longo do tempo, com ou sem divisão.
Top list, Table	Um único valor por valor da divisão. Exige Split results by.
Big number	Um único valor para todo o intervalo. Sem divisão.

Ajuste as opções de exibição

Expanda Display options para ajustar o widget. As opções exibidas dependem da visualização:

Sort e Limit: mostram os valores Top ou Bottom e quantos (top lists e tabelas).
Value precision: casas decimais, de 0 a 6. Deixe em branco para automático.
Show overall, Show others, Show percentage: adicionam uma linha de total, agrupam os valores restantes em uma linha ou mostram a participação de cada valor (top lists e tabelas).
Target line: um valor de referência desenhado no gráfico (séries temporais).

Salve

Confira a Preview e escolha Save. O widget é adicionado ao Monitor.

Medidas

O dataset Traces oferece as medidas GenAI abaixo.

Área	Medidas
Usage	`Requests`, `Tokens`
Cost	`LLM cost`
Errors	`Errors`, `Error rate`
Latency	`Latency (avg)`, `Latency p50`, `Latency p95`, `Latency p99`
Streaming	`Time to first token (avg)`, `Time to first token p50`, `Time to first token p95`, `Time to first token runs`
Evaluators	`Evaluator runs`, `Evaluator pass rate`, `Evaluator failure rate`, `Evaluator score (avg)`, `Evaluator errors`, `Evaluator error rate`
Guardrails	`Guardrail runs`, `Guardrails triggered`, `Guardrail block rate`

Gerenciar Monitors

AI Studio
API e SDK

A lista Monitors mostra cada Monitor com seu escopo, número de widgets, última atualização e quem o atualizou.

Use Search por nome ou descrição e Filter por Scope.
Abra o menu de uma linha para abrir, usar Duplicate ou Delete em um Monitor. Uma cópia duplica todos os widgets.
Para renomear um Monitor, alterar sua descrição ou o intervalo padrão, abra-o e escolha Settings no menu .

Operação	Endpoint
Criar um Monitor	`POST /v2/monitors`
Listar Monitors	`GET /v2/monitors`
Obter um Monitor	`GET /v2/monitors/{monitor_id}`
Atualizar um Monitor	`PATCH /v2/monitors/{monitor_id}`
Excluir um Monitor	`DELETE /v2/monitors/{monitor_id}`

GET /v2/monitors retorna os Monitors visíveis para quem faz a chamada, dos mais recentes para os mais antigos, com has_more. Quem filtra por project_id vê os Monitors desse projeto mais os Monitors de todo o workspace; uma chave de API com escopo de projeto vê apenas o próprio projeto. Pagine com starting_after ou ending_before definido como um monitor_id da página anterior. limit aceita de 1 a 200, com padrão 25. project_id restringe o resultado a um projeto, search busca no nome de exibição e na descrição sem diferenciar maiúsculas e minúsculas, e workspace_wide restringe a Monitors de todo o workspace ou com escopo de projeto.PATCH /v2/monitors/{monitor_id} substitui somente os campos enviados. O JSON do Protobuf codifica update_mask como uma string de caminhos separados por vírgulas, escolhidos entre display_name, description, widgets e default_range:

cURL

curl -X PATCH "https://router.toqan.ai/eu/v2/monitors/$MONITOR_ID" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [],
    "update_mask": "widgets"
  }'

Um caminho incluído na máscara é substituído por completo, então widgets pode ser esvaziado. Sem máscara, um array widgets não vazio ainda substitui todo o conjunto, e um array vazio ou omitido mantém os widgets existentes; por isso, obtenha o Monitor antes ao editar um único widget. project_id é imutável. Excluir um Monitor exclui também seus widgets, já que eles são armazenados em linha.

Permissões

Visualizar, criar, editar e excluir Monitors dependem, cada um, da função do membro. Membros sem acesso de edição veem os dashboards somente para leitura: os widgets não podem ser movidos, redimensionados, adicionados ou editados. Monitors de workspace exigem, além disso, um administrador do workspace para serem criados, editados ou excluídos. Create alert em um widget também exige permissão para criar Alerts. Para chaves de API, a permissão Read abrange listar e obter, e Write abrange criar, atualizar e excluir.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

O que são Monitors

Criar um Monitor

Modelos

Usar o dashboard

Ações do widget

Adicionar um widget

Medidas

Gerenciar Monitors

Permissões

​O que são Monitors

​Criar um Monitor

​Modelos

​Usar o dashboard

​Ações do widget

​Adicionar um widget

​Medidas

​Gerenciar Monitors

​Permissões

O que são Monitors

Criar um Monitor

Modelos

Usar o dashboard

Ações do widget

Adicionar um widget

Medidas

Gerenciar Monitors

Permissões