Métricas de API do Auth0
A página API Metrics mostra quanto tráfego de API um tenant Auth0 processa, que parte desse tráfego tem sucesso e até que ponto o tenant se aproxima dos seus limites de pedidos (rate limits). Os dados vêm de um Metric Stream do Auth0, que é separado do log stream que transporta os eventos.
O que é necessário
Seção intitulada “O que é necessário”- Um tenant Auth0 ligado ao Identiguard. Consulte Ligar o Auth0.
- Um plano Auth0 que suporte Metric Streams. Normalmente é um plano Enterprise. Confirme com o cliente antes de começar.
- A função Admin no workspace para configurar o stream. Todas as funções, incluindo Viewer, podem abrir a página e ler os gráficos.
- Acesso ao dashboard do Auth0, para criar o stream em Monitoring → Streams.
O metric stream tem o seu próprio endpoint e o seu próprio segredo. Não utiliza o token do log stream. O provider Terraform do Auth0 não suporta metric streams, por isso este stream é sempre criado manualmente no Auth0.
Abrir a página
Seção intitulada “Abrir a página”- Abra Tenants.
- Em Tenant overview, encontre o tenant Auth0.
- Escolha o ícone de gráfico de linhas (tooltip API Metrics) na respetiva linha. Só as linhas Auth0 têm este ícone.
O título da página é API Metrics, com o nome do tenant e “Auth0 API request volume and response type from the OTLP metric stream.” (Volume de pedidos à API do Auth0 e tipo de resposta, a partir do metric stream OTLP.)
Se o tenant ainda não tiver um metric stream, a página mostra o cartão Enable the Auth0 Metric Stream (Ativar o Metric Stream do Auth0) em vez dos gráficos.
Configurar um metric stream num tenant novo
Seção intitulada “Configurar um metric stream num tenant novo”- No formulário Add New Auth0 Tenant, assinale Set up a metric stream now na secção Metric stream.
- Escolha Create Auth0 Tenant.
- No ecrã de configuração, encontre o painel Metric stream. Copie o OTLP endpoint URL e o Bearer token (shown once) (mostrado uma única vez).
- No Auth0, vá a Monitoring → Streams → Create Stream e escolha Metric Stream do tipo HTTP.
- Cole o URL do endpoint OTLP.
- Escolha Bearer Token como método de autenticação e cole o token.
- Guarde o stream.
Configurar um metric stream num tenant existente
Seção intitulada “Configurar um metric stream num tenant existente”A configuração está na página API Metrics. Não está na página Edit do tenant.
- Abra Tenants e escolha o ícone de gráfico de linhas (API Metrics) na linha do Auth0.
- No cartão Enable the Auth0 Metric Stream, escolha Generate endpoint. Só os Admins o podem fazer. As outras funções veem o botão desativado, com o tooltip “Admin access required to generate a metric-stream endpoint” (É necessário acesso de Admin para gerar um endpoint de metric stream).
- O cartão mostra o aviso “Shown once - copy these now. The header secret cannot be retrieved again after you leave this page.” (Mostrado uma única vez: copie agora. O segredo do cabeçalho não pode ser recuperado depois de sair desta página.)
- Copie o Endpoint URL e o Header secret com os respetivos botões Copy. O Header name é mostrado para referência.
- No Auth0, siga os passos em Manual setup in Auth0:
- Vá a Monitoring → Streams → New Metric Stream.
- Escolha o tipo HTTP.
- Cole o URL do endpoint como endpoint OTLP.
- Escolha Bearer Token como método de autenticação e cole o segredo do cabeçalho como token. Cole apenas o segredo.
- De volta ao Identiguard, escolha Continue to metrics. O segredo desaparece do ecrã de forma definitiva.
- Observe o mosaico Stream status. Muda de “nothing received yet” (ainda nada recebido) para Active quando o Auth0 entrega as primeiras métricas.
Os controlos
Seção intitulada “Os controlos”| Controlo | O que faz |
|---|---|
| Botões de intervalo 5m, 15m, 1h, 24h, 7d, 30d, 90d | Definem a janela temporal de todos os cartões. A predefinição é 24h. |
| Sete menus de filtro: API, Operation, Failure code, Client ID, Connection ID, Country code, Grant type | Restringem todos os cartões a um valor. Cada um começa em All. |
| Updated Ns ago ou Updated <hora> | Quando os dados foram carregados pela última vez |
| Ícone de atualização (Refresh metrics) | Carrega os dados outra vez, agora |
O menu de intervalo
Seção intitulada “O menu de intervalo”O intervalo também define o detalhe dos gráficos.
| Intervalo | Um ponto no gráfico é | Notas |
|---|---|---|
| 5m, 15m | Um segundo | Vista em direto. A página atualiza-se sozinha a cada 10 segundos enquanto o separador do browser estiver visível. Os filtros não estão disponíveis. |
| 1h, 24h | Um minuto | |
| 7d, 30d | Uma hora | |
| 90d | Um dia |
Em 5m e 15m os menus de filtro ficam desativados, com a nota “Dimension filters aren’t available on 5m/15m - per-second data can’t be filtered by dimension. Switch to 1h or a longer range to filter.” (Os filtros por dimensão não estão disponíveis em 5m/15m: os dados por segundo não podem ser filtrados por dimensão. Mude para 1h ou para um intervalo mais longo para filtrar.)
Quando alguns dados mais antigos não podem ser lidos com os filtros escolhidos, a página diz: “Some older history in this range could not be read with the current filters and was omitted from the charts below (never fabricated).” (Parte do histórico mais antigo deste intervalo não pôde ser lida com os filtros atuais e foi omitida dos gráficos abaixo, nunca inventada.) Os gráficos mostram então menos histórico do que o intervalo. Limpe os filtros ou escolha um intervalo mais curto.
Os cartões
Seção intitulada “Os cartões”Os cartões aparecem por esta ordem.
Mosaicos de resumo
Seção intitulada “Mosaicos de resumo”| Mosaico | O que mostra |
|---|---|
| Requests (<intervalo>) | Total de pedidos à API no intervalo. A indicação mostra “N not succeeded” (N sem sucesso). |
| Success rate | A percentagem de pedidos com sucesso, “across the selected range and filters” (no intervalo e nos filtros selecionados). Fica vermelho abaixo de 90%. Mostra No traffic quando não houve pedidos. |
| Max RPS | O “busiest single second in range” (o segundo mais movimentado do intervalo), em pedidos por segundo |
| Avg RPS | A “average across the range” (média ao longo do intervalo), em pedidos por segundo |
| Rate limited | O número de pedidos que o Auth0 recusou com uma resposta 429 no intervalo |
| Stream status | Active, ou Stale a vermelho. A indicação mostra “last received <hora>” (última receção) ou “nothing received yet”. |
Stale significa que o metric stream está ativado, mas o Identiguard não recebe nada há mais de 15 minutos, ou nunca recebeu nada.
Max RPS e Avg RPS dependem de dados por segundo, que o Identiguard guarda a partir do momento em que o stream faz a primeira entrega. Antes disso, mostram Not available com “per-second history begins at the point of capture” (o histórico por segundo começa no momento da captura). Quando os dados por segundo cobrem apenas parte do intervalo, a indicação mostra “measured over the last X of this Y range” (medido nos últimos X deste intervalo de Y).
Sustained request rate
Seção intitulada “Sustained request rate”“How long traffic in the last <intervalo> ran above each rate threshold, second-accurate.” (Durante quanto tempo o tráfego esteve acima de cada limiar no último intervalo, com precisão ao segundo.)
Quatro mosaicos: >100 rps, >300 rps, >400 rps e >500 rps. Cada um mostra uma duração. Por exemplo, 2 minutos em >300 rps significa que, em 120 segundos distintos do intervalo, o tenant processou mais de 300 pedidos por segundo.
Utilize este cartão para comparar o tráfego real com o limite de pedidos do tenant no Auth0. Responde a “durante quanto tempo estivemos acima do limite”, algo que uma média esconde.
API requests
Seção intitulada “API requests”Barras empilhadas, uma barra por passo de tempo. Cada barra é dividida por tipo de resposta:
- Succeeded
- Rate limited
- Erro de cliente ou de servidor
- Deteção de anomalias
- Qualquer outro código de falha
Em 5m e 15m a divisão é mais simples: Succeeded, Rate limited e Failed. Os dados por segundo não guardam a diferença entre tipos de erro.
Requests per second
Seção intitulada “Requests per second”Um gráfico de linhas: “Bucket-average request rate, same window as the chart above - not the true instantaneous peak (see the sustained-rate card for that).” (Taxa média de pedidos por passo de tempo, na mesma janela do gráfico acima. Não é o verdadeiro pico instantâneo. Para isso, veja o cartão de taxa sustentada.)
Cada ponto é a taxa média num passo de tempo. Em 24h, um ponto é a média de um minuto, por isso um pico curto parece aqui menor do que foi. Para o pico real, leia Max RPS e Sustained request rate.
Response type
Seção intitulada “Response type”Um gráfico em anel ao lado do gráfico de linhas: “Share of requests by response type across the selected range and filters.” (Percentagem de pedidos por tipo de resposta no intervalo e nos filtros selecionados.) O centro mostra Total requests.
Per-stream request rate
Seção intitulada “Per-stream request rate”Uma tabela: “Requests, success rate and sustained rate for every Auth0 stream in the last <intervalo>.” (Pedidos, taxa de sucesso e taxa sustentada de cada stream Auth0 no último intervalo.)
Colunas: Stream, Requests, Success %, Max RPS, Avg RPS, >100, >300, >400, >500 e Trend (um pequeno gráfico de linhas). Na página de um único tenant a tabela tem uma linha.
Traffic by
Seção intitulada “Traffic by”Um gráfico com um seletor: App, Path, Country ou Grant type. O título acompanha o seletor, por exemplo Traffic by App. Mostra “Succeeded, rate-limited and failed requests by <dimensão> in the last <intervalo>, top 10 shown” (Pedidos com sucesso, limitados e falhados por dimensão no último intervalo, com os 10 primeiros).
- App agrupa pelo client ID do Auth0. Utilize-o para descobrir que aplicação causa o tráfego.
- Path agrupa por operação de API.
- Country agrupa por código de país.
- Grant type agrupa por tipo de grant OAuth. Só os pedidos de token têm um grant type, por isso a maior parte do tráfego não tem nenhum.
Top rate-limited operations
Seção intitulada “Top rate-limited operations”“Which Auth0 API operations were throttled (429) the most in the last <intervalo>.” (Que operações da API do Auth0 foram mais limitadas, com 429, no último intervalo.) Colunas: Operation, % rate limited, Events, Rate limited. Os 10 primeiros.
Busiest API operations
Seção intitulada “Busiest API operations”“The 10 Auth0 API operations that carried the most requests in the last <intervalo>.” (As 10 operações da API do Auth0 com mais pedidos no último intervalo.) Colunas: Operation, Requests, % of range, Failed, % failed.
Failures by API operation
Seção intitulada “Failures by API operation”“Which Auth0 API operations carried failure codes in the last <intervalo>.” (Que operações da API do Auth0 tiveram códigos de falha no último intervalo.) Colunas: Operation, % failed, Events, Failed.
Ler a página em cinco passos
Seção intitulada “Ler a página em cinco passos”- Escolha um intervalo. Utilize 24h para uma verificação diária, e 5m ou 15m para acompanhar um incidente em direto.
- Leia Success rate e Rate limited. Uma taxa de sucesso a vermelho ou um número de pedidos limitados acima de zero merece uma análise mais atenta.
- Leia Sustained request rate e compare com o limite de pedidos do tenant no Auth0.
- Utilize Top rate-limited operations e Failures by API operation para encontrar a operação.
- Mude Traffic by para App para encontrar o cliente. Depois restrinja todos os cartões com os menus de filtro, em 1h ou num intervalo mais longo.
Estados vazios
Seção intitulada “Estados vazios”| O que vê | Significado |
|---|---|
| Cartão Enable the Auth0 Metric Stream | O tenant ainda não tem um metric stream |
| No traffic in range | Um cartão não tem pedidos na janela |
| No traffic em Success rate | Não há pedidos, por isso não é possível calcular uma taxa |
| No Auth0 streams configured | Não há nenhum stream para medir |
| Not available | Ainda não há dados por segundo para o intervalo |
| “Metrics unavailable - the metrics query did not answer.” (Métricas indisponíveis: a consulta de métricas não respondeu.) | Não foi possível carregar os dados |
No dashboard
Seção intitulada “No dashboard”O Dashboard tem um cartão Auth0 API metrics: “API request volume and response type from every Auth0 tenant’s metric stream, combined” (Volume de pedidos à API e tipo de resposta do metric stream de todos os tenants Auth0, em conjunto). Aparece quando o workspace tem pelo menos um tenant Auth0, mesmo que nenhum tenha um metric stream.
É o mesmo painel para todos os tenants Auth0 em conjunto, com duas diferenças:
- O último mosaico é Streams reporting, mostrado como N of M. A indicação mostra “all streams receiving data” (todos os streams a receber dados), “stale: <nomes>” ou “not enabled: <nomes>” (não ativado).
- Um cartão adicional, Response type by stream, mostra “Succeeded, rate-limited and failed requests per Auth0 stream in the selected range” (Pedidos com sucesso, limitados e falhados por stream Auth0 no intervalo selecionado).
Com mais de um stream, Max RPS é o pico do stream mais movimentado. Não é um pico da soma de todos os streams.
Resolução de problemas
Seção intitulada “Resolução de problemas”Configuração
Seção intitulada “Configuração”| O que vê | Porquê | O que fazer |
|---|---|---|
| Cartão Enable the Auth0 Metric Stream em vez dos gráficos | O metric stream não está ativado para este tenant | Um Admin escolhe Generate endpoint e cria o stream no Auth0. |
| Generate endpoint está desativado, com “Admin access required to generate a metric-stream endpoint” | A sua função é Member ou Viewer | Peça a um Admin do workspace. |
| “Failed to enable the metric stream (<status>).” (Falha ao ativar o metric stream.) ou “Network error while generating the endpoint.” (Erro de rede ao gerar o endpoint.) | O pedido falhou | Tente outra vez. |
| “Metric stream is already enabled for this tenant. Pass {“rotate”:true} to generate a new secret.” (O metric stream já está ativado para este tenant.) | O endpoint já tinha sido gerado, por exemplo noutro separador do browser | Recarregue a página. O segredo não pode ser mostrado outra vez e não existe botão para emitir um novo. Se o segredo se perder, contacte a equipa de produto. |
| Não encontra Metric Streams no dashboard do Auth0 | O plano Auth0 do cliente não os inclui | Confirme o plano com o cliente. Sem ele, esta funcionalidade não pode ser utilizada. |
Leitura da página
Seção intitulada “Leitura da página”| O que vê | Porquê | O que fazer |
|---|---|---|
| Stream status está Stale, ou mostra “nothing received yet” | O Auth0 não está a entregar. O stream não foi criado, o endpoint está errado, o segredo está errado, ou a palavra Bearer foi escrita antes do segredo. |
No Auth0, abra o metric stream. Verifique que o tipo é HTTP, que a autenticação é Bearer Token e que o token é apenas o segredo. |
| Not available com “per-second history begins at the point of capture” | Ainda não existem dados por segundo para este intervalo | Aguarde. Os dados começam quando o stream faz a primeira entrega. |
| “measured over the last X of this Y range” | Os dados por segundo cobrem apenas parte do intervalo | Apenas informativo. Escolha um intervalo mais curto para ter cobertura total. |
| “Dimension filters aren’t available on 5m/15m - per-second data can’t be filtered by dimension. Switch to 1h or a longer range to filter.” | Os dados por segundo não podem ser filtrados | Escolha 1h ou mais. |
| “Some older history in this range could not be read with the current filters and was omitted from the charts below (never fabricated).” | Os dados mais antigos guardados não têm o detalhe desse filtro | Limpe os filtros ou escolha um intervalo mais curto. |
| “Metrics unavailable - the metrics query did not answer.” | Não foi possível carregar os dados | Escolha o ícone de atualização. Escale se o problema continuar. |
| No traffic in range, No traffic ou No Auth0 streams configured | Nada foi recebido na janela | Escolha um intervalo mais longo. Verifique Stream status. |
| A maioria das linhas não mostra grant type | Só os pedidos de token têm um grant type | Nada. É normal. |
| O mosaico Streams reporting do dashboard mostra 0 of N com “not enabled: <nomes>” | Esses tenants Auth0 não têm metric stream | Configure um, ou ignore o cartão. |
| O mosaico Streams reporting do dashboard mostra “stale: <nomes>” | Esses streams não entregam nada há mais de 15 minutos | Abra a página API Metrics desse tenant e verifique o stream no Auth0. |