TripPin deel 8: Diagnostische gegevens toevoegen

Deze meerdelige zelfstudie gaat over het maken van een nieuwe gegevensbronextensie voor Power Query. De zelfstudie is bedoeld om opeenvolgend te worden uitgevoerd elke les is gebaseerd op de connector die in de vorige lessen is gemaakt, en voegt incrementeel nieuwe mogelijkheden toe — aan uw connector.

In deze les gaat u het volgende doen:

  • Meer informatie over de functie Diagnostics.Trace
  • De diagnostische helperfuncties gebruiken om traceergegevens toe te voegen om fouten in uw connector op te sporen

Diagnostische gegevens inschakelen

Power Query gebruikers traceerlogregistratie kunnen inschakelen door het selectievakje onder Opties in | Diagnostische gegevens.

Schakel tracering in Power Query.

Als deze functie is ingeschakeld, zorgen volgende query's ervoor dat de M-engine traceergegevens naar logboekbestanden in een vaste gebruikersmap stuurt.

Wanneer u M-query's vanuit de Power Query SDK, wordt tracering ingeschakeld op projectniveau. Op de pagina projecteigenschappen staan drie instellingen met betrekking tot tracering:

  • Logboeken leeg maken — wanneer dit is ingesteld op true , wordt het logboek opnieuw ingesteld/geweerd wanneer u uw query's hebt uitgevoerd. U wordt aangeraden deze ingesteld te houden op true .
  • Engine-traceringen tonen — met deze instelling bepaalt u de uitvoer van ingebouwde traceringen van de M-engine. Deze traceringen zijn over het algemeen alleen nuttig voor leden van het Power Query-team. Daarom moet u deze doorgaans instellen op false .
  • Gebruikers traceringen tonen — Met deze instelling bepaalt u de traceergegevensuitvoer van uw connector. Stel deze in op true .

Project eigenschappen.

Zodra deze functie is ingeschakeld, ziet u logboekgegevens in het venster M Query-uitvoer, onder het tabblad Logboek.

Diagnostics.Trace

De functie Diagnostics.Trace wordt gebruikt om berichten naar het traceerlogboek van de M-engine te schrijven.

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

Belangrijk

M is een functionele taal met luie evaluatie. Wanneer u gebruikt, moet u er rekening mee houden dat de functie alleen wordt aangeroepen als de expressie waar deze deel van Diagnostics.Trace uitmaakt, daadwerkelijk wordt geëvalueerd. Voorbeelden hiervan vindt u verder in deze zelfstudie.

De traceLevel parameter kan een van de volgende waarden zijn (in aflopende volgorde):

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

Wanneer tracering is ingeschakeld, kan de gebruiker het maximale niveau van berichten selecteren dat hij of zij wil zien. Alle traceerberichten van dit niveau en onder worden uitgevoerd naar het logboek. Als de gebruiker bijvoorbeeld het niveau Waarschuwing selecteert, traceer dan berichten van , en wordt TraceLevel.Warning TraceLevel.Error weergegeven in de TraceLevel.Critical logboeken.

De message parameter is de werkelijke tekst die wordt uitgevoerd naar het traceerbestand. Houd er rekening mee dat de tekst de parameter niet bevat, tenzij value u deze expliciet opgeeft in de tekst.

De value parameter is wat de functie retournt. Wanneer de parameter is ingesteld op , wordt een nulparameterfunctie die de werkelijke waarde retourneert delayed true die u value evalueert. Wanneer delayed is ingesteld op , wordt de werkelijke false value waarde. Hieronder vindt u een voorbeeld van hoe dit werkt.

Diagnostics.Trace gebruiken in de TripPin-connector

Voor een praktisch voorbeeld van het gebruik van Diagnostics.Trace en de impact van de parameter werkt u de functie van de TripPin-connector bij om de delayed uitzondering te GetSchemaForEntity error verpakken:

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

U kunt een fout forceer tijdens de evaluatie (voor testdoeleinden!) door een ongeldige entiteitsnaam door te geven aan de GetEntity functie. Hier wijzigt u withData de regel in de functie en vervangt u door TripPinNavTable [Name] "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;

Schakel tracering in voor uw project en voer uw testquery's uit. Op het Errors tabblad ziet u de tekst van de fout die u hebt veroorzaakt:

Foutbericht.

Op het tabblad Log ziet u hetzelfde bericht. Houd er rekening mee dat als u verschillende waarden voor de message value parameters en gebruikt, deze anders zijn.

Foutenlogboek.

Houd er ook rekening mee dat het veld van Action het logboekbericht de naam (Soort gegevensbron) van uw extensie bevat (in dit geval Engine/Extension/TripPin ). Dit maakt het gemakkelijker om de berichten met betrekking tot uw extensie te vinden wanneer er meerdere query's bij betrokken zijn en/of systeemtraceren (mashup engine) is ingeschakeld.

Vertraagde evaluatie

Als voorbeeld van hoe de parameter werkt, moet u enkele wijzigingen aanbrengen en de delayed query's opnieuw uitvoeren.

Stel eerst de waarde delayed in op , maar laat de parameter zoals deze false value is:

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

