Criar uma avaliação de modernização de apps

A Avaliação de modernização de apps do Migration Center (codmod) é uma ferramenta com tecnologia de IA que automatiza o processo de avaliação de modernização do seu aplicativo. Nesta página, descrevemos as etapas para instalar, usar e resolver problemas da ferramenta codmod.

Sobre a Avaliação de Modernização de Apps

O processo típico de avaliação de modernização leva algumas semanas e exige muita experiência. Ao automatizar esse processo, a ferramenta codmod reduz significativamente esse tempo para algumas horas.

Essa ferramenta tem como objetivo fornecer informações baseadas em evidências sobre a arquitetura, a funcionalidade e os possíveis bloqueadores do aplicativo atual que podem atrasar a transformação para a nuvem.

Esta ferramenta é destinada aos seguintes papéis:

  • Arquitetos de TI
  • Tomadores de decisão
  • Proprietários do aplicativo

A ferramenta codmod tem como objetivo acelerar a transformação de aplicativos, fornecendo visibilidade clara das mudanças necessárias e dos benefícios obtidos com a transformação do aplicativo para o Google Cloud. A codmod é uma ferramenta de CLI portátil que usa o Gemini para analisar o código-fonte e oferece recomendações com base nas práticas recomendadas do Google Cloud .

Antes de começar

A ferramenta codmod requer os seguintes pré-requisitos:

  • Uma estação de trabalho Linux ou Windows (10 ou mais recente).
  • Acesso a um projeto do Google Cloud com a API Vertex AI ativada.
  • Uma instalação da CLI gcloud na sua estação de trabalho. Para mais informações, consulte Instalar a CLI gcloud.

Preços

O custo de usar o Gemini para avaliação de código é determinado principalmente pelo tamanho da base de código e é medido em tokens. A tabela a seguir mostra as estimativas de custo que você pode esperar com base nas linhas de código e no modelo escolhido:

Base de código Linhas de código (LOC) Custo estimado
adaptável 2.5-flash 2.5-pro 3.5-flash 3.8-flash (padrão)
Spring Petclinic ~6.500 US$ 20 US$ 3 US$ 20 US$ 3 US$ 9
Projeto James ~1.000.000 US$ 40 US$ 30 US$ 200 US$ 200 US$ 200
Elasticsearch ~5.000.000 US$ 200 US$ 200 US$ 900 US$ 500 US$ 500

Esses valores podem ser uma superestimativa porque não consideram possíveis economias devido ao seguinte:

  • Preços reduzidos para consultas curtas.
  • Preços reduzidos para armazenamento em cache implícito.
  • Descontos por compromisso de uso (CUDs).

Os custos desses parâmetros devem ser uma parte insignificante do custo total, especialmente para bases de código maiores. Para mais informações, consulte Preços da API Gemini.

Informações adicionais

A ferramenta usa os recursos avançados de compreensão e análise de código da API Vertex AI. Para mais informações sobre os modelos disponíveis e os recursos deles, consulte Modelos do Google na documentação da API Vertex AI.

Para manter o desempenho e a eficiência de custos ideais, o codmod tem um limite de tamanho de base de código de aproximadamente 6 milhões de linhas de código. Para bases de código que excedem esse limite, recomendamos dividi-las em partes menores e gerenciáveis para análise. Analisar seções menores também pode ajudar em avaliações mais focadas e reduzir o tempo geral de processamento.

Configurar codmod

Nesta seção, fornecemos instruções de instalação e autenticação para usar a ferramenta codmod.

Instalar codmod

Windows

Execute o seguinte comando no Windows PowerShell para fazer o download da versão mais recente do codmod:

$version=curl.exe -s https://codmod-release.storage.googleapis.com/latest
curl.exe -O "https://codmod-release.storage.googleapis.com/${version}/windows/amd64/codmod.exe"

Linux

Execute o seguinte comando para baixar a versão mais recente do codmod:

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/linux/amd64/codmod"
chmod +x codmod

