Bagikan melalui

TripPin bagian 8 - Menambahkan diagnostik

  • Artikel

Catatan

Konten ini saat ini mereferensikan konten dari implementasi warisan untuk diagnostik di Visual Studio. Konten akan diperbarui dalam waktu dekat untuk mencakup Power Query SDK baru di Visual Studio Code.

Tutorial multi-bagian ini mencakup pembuatan ekstensi sumber data baru untuk Power Query. Tutorial ini dimaksudkan untuk dilakukan secara berurutan—setiap pelajaran dibangun pada konektor yang dibuat dalam pelajaran sebelumnya, secara bertahap menambahkan kemampuan baru ke konektor Anda.

Dalam pelajaran ini, Anda akan:

  • Pelajari tentang fungsi Diagnostics.Trace
  • Gunakan fungsi pembantu Diagnostik untuk menambahkan informasi pelacakan untuk membantu men-debug konektor Anda

Mengaktifkan diagnostik

Pengguna Power Query dapat mengaktifkan pembuatan log jejak dengan memilih kotak centang di bawah Opsi | Diagnostik.

Aktifkan pelacakan di Power Query.

Setelah diaktifkan, setiap kueri berikutnya akan menyebabkan mesin M memancarkan informasi jejak ke file log yang terletak di direktori pengguna tetap.

Saat menjalankan kueri M dari dalam Power Query SDK, pelacakan diaktifkan di tingkat proyek. Pada halaman properti proyek, ada tiga pengaturan yang terkait dengan pelacakan:

  • Hapus Log—saat ini diatur ke true, log akan diatur ulang/dihapus saat Anda menjalankan kueri Anda. Kami sarankan Anda tetap mengatur ini ke true.
  • Tampilkan Jejak Mesin—pengaturan ini mengontrol output jejak bawaan dari mesin M. Jejak ini hanya berguna untuk anggota tim Power Query, jadi Anda biasanya ingin mengatur ini ke false.
  • Tampilkan Jejak Pengguna—pengaturan ini mengontrol output informasi pelacakan oleh konektor Anda. Anda akan ingin mengatur ini ke true.

Properti proyek.

Setelah diaktifkan, Anda akan mulai melihat entri log di jendela Output Kueri M, di bawah tab Log.

Diagnostics.Trace

Fungsi Diagnostics.Trace digunakan untuk menulis pesan ke dalam log jejak mesin M.

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

Penting

M adalah bahasa fungsi dengan evaluasi malas. Saat menggunakan Diagnostics.Trace, perlu diingat bahwa fungsi hanya akan dipanggil jika ekspresi bagian darinya benar-benar dievaluasi. Contoh ini dapat ditemukan nanti dalam tutorial ini.

Parameter traceLevel dapat menjadi salah satu nilai berikut (dalam urutan menurut):

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

Saat pelacakan diaktifkan, pengguna dapat memilih tingkat maksimum pesan yang ingin mereka lihat. Semua pesan pelacakan tingkat ini dan di bawah akan dihasilkan ke log. Misalnya, jika pengguna memilih tingkat "Peringatan", lacak pesan TraceLevel.Warning, TraceLevel.Error, dan TraceLevel.Critical akan muncul di log.

Parameter message adalah teks aktual yang akan dihasilkan ke file pelacakan. Teks tidak akan berisi value parameter kecuali Anda secara eksplisit menyertakannya dalam teks.

Parameter value adalah apa yang akan dikembalikan fungsi. delayed Ketika parameter diatur ke true, value akan menjadi fungsi parameter nol yang mengembalikan nilai aktual yang Anda evaluasi. Ketika delayed diatur ke false, value akan menjadi nilai aktual. Contoh cara kerjanya dapat ditemukan di bawah ini.

Menggunakan Diagnostik. Melacak di konektor TripPin

Untuk contoh praktis menggunakan Diagnostics.Trace dan dampak delayed parameter, perbarui fungsi konektor GetSchemaForEntity TripPin untuk membungkus error pengecualian:

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

Anda dapat memaksa kesalahan selama evaluasi (untuk tujuan pengujian!) dengan meneruskan nama entitas yang tidak valid ke GetEntity fungsi. Di sini Anda mengubah withData baris dalam TripPinNavTable fungsi, mengganti [Name] dengan "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;

Aktifkan pelacakan untuk proyek Anda, dan jalankan kueri pengujian Anda. Pada tab Errors Anda akan melihat teks kesalahan yang Anda munculkan:

Pesan kesalahan.

Selain itu, pada tab Log , Anda akan melihat pesan yang sama. Jika Anda menggunakan nilai yang berbeda untuk message parameter dan value , ini akan berbeda.

Log kesalahan.

Perhatikan juga bahwa Action bidang pesan log berisi nama (Jenis Sumber Data) ekstensi Anda (dalam hal ini, Engine/Extension/TripPin). Ini memudahkan untuk menemukan pesan yang terkait dengan ekstensi Anda ketika ada beberapa kueri yang terlibat dan/atau pelacakan sistem (mesin mashup) diaktifkan.

Evaluasi tertunda

Sebagai contoh cara delayed kerja parameter, Anda akan membuat beberapa modifikasi dan menjalankan kueri lagi.

Pertama, atur nilai ke delayed false, tetapi biarkan value parameter apa adanya:

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

