> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Monitors > Crie Monitors: dashboards personalizados com gráficos de custo, latência, erros e resultados de evaluators a partir de Traces, Metrics e Logs. ## **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** > [tab] AI Studio > > **1. Abra Monitors** > > Abra **Monitors** na seção **Observability** da barra lateral e escolha **+ Monitor**. > > **2. Dê um nome ao monitor** > > Insira um **Name** e uma **Description** opcional do que o **Monitor** acompanha. > > **3. 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. > > **4. Escolha um modelo** > > Em **Start from template**, mantenha **Blank monitor** ou comece a partir de um dashboard pronto. Consulte [Modelos](#templates). > > **5. 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. > > **6. Crie** > > Na caixa de diálogo **New monitor**, escolha **Create**. O dashboard é aberto imediatamente. > [tab] API e SDK > > Toda solicitação é autenticada com uma chave de API. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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 } > } > ] > }' > ``` > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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](#adding-a-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. ### Ações do widget 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**](/docs/pt-BR/ai-studio/observability/alerts.md) 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**](/docs/pt-BR/ai-studio/observability/notifiers.md) 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. ## **Adicionar um widget** 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. **1. 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](#measures). * **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**. **2. Filtre os dados** Em **Where**, escolha **+ Filter** para restringir a consulta, por exemplo a um modelo, provedor ou **Deployment**. Até 20 filtros por widget. **3. 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. **4. 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. | **5. 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). **6. 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** > [tab] AI Studio > > 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 . > [tab] API e SDK > > | 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`: > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.