Depurando comandos SQL no FirebirdSQL

Depurar comandos SQL no Firebird é necessário para vários propositos, o maior deles talvez seja analisar a execução das queries em tempo de desenvolvimento, por exemplo, queries parametrizadas se analisadas a partir do lado cliente não possuem valores, isto é, seus parametros não são revelados, mas do lado do servidor podemos verificar todas as queries e os valores que as mesmas receberam.

A ferramenta de depuração também pode ser usada para criar arquivos de log quer mais tarde serão analisadas por ferrametas de terceiros, funciona assim, você determina um período de testes, por exemplo, 3 dias e nesse período deixa o trace ligado, depois disso você submete o arquivo de log a uma ferramenta de analise que apontará falhas ocorridas ou pontos de atenção como por exemplo excesso de espera para a execução de uma querie.

Primeiro, precisamos criar um arquivo com a definição de depuração que desejamos, para termos apenas o básico, vamos criar o arquivo fbtrace.conf com o seguinte conteúdo:

database mydatabase.fdb
{
  # Do we trace database events or not
  enabled = true
  # Operations log file name. For use by system audit trace only
  #log_filename = name
  # Maximum size of log file (megabytes). Used by system audit trace for 
  # log's rotation : when current log file reached this limit it is renamed
  # using current date and time and new log file is created. Value of zero 
  # means that the log file size is unlimited and rotation will never happen.
  max_log_size = 0
  # SQL query filters. 
  #
  # Only SQL statements falling under given regular expression are reported 
  # in the log.
  include_filter=%(SELECT|INSERT|UPDATE|DELETE)%
  # SQL statements falling under given regular expression are NOT reported 
  # in the log.
  #exclude_filter 
  # Put attach/detach log records 
  log_connections = true
  # Trace only given connection id. If zero - trace all connections 
  #connection_id = 0
  # Put transaction start/end records 
  log_transactions = true
  # Put sql statement prepare records 
  log_statement_prepare = true
  # Put sql statement free records 
  log_statement_free = true
  # Put sql statement execution start records 
  log_statement_start = true
  # Put sql statement execution finish\fetch to eof records 
  log_statement_finish = true
  # Put record when stored procedure is start execution 
  log_procedure_start = true
  # Put record when stored procedure is finish execution 
  log_procedure_finish = true
  # Put record when stored function is start execution 
  log_function_start = true
  # Put record when stored function is finish execution 
  log_function_finish = true
  # Put trigger execute records 
  log_trigger_start = true
  # Put trigger execute records 
  log_trigger_finish = true
  # Put context variable change records (RDB$SET_CONTEXT)
  #log_context = false
  # Put errors happened
  log_errors = true
  # Put warnings
  log_warnings = true
  # Filters for errors and warnings GDS codes.
  # Comma separated list of GDS codes values and\or names.
  # For example: deadlock, req_sync, 335544321
  # Include filter. If empty, trace all errors\warnings events.
  # Else trace event if any code from list is found in status-vector.
  #include_gds_codes
  # Exclude filter. If empty, trace all errors\warnings events.
  # Else trace event if no code from list is found in status-vector.
  #exclude_gds_codes
  # Put trace session init and finish messages
  #log_initfini = true
  # Sweep activity
  log_sweep = true
  # Print access path (plan) with sql statement
  print_plan = true
  # Use legacy (false) or explained (true) plan format
  explain_plan = true
  # Print detailed performance info when applicable
  print_perf = true
  # Put blr requests compile/execute records 
  #log_blr_requests = false
  # Print blr requests or not
  #print_blr = false
  # Put dyn requests execute records 
  #log_dyn_requests = false
  # Print dyn requests or not
  #print_dyn = false
  # Put xxx_finish record only if its timing exceeds this number of milliseconds
  time_threshold =0 # default 100
  # Maximum length of SQL string logged 
  # Beware when adjusting max_xxx parameters! Maximum length of log record
  # for one event should never exceed 64K.
  max_sql_length = 4096 # default 300
  # Maximum length of blr request logged 
  #max_blr_length = 500
  # Maximum length of dyn request logged 
  #max_dyn_length = 500
  # Maximum length of individual string argument we log 
  max_arg_length = 4096 # default 80
  # Maximum number of query arguments to put in log 
  max_arg_count = 0 # default 30
}

O arquivo “C:\temp\fbtrace.conf” que vê acima foi baseado no modelo “C:\Program Files\Firebird\Firebird_4_0\fbtrace.conf”. Onde vê mydatabase.fdb é na realidade o nome do banco de dados que deseja analisar ou depurar, se você não especificar um nome, o trace será feito em todos eles. Você também pode também especificar o nome do database por uma regra baseada em regex como:

database = (%[\\/](e[[:DIGIT:]]{{2}}).fdb)

Para prosseguir precisaremos que tenha em mãos os parametros:

Nome do host ou IP
Porta
Usuário e Senha
Arquivo de configuração do trace
Local de instalação do Firebird, se for Windows.

Se não souber qualquer um deles, será impossível prosseguir.

O passo seguinte requer que abramos o terminal do Windows com permissões de admistrador e executar:

set path=%path%;"C:\Program Files\Firebird\Firebird_4_0"

O comando acima é para que os utilitários que acompanham o FirebirdSQL sejam visiveis ao terminal. Você não precisará dele, mas se o fizer, poderá economizar na digitação do caminho completo para o nome do utilitário. Depois disso, execute finalmente o comando que permitirá a depuração dos comandos SQL que o FirebirdSQL processará:

"C:\Program Files\Firebird\Firebird_4_0\fbtracemgr.exe" -se 127.0.0.1/3050:service_mgr -user SYSDBA -password masterkey -start -conf "C:\temp\fbtrace.conf"

Onde:

127.0.0.1 é o nome do host, neste caso usamos IP.

3050 é a porta do serviço usado pelo FirebirdSQL

SYSDBA é o nome do usuário

masterkey é a senha do usuário SYSDBA

“C:\temp\fbtrace.conf” é o nome do arquivo com as definições de trace.

Em seguida, todas as execuções que passarem pelo servidor e que sejam compátiveis com as definições contidas em fbtrace.conf serão exibidas no terminal. Caso não queira ver as informações no terminal, mas em outro arquivo, então use o redirecionador stdout:

"C:\Program Files\Firebird\Firebird_4_0\fbtracemgr.exe" -se 127.0.0.1/3050:service_mgr -user SYSDBA -password masterkey -start -conf "C:\temp\fbtrace.conf" <strong>&gt;c:\temp\fbtrace.log</strong>

No ambiente Linux, o processo é basicamente o mesmo, o que muda são apenas os nomes dos diretórios onde os utilitários são instalados.

Conclusão

Estude o arquivo modelo para saber como deixar o arquivo fbtrace.conf adequado às suas necessidades. Às vezes você vai querer modificar ele apenas para que todas as execuções no servidor sejam vistas por você, mas outro momento talvez prefira gerar um arquivo de log que mais tarde será submetido a uma ferramenta que fará a analise e apontará pontos de atenção ou falhas, este é o exemplo da ferramenta online da IBSurgeon.