Mengonfigurasi Pengelogan Pesan

Topik ini menjelaskan bagaimana Anda dapat mengonfigurasi pengelogan pesan untuk skenario yang berbeda.

Mengaktifkan Pengelogan Pesan

Windows Communication Foundation (WCF) tidak mencatat pesan secara default. Untuk mengaktifkan pengelogan pesan, Anda harus menambahkan pendengar jejak ke System.ServiceModel.MessageLogging sumber pelacakan dan mengatur atribut untuk <messagelogging> elemen dalam file konfigurasi.

Contoh berikut menunjukkan cara mengaktifkan pengelogan dan menentukan opsi tambahan.

<system.diagnostics>
  <sources>
    <source name="System.ServiceModel.MessageLogging">
      <listeners>
         <add name="messages"
              type="System.Diagnostics.XmlWriterTraceListener"
              initializeData="c:\logs\messages.svclog" />
        </listeners>
    </source>
  </sources>
</system.diagnostics>

<system.serviceModel>
  <diagnostics>
    <messageLogging
         logEntireMessage="true"
         logMalformedMessages="false"
         logMessagesAtServiceLevel="true"
         logMessagesAtTransportLevel="false"
         maxMessagesToLog="3000"
         maxSizeOfMessageToLog="2000"/>
  </diagnostics>
</system.serviceModel>

Untuk informasi selengkapnya tentang pengaturan pengelogan pesan, lihat Pengaturan yang Direkomendasikan untuk Pelacakan dan Pengelogan Pesan.

Anda dapat menggunakan add untuk menentukan nama dan jenis pendengar yang ingin Anda gunakan. Dalam konfigurasi contoh, Listener diberi nama "messages" dan menambahkan listener jejak .NET Framework standar (System.Diagnostics.XmlWriterTraceListener) sebagai jenis yang akan digunakan. Jika Anda menggunakan System.Diagnostics.XmlWriterTraceListener, Anda harus menentukan lokasi dan nama file output dalam file konfigurasi. Ini dilakukan dengan mengatur initializeData ke nama file log. Jika tidak, sistem melemparkan pengecualian. Anda juga dapat menerapkan pendengar kustom yang memancarkan log ke file default.

Nota

Karena pengelogan pesan mengakses ruang disk, Anda harus membatasi jumlah pesan yang ditulis ke disk untuk layanan tertentu. Ketika batas pesan tercapai, jejak di tingkat Informasi dihasilkan dan semua aktivitas pengelogan pesan berhenti.

Tingkat pengelogan, serta opsi tambahan, dibahas di bagian Tingkat Pengelogan dan Opsi.

Atribut switchValue dari source hanya valid untuk tujuan pelacakan. Jika Anda menentukan switchValue atribut untuk System.ServiceModel.MessageLogging sumber pelacakan sebagai berikut, atribut tersebut tidak berpengaruh.

<source name="System.ServiceModel.MessageLogging" switchValue="Verbose">
</source>

Jika Anda ingin menonaktifkan sumber pelacakan, Anda harus menggunakan atribut logMessagesAtServiceLevel, logMalformedMessages, dan logMessagesAtTransportLevel dari elemen messageLogging sebagai gantinya. Anda harus mengatur semua atribut ini ke false. Ini dapat dilakukan dengan menggunakan file konfigurasi dalam contoh kode sebelumnya, melalui antarmuka antarmuka pengguna Editor Konfigurasi, atau menggunakan WMI. Untuk informasi selengkapnya tentang alat Editor Konfigurasi, lihat Alat Editor Konfigurasi (SvcConfigEditor.exe). Untuk informasi selengkapnya tentang WMI, lihat Menggunakan Instrumentasi Manajemen Windows untuk Diagnostik.

Tingkat dan Opsi Pengelogan

Untuk pesan masuk, pengelogan terjadi segera setelah pesan terbentuk, segera sebelum pesan masuk ke kode pengguna di tingkat layanan, dan ketika pesan cacat terdeteksi.

Untuk pesan keluar, pencatatan log terjadi segera setelah pesan meninggalkan kode pengguna dan segera sebelum pesan dikirim melalui jaringan.

WCF mencatat pesan pada dua tingkatan yang berbeda: layanan dan transportasi. Pesan yang salah bentuk juga dicatat. Ketiga kategori tersebut independen satu sama lain dan dapat diaktifkan secara terpisah dalam konfigurasi.

Anda dapat mengontrol tingkat pencatatan dengan pengaturan atribut logMessagesAtServiceLevel, logMalformedMessages, dan logMessagesAtTransportLevel dari elemen messageLogging.

