# Análise de custo

> Entenda custo teórico vs. faturável, acompanhe os minutos do plano gratuito para GitHub e Latchkey, e encontre seus repositórios e workflows mais caros.

Source: https://latchkey.dev/pt/documentation/cost-analysis

## Summary

- Custo **teórico** = seu uso pelas tarifas de tabela (o sinal de tendência); **faturável** = o que você é efetivamente cobrado.
- Highest Spend e Repository Costs encontram os repositórios caros; os medidores de plano gratuito acompanham os minutos do GitHub e do Latchkey.
- Uma previsão projeta o gasto faturável do GitHub até o fim do ciclo assim que houver histórico de uso suficiente acumulado.
- Os KPIs de custo de runner do Latchkey sempre refletem o período de faturamento atual, independentemente do filtro de datas.

A página Cost Analysis responde "para onde vai o dinheiro da nossa CI?" tanto para runners hospedados pelo GitHub quanto do Latchkey.

A página é organizada em três seções: **Cost Overview** (os KPIs de destaque), **Cost Analysis** (os gráficos que você detalha) e **Latchkey Runner Costs** (o quanto seus runners gerenciados estão custando neste período de faturamento). Antes que qualquer disso seja útil, porém, você precisa da distinção sobre a qual toda a página é construída.

## Dois números para entender

Por que dois números? Os planos gratuitos absorvem a primeira fatia do seu uso, o que torna o custo faturável um sinal de tendência ruim: ele pode ficar perto de zero por parte de um período e depois subir abruptamente assim que os minutos gratuitos acabam, mesmo quando seu uso real cresceu de forma suave. O custo teórico se move em proporção ao uso, então é o que se deve ler quando você pergunta "estamos usando mais CI do que no mês passado?" O custo faturável é o que se deve ler quando você pergunta "quanto vamos pagar?"

> **Um exemplo prático (números ilustrativos)**
> Estes números são inventados para mostrar o formato, não retirados de nenhum plano. Imagine um mês em que seu uso pelas tarifas padrão resulta em $60 de custo teórico, e as inclusões do plano gratuito cobrem os primeiros $45 dele: o custo faturável é $15. No mês seguinte seu uso cresce 20%, então o custo teórico sobe para $72. O plano gratuito ainda cobre $45, então o custo faturável salta para $27: um aumento de 80% a partir de uma variação de 20% no uso. Lendo apenas a linha faturável, você concluiria que os custos explodiram; a linha teórica lhe diz a verdade, que é um crescimento modesto.

## Seção Cost Overview

- **Theoretical Cost** com um selo de tendência semana a semana e as porções de GitHub vs. Latchkey rotuladas embaixo. O selo de tendência compara o custo faturável dos últimos 7 dias com os 7 anteriores e mostra um traço até existirem duas semanas completas de dados.
- **Highest Spend (Theoretical)**: seus 3 principais repositórios por custo modelado no período selecionado.
- **Cost Per Build** e **Build Efficiency Ratio** para normalizar o gasto em relação à produção. O custo por build é o custo teórico médio por build bem-sucedido; a razão de eficiência é a taxa de sucesso de build em relação ao custo teórico, então maior significa mais builds bem-sucedidos por dólar.
- **Pilhas de KPI de GitHub e Latchkey**: a pilha do GitHub mostra o custo faturável previsto até o fim do ciclo mais os minutos do plano gratuito restantes e usados neste ciclo; a pilha do Latchkey, rotulada "Current billing period", mostra o custo estimado neste período de faturamento mais os minutos do plano gratuito restantes e usados neste período.
- **Free Tier Minutes Tracking**: medidores segmentados para minutos incluídos do GitHub e minutos incluídos do Latchkey lado a lado, com os limites refletindo as cotas do seu próprio plano.

Uma observação sobre **Cost Per Build**: o custo total sobe sempre que sua equipe entrega mais, o que geralmente é boa notícia, não um problema. O custo por build remove o volume do quadro. Se o custo total está em alta mas o custo por build está estável, você simplesmente está construindo mais. Se o próprio custo por build está subindo, cada build ficou mais caro: execuções mais longas, runners maiores ou novas etapas, e essa é a tendência que vale investigar.

A **previsão** também merece uma observação. Assim que o mês atual acumula histórico de uso suficiente, a pilha de KPI do GitHub projeta o gasto faturável até o fim do ciclo de faturamento como **Forecasted billable cost by end of cycle**, com base no seu padrão de gasto no mês até a data. Até lá, o cartão exibe "Not enough data yet - run more jobs for a forecast". De qualquer forma, você vê para onde o mês está indo enquanto ainda há tempo de reagir.

## Seção Cost Analysis

