AWS Cost Monitor

Problema que resolve

Muitas equipes só percebem aumentos de custo na AWS quando a fatura chega. Faltam visibilidade sobre onde o dinheiro está sendo gasto e avisos antecipados de variações inesperadas.

Para quem é útil

• Equipes e profissionais que usam AWS e querem visibilidade sobre o custo por serviço
• Times de engenharia e DevOps
• Quem estuda ou pratica FinOps na AWS

Como funciona

O princípio do projeto é Python calcula, IA interpreta.

• Cálculo determinístico em Python: o código consulta a AWS, soma, filtra e calcula percentuais e variações. A mesma entrada gera sempre o mesmo resultado.
• Interpretação por IA: a IA lê os números já calculados e produz uma leitura em linguagem natural. Os cálculos não são delegados ao modelo. A interpretação deve ser conferida com os dados, pois modelos podem gerar afirmações incorretas.
• Camada de IA desacoplada e substituível: hoje usa um modelo local. O design permite trocar por outros provedores, como OpenAI, Claude, Gemini ou Amazon Bedrock, sem mudar a lógica de análise. Essa troca ainda não está implementada (ver Roadmap).

Fluxo de execução, orquestrado por src/main.py, com configuração em src/config.py:

1. cost_explorer.py — coleta os custos no AWS Cost Explorer.
2. cost_analyzer.py — calcula a análise de forma determinística.
3. finops_rules.py — aplica as regras FinOps.
4. report_generator.py — gera o relatório em texto, JSON ou Markdown.
5. reports/ — pasta onde o relatório é salvo.

A camada de IA (llama_client.py) é opcional e não bloqueante: se o Llama estiver fora do ar, o relatório sai mesmo assim, sem a seção de interpretação.

Funcionalidades atuais (V1)

1. Verificação da conexão com a AWS via STS get_caller_identity (src/test_aws.py).
2. Coleta de custos no AWS Cost Explorer com boto3:
   • região configurável (padrão us-east-1);
   • janela configurável (padrão de 30 dias);
   • granularidade MONTHLY, métrica UnblendedCost e agrupamento por SERVICE;
   • tratamento explícito de credenciais ausentes, permissão insuficiente e erros do Cost Explorer.
3. Análise determinística: agrupamento por serviço, custo total, serviços com custo positivo, percentual por serviço, maior serviço e comparação entre os dois períodos mais recentes. Divisão por zero tratada: quando o período anterior tem custo zero, a variação fica None.
4. Regras FinOps determinísticas: alerta de crescimento de custo entre períodos, alerta de concentração de custo em um único serviço e ranking dos serviços de maior custo (top N). Limites configuráveis (padrões: 20% de crescimento, 50% de concentração e top 5). Sem IA e sem acesso à rede.
5. Interpretação com IA local: Llama por meio de uma API compatível com Ollama. Se o modelo estiver indisponível, isso é tratado: o relatório sai sem a seção de interpretação. A camada pode ser desligada com AI_ENABLED=false.
6. Relatório com período, custo total, custo e percentual por serviço, maior serviço, comparação entre períodos, alertas e interpretação. Formatos: texto (padrão), JSON ou Markdown.
7. Testes automatizados com pytest e mocks, sem acessar a conta AWS real nem o Llama: 39 testes.

Stack

• Python 3.14 ou superior
• uv
• boto3
• requests
• python-dotenv
• pytest
• AWS Cost Explorer
• AWS STS
• Llama local (por exemplo, via Ollama)

Segurança

• IAM de menor privilégio: a identidade usada precisa apenas de ce:GetCostAndUsage e sts:GetCallerIdentity.
• Credenciais fora do repositório: são lidas da configuração do AWS CLI ou de variáveis de ambiente e nunca ficam no repositório.
• Arquivos não versionados: .env, dados e relatórios gerados ficam fora do Git.

Política IAM mínima:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Limitações atuais

• A interpretação depende de um Llama local em execução. Sem ele, o relatório sai sem a seção de IA, que é o comportamento esperado.
• A granularidade é mensal e a janela é contada em dias corridos a partir da data atual.
• Não há persistência de histórico além dos arquivos em reports/.
• As regras FinOps cobrem apenas crescimento, concentração e ranking.

Roadmap

Itens planejados. Nada desta lista está implementado na V1.

• planejado Granularidade e janelas mais ricas, como DAILY e últimos N meses.
• planejado CLI com argumentos (--days, --format, --no-ai).
• planejado Sistema de alertas e notificações.
• planejado Outros provedores de IA: OpenAI, Claude, Gemini e Amazon Bedrock.
• planejado Evolução para arquitetura serverless: Lambda, EventBridge, SNS e CloudWatch.
• planejado Execução agendada e automatizada.