Tingkat Layanan

Pesan yang dicatat pada lapisan ini akan masuk (saat menerima) atau meninggalkan (saat mengirim) kode pengguna. Jika filter telah ditentukan, hanya pesan yang cocok dengan filter yang dicatat. Jika tidak, semua pesan di tingkat layanan dicatat. Pesan infrastruktur (transaksi, saluran rekan, dan keamanan) juga dicatat pada tingkat ini, kecuali untuk pesan Reliable Messaging. Pada pesan yang dialirkan, hanya header yang dicatat. Selain itu, pesan aman dicatat dalam bentuk yang sudah didekripsi pada tingkat ini.

Tingkat Transportasi

Pesan yang dicatat pada lapisan ini siap untuk dikodekan atau didekodekan sebelum atau setelah ditransmisikan melalui jaringan. Jika filter telah ditentukan, hanya pesan yang cocok dengan filter yang dicatat. Jika tidak, semua pesan di lapisan transportasi dicatat. Semua pesan infrastruktur dicatat pada lapisan ini, termasuk pesan olahpesan yang andal. Pada pesan yang dialirkan, hanya header yang dicatat. Selain itu, pesan aman dicatat sebagai dienkripsi pada tingkat ini, kecuali jika transportasi aman seperti HTTPS digunakan.

Tingkat Cacat

Pesan yang salah bentuk adalah pesan yang ditolak oleh tumpukan WCF pada tahap pemrosesan apa pun. Pesan malformasi dicatat dalam log as-is: dienkripsi jika memang demikian, dengan XML yang tidak benar, dan sebagainya. maxSizeOfMessageToLog menentukan ukuran pesan yang akan dicatat sebagai CDATA. Secara default, maxSizeOfMessageToLog sama dengan 256K. Untuk informasi selengkapnya tentang atribut ini, lihat bagian Opsi Lainnya.

Opsi Lainnya

Selain tingkat pengelogan, pengguna dapat menentukan opsi berikut:

Log Seluruh Pesan (logEntireMessage atribut): Nilai ini menentukan apakah seluruh pesan (header pesan dan isi) dicatat. Nilai defaultnya adalah false, yang berarti bahwa hanya header yang dicatat. Pengaturan ini memengaruhi tingkat pengelogan pesan layanan dan transportasi..
Pesan maks untuk dicatat (maxMessagesToLog atribut): Nilai ini menentukan jumlah maksimum pesan yang akan dicatat. Semua pesan (layanan, transportasi, dan pesan cacat) dihitung dalam kuota ini. Ketika kuota tercapai, jejak pesan dikeluarkan dan pesan tambahan tidak dicatat lagi. Nilai default adalah 10000.
Ukuran maksimum pesan yang dicatat (maxSizeOfMessageToLog atribut): Nilai ini menentukan ukuran maksimum pesan yang dicatat dalam satuan byte. Pesan yang melebihi batas ukuran tidak dicatat, dan tidak ada aktivitas lain yang dilakukan untuk pesan tersebut. Pengaturan ini memengaruhi semua tingkat pelacakan. Jika pelacakan ServiceModel aktif, jejak tingkat peringatan dipancarkan pada titik pengelogan pertama (ServiceModelSend* atau TransportReceive) untuk memberi tahu pengguna. Nilai default untuk tingkat layanan dan pesan pada tingkat transportasi adalah 256K, sedangkan nilai default untuk pesan yang rusak adalah 4K.

Perhatian

Ukuran pesan yang dihitung untuk dibandingkan maxSizeOfMessageToLog adalah ukuran pesan dalam memori sebelum serialisasi. Ukuran ini dapat berbeda dari panjang aktual string pesan yang sedang dicatat, dan dalam banyak kesempatan lebih besar dari ukuran aktual. Akibatnya, pesan mungkin tidak dicatat. Anda dapat memperhitungkan fakta ini dengan menentukan maxSizeOfMessageToLog atribut menjadi 10% lebih besar dari ukuran pesan yang diharapkan. Selain itu, jika pesan yang tidak terformat dengan benar dicatat, ruang disk yang sebenarnya digunakan oleh log pesan dapat mencapai 5 kali ukuran nilai yang ditentukan oleh maxSizeOfMessageToLog.

Jika tidak ada pendengar jejak yang ditentukan dalam file konfigurasi, tidak ada output pengelogan yang dihasilkan terlepas dari tingkat pengelogan yang ditentukan.

