Estatísticas de Federação de Instância Mastodon: Como Ler na API

Administradores de instâncias Mastodon frequentemente precisam monitorar como seu servidor se conecta com outras instâncias no fediverso. As estatísticas de federação mostram o número de instâncias conhecidas, usuários ativos e postagens trocadas. A API do Mastodon fornece essas métricas por meio de um endpoint dedicado. Este artigo explica como acessar o endpoint /api/v1/instance e interpretar os dados de federação que ele retorna.

O que o Endpoint da API de Instância do Mastodon Retorna

O endpoint da API do Mastodon /api/v1/instance é uma requisição GET sem autenticação. Ele retorna um objeto JSON contendo o nome da instância, descrição, informações de contato e um objeto stats. O objeto stats possui três campos: user_count, status_count e domain_count. Esses campos são atualizados periodicamente pelo job em segundo plano do Mastodon Scheduler::InstanceRefreshScheduler, que é executado a cada 15 minutos por padrão.

user_count é o número de usuários registrados apenas nesta instância. Ele não conta usuários de outras instâncias. status_count é o número de postagens (toots) criadas por usuários locais. domain_count é o número de domínios remotos únicos (instâncias) que este servidor já descobriu ou com os quais já se comunicou. Um domínio é contado uma vez, independentemente de quantos usuários ou postagens representa.

O endpoint também inclui um objeto configuration com limites de federação, como statuses_max_reblogs e media_attachments_allowed_mime_types. No entanto, as estatísticas de federação se limitam aos três campos em stats. Para métricas de federação mais aprofundadas, é necessário consultar endpoints adicionais da API, como /api/v1/instance/peers e /api/v1/instance/activity.

Como os Dados São Coletados

O Mastodon mantém uma tabela de banco de dados local chamada accounts e uma tabela chamada statuses. O domain_count é derivado da tabela accounts: ele conta valores distintos de domain de todas as contas remotas que já foram vistas pelo menos uma vez. Quando um usuário remoto envia uma postagem para sua instância, o Mastodon cria uma entrada de conta para aquele domínio. Isso significa que o domain_count reflete todos os domínios que já interagiram com sua instância, mesmo que essa interação tenha sido um único seguidor ou uma única postagem.

Passos para Recuperar e Interpretar Estatísticas de Federação

1. Envie uma requisição GET para o endpoint da API
   Use uma ferramenta como curl ou um navegador. A URL é https://suainstancia.social/api/v1/instance. Substitua suainstancia.social pelo domínio real do seu servidor Mastodon. Nenhuma autenticação é necessária.
2. Examine o objeto stats na resposta JSON
   A resposta contém um campo stats. Exemplo: "stats": {"user_count": 1200, "status_count": 45000, "domain_count": 850}. O domain_count de 850 significa que esta instância se comunicou com 850 outras instâncias Mastodon.
3. Verifique o user_count para crescimento de usuários locais
   Um user_count crescente indica novos registros. Um número estável sugere que o registro está fechado ou que nenhum novo usuário está entrando. Compare isso com status_count para ver se os usuários existentes estão postando ativamente.
4. Use /api/v1/instance/peers para obter uma lista de domínios federados
   Envie uma requisição GET para https://suainstancia.social/api/v1/instance/peers. Isso retorna um array de strings de domínio, como ["mastodon.social", "fosstodon.org"]. Essa lista é o mesmo conjunto que contribui para o domain_count.
5. Use /api/v1/instance/activity para atividade semanal
   Envie uma requisição GET para https://suainstancia.social/api/v1/instance/activity. Isso retorna um array de objetos com week (timestamp Unix), statuses (postagens locais criadas naquela semana), logins (número de usuários ativos) e registrations (novos usuários). Isso fornece uma visão temporal da atividade de federação.

Erros Comuns ao Ler Estatísticas de Federação

Interpretar user_count como Número Global de Usuários

Novos administradores frequentemente assumem que user_count representa todos os usuários no fediverso. Não é o caso. O campo conta apenas usuários registrados na sua instância específica. Para ver o número total de usuários em todas as instâncias federadas, seria necessário agregar dados da API de cada instância, o que é impraticável em escala. O Mastodon não fornece um contador global de usuários.

Assumir que domain_count é Igual ao Número de Conexões Ativas

domain_count conta todos os domínios que já interagiram com sua instância, incluindo domínios que agora estão extintos ou que bloquearam sua instância. Um domain_count alto não significa que sua instância está ativamente federando com todos esses domínios. Para verificar a federação ativa, você pode comparar o domain_count com o número de domínios que enviaram postagens nos últimos 30 dias usando o endpoint /api/v1/instance/activity e logs do servidor.

Depender de Dados Desatualizados

O objeto stats é atualizado a cada 15 minutos pelo Scheduler::InstanceRefreshScheduler. Se você fizer uma alteração, como adicionar um novo usuário ou bloquear um domínio, as estatísticas podem não ser atualizadas imediatamente. Você pode forçar uma atualização reiniciando os workers em segundo plano do Mastodon ou executando o scheduler manualmente com RAILS_ENV=production bin/tootctl refresh_instance_stats na linha de comando do servidor.

Endpoints da API do Mastodon para Dados de Federação

Endpoint	Dados Retornados	Autenticação Necessária
/api/v1/instance	Metadados da instância, incluindo objeto stats com user_count, status_count, domain_count	Não
/api/v1/instance/peers	Array de strings de domínio que já federaram com esta instância	Não
/api/v1/instance/activity	Array de objetos semanais com week, statuses, logins, registrations	Não

O endpoint /api/v1/instance/peers é útil para construir uma lista de instâncias federadas. O endpoint /api/v1/instance/activity fornece tendências históricas. Nenhum desses endpoints requer autenticação, tornando-os adequados para ferramentas de monitoramento e painéis públicos.

Agora você pode consultar a API de instância do Mastodon para recuperar estatísticas de federação e interpretar corretamente os campos user_count, status_count e domain_count. Use o endpoint /api/v1/instance/peers para obter uma lista completa de domínios e /api/v1/instance/activity para tendências semanais. Para dados em tempo real, considere configurar um cron job que chame a API a cada cinco minutos e registre os resultados.