Métricas

GET /v1/metrics responde o que os componentes do seu workspace fizeram em uma janela, balde a balde. Esta página diz o que é cada número e quanto confiar nele, para que ninguém leia uma contagem de entregas, ou de eventos do navegador, como se fosse um público verificado.

O que é medido

Métrica	Fonte	Confiança	O que é
loader_deliveries	loader_hits	forgeable	Vezes que a borda entregou o loader a uma página de um site seu: tráfego humano, em um hostname que o site não bloqueia. Não é uma impressão verificada.
conversions	submissions	counted	Envios aceitos (não spam) de uma coleção do componente, contados das linhas que o Taggor guarda. É a definição padrão de conversão.
impressions	component_events	forgeable	Componentes renderizados no navegador de um visitante: o loader avisa cada componente montado. Só tráfego humano.
interactions	component_events	forgeable	Eventos que um componente declarou em events e emitiu, informados pelos navegadores dos visitantes: no máximo 30 por componente por página, amostrados por eventSampleRate, então uma estimativa.
custom_events	component_events	forgeable	Eventos que um componente declarou em data.track e enviou com track, informados, limitados e amostrados do mesmo jeito.
interaction_rate	component_events	forgeable	interactions / impressions, como fração. null quando não há impressões.
conversion_rate	component_events	forgeable	conversions / impressions, como fração (0.0734 é 7,34 %). null quando não há impressões.

forgeable quer dizer que qualquer pessoa que conheça a chave do site (ela é pública, vai no seu HTML) pode aumentar a contagem pedindo o loader; por isso o Taggor nunca corta nem cobra só por ela. counted quer dizer linhas no nosso banco.

Tudo o que vem de eventos do navegador também é forgeable, a taxa de conversão inclusive: uma taxa nunca é counted, mesmo quando o numerador é (conversion_rate divide envios guardados por impressões forjáveis). Não a apresente como taxa verificada. Uma métrica sem dado é null e nunca 0. O array metrics de toda resposta repete isto: cada item tem source, trust, available e, quando não está disponível, um reason (no_event_source, reader_unavailable ou not_attributable).

Peça uma janela

curl -s -H "Authorization: Bearer $TAGGOR_API_KEY" \
  "$TAGGOR_API_URL/v1/metrics?granularity=day&group_by=version"

Parâmetro	Significado
from, to	A janela [from, to), RFC 3339. Padrão: to é agora e from é 7 dias (day) ou 24 horas (hour) antes.
granularity	hour (janela de até 7 dias) ou day (até 90 dias, que é quanto o dado é guardado). Padrão day.
group_by	site, component, version, country, device, hostname ou event (veja “Recortes” abaixo).
site_id, component_id, version_id	Restringe a um dos seus. Um site que não é seu dá 404.
environment	production (padrão) ou staging: os sites de teste ficam à parte, como no seu uso.

A resposta tem totals, uma series com um ponto por balde (com zeros onde a fonte respondeu e não achou nada) e, com group_by, groups, cada um com seus totals e os baldes que têm dado. Agrupadas por site, componente ou versão, as conversions somam o total.

Recortes

group_by	O que é recortado
site	Todas as métricas.
component, version	conversions. As entregas do loader e as métricas do navegador vêm null por grupo (o total continua com elas).
country	As métricas do navegador, pelo país de duas letras que a rede informa para o pedido. Nenhum endereço IP é guardado.
device	As métricas do navegador, por uma de quatro classes: mobile, desktop, tablet ou other. Nenhum user agent é guardado.
hostname	As métricas do navegador, pelo hostname da página em que o componente estava.
event	interactions e custom_events, pelo nome do evento que o componente informou.

Uma métrica que um recorte não consegue cortar vem null por grupo, nunca 0, e o breakdown_available dela é false. Um grupo dos quatro últimos tem totals e uma series vazia. O grupo unknown reúne os eventos que vieram sem valor (um pedido para o qual a rede não informou país). Um filtro component_id ou version_id deixa as entregas do loader e as métricas do navegador null, então os quatro últimos recortes não respondem grupos com ele.

Se o leitor do Analytics Engine estiver fora, essas métricas vêm null com reader_unavailable e as conversões continuam respondendo.

Amostragem e limites

Em alto volume o Analytics Engine guarda um ponto para vários eventos e registra o peso em _sample_interval. Toda contagem de entregas aqui é uma soma de pesos, nunca uma contagem de linhas; assim um conjunto amostrado ainda dá uma estimativa do total real. As conversões vêm de um banco e não são amostradas.

• No máximo 10.000 células (grupos vezes baldes) por resposta: um group_by=site que passaria disso dá 400 pedindo uma janela menor, dias em vez de horas ou um site_id. truncated: true quer dizer que uma fonte cortou a resposta; leia os números como um piso.
• No máximo 200 grupos são listados.
• 30 requisições por minuto por credencial (a classe de limite metrics).
• Exige o escopo metrics:read; todo papel o tem, inclusive o de leitor.
• Os números ficam um pouco atrás (segundos) e são aproximados; a mesma janela lida de novo em um minuto pode vir de um cache.

Privacidade

Tudo acima é contagem: nenhum identificador de visitante, endereço IP ou user agent é guardado ou devolvido. Veja Formulários e dados para o que um envio guarda, que é seu.

Vem depois

As suas próprias definições de conversão ainda não entram nestes números; esta página dirá quando passarem a entrar. Até lá, conversions é a medida de resultado.

Pelo terminal e por um agente

taggor metrics mostra os mesmos números desta rota: uma linha por métrica com a fonte e a confiança, e --json imprime a resposta da rota sem mudar nada. Flags: --from, --to, --granularity, --group-by, --site, --component, --version, --environment. Um agente ligado ao servidor MCP tem a tool get_metrics (escopo metrics:read), que diz o mesmo: números de eventos do navegador são forgeable (forjáveis).