Para usar o comando codmod, adicione o executável ao caminho ou crie um alias.

Autenticar-se no Google Cloud

Para usar a ferramenta codmod, você precisa de um projeto do Google Cloud .

  1. Verifique se a API Vertex AI está ativada no projeto no console ou usando a CLI:

    gcloud services enable aiplatform.googleapis.com --project <project-id>

  2. Verifique se você tem o papel roles/aiplatform.user ou semelhante no projeto.

  3. Para autenticar, execute o seguinte comando:

    gcloud auth application-default login

Como alternativa, é possível usar uma conta de serviço e definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Para saber mais, consulte Como o Application Default Credentials funciona.

Gerenciar a configuração codmod

As seções a seguir explicam como configurar codmod com o comando codmod config.

Listar todas as configurações

Para ver todas as propriedades de configuração atuais e os valores delas, execute o seguinte comando:

codmod config list

Definir um valor padrão para uma flag

Para definir um valor padrão para uma propriedade, use o comando set. Por exemplo, para definir o ID do projeto padrão, execute:

codmod config set project "PROJECT_ID"

Substitua PROJECT_ID pelo ID do projeto do Google Cloud .

Para definir a região padrão, execute:

codmod config set region "REGION"

Substitua REGION pela região do Google Cloud . Consulte a lista de regiões disponíveis. Se você não tiver certeza de qual região usar, use us-central1.

Receber um valor específico

Para ver o valor de uma única propriedade, use o comando get. Por exemplo, para receber o ID do projeto configurado, execute o seguinte comando:

codmod config get project

Remover um valor padrão

Para remover um padrão configurado e reverter para a configuração padrão original da ferramenta, use o comando unset. Por exemplo, para remover o ID do projeto padrão, execute o seguinte comando:

codmod config unset project

Criar um relatório de avaliação do codmod

As seções a seguir descrevem como criar a avaliação padrão e como personalizá-la de acordo com suas necessidades.

Criar o relatório padrão

Para criar um relatório de avaliação, execute a ferramenta codmod com as seguintes flags:

codmod create -c "CODEBASE" -o "OUTPUT"

Substitua:

  • CODEBASE: especifica o diretório que contém o código-fonte a ser analisado e pode ser especificado várias vezes.
  • OUTPUT: especifica o caminho em que o relatório gerado é salvo. O relatório está no formato HTML.

É possível substituir o projeto e a região padrão com as sinalizações -p "PROJECT_ID" e -r "REGION", respectivamente.

Também é possível especificar as seguintes flags opcionais:

  • --modelset [2.5-flash|2.5-pro|3.5-flash|3.8-flash|adaptive]: especifica quais modelos do Gemini usar. O valor padrão é 3.8-flash. O modo adaptável oferece uma redução significativa de custos, mas pode comprometer a qualidade do relatório em comparação com o modo 2.5-pro.
  • --format <html|markdown|odt|json>: o formato usado para o relatório gerado. O padrão é HTML.
  • --allow-large-codebase: por padrão, o codmod vai pedir confirmação antes de analisar bases de código com mais de 1 milhão de linhas de código para evitar custos altos. Essa opção serve como uma confirmação não interativa. Também é possível ativar isso por padrão executando codmod config set allow_large_codebase true.
  • --improve-fidelity: quando definido, codmod gera seções em série, em vez de em paralelo. Isso melhora a consistência entre as diferentes seções do relatório final, mas requer um tempo de execução mais longo.
  • --force-include <strings>, --force-exclude <strings>: por padrão, o codmod verifica extensões de arquivo conhecidas, incluindo Java, .NET e Python. Use essas flags para incluir ou excluir extensões de arquivo. O argumento precisa ser uma expressão regular com a sintaxe RE2.
  • --experiments: especifique --experiments=enable_pdf,enable_images para oferecer suporte a PDFs e imagens em codmod.
  • --context <string>: qualquer contexto adicional que você queira fornecer sobre o projeto. A ferramenta considera esse contexto ao gerar o relatório.
  • --context-file <path>: igual a --context, em que o contexto é fornecido no arquivo especificado.
  • --supporting-documents <path>: especifica um diretório de documentação de suporte sobre a base de código. Os arquivos nesse diretório podem ser referenciados no contexto fornecido com as flags --context ou --context-file para serem incluídos na análise. Os formatos aceitos incluem texto, PDF e imagens (PNG, JPG, JPEG).