- **Cost Over Time**: custo faturável e teórico diário como duas séries ao longo do intervalo de datas selecionado.
- **Repository Costs**: custo teórico e faturável por repositório, com um menu suspenso Top 5 / Bottom 5. Os nomes dos repositórios têm link direto para o GitHub, para que você possa ir de um pico de custo aos arquivos de workflow por trás dele em um clique.
- **Cost by Runner OS**: uma rosca de gasto entre Linux, Windows e macOS, separando Linux (GitHub) de Linux (Latchkey) quando ambos existem.

Duas dicas de leitura para esta seção. No **Cost Over Time**, o ponto em que a linha faturável começa a acompanhar a linha teórica é o ponto em que seus minutos do plano gratuito acabaram; antes disso, os minutos gratuitos estavam absorvendo a diferença. E no **Cost by Runner OS**, lembre-se de que o GitHub cobra um adicional pelos minutos de Windows e macOS, então uma grande fatia de Windows ou macOS costuma ser uma lista de jobs que vale mover para runners Linux mais baratos.

## Seção Latchkey Runner Costs

Se você executa jobs em runners gerenciados, esta seção aparece com uma tabela de custo por configuração: **Config Name** (com o rótulo de runner que você usa nos arquivos de workflow, como `latchkey-small`), um selo de tipo **Custom or Preset**, **Jobs**, **Avg Duration** e **Cost** para o período selecionado. Quando minutos gratuitos foram usados, um rodapé mostra **"Free tier applied: X / Y min"** e o valor em dólares economizado. Os KPIs de custo de runner do Latchkey sempre refletem o período de faturamento atual, independentemente do filtro de intervalo de datas.

Acima da tabela, um destaque exibe **"Estimated savings vs GitHub-hosted: $X"**: os dólares que sua equipe economizou ao executar jobs em runners do Latchkey em vez de runners comparáveis hospedados pelo GitHub no período selecionado. Ele aparece sempre que a economia é positiva.

## Linha CLI Jobs

Se sua equipe executa jobs avulsos a partir do [Latchkey CLI](/documentation/latchkey-cli) ou da ferramenta MCP `run_job`, esse gasto aparece como sua própria linha **CLI Jobs**, com o gasto e a contagem de jobs do período. Esses jobs não pertencem a nenhum repositório nem a nenhum workflow, então esta linha é o dinheiro que o detalhamento por repositório não consegue alocar; ele ainda faz parte do Theoretical Cost. A linha fica oculta enquanto um filtro de repositório ou de workflow está ativo ou quando o filtro de tipo de runner está definido como apenas GitHub, e ela desaparece completamente em períodos sem jobs de CLI.

## Filtros nesta página

A barra de filtros compartilhada funciona aqui como funciona em qualquer lugar: tipo de runner, multisseleções de repositório e workflow, o mesmo seletor de intervalo de datas com suas predefinições 7D, 30D, 90D, 1Y e YTD mais um intervalo personalizado, e redefinir. Todo gráfico também abre em um modo de tela cheia que mantém a barra de filtros, e a engrenagem de configurações de exibição tem um botão "Show decimals" que alterna os valores em dólares entre precisão de centavos e dólares inteiros arredondados. A única exceção ao filtro de datas: os KPIs de custo de runner do Latchkey sempre refletem o período de faturamento atual.

## Qual gráfico responde qual pergunta

| Você quer saber | Olhe para |
| --- | --- |
| O gasto de CI está em tendência de alta ou de baixa? | **Theoretical Cost** e seu selo de tendência semana a semana |
| Quais repositórios custam mais? | **Highest Spend (Theoretical)**, depois **Repository Costs** com a chave Top/Bottom |
| O gasto cresceu porque construímos mais, ou porque os builds ficaram mais caros? | **Cost Per Build** e **Build Efficiency Ratio** |
| Quando exatamente o pico aconteceu? | **Cost Over Time**, com o intervalo de datas estreitado em torno dele |
| Como ficará a fatura? | As **pilhas de KPI** de GitHub e Latchkey (custo faturável previsto para o período) |
| Quão perto estamos de esgotar os minutos gratuitos? | Os medidores de **Free Tier Minutes Tracking** |
| Um sistema operacional está impulsionando a conta? | **Cost by Runner OS** |
| Quanto cada tamanho de runner está nos custando? | A tabela por configuração em **Latchkey Runner Costs** |
| Quanto custaram nossos jobs avulsos de CLI e de agentes? | A linha **CLI Jobs** |

## Usando esta página para de fato cortar custo

Uma rotina sugerida quando o gasto precisa cair. Nada aqui é imposto pelo produto; é simplesmente a ordem em que os gráficos respondem às perguntas uns dos outros:

