jsonscraper
Mercados
Voltar ao jornal

UptimeScout: como verificar se houve uma falha no serviço na região do usuário

Um caso prático: reunir o histórico de observações por região e distinguir um sinal recente de um intervalo desconhecido

Política editorial Comunique um erro

Quando usuários de um país relatam problemas, mas a equipe vê o serviço funcionando normalmente, é mais útil verificar as observações especificamente da região deles. A API do UptimeScout permite consultar o histórico de um serviço selecionado por código regional e obter intervalos com o número de medições. O resultado é uma tabela verificável para analisar o relato: horário do intervalo, resolução, distribuição dos sinais e quantidade de amostras.

Artigo: UptimeScout: como verificar se houve uma falha no serviço na região do usuário
Resumo: A verificação regional de disponibilidade pode ajudar a determinar se um incidente relatado por um usuário coincidiu com as observações do UptimeScout. Veja um procedimento reproduzível: escolha o serviço e a região, consulte o histórico, verifique a atualidade e a resolução dos dados e salve o resultado junto com a resposta original.
Função da imagem: capa — ideia central
Seção: 
Tema visual: fotografia editorial de um mapa regional de interrupções dobrado
A região e o intervalo de tempo delimitam a verificação de disponibilidade.© jsonscraper · criado com IA

O cenário prático é diagnosticar uma possível falha regional. Dados de entrada: o identificador do serviço no catálogo do UptimeScout, um código regional como US ou GB e um intervalo do histórico. O resultado ajuda a comparar o horário do relato do usuário com as observações do serviço. A própria API descreve os dados como sinais de disponibilidade observada; a verificação do serviço é útil para localizar a questão, não para substituir as verificações da aplicação.

Primeiro, confirme o serviço e a região

Comece pelo catálogo: encontre o serviço desejado pelo nome ou pela busca e registre seu ID exato. A especificação OpenAPI do UptimeScout descreve a busca por meio de GET /v1/services e dos parâmetros q, service, region, limit e offset. Para um relatório de diagnóstico, é melhor armazenar o ID, e não apenas o nome exibido: assim, uma nova consulta apontará para o mesmo item do catálogo.

A região é definida por um código próprio de duas letras. É importante salvá-la junto com o resultado: uma resposta para US e outra sem filtro regional respondem a perguntas diferentes. Se a descrição precisar ser exibida em português, o parâmetro lang=pt controla a localização da descrição, enquanto o parâmetro region seleciona as observações. A documentação distingue explicitamente essas duas funções.

Consulte o histórico, não apenas um status

Para analisar um incidente, use /v1/history com o parâmetro obrigatório service e a region selecionada. O parâmetro hours define o intervalo do histórico; a especificação permite valores de 1 a 2160 horas. A consulta também prevê lang. De acordo com a OpenAPI, a autorização é feita com uma licença no esquema Bearer. Na execução prática, mantenha a chave em uma variável de ambiente e não a registre no log das consultas.

import os
import requests

response = requests.get(
    "https://api.uptimescout.com/v1/history",
    headers={"Authorization": f"Bearer {os.environ['UPTIMESCOUT_LICENSE_KEY']}"},
    params={"service": "github", "region": "GB", "hours": 24, "lang": "ru"},
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data)

Este é um exemplo mínimo de consulta, não um resultado publicado de uma investigação real. O identificador github e a região GB são parâmetros ilustrativos: antes de aplicar o exemplo, escolha o serviço e a região relevantes para seu caso. É útil salvar a resposta completa em JSON e adicionar o horário de recebimento e a descrição da consulta em campos separados do seu sistema de auditoria. Assim, é possível repetir a análise e identificar exatamente qual captura de dados foi usada.

Resolução e lacunas fazem parte do resultado

No array history, são importantes os campos observed_at, resolution_seconds, aggregated, samples e counts. A resolução informa a duração do intervalo; samples indica quantas observações foram incluídas na agregação, e counts contém a distribuição dos sinais. Analise esses campos em conjunto: uma linha com poucas amostras tem um peso diferente para a análise de uma agregação com muitas observações.

Artigo: UptimeScout: como verificar se houve uma falha no serviço na região do usuário
Resumo: A verificação regional de disponibilidade pode ajudar a determinar se um incidente relatado por um usuário coincidiu com as observações do UptimeScout. Veja um procedimento reproduzível: escolha o serviço e a região, consulte o histórico, verifique a atualidade e a resolução dos dados e salve o resultado junto com a resposta original.
Função da imagem: ilustração de apoio 2 — um aspecto específico diferente
Seção: Resolução e lacunas fazem parte do resultado
Como ler o histórico: região, intervalos de tempo, resolução e lacunas.© jsonscraper · ilustração gerada por IA

O UptimeScout descreve o histórico como intervalos de tempo com granularidade variável conforme o período selecionado: intervalos de um e cinco minutos para períodos curtos, horários para um dia e diários para períodos longos. Agregações antigas armazenadas podem ter uma resolução mais grosseira. Portanto, não conclua que “a falha começou exatamente neste minuto” se a linha representa uma agregação horária ou diária. Use os valores efetivos de resolution_seconds e os campos effective_start e history_resolution da resposta para delimitar o que os dados permitem concluir.

Trate um intervalo ausente como desconhecido. A especificação pede expressamente que lacunas sejam consideradas intervalos desconhecidos: um espaço vazio no histórico, por si só, não representa nem funcionamento normal nem falha. Essa regra simples evita que relatórios preencham lacunas indevidamente com um status “verde” ou com zeros.

Compare o histórico com o sinal atual

Se precisar verificar o estado no momento do relato, consulte /v1/status para o mesmo service e region. No objeto do serviço, observe conjuntamente status, observed_at e stale; a documentação apresenta esses campos como forma de compreender o estado e a atualidade do sinal. O status de nível superior se refere ao resultado da consulta à API, enquanto service.status descreve o sinal de disponibilidade do serviço específico. Essa distinção é especialmente útil em relatórios automatizados: uma resposta HTTP bem-sucedida e o estado de um serviço externo são coisas diferentes.

Para várias dependências, você pode consultar /v1/statuses e depois usar o histórico apenas para os serviços e regiões em que ocorreu uma anomalia. A especificação também oferece /v1/summary e /v1/incidents. Ao diagnosticar esta última rota, considere sua função exata: o endpoint retorna sinais recentes de interrupção em nível elevado, não incidentes confirmados pelo próprio fornecedor. Portanto, o resultado serve como motivo para conferência, não como conclusão definitiva sobre a causa.

Como apresentar uma conclusão sem especular

Na linha do relatório, salve o ID do service, a region, o período da consulta, observed_at, resolution_seconds, samples, counts e a indicação de lacunas. Adicione o link para o relato ou incidente interno separadamente dos campos da API. Em seguida, compare o intervalo de tempo com os logs da aplicação, os rastreamentos regionais e o relato do usuário. Se o intervalo da agregação for mais amplo que o incidente, formule o resultado de acordo: as observações da região selecionada, durante o período especificado, contêm determinados sinais, com uma resolução e uma quantidade de amostras específicas.

Essa análise oferece à pessoa de plantão uma direção útil: verificar a parte regional do serviço externo ou continuar o diagnóstico da própria aplicação e da rede do usuário. A possibilidade de reproduzi-la depende de salvar os parâmetros da consulta e o JSON original; a qualidade das conclusões temporais depende de considerar explicitamente a resolução, as amostras e os períodos desconhecidos. Esse é o resultado prático de um caso de disponibilidade: não apenas um rótulo de status atual, mas um registro delimitado por região e tempo que outra pessoa pode verificar.

Pessoas

Nenhuma pessoa listada para este artigo ainda.

Continue lendoComo ler os incidentes do UptimeScout: um sinal de falha ainda não é um incidente confirmado
Leia o próximo artigo

Transforme o que lê numa integração funcional

Explore as APIs de dados sociais da jsonscraper, teste pedidos e crie o seu próximo fluxo de trabalho.

Explorar APIs