Skip to main content

database trace-command

[Conexão] Execute um comando individual como parte de um build rastreado.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Este conteúdo descreve a versão mais recente do CodeQL CLI. Para obter mais informações sobre essa versão, confira https://github.com/github/codeql-cli-binaries/releases.

Para ver os detalhes das opções disponíveis para esse comando em uma versão anterior, execute o comando com a opção --help no terminal.

Sinopse

Shell
codeql database trace-command [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> <command>...

Descrição

[Conexão] Execute um comando individual como parte de um build rastreado.

Isso executa uma linha de comando individual especificada em um rastreamento, possivelmente executando alguma extração, mas não finaliza o banco de dados CodeQL resultante.

Opções

Opções principais

<database>

[Obrigatório] Caminho para o banco de dados CodeQL em construção. Isso precisa ter sido preparado para extração com codeql database init.

Se a opção --db-cluster for fornecida, esse não será um banco de dados propriamente dito, mas um diretório que contém bancos de dados, e todos esses bancos de dados serão processados juntos.

<command>...

O comando a ser executado. Isso pode consistir em um ou mais argumentos, que são usados para criar o processo. Recomendamos transmitir o argumento '--' antes de listar os argumentos do comando, a fim de evitar confusão entre os argumentos dele e os nossos.

É esperado que o comando saia com um código status igual a 0. Qualquer outro código de saída é interpretado como uma falha.

O comando pode ser omitido quando --index-traceless-dbs é fornecido.

-j, --threads=<num>

Instrua o extrator a usar esse número de threads. Essa opção é transmitida para o extrator como uma sugestão. Se a variável de ambiente CODEQL_THREADS estiver definida, o valor da variável de ambiente terá precedência sobre essa opção.

Você pode transmitir 0 para usar um thread por núcleo no computador ou -N para manter N núcleos não utilizados (com a exceção de que ainda será usado, pelo menos, um thread).

-M, --ram=<MB>

Instrua o extrator a usar essa quantidade de memória. Essa opção é transmitida para o extrator como uma sugestão. Se a variável de ambiente CODEQL_RAM estiver definida, o valor da variável de ambiente terá precedência sobre essa opção.

--[no-]db-cluster

Indica que o diretório fornecido na linha de comando não é um banco de dados propriamente dito, mas um diretório que contém um ou mais bancos de dados em construção. Esses bancos de dados serão processados juntos.

--no-tracing

[Avançado] Não rastreie o comando especificado. mas dependa dele para produzir todos os dados necessários diretamente.

--extra-tracing-config=<tracing-config.lua>

[Avançado] O caminho para um arquivo de configuração do rastreador. Ele pode ser usado para modificar o comportamento do rastreador de build. Ele pode ser usado para escolher processos do compilador executados como parte do comando de build e disparar a execução de outras ferramentas. Os extratores fornecerão arquivos de configuração do rastreador padrão que devem funcionar na maioria das situações.

--[no-]index-traceless-dbs

Além do comando especificado, execute o script main para os extratores que não dependem do rastreamento de um processo de build. Se você estiver construindo bancos de dados para várias linguagens com --db-cluster, essa opção deverá ser fornecida a exatamente uma invocação de codeql database trace-command.

--[no-]use-build-mode

Determine o que executar com base no modo de compilação do banco de dados. Esta opção não pode ser usada em conjunto com --index-traceless-dbs.

--working-dir=<dir>

[Avançado] O diretório no qual o comando especificado deve ser executado. Se esse argumento não for fornecido, o comando será executado no valor de --source-root transmitido para codeql database create, se houver um. Se nenhum argumento --source-root for fornecido, o comando será executado no diretório de trabalho atual.

--no-run-unnecessary-builds

[Avançado] Só execute os comandos de build especificados se um banco de dados em construção usar um extrator que dependa do rastreamento de um processo de build. Se essa opção não for fornecida, o comando será executado mesmo quando o CodeQL não precisar dele, na suposição de que você precisa dos efeitos colaterais dele por outros motivos.

Opções para controlar o comportamento do extrator

-O, --extractor-option=<extractor-option-name=value>

Defina as opções para os extratores do CodeQL. extractor-option-name deve ter o formato extractor_name.group1.group2.option_name ou group1.group2.option_name. Se extractor_option_name começar com o nome de um extrator, o extrator indicado precisará declarar a opção group1.group2.option_name. Caso contrário, qualquer extrator que declare a opção group1.group2.option_name terá a opção definida. value pode ser qualquer cadeia de caracteres que não contenha uma nova linha.

Use essa opção de linha de comando repetidamente para definir várias opções de extratores. Se você fornecer vários valores para a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas após as opções de extratores fornecidas por meio de --extractor-options-file.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

--extractor-options-file=<extractor-options-bundle-file>

Especifique os arquivos de pacote de opções de extratores. Um arquivo de pacote de opções de extratores é um arquivo JSON (extensão .json) ou um arquivo YAML (extensão .yaml ou .yml) que define as opções de extratores. O arquivo precisa ter a chave de mapa de nível superior 'extractor' e, abaixo dela, os nomes de extratores como chaves de mapa de segundo nível. Outros níveis de mapas representam grupos de extratores aninhados, e as opções de cadeia de caracteres e matriz são entradas de mapa com valores de cadeia de caracteres e matriz.

Os arquivos do pacote de opções de extratores são lidos na ordem em que são especificados. Se diferentes arquivos do pacote de opções de extratores especificarem a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas antes das opções de extratores fornecidas por meio de --extractor-option.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

Opções comuns

-h, --help

Mostre este texto de ajuda.

-J=<opt>

[Avançado] Forneça a opção para a JVM que executa o comando.

(Use-a com cautela, pois as opções que contêm espaços não serão tratadas corretamente.)

-v, --verbose

Aumente incrementalmente o número de mensagens de progresso impressas.

-q, --quiet

Diminua incrementalmente o número de mensagens de progresso impressas.

--verbosity=<level>

[Avançado] Defina explicitamente o nível de detalhamento como erros, avisos, progresso, progresso+, progresso++ ou progresso+++. Substitui -v e -q.

--logdir=<dir>

[Avançado] Escreva logs detalhados em um ou mais arquivos no diretório fornecido, com nomes gerados que incluem carimbos de data/hora e o nome do subcomando em execução.

(Para gravar um arquivo de log com um nome sobre o qual você tem controle completo, forneça --log-to-stderr e redirecione stderr conforme desejado.)

--common-caches=<dir>

[Avançado] Controle a localização dos dados armazenados em cache no disco que persistirão entre várias execuções da CLI, como pacotes QL baixados e planos de consulta compilada. Se não for definido explicitamente, o padrão corresponde a um diretório intitulado .codeql no diretório inicial do usuário; que será criado se ainda não existir.

Disponível desde v2.15.2.