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. Esta página descreve as etapas para instalar, usar e solucionar problemas da ferramenta codmod.

Sobre a avaliação de modernização de apps

O processo de avaliação de modernização típico 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.

Essa 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, oferecendo visibilidade clara das mudanças necessárias e dos benefícios obtidos com a transformação do aplicativo para Google Cloud. O codmod é uma ferramenta de CLI portátil que usa o Gemini para analisar o código-fonte e fornece recomendações com base em Google Cloud práticas recomendadas.

Antes de começar

A ferramenta codmod exige os seguintes pré-requisitos:

  • Uma estação de trabalho Linux ou Windows (10 ou mais recente).
  • Acesso a um Google Cloud projeto que tenha a API Vertex AI ativada.
  • Uma instalação da CLI gcloud na 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 é impulsionado principalmente pelo tamanho da base de código e é medido em tokens. A tabela a seguir mostra as estimativas de custos 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.0-flash 2.5-pro (padrão) 2.5-flash
Spring Petclinic ~6.500 US$ 20 US$ 2 US$ 30 US$ 4
Projeto James ~1.000.000 US$ 60 US$ 30 US$ 500 US$ 40
Elasticsearch ~5.000.000 US$ 200 US$ 200 US$ 3.000 US$ 200

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

Espera-se que os custos desses parâmetros sejam 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 a performance ideal e a eficiência de custos, 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 excedam esse limite, recomendamos dividi-las em partes menores e gerenciáveis para análise. A análise de seções menores também pode ajudar em avaliações mais focadas e potencialmente reduzir o tempo total de processamento.

Configurar codmod

Esta seção fornece 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 fazer o download da 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 codmod ferramenta, você precisa de um Google Cloud projeto.

  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, você pode 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 codmod config comando.

Listar todas as configurações

Para conferir 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 Google Cloud ID do projeto.

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

codmod config set region "REGION"

Substitua REGION pela Google Cloud região. 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 conferir 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

Cancelar a definição de 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 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 pelas -p "PROJECT_ID" e -r "REGION" flags, respectivamente.

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

  • --modelset [2.0-flash|2.5-flash|2.5-pro|adaptive]: especifica quais modelos do Gemini usar. O valor padrão é 2.5-pro. O modelo adaptável oferece uma redução de custos significativa com uma possível compensação na qualidade do relatório em comparação com 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, codmod pede confirmação antes de analisar bases de código maiores que 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 essa opção 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 diferentes seções do relatório final, mas exige um tempo de execução maior.
  • --force-include <strings>, --force-exclude <strings>: por padrão, codmod verifica extensões de arquivo populares, 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 no 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 --context ou --context-file flags para serem incluídos na análise. Os formatos com suporte 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ária uma atenção maior à camada de dados, um relatório poderá ser criado com foco nessa área:

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

Criar um relatório para uma intenção 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 com suporte:

  • Transformação de carga de trabalho do Microsoft (MICROSOFT_MODERNIZATION): use com aplicativos executados no SO Microsoft. A avaliação vai se concentrar em jornadas de transformação que modernizarão 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 executados em outra infraestrutura de hiperescala. A avaliação vai se concentrar nas mudanças recomendadas para transformar o aplicativo, como mapear outros serviços de fornecedores de nuvem para Google Cloud serviços.
  • Transformação Java legada (JAVA_LEGACY_TO_MODERN): use com aplicativos que executam a versão Java 8 ou semelhante. A avaliação vai se concentrar em encontrar dependências de upgrade e áreas no código afetadas pela mudança para Java 21 (a LTS atual).
  • Transformação Java WILDFLY legada (WILDFLY_LEGACY_TO_MODERN): use com bases de código Java EE/Jakarta EE executadas 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 API.
  • Migração de aplicativos C/C++ para arquitetura Arm (ARM_MIGRATION): use com aplicativos C/C++ para avaliar a prontidão deles e o esforço necessário para migrar de arquiteturas baseadas em x86 para arquiteturas baseadas em Arm, como Google Cloud VMs 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 do sistema de build e considerações de teste necessárias para uma transição bem-sucedida para o Arm de Google Cloud ou outro CSP, como as instâncias Graviton da AWS.