Opsi pengelogan pesan, seperti atribut yang dijelaskan di bagian ini, dapat diubah saat runtime menggunakan Instrumentasi Manajemen Windows (WMI). Ini dapat dilakukan dengan mengakses instans AppDomainInfo , yang mengekspos properti Boolean ini: LogMessagesAtServiceLevel, , LogMessagesAtTransportLeveldan LogMalformedMessages. Oleh karena itu, jika Anda mengonfigurasi pendengar pelacakan untuk pengelogan pesan, tetapi atur opsi ini ke false dalam konfigurasi, Anda nantinya dapat mengubahnya menjadi true saat aplikasi berjalan. Ini secara efektif memungkinkan pengelogan pesan pada runtime. Demikian pula, jika Anda mengaktifkan pengelogan pesan dalam file konfigurasi, Anda dapat menonaktifkannya saat runtime menggunakan WMI. Untuk informasi selengkapnya, lihat Menggunakan Instrumentasi Manajemen Windows untuk Diagnostik.

Bidang source dalam log pesan menentukan konteks di mana pesan dicatat: saat mengirim/menerima pesan permintaan, untuk permintaan-balas atau permintaan satu arah, pada model layanan atau lapisan transportasi, atau dalam kasus pesan yang tidak benar.

Untuk pesan cacat, source sama dengan Malformed. Jika tidak, sumber memiliki nilai berikut berdasarkan konteks.

Untuk Permintaan/Balasan:

Lapisan	Kirim Permintaan	Terima Permintaan	Kirim Balasan	Terima Balasan
Lapisan Model Layanan	Pelayanan Tingkat Kirim Permohonan	Pelayanan Tingkat Menerima Permohonan	Pelayanan Tingkat Kirim Jawab	Pelayanan Tingkat Menerima Jawab
Lapisan transportasi	Transportasi Kirim	Transportasi Menerima	Transportasi Kirim	Transportasi Menerima

Untuk Permintaan Satu Arah:

Lapisan	Kirim Permintaan	Terima Permintaan
Lapisan Model Layanan	Pelayanan Tingkat Kirim Datagram	Pelayanan Tingkat Menerima Datagram
Lapisan transportasi	Transportasi Kirim	Transportasi Menerima

Filter Pesan

Filter pesan ditentukan dalam elemen konfigurasi messageLogging dari bagian konfigurasi diagnostics. Mereka diterapkan pada tingkat layanan dan transportasi. Ketika satu atau beberapa filter ditentukan, hanya pesan yang cocok dengan setidaknya salah satu filter yang dicatat. Jika tidak ada filter yang ditentukan, semua pesan akan diteruskan.

Filter mendukung sintaks XPath lengkap dan diterapkan dalam urutan muncul dalam file konfigurasi. Filter yang salah secara sintaksis menghasilkan pengecualian konfigurasi.

Filter juga menyediakan fitur keamanan menggunakan nodeQuota atribut , yang membatasi jumlah maksimum simpul di XPath DOM yang dapat diperiksa agar sesuai dengan filter.

Contoh berikut menunjukkan cara mengonfigurasi filter yang hanya merekam pesan yang memiliki bagian header SOAP.

<messageLogging logEntireMessage="true"
    logMalformedMessages="true"
    logMessagesAtServiceLevel="true"
    logMessagesAtTransportLevel="true"
    maxMessagesToLog="420">
    <filters>
        <add nodeQuota="10" xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
                 /soap:Envelope/soap:Header
        </add>
     </filters>
</messageLogging>

Filter tidak dapat diterapkan ke isi pesan. Filter yang mencoba memanipulasi isi pesan dihapus dari daftar filter. Sebuah peristiwa juga dikeluarkan yang menunjukkan hal ini. Misalnya, filter berikut akan dihapus dari tabel filter.

<add xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">/s:Envelope/s:Body[contains(text(), "Hello")]</add>

Mengonfigurasi Pendengar Kustom

Anda juga dapat mengonfigurasi pendengar kustom dengan opsi tambahan. Pendengar kustom dapat berguna dalam memfilter elemen PII khusus aplikasi dari pesan sebelum pengelogan. Contoh berikut menunjukkan konfigurasi pendengar kustom.

<system.diagnostics>
   <sources>
     <source name="System.ServiceModel.MessageLogging">
           <listeners>
             <add name="MyListener"
                    type="YourCustomListener"
                    initializeData="c:\logs\messages.svclog"
                    maxDiskSpace="1000"/>
           </listeners>
     </source>
   </sources>
</system.diagnostics>

Perlu diketahui bahwa atribut type harus diatur ke nama assembly yang memenuhi syarat dari tipe tersebut.

Lihat juga

Last updated on 2025-06-17

Bagikan melalui