Saat menjalankan kueri, Anda akan menerima kesalahan bahwa "Kami tidak dapat mengonversi nilai tipe Fungsi ke Jenis", dan bukan kesalahan aktual yang Anda munculkan. Ini karena panggilan sekarang mengembalikan function nilai, bukan nilai itu sendiri.

Selanjutnya, hapus fungsi dari value parameter:

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

Saat menjalankan kueri, Anda akan menerima kesalahan yang benar, tetapi jika Anda memeriksa tab Log , tidak akan ada pesan. Ini karena error akhirnya dinaikkan/dievaluasi selama panggilan ke Diagnostics.Trace, sehingga pesan tidak pernah benar-benar keluaran.

Sekarang setelah Anda memahami dampak delayed parameter, pastikan untuk mengatur ulang konektor Anda kembali ke status kerja sebelum melanjutkan.

Fungsi pembantu diagnostik di Diagnostics.pqm

File Diagnostics.pqm yang disertakan dalam proyek ini berisi banyak fungsi pembantu yang mempermudah pelacakan. Seperti yang ditunjukkan dalam tutorial sebelumnya, Anda dapat menyertakan file ini dalam proyek Anda (mengingat untuk mengatur Tindakan Build ke Kompilasi), lalu memuatnya dalam file konektor Anda. Bagian bawah file konektor Anda sekarang akan terlihat seperti cuplikan kode di bawah ini. Jangan ragu untuk menjelajahi berbagai fungsi yang disediakan modul ini, tetapi dalam sampel ini, Anda hanya akan menggunakan Diagnostics.LogValue fungsi dan 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

Fungsi Diagnostics.LogValue ini sangat seperti Diagnostics.Trace, dan dapat digunakan untuk menghasilkan nilai dari apa yang Anda evaluasi.

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

Parameter prefix ditambahkan ke pesan log. Anda akan menggunakan ini untuk mencari tahu panggilan mana yang menghasilkan pesan. Parameter value adalah apa yang akan dikembalikan fungsi, dan juga akan ditulis ke pelacakan sebagai representasi teks dari nilai M. Misalnya, jika value sama table dengan dengan kolom A dan B, log akan berisi representasi yang setara #table : #table({"A", "B"}, {{"row1 A", "row1 B"}, {"row2 A", row2 B"}})

Catatan

Menserialisasikan nilai M ke teks bisa menjadi operasi yang mahal. Perhatikan ukuran potensi nilai yang Anda keluarkan ke pelacakan.

Catatan

Sebagian besar lingkungan Power Query akan memotong pesan pelacakan ke panjang maksimum.

Sebagai contoh, Anda akan memperbarui TripPin.Feed fungsi untuk melacak argumen dan schema yang url diteruskan ke fungsi.

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;

Anda harus menggunakan nilai dan _schema baru _url dalam panggilan ke GetAllPagesByNextLink. Jika Anda menggunakan parameter fungsi asli, Diagnostics.LogValue panggilan tidak akan pernah benar-benar dievaluasi, sehingga tidak ada pesan yang ditulis ke jejak. Pemrograman fungsi ini menyenangkan!

Saat menjalankan kueri, Anda sekarang akan melihat pesan baru di log.

Mengakses url:

Mengakses pesan url.

Jenis skema:

Pesan jenis skema.

Anda melihat versi schema serial parameter type, daripada apa yang akan Anda dapatkan ketika Anda melakukan sederhana Text.FromValue pada nilai jenis (yang menghasilkan "jenis").

Diagnostics.LogFailure

Fungsi Diagnostics.LogFailure ini dapat digunakan untuk membungkus panggilan fungsi, dan hanya akan menulis ke jejak jika panggilan fungsi gagal (yaitu, mengembalikan error).

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

Secara internal, Diagnostics.LogFailure menambahkan try operator ke function panggilan. Jika panggilan gagal, text nilai ditulis ke pelacakan sebelum mengembalikan yang asli error. function Jika panggilan berhasil, hasilnya dikembalikan tanpa menulis apa pun ke pelacakan. Karena kesalahan M tidak berisi jejak tumpukan penuh (artinya, Anda biasanya hanya melihat pesan kesalahan), ini dapat berguna ketika Anda ingin menentukan di mana kesalahan dimunculkan.

Sebagai contoh (buruk), ubah withData baris TripPinNavTable fungsi untuk memaksa kesalahan sekali lagi:

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

Dalam jejak, Anda dapat menemukan pesan kesalahan yang dihasilkan yang berisi , dan informasi kesalahan asli Anda text.

Pesan LogFailure.

Pastikan untuk mengatur ulang fungsi Anda ke status kerja sebelum melanjutkan tutorial berikutnya.

Kesimpulan

Pelajaran singkat ini (tetapi penting!) menunjukkan kepada Anda cara menggunakan fungsi pembantu diagnostik untuk masuk ke file pelacakan Power Query. Saat digunakan dengan benar, fungsi-fungsi ini berguna dalam men-debug masalah dalam konektor Anda.

Catatan

Sebagai pengembang konektor, Anda bertanggung jawab untuk memastikan bahwa Anda tidak mencatat informasi sensitif atau dapat diidentifikasi secara pribadi (PII) sebagai bagian dari pengelogan diagnostik Anda. Anda juga harus berhati-hati untuk tidak mengeluarkan terlalu banyak informasi jejak, karena dapat berdampak negatif pada performa.

Langkah berikutnya

TripPin Bagian 9 - Uji Koneksi ion