User's blog

Dashboard de métricas Git serverless com Amazon QuickSight

Written by

Make.com Service User

in

Por que monitorar métricas Git com serviços AWS?

A atividade no Git é um dos sinais mais ricos que equipes de engenharia produzem. Commits, pull requests, issues e padrões de contribuição revelam muito sobre a saúde e a velocidade de um time. O problema histórico sempre foi: extrair essas métricas em escala exige pipelines de Extração, Transformação e Carga (ETL) feitos à mão, infraestrutura dedicada e manutenção constante.

Além disso, com a adoção crescente de ferramentas de IA para desenvolvimento, surge uma pergunta legítima: essas ferramentas estão de fato acelerando os times, ou apenas inflando contadores? O framework AI-Driven Development Lifecycle (AI-DLC) da AWS deixa isso claro: se você usa ferramentas de IA para codificação, precisa de números para embasar a decisão. Defina uma linha de base, acompanhe o que muda e não pare de medir. Sem isso, você está voando às cegas.

Para resolver esse problema, a AWS publicou uma solução serverless que automatiza a coleta de métricas do GitHub e do GitLab, processa os dados e os exibe em dashboards interativos usando o Amazon QuickSight. A proposta é oferecer visibilidade quase em tempo real sobre atividades de desenvolvimento, com custo baixo e zero gestão de servidores.

Visão geral da solução

A solução implementa um pipeline orientado a eventos que coleta métricas de repositórios via APIs do GitHub e GitLab de forma agendada. Os dados são processados por um fluxo de orquestração serverless e persistidos no Amazon Simple Storage Service (Amazon S3) para visualização no Amazon QuickSight.

As principais capacidades da solução incluem:

  • Detecção inteligente de mudanças: uma função dedicada monitora os feeds de eventos do GitHub e do GitLab para verificar se houve alterações — commits, pull requests, issues, criação ou exclusão de repositórios — desde a última coleta. Se nada mudou, o processamento é ignorado por completo.
  • Particionamento adaptativo: para organizações com mais de 20 repositórios, a solução divide automaticamente a carga em lotes paralelos e os processa de forma concorrente usando os Map states do AWS Step Functions.
  • Carga completa e incremental: na primeira execução, o sistema realiza uma carga completa de todos os metadados. Nas execuções seguintes, coleta apenas o que mudou. A cada 24 horas, uma carga completa é acionada automaticamente para garantir a precisão dos dados.
  • Agendamento configurável: a frequência de coleta é definida como parâmetro no AWS CloudFormation, aceitando expressões rate() e cron().

Arquitetura da solução

A arquitetura usa seis serviços AWS principais para construir um pipeline totalmente gerenciado e orientado a eventos:

Amazon EventBridge Scheduler

O Amazon EventBridge Scheduler dispara o fluxo de trabalho no intervalo configurado, sem necessidade de gatilhos externos ou intervenção manual.

AWS Step Functions

O AWS Step Functions orquestra todo o fluxo de coleta por meio de uma máquina de estados. Ela invoca primeiro o detector de mudanças e, com base no resultado, decide entre uma carga completa ou incremental. Se o número de repositórios ativos ultrapassar o limite de particionamento (padrão: 20), os repositórios são divididos em lotes iguais e processados em paralelo. O fluxo inclui lógica de retentativas com backoff exponencial para falhas transitórias de API.

AWS Lambda

O AWS Lambda executa duas funções distintas:

  • Detector de mudanças (github-change-detector): consulta os feeds de atividade para determinar o tipo de carga. Monitora seis categorias de eventos: push, pull requests, criação e atualização de issues, criação e exclusão de repositórios, e mudanças de contribuidores. Se não houver eventos relevantes desde a última verificação, o fluxo é encerrado antecipadamente.
  • Coletor de métricas (github-metrics-collector): realiza a coleta efetiva dos dados. Opera em três modos: collect_all para processamento direto, collect_chunk para processar um subconjunto de repositórios em execução paralela, e aggregate para combinar os resultados dos lotes.

AWS Secrets Manager

Os tokens Git são armazenados com segurança no AWS Secrets Manager. Ambas as funções Lambda recuperam os tokens em tempo de execução, garantindo que as credenciais nunca sejam codificadas diretamente no código ou passadas como variáveis de ambiente.

Amazon S3

As métricas coletadas são armazenadas no Amazon S3 com versionamento e criptografia do lado do servidor habilitados. O resultado inclui um arquivo JSON estruturado com a resposta completa da API e um arquivo CSV achatado, otimizado para análise. Ambos os arquivos contêm campos como nome do repositório, total de commits, pull requests abertas e fechadas, issues abertas e fechadas, número de contribuidores, linguagem principal, timestamp da última atividade e data de criação do repositório.

Amazon QuickSight

