TripPin parte 8 – Adicionando diagnóstico

Este tutorial de várias partes aborda a criação de uma nova extensão de fonte de dados para o Power Query. O tutorial deve ser feito sequencialmente — cada lição se baseia no conector criado nas lições anteriores, adicionando progressivamente novos recursos ao conector.

Nesta lição, você:

Habilitando o diagnóstico

Os usuários do Power Query podem habilitar o log de rastreamento selecionando a caixa de seleção em Opções | Diagnóstico.

Uma vez habilitada, todas as consultas subsequentes fazem com que o mecanismo M emita informações de rastreamento para arquivos de log localizados em um diretório de usuário fixo.

Quando você executa consultas M de dentro do SDK do Power Query, o rastreamento é habilitado no nível do projeto. Na página de propriedades do projeto, há três configurações relacionadas ao rastreamento:

• Limpar Log: quando configurado para true, o log é redefinido/limpo quando você executa suas consultas. Recomendamos que você mantenha este conjunto como true.

• Mostrar Rastreamentos do Mecanismo: essa configuração controla a saída de rastreamentos internos do mecanismo M. Esses rastreamentos são úteis apenas para membros da equipe do Power Query, portanto, você normalmente deseja manter esse conjunto como false.

• Mostrar Rastreamentos de Usuário: essa configuração controla as informações de rastreamento fornecidas pelo seu conector. Você deseja definir essa configuração como true.

  

Quando habilitadas, as entradas de log são mostradas na janela Saída da Consulta M, na guia Log.

Diagnostics.Trace

A função Diagnostics.Trace é usada para gravar mensagens no log de rastreamento do mecanismo M.

Diagnostics.Trace = (traceLevel as number, message as text, value as any, optional delayed as nullable logical as any) => ...

O traceLevel parâmetro pode ser um dos seguintes valores (em ordem decrescente):

• TraceLevel.Critical
• TraceLevel.Error
• TraceLevel.Warning
• TraceLevel.Information
• TraceLevel.Verbose

Quando o rastreamento está habilitado, o usuário pode selecionar o nível máximo de mensagens que deseja ver. Todas as mensagens de rastreamento desse nível e abaixo são enviadas para o log. Por exemplo, se o usuário selecionar o nível "Aviso", mensagens de rastreamento de TraceLevel.Warning, TraceLevel.Error e TraceLevel.Critical aparecerão nos logs.

O message parâmetro é a saída de texto real para o arquivo de rastreamento. O texto não contém o value parâmetro, a menos que você o inclua explicitamente no texto.

O value parâmetro é o que a função retorna. Quando o delayed parâmetro é definido como true, value é uma função de parâmetro zero que retorna o valor real que você está avaliando. Quando delayed é definido como false, value é o valor real. Um exemplo de como isso funciona pode ser encontrado na avaliação atrasada.

Usando a funcionalidade Diagnostics.Trace no conector TripPin

Para um exemplo prático de como usar Diagnostics.Trace e o impacto do parâmetro delayed, atualize a função do conector GetSchemaForEntity TripPin para envolver uma exceção error.

GetSchemaForEntity = (entity as text) as type =>
    try
        SchemaTable{[Entity=entity]}[Type]
    otherwise
        let
            message = Text.Format("Couldn't find entity: '#{0}'", {entity})
        in
            Diagnostics.Trace(TraceLevel.Error, message, () => error message, true);

Você pode forçar um erro durante a avaliação (para fins de teste) passando um nome de entidade inválido para a GetEntity função. Aqui você altera a withData linha na TripPinNavTable função, substituindo [Name] por "DoesNotExist".

TripPinNavTable = (url as text) as table =>
    let
        // Use our schema table as the source of top level items in the navigation tree
        entities = Table.SelectColumns(SchemaTable, {"Entity"}),
        rename = Table.RenameColumns(entities, {{"Entity", "Name"}}),
        // Add Data as a calculated column
        withData = Table.AddColumn(rename, "Data", each GetEntity(url, "DoesNotExist"), type table),
        // Add ItemKind and ItemName as fixed text values
        withItemKind = Table.AddColumn(withData, "ItemKind", each "Table", type text),
        withItemName = Table.AddColumn(withItemKind, "ItemName", each "Table", type text),
        // Indicate that the node should not be expandable
        withIsLeaf = Table.AddColumn(withItemName, "IsLeaf", each true, type logical),
        // Generate the nav table
        navTable = Table.ToNavigationTable(withIsLeaf, {"Name"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        navTable;

Habilite o rastreamento para seu projeto e execute suas consultas de teste. Na guia Errors, você deverá ver o texto do erro que você levantou:

Além disso, na Log guia, você deverá ver a mesma mensagem. Se você usar valores diferentes para os parâmetros message e value, esses valores seriam diferentes.

Observe também que o Action campo da mensagem de log contém o nome (Tipo de Fonte de Dados) da sua extensão (nesse caso, Engine/Extension/TripPin). Esse campo facilita a localização das mensagens relacionadas à sua extensão quando há várias consultas envolvidas e/ou o rastreamento do sistema (mecanismo de mashup) está habilitado.

Avaliação atrasada

Como exemplo de como o delayed parâmetro funciona, você precisa fazer algumas modificações e executar as consultas novamente.

Primeiro, defina o delayed valor como false, mas deixe o value parâmetro as-is:

Diagnostics.Trace(TraceLevel.Error, message, () => error message, false);

Ao executar a consulta, você recebe um erro que "Não é possível converter um valor do tipo Função para o tipo Tipo" e não o erro real gerado. Essa diferença ocorre porque a chamada agora está retornando um function valor, em vez do valor em si.

Em seguida, remova a função do value parâmetro:

Diagnostics.Trace(TraceLevel.Error, message, error message, false);

Ao executar a consulta, você receberá o erro correto, mas se verificar a guia Log, não haverá mensagens. Essa discrepância ocorre porque o error acaba sendo avaliado durante a chamada para o Diagnostics.Trace, então a mensagem nunca é realmente exibida.

Agora que você entende o impacto do delayed parâmetro, lembre-se de redefinir o conector de volta para um estado de trabalho antes de continuar.

Funções auxiliares de diagnóstico em Diagnostics.pqm

O arquivo Diagnostics.pqm incluído neste projeto contém muitas funções auxiliares que facilitam o rastreamento. Conforme mostrado no tutorial anterior, você pode incluir esse arquivo em seu projeto (lembrando de definir a Ação de Build para Compilar) e, em seguida, carregá-lo no arquivo do conector. A parte inferior do arquivo do conector agora deve ser semelhante ao snippet de código a seguir. Fique à vontade para explorar as várias funções que este módulo fornece, mas neste exemplo, você usa apenas as funções Diagnostics.LogValue e Diagnostics.LogFailure.

// Diagnostics module contains multiple functions. We can take the ones we need.
Diagnostics = Extension.LoadFunction("Diagnostics.pqm");
Diagnostics.LogValue = Diagnostics[LogValue];
Diagnostics.LogFailure = Diagnostics[LogFailure];

Diagnostics.LogValue

A Diagnostics.LogValue função é muito parecida Diagnostics.Tracee pode ser usada para gerar o valor do que você está avaliando.

Diagnostics.LogValue = (prefix as text, value as any) as any => ...

O prefix parâmetro é anexado à mensagem de log. Use esse parâmetro para descobrir qual saída de chamada produziu a mensagem. O parâmetro value é o que a função retorna e também é gravado no rastreamento como uma representação em texto do valor M. Por exemplo, se value for igual a um table com as colunas A e B, o log conterá a representação equivalente #table : #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

Por exemplo, atualize a função TripPin.Feed para rastrear os argumentos url e schema passados para a função.

TripPin.Feed = (url as text, optional schema as type) as table =>
    let
        _url = Diagnostics.LogValue("Accessing url", url),
        _schema = Diagnostics.LogValue("Schema type", schema),
        //result = GetAllPagesByNextLink(url, schema)
        result = GetAllPagesByNextLink(_url, _schema)
    in
        result;

Você precisa usar os novos valores _url e _schema na chamada para GetAllPagesByNextLink. Se você usou os parâmetros de função originais, as chamadas Diagnostics.LogValue nunca são realmente avaliadas e, portanto, nenhuma mensagem é gravada no rastreio. Programação funcional é divertida!

Ao executar suas consultas, agora você deverá ver novas mensagens no log.

Acessando a URL:

Tipo de esquema:

A versão serializada do schema parâmetro type é exibida, em vez do que você obtém ao realizar um simples Text.FromValue sobre um valor de tipo (o que resulta em "tipo").

Diagnostics.LogFailure

A função Diagnostics.LogFailure pode ser usada para encapsular chamadas de função e grava somente no log de rastreamento se a execução da chamada de função falhar (ou seja, retorna um error).

Diagnostics.LogFailure = (text as text, function as function) as any => ...

Internamente, Diagnostics.LogFailure adiciona à function chamada um operador try. Se a chamada falhar, o valor text será gravado no log antes de retornar o valor original error. Se a function chamada for bem-sucedida, o resultado será retornado sem gravar nada no registro de eventos. Como os erros de M não contêm um rastreamento de pilha completo (ou seja, você normalmente só vê a mensagem do erro), essa função pode ser útil quando você deseja identificar onde o erro foi gerado.

Como um exemplo (ruim), modifique a linha withData da função TripPinNavTable para forçar um erro novamente.

withData = Table.AddColumn(rename, "Data", each Diagnostics.LogFailure("Error in GetEntity", () => GetEntity(url, "DoesNotExist")), type table),

No rastreamento, você pode encontrar a mensagem de erro resultante contendo seu text, bem como as informações de erro originais.

Certifique-se de redefinir sua função para um estado de trabalho antes de prosseguir com o próximo tutorial.

Conclusion

Esta breve (mas importante) lição mostrou como usar as funções auxiliares de diagnóstico para fazer logon nos arquivos de rastreamento do Power Query. Quando usadas corretamente, essas funções são úteis na depuração de problemas no conector.

Próximas etapas

Parte 9 do TripPin – TestConnection