Criar um relatório completo

Se você precisar de uma análise completa, crie um relatório usando o comando create full:

codmod create full -c "~/mycodebase/" -o "report.html"

Criar um relatório focado na camada de dados

Se for necessário prestar mais atenção à camada de dados, é possível criar um relatório com foco nessa área:

codmod create data-layer -c "CODEBASE" -o "OUTPUT"

Criar um relatório para uma intent de transformação específica

Se você quiser focar o relatório em uma intenção de modernização específica, use uma das seguintes intenções compatíveis:

  • Transformação de carga de trabalho da Microsoft (MICROSOFT_MODERNIZATION): use com aplicativos em execução no SO da Microsoft. A avaliação se concentrará em jornadas de transformação que modernizarão os frameworks baseados em .NET para usar a versão mais recente e reduzir as dependências de licenças da Microsoft.
  • Transformação de carga de trabalho de nuvem para nuvem (CLOUD_TO_CLOUD): use com aplicativos em execução em outra infraestrutura de hiperescala. A avaliação vai se concentrar nas mudanças recomendadas para transformar o aplicativo, como o mapeamento de outros serviços de fornecedores de nuvem para os serviços doGoogle Cloud .
  • Transformação legada do Java (JAVA_LEGACY_TO_MODERN): use com aplicativos que executam a versão Java 8 ou similar. A avaliação se concentrará em encontrar dependências de upgrade e áreas no código afetadas pela mudança para o Java 21 (o LTS atual).
  • Transformação legada do Java WILDFLY (WILDFLY_LEGACY_TO_MODERN): use com bases de código Java EE/Jakarta EE em execução em versões do servidor de aplicativos WildFly anteriores à mais recente. A avaliação vai se concentrar na identificação de dependências de upgrade e áreas no código afetadas pelo upgrade da versão do servidor de aplicativos WildFly, incluindo as mudanças necessárias para diferenças e compatibilidade de APIs.
  • Migração de aplicativos C/C++ para a arquitetura Arm (ARM_MIGRATION): use com aplicativos C/C++ para avaliar a prontidão e o esforço necessários para migrar de arquiteturas baseadas em x86 para arquiteturas baseadas em Arm, como VMs Google Cloud Axion C4A. A avaliação se concentra na identificação de possíveis problemas de portabilidade de código, dependências específicas da arquitetura, modificações no sistema de build e considerações de teste necessárias para uma transição bem-sucedida para o Arm do Google Cloud ou de outro CSP, como as instâncias Graviton da AWS.

Para criar um relatório focado na intent, use a flag --intent:

codmod create -c "CODEBASE" -o "OUTPUT" --intent "INTENT"

Criar um relatório com outras seções

A ferramenta permite incluir outras seções que não estão incluídas por padrão para reduzir custos. As seguintes seções são compatíveis:

  • files: uma visualização hierárquica estruturada das pastas do projeto e uma descrição do conteúdo de cada pasta para ajudar você a se orientar nos arquivos do projeto.
  • classes: um catálogo de classes de código com informações sobre cada classe e as dependências dela em outras classes. Os idiomas compatíveis são Java e C#.

Para criar as seções adicionais, use a flag --optional-sections:

codmod create -c "CODEBASE" -o "OUTPUT" --optional-sections "SECTIONS"

Substitua SECTIONS por uma lista de valores separada por vírgulas.