O Amazon QuickSight lê os dados CSV do S3 ou via Amazon Athena para consultas SQL. Os dados são carregados no SPICE (Super-fast, Parallel, In-memory Calculation Engine — Motor de Cálculo Em Memória Paralelo e Ultra-rápido), uma camada de processamento em memória, para construir dashboards interativos com visualizações de métricas resumidas, tendências de pull requests, atividade de desenvolvimento ao longo do tempo, detalhamento por repositório e análise de contribuidores.

Pré-requisitos

Para seguir o passo a passo, você vai precisar de:

Passo a passo de implantação

Passo 1: Criar tokens de acesso pessoal

Antes de implantar a infraestrutura, você precisa de tokens de API para cada plataforma Git que pretende monitorar.

Para o GitHub: acesse Configurações → Configurações do desenvolvedor → Personal access tokens → Tokens (classic). Gere um novo token selecionando apenas as permissões mínimas necessárias: repo (acesso somente leitura a metadados, commits e pull requests) e read:org (acesso somente leitura à associação da organização). Copie e armazene o token com segurança.

Para o GitLab: acesse Configurações → Access Tokens, crie um novo token com os escopos necessários e copie o token gerado.

Passo 2: Armazenar tokens no AWS Secrets Manager

Armazene cada token como um secret no AWS Secrets Manager usando a AWS CLI:

# Armazenar token do GitHub
aws secretsmanager create-secret \
  --name git-dashboard/github-token \
  --description "GitHub Personal Access Token for Git Dashboard" \
  --secret-string "ghp_YOUR_TOKEN_HERE" \
  --region us-east-1

# Armazenar token do GitLab
aws secretsmanager create-secret \
  --name git-dashboard/gitlab-token \
  --description "GitLab Personal Access Token for Git Dashboard" \
  --secret-string "glpat-YOUR_TOKEN_HERE" \
  --region us-east-1

Passo 3: Implantar a stack do CloudFormation

Faça o download do template CloudFormation de exemplo e implante a solução em seu ambiente de não produção.

Opção 1: via AWS CLI. Substitua os valores entre colchetes angulares (<...>) pelo seu ID de conta AWS, região e os ARNs dos secrets do Passo 2:

aws cloudformation create-stack \
  --stack-name git-metrics-pipeline \
  --template-body file://infrastructure/template.yaml \
  --parameters \
  ParameterKey=BucketName,ParameterValue=git-metrics-<ACCOUNT_ID>-<REGION> \
  ParameterKey=ScheduleExpression,ParameterValue="rate(10 minutes)" \
  ParameterKey=ChunkingThreshold,ParameterValue=20 \
  ParameterKey=GitHubTokenSecretArn,ParameterValue=<YOUR_GITHUB_SECRET_ARN> \
  ParameterKey=GitLabTokenSecretArn,ParameterValue=<YOUR_GITLAB_SECRET_ARN> \
  ParameterKey=EnabledPlatforms,ParameterValue="github,gitlab" \
  --capabilities CAPABILITY_NAMED_IAM

Opção 2: via AWS Management Console. Acesse o console do AWS CloudFormation, escolha “Create stack” com novos recursos, faça upload do template, preencha os parâmetros e clique em Submit. A stack atinge o status CREATE_COMPLETE em 3 a 5 minutos, criando: um bucket S3 com versionamento e criptografia, duas funções Lambda (runtime Python 3.13), uma role IAM com permissões de privilégio mínimo, uma máquina de estados do Step Functions, uma regra de agendamento no EventBridge e as roles IAM associadas.

Passo 4: Fazer upload do pacote de implantação Lambda

O template do CloudFormation implanta código placeholder nas funções Lambda. Atualize-as com a lógica real usando o pacote pré-compilado do repositório clonado. O arquivo lambda-package.zip está no diretório deployment/. Substitua <YOUR_BUCKET_NAME> pelo nome do bucket S3 criado pela sua stack:

# Fazer upload do pacote para o S3
aws s3 cp deployment/lambda-package.zip s3://<YOUR_BUCKET_NAME>/lambda/lambda-package.zip

# Atualizar a Lambda do Detector
aws lambda update-function-code \
  --function-name github-change-detector \
  --s3-bucket <YOUR_BUCKET_NAME> \
  --s3-key lambda/lambda-package.zip

# Atualizar a Lambda do Coletor
aws lambda update-function-code \
  --function-name github-metrics-collector \
  --s3-bucket <YOUR_BUCKET_NAME> \
  --s3-key lambda/lambda-package.zip

Passo 5: Executar e validar

Acione o fluxo manualmente para verificar o funcionamento de ponta a ponta. Substitua <ACCOUNT_ID> pelo seu ID de conta AWS de 12 dígitos e <REGION> pela região de implantação:

aws stepfunctions start-execution \
  --state-machine-arn arn:aws:states:<REGION>:<ACCOUNT_ID>:stateMachine:github-metrics-workflow \
  --input '{}'