Wanneer u de query uitvoert, ontvangt u de foutmelding 'We kunnen een waarde van het type Functie niet converteren naar type' en niet de werkelijke fout die u hebt veroorzaakt. Dit komt doordat de aanroep nu een waarde function retourneert in plaats van de waarde zelf.

Verwijder vervolgens de functie uit de value parameter :

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

Wanneer u de query uitvoert, ontvangt u de juiste fout, maar als u het tabblad Logboek controleert, worden er geen berichten weergegeven. Dit komt doordat de wordt verhoogd/geëvalueerd tijdens de aanroep van , zodat error het bericht nooit daadwerkelijk wordt Diagnostics.Trace uitgevoerd.

Nu u de impact van de parameter begrijpt, moet u ervoor zorgen dat u uw connector opnieuw in een werkende status herstelt delayed voordat u doorgaat.

Diagnostische helperfuncties in Diagnostics.pqm

Het bestand Diagnostics.pqm dat in dit project is opgenomen, bevat een aantal helperfuncties die het traceren eenvoudiger maken. Zoals u in de vorigezelfstudie hebt laten zien, kunt u dit bestand opnemen in uw project (vergeet niet om de buildactie in te stellen op Compileren) en het vervolgens in uw connectorbestand te laden. De onderkant van het connectorbestand ziet er nu uit als het onderstaande codefragment. U kunt de verschillende functies van deze module verkennen, maar in dit voorbeeld gebruikt u alleen de Diagnostics.LogValue functies Diagnostics.LogFailure en .

// 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

De functie lijkt veel op en kan worden gebruikt om de waarde uit te geven van wat Diagnostics.LogValue Diagnostics.Trace u evalueert.

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

De prefix parameter wordt toegevoegd aan het logboekbericht. U gebruikt deze om te achterhalen welke aanroep het bericht uitvoert. De parameter is wat de functie retourneert en wordt ook naar de traceer geschreven als value een tekstweergave van de M-waarde. Als bijvoorbeeld gelijk is aan een met kolommen A en B, bevat het logboek value table de equivalente #table weergave: #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

Notitie

Het serialiseren van M-waarden naar tekst kan een dure bewerking zijn. Let op de mogelijke grootte van de waarden die u naar de traceer uitvoert.

Notitie

In Power Query omgevingen worden traceerberichten afgekapt tot een maximale lengte.

Als voorbeeld werkt u de functie bij om de argumenten en te traceren TripPin.Feed die zijn doorgegeven aan de functie url schema .

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;

Houd er rekening mee dat u de nieuwe waarden _url en moet gebruiken in de _schema aanroep naar GetAllPagesByNextLink . Als u de oorspronkelijke functieparameters hebt gebruikt, worden de aanroepen nooit daadwerkelijk geëvalueerd, waardoor er geen berichten Diagnostics.LogValue naar de traceer worden geschreven. Functioneel programmeren is leuk!

Wanneer u uw query's hebt uitgevoerd, ziet u nu nieuwe berichten in het logboek.

URL openen:  Url-bericht openen.

Schematype:  Bericht schematype.

U ziet de geseraliseerde versie van de parameter in plaats van wat u zou krijgen wanneer u een eenvoudige op een schema type Text.FromValue typewaarde doet (wat resulteert in 'type').

Diagnostics.LogFailure

De functie kan worden gebruikt om functie-aanroepen te verpakken en schrijft alleen naar de trace als de functie-aanroep mislukt (dat wil Diagnostics.LogFailure zeggen, retourneert een error ).

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

Voegt intern een Diagnostics.LogFailure operator toe aan de try function aanroep. Als de aanroep mislukt, wordt text de waarde naar de tracer geschreven voordat de oorspronkelijke wordt retourneert. error Als de function aanroep slaagt, wordt het resultaat geretourneerd zonder iets naar de traceer te schrijven. Omdat M-fouten geen volledige stack-trace bevatten (dat wil zeggen dat u doorgaans alleen het bericht van de fout ziet), kan dit handig zijn als u wilt aangeven waar de fout daadwerkelijk is opgetreden.

Als voorbeeld (slecht) wijzigt u de withData regel van de functie om opnieuw een fout af te TripPinNavTable dwingen:

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

In de trace vindt u het resulterende foutbericht met uw text , en de oorspronkelijke foutgegevens.

LogFailure-bericht.

Zorg ervoor dat u uw functie opnieuw in werking stelt voordat u doorgaat met de volgende zelfstudie.

Conclusie

In deze korte (maar belangrijke!) les hebt u geleerd hoe u de diagnostische helperfuncties gebruikt om u aan te melden bij de Power Query traceerbestanden. Wanneer deze functies goed worden gebruikt, zijn ze zeer nuttig bij het oplossen van problemen binnen uw connector.

Notitie

Als connectorontwikkelaar is het uw verantwoordelijkheid om ervoor te zorgen dat u geen gevoelige of persoonsgegevens (PII) in een logboek oplogt als onderdeel van uw diagnostische logboekregistratie. U moet er ook op letten dat er niet te veel traceergegevens worden uitgevoerd, omdat dit een negatieve invloed kan hebben op de prestaties.

Volgende stappen

TripPin Deel 9 - TestConnection