Para criar um relatório focado na intenção, use a flag --intent:

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

Criar um relatório com seções adicionais

A ferramenta oferece suporte à inclusão de seções adicionais que não são incluídas por padrão para reduzir custos. As seguintes seções são compatíveis:

  • files: uma visualização hierárquica estruturada de pastas de projetos e uma descrição por 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. As linguagens com suporte 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 separados por vírgulas.

Criar um relatório personalizado

Se você quiser explorar 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. É possível desativar esse comportamento especificando --improve-context=false.

Flags adicionais:

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

Modificar um relatório existente

É possível criar uma nova seção em um relatório ou modificar uma seção existente com base em uma seção específica. Por exemplo, você pode querer 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:

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

Para mostrar 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

Modifique uma seção existente executando o seguinte comando:

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

Criar uma nova seção do 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 flagfrom-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. É possível desativar esse comportamento especificando --improve-context=false.

Observe o seguinte:

  • create section e revise section só oferecem suporte ao 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 que você calcule o custo aproximado da criação de um relatório. Para conferir a 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 ecreate custom.

Definir o nível de detalhamento

O detalhamento codmod é configurado usando a --verbosity LEVEL flag. O nível de detalhamento 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 será exibida no terminal. A mensagem inclui o novo número da versão e um link para fazer o download da atualização. Esse processo ajuda a garantir que você fique atualizado com os recursos, melhorias e correções de bugs mais recentes.

Desativar verificações de versão

Se você 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 de volta para false:

codmod config set disable_version_check false

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

codmod config list

Conclusão da linha de comando

A ferramenta de CLI codmod oferece suporte à conclusão da linha de comando do shell para Bash, Zsh, Fish e PowerShell. Esse recurso ajuda você a digitar comandos, flags e argumentos rapidamente pressionando a tecla Tab para conferir e selecionar as opções disponíveis.

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

  • Comandos e flags de preenchimento automático:comece a digitar um comando ou flag codmod e pressione Tab para conferir as possíveis conclusões.
  • Descobrir opções:confira 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 intenções predefinidas.
  • Sugestões contextuais:a conclusão é adaptada ao comando. Por exemplo:
    • codmod config set [TAB] sugere as chaves de configuração disponíveis que podem ser definidas.
    • codmod config get [TAB] sugere as chaves de configuração disponíveis que podem ser recebidas.
    • A conclusão do caminho do arquivo só é oferecida 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 a conclusão do shell

Antes de ativar a conclusão do shell, verifique se o comando codmod funciona adicionando o executável ao caminho ou criando um alias.

Para carregar conclusões 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 a conclusão do Bash no Linux, adicione o seguinte ao seu ~/.bashrc:

source <(codmod completion bash)

Reinicie o shell ou a origem do 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 codmod binário executando ochmod +x codmod comando.
  • A CLI parece travar:a análise pode levar muito tempo, mas geralmente é possível conferir o progresso na barra de progresso na 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, codmod usa o modelo gemini-2.5-pro. No entanto, isso está sujeito a mudanças, já que diferentes conjuntos de modelos usam modelos diferentes para fins diferentes.

  • Erros de relatório:em caso de erro que precise de investigação, colete as informações de depuração para ajudar nossa equipe de desenvolvimento. Os registros fornecem detalhes importantes para a solução de problemas. Execute o seguinte comando 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

Faça o download dos avisos de código aberto para dependências da versão mais recente do codmod executando:

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 desse produto, coletamos dados de uso pseudoanonimizados. Esses dados são tratados de acordo com nosso Aviso de privacidade da política de privacidade 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 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 codmod, clique no botão Feedback no relatório HTML gerado.