Criar um relatório personalizado

Se você quiser analisar alguns tópicos personalizados específicos, crie um relatório personalizado com base no contexto fornecido usando o seguinte comando:

codmod create custom -c "CODEBASE" -o "OUTPUT" --context "CONTEXT"

Por padrão, um LLM é usado para expandir o contexto fornecido e adaptá-lo para garantir que uma seção coerente seja gerada. Para desativar esse comportamento, especifique --improve-context=false.

Outras flags:

  • --from-template <path>: especifica um arquivo de modelo que define a estrutura do documento no formato de arquivo de texto ou PDF. codmod detecta a estrutura e pede aprovação para continuar gerando o relatório.
  • --skip-template-approval: pula o pedido de aprovação ao usar a flag --from-template.

Modificar um relatório

É possível criar uma nova seção em um relatório ou modificar uma seção atual com base em uma seção específica. Por exemplo, talvez você queira se concentrar em um aspecto específico da arquitetura do sistema ou em um tipo específico de vulnerabilidade de segurança.

Os comandos que modificam um relatório exigem as seguintes flags:

  • Um de --context e --context-file: especifique a solicitação de modificação.
  • --from-report: especifica o caminho para o arquivo de relatório atual.
  • --from-section: nome da seção que será usada como base para uma nova seção (por exemplo, "Visão geral" ou "Arquitetura").

Para exibir todas as seções disponíveis em um relatório específico, execute o seguinte comando:

codmod list-sections --from-report "REPORT"

Revisar uma seção do relatório

Execute o seguinte comando para modificar uma seção:

codmod revise section -c "CODEBASE" --from-report "REPORT" \
  -o "REVISED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"

Criar uma seção de relatório

Crie uma nova seção usando o seguinte comando:

codmod create section -c "CODEBASE" --from-report "REPORT" \
  -o "REGENERATED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"
  • A flag from-section no comando create section é opcional.
  • Por padrão, um LLM é usado para expandir o contexto fornecido e adaptá-lo para garantir que uma seção coerente seja gerada. Para desativar esse comportamento, especifique --improve-context=false.

Observe o seguinte:

  • create section e revise section são compatíveis apenas com o formato de relatório html.
  • create section, revise section, list-sections esperam que a flag --from-report aponte para um relatório no formato HTML.

Estimar custos de avaliação

A ferramenta codmod ajuda você a entender o custo de uso da ferramenta, permitindo calcular o custo aproximado de criação de um relatório. Para ver sua estimativa de custo, execute o seguinte comando:

codmod create --estimate-cost -c "CODEBASE"

As estimativas de custo não são compatíveis com os comandos create section e create custom.

Defina o nível de detalhamento

A verbosidade codmod é configurada usando a flag --verbosity LEVEL. O nível de verbosidade dos registros é um dos seguintes: debug, info, warn, error ou none. O valor padrão é warn.

Verificar e atualizar a versão da CLI codmod

A CLI codmod pode verificar automaticamente se uma versão mais recente está disponível.

Verificações automáticas

A cada 24 horas, a CLI consulta um bucket do Cloud Storage para verificar se uma versão mais recente do codmod foi lançada. Se uma versão mais recente for encontrada, uma mensagem de notificação vai aparecer no terminal. A mensagem inclui o número da nova versão e um link para baixar a atualização. Esse processo ajuda a garantir que você fique por dentro dos recursos, das melhorias e das correções de bugs mais recentes.

Desativar as verificações de versão

Se preferir desativar a verificação automática de versão, use o comando config set:

codmod config set disable_version_check true

Para reativar a verificação de versão, defina o valor como false:

codmod config set disable_version_check false

Para conferir o estado atual dessa e de outras configurações, execute:

codmod config list

Preenchimento automático da linha de comando