Monitore a execução no console do AWS Step Functions. Uma execução bem-sucedida produz o status SUCCEEDED em poucos minutos. Verifique se o arquivo response.json aparece no bucket S3 sob o prefixo output/.

Passo 6: Conectar o Amazon QuickSight ao armazenamento de dados no S3

Crie um arquivo de manifesto chamado manifest.json apontando para o bucket S3 e o arquivo JSON. Consulte os formatos suportados para arquivos de manifesto do Amazon S3 para informações sobre o formato. Substitua <ACCOUNT_ID> e <REGION> pelos seus valores:

{
  "fileLocations": [
    {
      "URIs": [
        "s3://<Your_Bucket_Name>-<REGION>/output/response.json"
      ]
    }
  ],
  "globalUploadSettings": {
    "format": "JSON",
    "delimiter": ",",
    "textqualifier": "'",
    "containsHeader": "true"
  }
}

Acesse o console do Amazon QuickSight, navegue até Dados → Fontes de dados e escolha “Create data source”. Selecione Amazon S3, forneça um nome para a fonte de dados, faça upload do arquivo de manifesto e clique em Connect.

Observação: se você receber um erro de permissão indicando que o QuickSight não tem acesso ao bucket S3, será necessário autorizar o QuickSight a acessar seus recursos S3. Acesse QuickSight → nome da conta → Manage QuickSight → Security & permissions → Quick Sight access to AWS services → Manage → Amazon S3, e adicione o bucket de métricas. Para instruções detalhadas, consulte Gerenciando permissões do Amazon QuickSight para recursos AWS.

Em seguida, navegue até Dados → Datasets e escolha “Create dataset”. Selecione a fonte de dados criada e clique em Visualize. Isso cria uma nova análise. Crie as visualizações dos dashboards interativos alterando o tipo de visual e escolhendo campos como total de commits, pull requests, issues, tendências de merge de PRs e repositórios ativos versus inativos. Um código de exemplo para criar um dashboard está disponível no repositório GitHub que acompanha a solução.

Passo 7 (opcional): Configurar alertas

Configure alarmes no Amazon CloudWatch para monitorar a saúde do pipeline. Por exemplo, crie um alarme que dispare quando o número de falhas de execução do Step Functions ultrapassar zero em uma janela de uma hora, enviando uma notificação para um tópico do Amazon Simple Notification Service (Amazon SNS) para a equipe de operações.

Limpeza dos recursos

Para evitar cobranças contínuas, remova todos os recursos quando não precisar mais da solução:

# Passo 1: Esvaziar e excluir o bucket S3
aws s3 rm s3://git-metrics-amzn-s3-demo-bucket --recursive
aws s3 rb s3://git-metrics-amzn-s3-demo-bucket

# Passo 2: Excluir a stack do CloudFormation
aws cloudformation delete-stack --stack-name git-metrics-pipeline
aws cloudformation wait stack-delete-complete --stack-name git-metrics-pipeline

# Verificar se a stack foi excluída
aws cloudformation describe-stacks \
  --stack-name git-metrics-pipeline \
  --query "Stacks[0].StackStatus"

# Passo 3: Excluir os secrets do Secrets Manager
aws secretsmanager delete-secret --secret-id git-dashboard/github-token --force-delete-without-recovery
aws secretsmanager delete-secret --secret-id git-dashboard/gitlab-token --force-delete-without-recovery

Por fim, remova os datasets e análises do QuickSight diretamente pelo console. Após esses passos, nenhum recurso desta solução permanece na conta e nenhum custo adicional será gerado.

Conclusão

A solução demonstra como construir um sistema de análise Git totalmente serverless que coleta automaticamente dados de atividade de desenvolvimento do GitHub e do GitLab, persiste tudo no Amazon S3 e visualiza os resultados em dashboards interativos do Amazon QuickSight. O resultado é uma solução de inteligência de engenharia leve, de baixo custo e com manutenção operacional próxima de zero.

Gerentes de engenharia ganham visibilidade sobre o status dos sprints, gerentes de produto ganham confiança sobre a prontidão para releases, e desenvolvedores ganham consciência sobre suas contribuições — tudo isso sem gerenciar nenhuma infraestrutura.

Para equipes que adotam ferramentas modernas de desenvolvimento com IA, a solução também se alinha à metodologia do AI-Driven Development Lifecycle (AI-DLC). Ela fornece a camada de medição contínua necessária para definir linhas de base, rastrear mudanças de velocidade e quantificar o retorno sobre o investimento (ROI) real. Métricas como commits por sprint, throughput de PRs, tempo de ciclo de revisão e diversidade de contribuidores ajudam a determinar se as ferramentas de IA estão gerando melhorias reais na entrega.

Recursos adicionais

Fonte

A serverless, data-driven Git metrics dashboard using Amazon Quick Sight (https://aws.amazon.com/blogs/machine-learning/a-serverless-data-driven-git-metrics-dashboard-using-amazon-quick-sight/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts