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 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
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.