Práticas recomendadas para configurar limites de taxa de API

Sobre uma abordagem orientada por dados para limites de taxa

Sem limites de taxa, uma única integração de CI que faz dezenas de milhares de solicitações por hora pode diminuir a velocidade de toda a instância para cada usuário. Mas definir limites de forma muito agressiva pode interromper as integrações em que suas equipes dependem. Uma abordagem controlada por dados ajuda você a encontrar o equilíbrio certo: comece observando padrões reais de uso e, em seguida, imponha gradualmente limites com base nos dados coletados.

A abordagem segue estas fases:

       **Observe**: habilite o encaminhamento de logs e analise os padrões de tráfego da API.

       **Linha de base**: habilite os limites de taxa com um valor inicial alto para começar a coletar dados de limite de taxa.

       **Refinar**: ajuste os limites com base no uso observado e comunique-se com as equipes afetadas.

       **Manter**: monitorar e ajustar continuamente os limites ao longo do tempo.

Para obter informações sobre como habilitar limites de taxa de uso por meio do Console de Gerenciamento, consulte Como configurar limites de taxa.

Pré-requisitos

Antes de começar, verifique se você tem:

Acesso de administrador ao Console de Gerenciamento
Acesso à configuração de encaminhamento de log
A capacidade de analisar logs centralizados
Uma compreensão dos padrões de uso da API da sua organização e das integrações críticas

Etapa 1: Habilitar o encaminhamento de log

Use o encaminhamento de log para centralizar os logs de solicitação de API para monitoramento e análise. Para obter mais informações, consulte Encaminhamento de logs.

Ao analisar logs encaminhados, concentre-se nesses campos principais:

Campo	Descrição
`Timestamp`	Rastreia quando as solicitações são feitas
`user` / `gh.actor.login`	Identifica o usuário ou a integração que faz solicitações
`path_info` / `gh.request.api.route`	A rota de API que está sendo acessada
`status`	Código de resposta HTTP (por exemplo, `200` para sucesso ou `429` quando o limite de taxa é atingido)
`user_agent`	Identifica o cliente ou a integração que envia a solicitação

Etapa 2: Analisar tendências de API antes de habilitar limites

Antes de habilitar os limites de taxa, analise suas tendências gerais de uso para estabelecer uma linha de base:

        **Identifique os principais consumidores.** Encontre usuários ou integrações fazendo o maior número de solicitações.

        **Examine os pontos de extremidade de alta demanda.** Realce as rotas de API (`path_info`) que recebem mais tráfego e podem se beneficiar da otimização.

        **Detectar padrões ineficientes.** Procure sinais de uso pesado ou ineficiente, como sondagem frequente sem cache ou solicitações redundantes.

Esses dados de linha de base ajudarão você a definir limites de taxa que são informados pelo uso real em vez de adivinhações.

Etapa 3: Habilitar limites de taxa com um valor inicial alto

Quando estiver pronto para habilitar os limites de taxa, comece com um limite alto para que você possa coletar dados adicionais sem interromper os fluxos de trabalho existentes.

No Console de Gerenciamento, defina o limite de taxa da API principal para um valor elevado, como 25.000 requisições por hora. Para obter mais informações, consulte Como configurar limites de taxa.

Depois de habilitar a limitação de taxa, monitore os campos gh.rate_limit que aparecem nos seus logs encaminhados.

Campo	Descrição
`gh.rate_limit.primary.max`	Máximo de solicitações permitidas
`gh.rate_limit.primary.remaining`	Solicitações restantes no período atual
`gh.rate_limit.primary.used`	Solicitações já feitas no período
`gh.rate_limit.primary.reset`	Carimbo de data/hora unix quando o período de limite de taxa é redefinido

Etapa 4: Refinar limites e lidar com uso intenso

Use os dados dos gh.rate_limit campos para tomar decisões informadas:

        **Identifique os usuários próximos ao limite.** Encontre usuários ou integrações que frequentemente se aproximam ou excedem o limite.

        **Determine os limites apropriados.** Defina limites de taxa com base nas tendências de uso observadas em vez de valores arbitrários.

        **Comunique-se com as equipes afetadas.** Trabalhe com as equipes para otimizar o uso da API por meio de técnicas como envio em lote de solicitações, cache de resposta e solicitações condicionais.

Etapa 5: Reduzir limites e preservá-los ao longo do tempo

Depois de ter uma visão clara do uso da API, reduza gradualmente o limite de taxa para se alinhar à capacidade da instância e aos padrões reais de uso. Monitore interrupções não intencionais após cada ajuste.

À medida que você refina limites, trabalhe com equipes cujas integrações são afetadas. Técnicas como envio em lote de solicitações, cache de resposta e solicitações condicionais podem ajudar as equipes a reduzir o uso da API. Você também pode isentar usuários específicos dos limites de taxa usando o ghe-config utilitário. Para obter mais informações, consulte Utilitários de linha de comando.

Examine os dados de limite de taxa periodicamente, uma vez que os padrões de uso mudam à medida que novas integrações são adicionadas e os fluxos de trabalho evoluem.

Considerações adicionais

        **Limites da API do GraphQL.** A API do GraphQL tem um limite de taxa separado (padrão: 5.000 pontos por hora) que não pode ser ignorado por meio da lista de isenção. Para obter mais informações, consulte [AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api).

        **Limites de taxa secundários.** Você também pode habilitar limites de taxa secundários para proteger o nível geral de serviço. Para obter mais informações, consulte [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-secondary-rate-limits).

Leitura adicional

        [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)