A ferramenta de CLI codmod é compatível com o preenchimento de linha de comando do shell para Bash, Zsh, Fish e PowerShell. Esse recurso ajuda você a digitar rapidamente comandos, flags e argumentos pressionando a tecla Tab para ver e selecionar as opções disponíveis.

O preenchimento automático oferece os seguintes benefícios:

  • Preenchimento automático de comandos e flags:comece a digitar um comando ou flag do codmod e pressione Tab para ver as opções de preenchimento.
  • Descobrir opções:confira os valores válidos para determinadas flags. Por exemplo:
    • codmod create --modelset [TAB] sugere conjuntos de modelos disponíveis (por exemplo, 2.0-flash, 2.5-pro).
    • codmod create --format [TAB] sugere formatos de saída (por exemplo, html, json, markdown).
    • codmod create --intent [TAB] sugere intents predefinidas.
  • Sugestões que consideram o contexto:o preenchimento é adaptado ao comando. Por exemplo:
    • codmod config set [TAB] sugere as chaves de configuração disponíveis que você pode definir.
    • codmod config get [TAB] sugere as chaves de configuração disponíveis que você pode receber.
    • O preenchimento do caminho do arquivo é oferecido apenas para flags ou argumentos que esperam um caminho de arquivo ou diretório (por exemplo, --codebase, --output-path). Outras flags, como --project, não sugerem mais nomes de arquivos.

Ativar o preenchimento do shell

Antes de ativar o preenchimento automático do shell, verifique se o comando codmod funciona adicionando o executável ao caminho ou criando um alias.

Para carregar preenchimentos para o shell, execute o comando apropriado. As instruções variam de acordo com o shell. Use o comando help para receber instruções específicas:

# For Bash
codmod completion bash --help

# For Zsh
codmod completion zsh --help

# For Fish
codmod completion fish --help

# For PowerShell
codmod completion powershell --help

Por exemplo, para carregar o preenchimento do Bash no Linux, adicione o seguinte ao ~/.bashrc:

source <(codmod completion bash)

Reinicie o shell ou use o comando source no seu perfil (por exemplo, source ~/.bashrc) para que as mudanças entrem em vigor.

Solução de problemas

  • Permissão negada:se você encontrar um erro de "permissão negada", verifique se concedeu a permissão de execução ao binário codmod executando o comando chmod +x codmod.
  • A CLI parece travar:a análise pode levar muito tempo, mas geralmente é possível ver o progresso na barra de progresso da CLI. Se a barra de progresso permanecer em 0% após 15 minutos, verifique se você tem cota suficiente para o modelo relevante. Por padrão, o codmod usa o modelo gemini-3.8-flash. No entanto, isso está sujeito a mudanças, já que diferentes conjuntos de modelos usam modelos diferentes para finalidades diferentes.

  • Relatar erros:se houver um erro que precise de investigação, colete as informações de depuração para ajudar nossa equipe de desenvolvimento. Os registros fornecem detalhes cruciais para a solução de problemas. Execute o comando a seguir para coletar os registros, compacte e compartilhe o arquivo resultante com a equipe em codmod-feedback-external@google.com.

    codmod collect-logs -o "codmod_logs.zip"

Licenças de código aberto

Para fazer o download dos avisos de código aberto para dependências da versão mais recente de codmod, execute:

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/THIRD_PARTY_NOTICES.txt"

Receber suporte e enviar feedback

Para ajudar a melhorar a qualidade deste produto, coletamos dados de uso pseudoanonimizados. Esses dados são tratados de acordo com nosso Google Cloud Aviso de Privacidade. Você pode mudar sua preferência a qualquer momento executando o seguinte comando:

codmod config set disable_usage_reporting true

Você pode receber suporte e enviar feedback das seguintes maneiras:

  • Para receber suporte para o codmod, clique no botão Suporte no relatório HTML gerado ou envie um e-mail para codmod-feedback-external@google.com.
  • Para compartilhar feedback sobre o codmod, clique no botão Feedback no relatório HTML gerado.