Depuração

De DTI Wiki

Esta é a versão publicada, verificada a 18 de novembro de 2011. O rascunho contém 1 alteração pendente.

Precisão	Objetiva
Profundidade	Básica
Inteligibilidade	Aceitável

Ir para: navegação, pesquisa

Para depuração de códigos PL/SQL NÃO use DBMS_OUTPUT, utilize as ferramentas do LOG4PLSQL instalado no esquema DLOG. Nenhum código que contenha instruções DBMS_OUTPUT será passado para a base de homologação (TEST) ou produção (SUN) mesmo que o código esteja comentado.

Tabela de conteúdo

1 LOG4PLSQL - Oracle Database Logging Tools

LOG4PLSQL - Oracle Database Logging Tools

LOG4PLSQL is developed by the LOG4PLSQL project team, see http://log4plsql.sourceforge.net.

Destino dos logs

O destino padrão dos logs gerados pela ferramenta é a tabela TLOG (DLOG.TLOG), opcionalmente podem ser direcionados também para a saída padrão (DBMS_OUTPUT), porém isso só poderá ser feito na base de desenvolvimento (LNX).

Os registros podem ser consultados na tabela TLOG (DLOG.TLOG) ou na view VLOG (DLOG.VLOG) e ficarão armazenados por 7 dias.

Procedimentos

A ferramenta disponibiliza alguns procedimentos para depuração dependendo do tipo de mensagem.

debug - valor 60 - Mensagens informativas para depuração de um aplicativo em nível refinado.
info - valor 50 - Mensagens informativas para acompanhamento da execução de um aplicativo em nivel menos refinado.
waring - valor 40 - Mensagens para situações potencialmente prejudiciais.
error - valor 30 - Mensagens para eventos de erro mas que ainda permitam que o aplicativo continue executando.
fatal - valor 20 - Mensagens para eventos de erro muito grave que, presumivelmente, façam com que a aplicação seja abortada.

Nas bases de desenvolvimento e homologação todas as mensagens serão gravadas, na base de produção somente serão gravadas as mensagens a partir de warnig.

Uso básico

Os procedimentos podem ser chamados sem passagem de parâmetros, neste caso a mensagem padrão será SQLCODE SQLERRM, como mostrado no exemplo abaixo.

    PROCEDURE prc_basico IS
    BEGIN
        dlog.plog.debug;
        dlog.plog.info;
        dlog.plog.warn;
        dlog.plog.error;
        dlog.plog.fatal;
    END prc_basico;

Neste caso o resultado é gravado na tabela TLOG. O resultado mostrado abaixo é uma consulta a view VLOG.

[Ago 12, 16:22:22:89][DEBUG][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:0 SQLERRM:ORA-0000: normal, successful completion]
[Ago 12, 16:22:22:89][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:0 SQLERRM:ORA-0000: normal, successful completion]
[Ago 12, 16:22:22:89][WARN][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:0 SQLERRM:ORA-0000: normal, successful completion]
[Ago 12, 16:22:22:89][ERROR][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:0 SQLERRM:ORA-0000: normal, successful completion]
[Ago 12, 16:22:22:89][FATAL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:0 SQLERRM:ORA-0000: normal, successful completion]

A mensagem pode ser passada por parâmetro, como mostrado abaixo.

    PROCEDURE prc_basico IS
    BEGIN
        dlog.plog.debug('Mensagem de depuração');
        dlog.plog.info('Mensagem de informação');
        dlog.plog.warn('Mensagem de atenção');
        dlog.plog.error('Mensagem de erro');
        dlog.plog.fatal('Mensagem de erro fatal');
    END prc_basico;

Desta forma o resultado obtido será como mostrado abaixo. Consulta a view VLOG.

[Ago 12, 16:22:22:89][DEBUG][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de depuração]
[Ago 12, 16:22:22:89][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de informação]
[Ago 12, 16:22:22:89][WARN][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de atenção]
[Ago 12, 16:22:22:89][ERROR][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de erro]
[Ago 12, 16:22:22:89][FATAL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de erro fatal]

Assertings

O uso de assert pode ser útil para verificar os valores de variáveis ou parâmetros da aplicação. Os parâmetros para assert são:

condicao - boolean, obrigatório, se for falso a mensgaem será gravada;
mensagem - varchar2, opcional, default assert condition error;
codigo - number, opcional, default -20000, valores possíveis entre -20000 a -20999;
raise - boolean, opcional, default FALSE, se verdadeiro um RAISE será executado utilizando codigo e mensagem.

A mensagem do assert só é gravada se a condição passada por parâemtro for falsa, veja exemplos abaixo.

    PROCEDURE prc_asserts(in_dtinicial IN DATE,
                          in_dtfinal   IN DATE,
                          in_coderro   IN NUMBER DEFAULT -20999,
                          in_raise     IN BOOLEAN DEFAULT FALSE) IS
    BEGIN
        dlog.plog.assert(in_dtinicial <= in_dtfinal);
        dlog.plog.assert(in_dtinicial <= in_dtfinal, 'Data inicial maior que data final');
        dlog.plog.assert(in_dtinicial <= in_dtfinal, 'Data inicial maior que data final', in_coderro, in_raise);
    END prc_asserts;
 
    -- Chamando o procedimento.
    BEGIN
        pkg_log4plsql.prc_asserts(SYSDATE, SYSDATE - 1, -20199);
    END;

Cada chamada a assert grava uma mensagem de erro de acordo com os parâmetros passados. Se for passado TRUE como quarto parâmetro será executado um RAISE_APPLICATION_ERROR com o código informado no terceiro parâmetro e a aplicação será abotrada.

Observe as mensagens abaixo (VLOG).

[Ago 15, 10:34:58:21][ALL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][AAS-20000: assert condition error]
[Ago 15, 10:34:58:21][ALL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][AAS-20000: Data inicial maior que data final]
[Ago 15, 10:34:58:21][ALL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][AAS-20199: Data inicial maior que data final]

Usando variável de contexto

Os logs podem ser configurados por uma variável de contexto. Esta variável permite ao desenvolvedor alterar os valores default de configuração para uma seção, como por exemplo o nível de mensagens a gravar e o local de saída das mensagens.

Para utilizar vairáveis de contexto o desenvolvedor deve chamar o procedimento init() como nos exemplos abaixo.

Inicializando variável de contexto com valores padrão.

    PROCEDURE prc_contexto IS
 
        v_ctx dlog.plogparam.log_ctx := dlog.plog.init();    
 
    BEGIN
 
        dlog.plog.info('Usando variáveis de contexto');
        dlog.plog.debug(v_ctx, 'Mensagem de depuração com variável de contexto');
        dlog.plog.info(v_ctx, 'Mensagem de informação com variável de contexto');
        dlog.plog.warn(v_ctx, 'Mensagem de atenção com variável de contexto');
        dlog.plog.error(v_ctx, 'Mensagem de erro com variável de contexto');
        dlog.plog.fatal(v_ctx, 'Mensagem de erro fatal com variável de contexto');
 
    END prc_contexto;

Mensagens gravadas com inicialização padrão (VLOG).

[Ago 15, 16:11:02:49][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Usando variáveis de contexto]
[Ago 15, 16:11:02:49][DEBUG][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de depuração com variável de contexto]
[Ago 15, 16:11:02:49][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de informação com variável de contexto]
[Ago 15, 16:11:02:49][WARN][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de atenção com variável de contexto]
[Ago 15, 16:11:02:49][ERROR][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de erro com variável de contexto]
[Ago 15, 16:11:02:49][FATAL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Mensagem de erro fatal com variável de contexto]

Inicializando variável de contexto com valores diferentes do padrão, onde foram alterados a seção, o nível e saída.

    PROCEDURE prc_contexto IS
 
        /* Valores default para as bases de desenvolvimento e homologação
        v_ctx dlog.plogparam.log_ctx := dlog.plog.init(psection           => NULL,             (Nome da seção)
                                                       plevel             => dlog.plog.ldebug, (Maior nível de depuração)
                                                       plog4j             => FALSE,            (Não instalado - Advanced Queue)
                                                       plogtable          => TRUE,             (Grava log na tabela de TLOG)
                                                       pout_trans         => TRUE,             (Transação autônoma)
                                                       palert             => FALSE,            (Não habilitado - alert.log)
                                                       ptrace             => FALSE,            (Não habilitado - trace file)
                                                       pdbms_output       => FALSE,            (Gera log na saída padrão DBMS_OUTPUT)
                                                       psession           => FALSE,            (Não habilitado - v$session)
                                                       pdbms_output_wrap  => 100);             (Comprimento da saída no DBMS_OUTPUT)
 
        Na base de produção a diferença está em plevel => dlog.plog.lwarn */
 
        v_ctx dlog.plogparam.log_ctx := dlog.plog.init(psection     => 'prc_contexto',
                                                       plevel       => LOG.plog.lwarn,
                                                       pdbms_output => TRUE);
 
    BEGIN
 
        dlog.plog.info('Usando variáveis de contexto');
        dlog.plog.debug(v_ctx, 'Mensagem de depuração com variável de contexto');
        dlog.plog.info(v_ctx, 'Mensagem de informação com variável de contexto');
        dlog.plog.warn(v_ctx, 'Mensagem de atenção com variável de contexto');
        dlog.plog.error(v_ctx, 'Mensagem de erro com variável de contexto');
        dlog.plog.fatal(v_ctx, 'Mensagem de erro fatal com variável de contexto');
 
    END prc_contexto;

Mensagens gravadas com inicialização diferente do padrão.

Observe que a chamada a INFO não utiliza a variável de contexto, por este motivo foi gravada na tabela de log mas não foi apresentada no DBMS_OUTPUT.

As chamadas com utilização da variável de contexto só foram geradas a partir do nível warining e foram apresentadas também na saída padrão DBMS_OUTPUT.

Mensagens gravadas na tabela de log (VLOG).

[Ago 15, 16:48:56:16][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Usando variáveis de contexto]
[Ago 15, 16:48:56:16][WARN][ADDESENV][prc_contexto][Mensagem de atenção com variável de contexto]
[Ago 15, 16:48:56:20][ERROR][ADDESENV][prc_contexto][Mensagem de erro com variável de contexto]
[Ago 15, 16:48:56:20][FATAL][ADDESENV][prc_contexto][Mensagem de erro fatal com variável de contexto]

Saída no DBMS_OUTPUT.

16:48:56:16-WARN-prc_contexto Mensagem de atenção com variável de contexto
16:48:56:20-ERROR-prc_contexto Mensagem de erro com variável de contexto
16:48:56:20-FATAL-prc_contexto Mensagem de erro fatal com variável de contexto

Teste de nível de depuração

A melhor maneira de codificar as chamadas de depuração é fazendo um teste antes da chamada com a função isEnabled.

isDebugEnabled
isInfoEnabled
isWarnEnabled
isErrorEnabled
isFatalEnabled

Esta forma de codificação será exigida quando a depuração for em cálculos, relatórios complexos ou processamentos com laços, pois os testes feitos antes da chamada ao procedimento de depuração diminuem consideravelmente o custo e o tempo de processamento.

    PROCEDURE prc_contexto IS
 
        v_ctx dlog.plogparam.log_ctx := dlog.plog.init(psection          => 'prc_contexto',
                                                       plevel            => LOG.plog.lwarn,
                                                       pdbms_output      => TRUE,
                                                       pdbms_output_wrap => 150);
 
 
    BEGIN
 
        dlog.plog.info('Usando variáveis de contexto com teste antes da chamada');
        IF dlog.plog.isdebugenabled(v_ctx) THEN
            dlog.plog.debug(v_ctx, 'Mensagem de depuração com variável de contexto');
        END IF;
        IF dlog.plog.isinfoenabled(v_ctx) THEN
            dlog.plog.info(v_ctx, 'Mensagem de informação com variável de contexto');
        END IF;
        IF dlog.plog.iswarnenabled(v_ctx) THEN
            dlog.plog.warn(v_ctx, 'Mensagem de atenção com variável de contexto');
        END IF;
        IF dlog.plog.iserrorenabled(v_ctx) THEN
            dlog.plog.error(v_ctx, 'Mensagem de erro com variável de contexto');
        END IF;
        IF dlog.plog.isfatalenabled(v_ctx) THEN
            dlog.plog.fatal(v_ctx, 'Mensagem de erro fatalcom variável de contexto');
        END IF;
 
    END prc_contexto;

Mensagens gravadas na tabela de log (VLOG).

[Ago 15, 16:48:56:16][INFO][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][Usando variáveis de contexto com teste antes da chamada]
[Ago 15, 16:48:56:16][WARN][ADDESENV][prc_contexto][Mensagem de atenção com variável de contexto]
[Ago 15, 16:48:56:20][ERROR][ADDESENV][prc_contexto][Mensagem de erro com variável de contexto]
[Ago 15, 16:48:56:20][FATAL][ADDESENV][prc_contexto][Mensagem de erro fatal com variável de contexto]

Saída no DBMS_OUTPUT.

16:48:56:16-WARN-prc_contexto Mensagem de atenção com variável de contexto
16:48:56:20-ERROR-prc_contexto Mensagem de erro com variável de contexto
16:48:56:20-FATAL-prc_contexto Mensagem de erro fatal com variável de contexto

Concatenando mensagem de erro

Também podem ser criadas mensagens concantenando os retornos de erro do banco de dados.

    PROCEDURE prc_getanomes(in_ano IN anomes.ano%TYPE,
                            in_mes IN anomes.mes%TYPE) IS
            v_ctx dlog.plogparam.log_ctx := dlog.plog.init(psection          => 'prc_contexto',
                                                           plevel            => dlog.plog.lwarn,
                                                           pdbms_output      => TRUE,
                                                           pdbms_output_wrap => 150);
            v_encctb anomes.enccontabil%TYPE;
    BEGIN
        SELECT am.enccontabil
        INTO   v_encctb
        FROM   anomes am
        WHERE  am.ano = in_ano
        AND    am.mes = in_mes;
    EXCEPTION
        WHEN NO_DATA_FOUND THEN
            dlog.plog.error(v_ctx,
                            'Ano informado não cadastrado. Esta mensagem tem mais de 150 caracteres e ' ||
                            'está concatenada com a mensagem de erro do banco de dados. ' || SQLERRM);
    END prc_getanomes;
 
    -- Chamando o procedimento
    BEGIN
        pkg_log4plsql.prc_getanomes(2011, 15);
    END;

Mensagens gravadas na tabela de log (VLOG).

[Ago 16, 10:29:46:24][ERROR][ADDESENV][prc_contexto][Ano informado não cadastrado. Esta mensagem tem mais de 150 caracteres e está concatenada com a mensagem de erro do banco de dados. ORA-01403: dados não encontrados]

Saída no DBMS_OUTPUT.

10:14:49:30-ERROR-prc_contexto Ano informado não cadastrado. Esta mensagem tem mais de 150 caracteres e está concatenada com a mensagem de erro do ba
nco de dados. ORA-01403: dados não encontrados

Criando mensagens com hierarquia

É possível criar mensagens com hierarquia.

SetBeginSection - para criação de um novo nível na hierarquia.
SetEndSection - para fechar um nível da hierarquia.
GetSection - Retorna o nome da seção.

    PROCEDURE prc_hierarquia IS
            v_ctx dlog.plogparam.log_ctx := dlog.plog.init(psection => 'prc_hierarquia');
    BEGIN
        dlog.plog.debug(v_ctx, 'Usando log hierárquico');
 
        dlog.plog.debug(v_ctx, 'Seção: ' || dlog.plog.getsection(v_ctx));
 
        dlog.plog.setbeginsection(v_ctx, 'Nível 0');
        dlog.plog.debug(v_ctx, 'Mensagem 1');
 
        dlog.plog.setbeginsection(v_ctx, 'Nível 1');
        dlog.plog.debug(v_ctx, 'Mensagem 2');
 
        dlog.plog.setbeginsection(v_ctx, 'Nível 2');
        dlog.plog.debug(v_ctx, 'Mensagem 3');
        dlog.plog.debug(v_ctx, 'Mensagem 4');
 
        dlog.plog.setendsection(v_ctx, 'Nível 2');
        dlog.plog.debug(v_ctx, 'Mensagem 5');
 
        dlog.plog.setendsection(v_ctx);
 
        dlog.plog.debug(v_ctx, 'Mensagem 6');
    END prc_hierarquia;

Mensagens gravadas na tabela de log (VLOG).

[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia][Usando log hierárquico]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia][Seção: prc_hierarquia]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia.Nível 0][Mensagem 1]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia.Nível 0.Nível 1][Mensagem 2]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia.Nível 0.Nível 1.Nível 2][Mensagem 3]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia.Nível 0.Nível 1.Nível 2][Mensagem 4]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia.Nível 0.Nível 1][Mensagem 5]
[Ago 16, 10:35:58:02][DEBUG][ADDESENV][prc_hierarquia][Mensagem 6]

Backtrace

É possível gravar erros não tratados em procedimentos chamados usando a função full_error_backtrace.

Esta função faz o rastreamento do erro desde o procedimento onde ele ocorreu (exceção não tratada no procedimento) até o primeiro procedimento onde o erro for tratado.

O exemplo abaixo mostra que o erro ocorrido no procedimento prc_getano é propagado para o tratamento de exceção do procedimento prc_backtrace onde a função dlog.plog.full_error_backtrace é chamada.

    PROCEDURE prc_getano(in_ano ano.ano%TYPE) IS
        v_encctb ano.enccontabil%TYPE;
    BEGIN
        SELECT a.enccontabil
        INTO   v_encctb
        FROM   ano a
        WHERE  a.ano = in_ano;
    END prc_getano;
 
    PROCEDURE prc_chamagetano(in_ano ano.ano%TYPE) IS
    BEGIN
        prc_getano(in_ano);
    END prc_chamagetano;
 
    PROCEDURE prc_backtrace(in_ano ano.ano%TYPE) IS
    BEGIN
        prc_chamagetano(in_ano);
        dlog.plog.info('Procedimento executado com sucesso');
    EXCEPTION
        WHEN OTHERS THEN
            dlog.plog.full_error_backtrace;
    END prc_backtrace;
 
    -- Chamada do procedimento
    BEGIN
        pkg_log4plsql.prc_backtrace(2158);
    END;

Mensagens gravadas na tabela de log (VLOG).

"[Ago 16, 11:14:42:09][ALL][ADDESENV][block-->ADDESENV.PKG_LOG4PLSQL][SQLCODE:100 SQLERRM:ORA-01403: dados não encontrados Error back trace:
em ""ADDESENV.PKG_LOG4PLSQL"", line 193
em ""ADDESENV.PKG_LOG4PLSQL"", line 214
em ""ADDESENV.PKG_LOG4PLSQL"", line 231
]"

Padrão de utilização na DTI

O uso na DTI foi padronizado para que as alterações do contexto de depuração possam ser feitas sem a necessidade de alteração e recompilação do código PL/SQL.

As chamadas aos procedimentos de depuração serão feitas sempre utilizando uma variável de contexto que será inicializada como mostrado abaixo.

    PROCEDURE prc_contexto;
 
        /* Variável de contexto para depuração */        
        v_ctx dlog.plogparam.log_ctx := dlog.fun_getctx(dlog.plog.init(), sys.fun_whoami);
 
    BEGIN
 
        dlog.plog.debug(v_ctx, 'Exemplo de mensagem de depuração com variável de contexto');
 
        /* É recomendada esta forma de codificação porque há menor impacto na performance da aplicação */
        IF dlog.plog.isdebugenabled(v_ctx) THEN
            dlog.plog.debug(v_ctx, 'Exemplo de mensagem de depuração com variável de contexto');
        END IF;
 
    END prc_contexto;

Foi criado uma tabela para armazenar as configurações de contexto individual por objeto a ser depurado. Desta forma é possível configurar um contexto diferente do contexto padrão do servidor, para um objeto específico e por tempo determinado.

Esta configuração permite a alteração do nome da seção, nível de depuração, exibição na saída padrão, tamanho da linha na saída padrão e ainda a data e hora final do contexto.

A configuração pode ser feita para procedures, functions, triggers ou packages. Para os packages a configuração pode ser feita tanto para o package como um todo ou para procedures ou functions internas.

Os objetos que não estiverem cadastrados ou estiverem com a data limite vencida serão depurados de acordo com a configuração padrão do servidor.

A manutenção pode ser acessada somente pelos analistas e desenvolvedores da DTI e está disponível no Menu Geral dos Sistemas Informatizados em Administrativo >> Suporte >> Depuração de código Pl/Sql.

Depuração

De DTI Wiki

Tabela de conteúdo

LOG4PLSQL - Oracle Database Logging Tools

Destino dos logs

Procedimentos

Uso básico

Assertings

Usando variável de contexto

Teste de nível de depuração

Concatenando mensagem de erro

Criando mensagens com hierarquia

Backtrace

Padrão de utilização na DTI

Ferramentas pessoais

Espaços nominais

Variantes

Visualizações

Ações

Pesquisa

Navegação

Ferramentas