1. **Estabeleça a tendência** Comece com **Theoretical Cost** e seu selo semana a semana. Se a tendência estiver estável, você está otimizando uma conta estável; se estiver subindo, você está perseguindo uma mudança, e o resto da passagem é sobre descobrir quando e onde.
2. **Encontre a concentração** Abra **Highest Spend (Theoretical)** e **Repository Costs**. O gasto de CI costuma ser concentrado: um pequeno número de repositórios tende a carregar a maior parte da conta, então o esforço gasto no topo deste gráfico compensa muito mais do que em qualquer outro lugar.
3. **Separe volume de preço** Confira **Cost Per Build**. Se estiver estável enquanto o custo total sobe, a equipe está entregando mais e a solução honesta é orçamento, não otimização. Se estiver subindo, cada build ficou mais caro e há desperdício real a encontrar.
4. **Isole o pipeline** Use os filtros de repositório e workflow para dar zoom em um candidato, e leia **Cost Over Time** para o intervalo selecionado. Isso geralmente identifica o dia em que um pico começou e o workflow responsável.
5. **Aja sobre isso** Confira o [AI Insight](/documentation/optimization-insights): a análise noturna revela descobertas de custo quantificadas, cada uma com uma ação que o Latchkey pode executar por você (reduzir um runner superdimensionado, adicionar caching), aplicada como um pull request que você aprova. Se o problema for esgotamento do plano gratuito em vez de desperdício, veja [Uso de runners e minutos gratuitos](/documentation/runner-usage-and-free-minutes) e [Gerenciando o faturamento](/documentation/managing-billing).

> ****
> Use o filtro de workflow para isolar um pipeline quando surgir um pico de custo; combinado com o gráfico Cost Over Time, isso geralmente identifica o dia e o workflow responsável.

## Referência de métricas

| Métrica | O que ela informa |
| --- | --- |
| Theoretical Cost | Custo combinado de todo o uso de CI no intervalo selecionado, hospedado pelo GitHub mais Latchkey, precificado antes dos minutos gratuitos |
| Week over Week | Variação percentual no custo faturável, últimos 7 dias vs. os 7 dias anteriores; um traço até existirem duas semanas completas de dados |
| Cost Per Build (Theoretical) | Custo teórico médio por build bem-sucedido, antes do plano gratuito |
| Build Efficiency Ratio | Taxa de sucesso de build em relação ao custo teórico; maior significa mais builds bem-sucedidos por dólar |
| Forecasted billable cost by end of cycle | Gasto faturável projetado do GitHub até o fim do mês; "Not enough data yet" até acumular histórico |
| Free Tier Minutes Tracking | Medidores de "X / Y minutes used" para o seu plano do GitHub e o seu plano do Latchkey, lado a lado |
| Cost Over Time | Custo faturável e teórico diário; onde a linha faturável começa a acompanhar a linha teórica é onde os minutos gratuitos acabaram |
| Cost by Runner OS | Gasto dividido entre Linux, Windows e macOS, com fatias de Linux (GitHub) e Linux (Latchkey) quando ambas existem |
| Estimated savings vs GitHub-hosted | Dólares economizados ao executar jobs em runners do Latchkey em vez de runners comparáveis hospedados pelo GitHub; mostrado quando positivo |
| Free tier applied: X / Y min | Minutos gratuitos do Latchkey aplicados contra os minutos incluídos do seu plano, e seu valor em dólares, no rodapé da tabela de custos de runner |
| CLI Jobs | Gasto e contagem de jobs para jobs iniciados a partir do Latchkey CLI ou da ferramenta MCP run_job; eles não pertencem a nenhum repositório, então aparecem aqui e dentro do Theoretical Cost, não no detalhamento por repositório |

Para modelar o gasto antes que ele apareça nesta página - um novo repo, um runner maior, mais jobs - use a [calculadora de custo do GitHub Actions](/learn/ci-cost/github-actions-cost-calculator) no Learn, ou navegue pelos [guias de custo de CI](/learn/ci-cost) para a mecânica de preços entre provedores.

### Qual a diferença entre custo teórico e faturável?

O custo teórico é seu uso precificado pelas tarifas de tabela, o que o torna o sinal de tendência mais limpo, porque ignora cotas gratuitas e descontos. O custo faturável é o que você realmente paga depois de aplicá-los. Acompanhe o teórico para ver se o uso está crescendo; acompanhe o faturável para ver quanto deve.

### Por que os custos de runner do Latchkey ignoram meu filtro de datas?

Os KPIs de custo de runner do Latchkey sempre refletem o período de faturamento atual, seja qual for o intervalo do filtro. Eles respondem quanto você deve neste ciclo, que é uma pergunta de período de faturamento e não de intervalo de datas. Os gráficos de custo do GitHub seguem o filtro.

### Quando a previsão de gastos aparece?

Quando há histórico de uso suficiente no ciclo atual para projetar. A previsão estima o gasto faturável do GitHub até o fim do período; no início de um ciclo não há sinal suficiente, então ela fica oculta em vez de mostrar um número em que você não deveria confiar.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt