Organizando Custos: Grupos, Apps e Código

Conectar uma fonte de custo (AWS, Azure, IA, SaaS) já mostra o total gasto — mas "R$ 42.000 na AWS esse mês" não diz se isso é o ERP, o app mobile ou um ambiente de testes esquecido ligado. É a estrutura de Grupos → Apps → Custo por Código que faz a ponte entre o número da fatura e a pergunta que interessa: esse investimento em tecnologia é o certo pro resultado que o negócio precisa?

Este guia assume que você já conectou pelo menos uma fonte de custo — se não, comece pelo Início Rápido.

A hierarquia

• Grupo — o nível mais alto, geralmente um sistema, squad ou unidade de negócio. Pode ter budget próprio e conter outros grupos (subgrupos).
• App — a unidade que de fato recebe custo real (via tag AWS/Resource Group Azure) e budget. Pertence a um Grupo.
• Custo por Código — opcional, granularidade abaixo do App, via SDK — não é uma entidade cadastrada na tela, é um label que aparece automaticamente quando o código é instrumentado.

Grupos

Criados na tela Custos por Negócio → + Criar Grupo.

Campo	Obrigatório	Pra que serve
Nome do grupo	Sim	ex: "ERP", "Squad Ecommerce"
Tag Key / Tag Value	Não	Mecanismo legado de associação por tag. Hoje o vínculo real é App → Grupo (campo "Grupo" no cadastro do App, abaixo) — deixe em branco a menos que esteja migrando uma estrutura antiga.
Métrica / Volume Atual / Receita por Unidade	Não	Unit Economics — se o grupo gera receita mensurável (ex: "usuários ativos" a R$ 0,20/unidade), a plataforma calcula custo por unidade e margem automaticamente.
Budget Mensal (USD) / Alertar em (%)	Não	Teto de gasto do grupo — ver seção abaixo.

Um grupo pode conter subgrupos (grupo dentro de grupo) — útil quando "Squad Ecommerce" precisa de uma visão consolidada, mas você quer o detalhe por sub-time depois.

Budget do Grupo — a regra que conecta Grupo e App

Se você define um budget no Grupo, a plataforma passa a garantir que a soma dos budgets de todos os Apps daquele grupo nunca ultrapasse o budget do grupo. Sem budget no grupo, não existe teto — a tela só soma os budgets dos apps informativamente.

Se você tentar salvar um App com um budget que estouraria o teto do grupo, aparece um alerta com três caminhos:

1. "Ajustar budget do App" — fecha o alerta e mantém o formulário aberto pra você reduzir o valor pra caber no que sobrou.
2. "Aumentar budget do Grupo para [valor] e continuar" — sobe o teto automaticamente pro valor exato necessário; fica registrado no histórico do grupo (data e motivo).
3. "Manter budget do App mesmo assim (ultrapassa o grupo)" — permite o excesso deliberadamente, sem alterar o teto do grupo (útil quando o estouro é temporário e você não quer redefinir o orçamento do grupo por causa disso).

Apps

Criados na tela Custos por Negócio → + Nova App.

Campo	Obrigatório	Pra que serve
Nome da Aplicação	Sim	Se você for instrumentar Custo por Código, use o mesmo texto no product do SDK (ver abaixo — a aba dedicada exige match exato, o drawer do App é mais tolerante)
Descrição, Cor	Não	Só organização visual
Grupo	Não	Vincula o App a um Grupo — é este campo, não a tag do grupo, que define a hierarquia
Budget Mensal (USD) / Alertar em (%)	Não	Budget do próprio App, sujeito à regra de soma do grupo acima
% Custos Compartilhados	Não	Fração de custos não atribuíveis diretamente (rateio) que deve ser somada a este app — ver tela Rateio
Tags AWS (chave/valor)	Não, mas necessário pra custo real aparecer	As Cost Allocation Tags que identificam quais recursos AWS pertencem a este App
Resource Group	Só contas Azure	Alternativa às tags — no Azure a unidade de associação é o Resource Group, não tag livre

Como a associação por tag funciona de verdade

O CloudBroker pede o custo por tag direto do AWS Cost Explorer (GroupBy: TAG). Isso só funciona se a tag key usada estiver ativada como Cost Allocation Tag no console AWS (Billing → Cost Allocation Tags) — uma tag que existe no recurso mas nunca foi ativada lá não aparece no Cost Explorer, e o custo desse recurso cai em "Sem identificação" até você ativar a tag (pode levar até 24h pra propagar depois de ativada).

Custo por container (ECS/Fargate e EKS)

Pra container você não precisa criar tag nenhuma: a AWS gera as tags que identificam o serviço e o cluster, e elas aparecem na lista de Tags AWS do App como qualquer outra:

Chave	O que ela separa
aws:ecs:serviceName	Custo por serviço ECS / Fargate
aws:ecs:clusterName	Custo por cluster ECS
aws:eks:cluster-name	Custo por cluster EKS

O número vem da sua fatura, não de uma tabela de preços — então Savings Plans, Reserved Instances e Spot já entram descontados. Se você tem commitment, é a diferença entre ver o que pagou e ver o que teria pagado sem desconto.

São duas condições, as duas na sua conta AWS:

1. Ativar a chave em Billing → Cost Allocation Tags, na conta pagadora — a mesma regra da seção anterior.

2. Ligar as tags gerenciadas nos seus serviços ECS. Sem isso a AWS não carimba o custo das tasks:

aws ecs update-service \
  --cluster SEU-CLUSTER \
  --service SEU-SERVICO \
  --enable-ecs-managed-tags \
  --propagate-tags SERVICE

Se os serviços são criados por Terraform, CloudFormation ou CDK, declare lá em vez de rodar o comando — senão o próximo apply desfaz a mudança e o custo volta a ficar sem identificação, sem ninguém entender por quê.

O sintoma que engana

Se a chave aparece na lista mas todos os valores vêm vazios, a causa é a condição 2, não a 1.

É contraintuitivo justamente porque a tag está ativada. Mas o Cost Explorer só consegue agrupar pelo que a AWS carimbou, e sem enableECSManagedTags ela não carimba nada — o resultado fica indistinguível de uma conta que não roda container.

Nada disso é retroativo. A atribuição começa quando as duas condições estão valendo e as tasks são recriadas (um deploy novo, ou o próximo start do serviço). O custo anterior a isso continua sem tag.

A visão em tabela (DRE)

Em Custos por negócio, o botão 📊 Tabela (DRE) (alternativo a ▦ Cards) mostra a mesma estrutura como uma planilha de despesas:

• Linhas: cada Grupo (com subtotal, expansível) e, dentro dele, seus Apps. Apps sem Grupo aparecem num pseudo-grupo Sem Grupo, sempre por último — ele não é um Grupo cadastrado, é o que ainda falta organizar.
• Colunas: ☁️ Cloud · 🤖 IA (com tokens) · { } Código (com requests) · 🔗 SaaS · ⚖️ Rateio · Total · Budget (% consumido do orçamento, ou "sem orçamento"). Acima da tabela, uma faixa de KPIs mostra o total consolidado e o total de cada categoria.
• TOTAL GERAL: a última linha soma a conta inteira por categoria, com o peso de cada uma — mesma fonte dos KPIs do topo, então os dois sempre batem.
• IA e Código marcados com i foram atribuídos pelo nome do App (não por vínculo direto) e podem não capturar tudo.

Erro não é zero

Se uma fonte de custo falhar, a célula mostra ⚠ Erro (com "tentar de novo"), nunca R$ 0,00. O total afetado sai marcado parcial — X indisponível, e o % do Budget ganha a marca parcial. Categoria sem fonte configurada aparece como —; quando nenhuma fonte de IA está configurada, um aviso explica que a coluna IA não é custo zero, é ausência de medição.

No fim da tabela, o painel 🧮 Reconciliação — todo custo tem dono? mostra o que ainda não está associado a nenhum App:

• Cloud não identificado — redistribuído via Rateio nos grupos e apps (depois que o Rateio é calculado).
• SaaS não identificado — existe no dado, mas ainda não é somado nesta visão consolidada.
• IA + Código não identificados — sem rastreio hoje: esses eventos são casados por nome; o que não bate com nenhum App não aparece na tabela.

Custo por Código (opcional)

Granularidade abaixo do App — não é cadastrado na tela, aparece automaticamente quando você instrumenta seu backend com o SDK:

const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
  apiKey: "cb-key-xxxx", product: "Backend", team: "erp",
});

await s3.send(new PutObjectCommand({ Bucket: "b", Key: "nf.pdf", Body: buf }), {
  cbLabel: "emissao-nota-fiscal",
});

Duas visões, dois critérios de match diferentes

No drawer do App (dentro de "Custos por Negócio"), o product só precisa conter o nome do App como substring, sem diferenciar maiúsculas — "Backend", "backend" e "backend api" todos batem com um App chamado "Backend". Já na aba dedicada Custo por Código, o match é exato e sensível a maiúsculas — só "Backend" idêntico aparece lá. Pra evitar qualquer ambiguidade, use sempre o nome do App exatamente como cadastrado.

Exemplo 1 — Grupo por Sistema

Empresa organiza custo por sistema de negócio. O ERP tem dois componentes técnicos, e dentro do Backend você quer saber quanto custa cada funcionalidade.

Grupo: ERP — Budget Mensal 2000 (USD), Alertar em 80

App 1: Web

• Grupo: ERP
• Tags AWS: app = erp-web
• Budget Mensal: 600

App 2: Backend

• Grupo: ERP
• Tags AWS: app = erp-backend
• Budget Mensal: 1400
• Instrumentado com o SDK, product: "Backend", labels emissao-nota-fiscal e pagamento — agora o drawer do App "Backend" mostra o breakdown: quanto da fatura AWS é emissão de nota fiscal vs. processamento de pagamento.

Soma dos apps (600 + 1400 = 2000) bate exatamente com o teto do grupo — qualquer app novo no grupo ERP vai precisar do alerta de estouro pra ser adicionado.

Exemplo 2 — Grupo por Squad e Ambiente

Time de tecnologia organiza por squad, e dentro do squad por ambiente — sem preocupação com Custo por Código, só com visibilidade de quanto cada ambiente consome.

Grupo: Squad Ecommerce — Budget Mensal 5000 (USD), Alertar em 90

App 1: Ambiente de DEV

• Grupo: Squad Ecommerce
• Tags AWS: env = dev
• Budget Mensal: 800

App 2: Ambiente de Staging

• Grupo: Squad Ecommerce
• Tags AWS: env = staging
• Budget Mensal: 1500

Sem Custo por Código aqui — a granularidade que interessa pra esse time é por ambiente, não por feature de código. Se Ambiente de Staging sozinho já passar de 1500, o time recebe o alerta de 90% antes de virar surpresa na fatura do fim do mês.

Erros comuns

Sintoma	Causa	Solução
Custo por Código não aparece pra um App na aba Custo por Código	product no SDK não bate exatamente (maiúsculas/minúsculas) com o "Nome da Aplicação" — essa visão exige match exato	Confira maiúsculas/minúsculas e espaços — precisa ser idêntico
App fica com custo R$ 0,00 mesmo com tag configurada	Tag existe no recurso AWS mas não foi ativada como Cost Allocation Tag	Ative em Billing → Cost Allocation Tags no console AWS; aguarde até 24h
A tag aws:ecs:serviceName aparece na lista, mas todos os valores vêm vazios	As tags gerenciadas estão desligadas no serviço ECS — a AWS não carimbou o custo das tasks. A chave estar ativada não basta	Rode o update-service com --enable-ecs-managed-tags --propagate-tags SERVICE e aguarde as tasks serem recriadas — ver Custo por container
Não encontro nenhuma tag aws:ecs: ou aws:eks: na lista	A chave nunca foi ativada como Cost Allocation Tag	Ative em Billing → Cost Allocation Tags na conta pagadora — em organizações, não é a mesma conta que você conectou ao CloudBroker
Não consigo salvar um App com o budget que eu queria	Somaria mais que o teto do Grupo	Veja as 3 opções do alerta de estouro — geralmente "Aumentar budget do Grupo e continuar" é o caminho certo se o novo total reflete a realidade
App não aparece dentro do Grupo esperado	Campo "Grupo" do App não foi preenchido, ou só a Tag Key do grupo (legada) foi usada	Edite o App e selecione o Grupo diretamente no campo "Grupo"

Próximo passo

Se seus Apps já têm custo real aparecendo, o próximo ganho é o SDK pra granularidade de código, ou o FinOps Advisor pra perguntar "quanto custa o ERP esse mês" em linguagem natural.