Kebijakan MessageLogging

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Apa

Salah satu cara terbaik untuk melacak masalah di lingkungan runtime API adalah dengan mencatat pesan. Anda dapat melampirkan dan mengonfigurasi kebijakan MessageLogging di API untuk mencatat pesan khusus ke disk lokal (khusus Edge untuk Private Cloud) atau ke syslog.

Contoh

Syslog

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Penggunaan umum dari jenis kebijakan {i>MessageLogging<i} adalah mencatat ke akun syslog. Kapan yang dikonfigurasikan untuk syslog, proxy API akan meneruskan pesan log dari Apigee Edge ke remote server {i>syslog<i}. Anda pasti sudah memiliki server syslog. Jika tidak, pengelolaan log publik seperti Splunk, Sumo Logic, dan Loggly, juga tersedia. lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.

Misalnya, bayangkan Anda perlu mencatat informasi tentang setiap pesan permintaan yang API yang diterima dari aplikasi konsumen. Nilai 3f509b58 mewakili nilai kunci khusus untuk layanan loggly. Jika Anda memiliki akun loggly, ganti kunci loggly Anda. Tujuan pesan log yang dibuat akan diisi dengan empat nilai: organisasi, API proxy, dan nama lingkungan yang terkait dengan transaksi, bersama dengan nilai untuk kueri pada pesan permintaan.

Jika memiliki deployment Edge for Private Cloud, Anda juga dapat menulis pesan log ke .

Syslog melalui TLS/SSL

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

Anda dapat mengirim pesan ke penyedia logging pesan pihak ketiga melalui TLS/SSL dengan menambahkan atribut Blok <SSLInfo>.

Rotasi file: ukuran

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotasi file berdasarkan ukuran file.

Rotasi file: waktu

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotasi file berdasarkan waktu.

Rotasi file: waktu & ukuran

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Rotasi file berdasarkan waktu dan ukuran.

Streaming diaktifkan

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Logging pesan yang mendukung streaming


Referensi elemen

Gunakan elemen berikut untuk mengonfigurasi jenis kebijakan MessageLogging.

Nama Kolom Deskripsi Kolom

File

Tujuan file lokal. (Logging file hanya didukung di Edge untuk Private Cloud deployments.) Untuk mengetahui informasi tempat file disimpan, lihat File log lokasi di Edge untuk Private Cloud.

Message Membuat pesan yang akan dikirim ke {i>file<i} log, dengan menggabungkan teks dengan variabel untuk menangkap informasi yang Anda inginkan. Lihat Contoh.
FileName Nama file log tempat pesan dicatat.
FileRotationOptions
rotateFileOnStartup

Atribut. Nilai valid: true/false

Jika disetel ke benar (true), file log akan diputar setiap kali mesin pesan akan dimulai ulang.

FileRotationType Menentukan kebijakan rotasi (size atau time) dari file log.
MaxFileSizeInMB (Saat memilih size sebagai jenis rotasi) Menentukan ukuran file log yang memicu server untuk memindahkan pesan log ke file terpisah. Setelah file log mencapai ukuran yang ditentukan, server mengganti nama file log saat ini.
RotationFrequency (Saat memilih time sebagai jenis rotasi) Menentukan waktu dalam menit yang memicu server untuk memindahkan pesan log ke server terpisah . Setelah interval yang ditentukan berlalu, file log saat ini diganti namanya.
MaxFilesToRetain

Menentukan jumlah maksimum file yang akan dipertahankan dalam konteks rotasi Anda setelan. Nilai defaultnya adalah 8.

Jika Anda menetapkan nol (0), file log akan disimpan tanpa batas waktu, tetapi sesuai dengan file Anda pengaturan rotasi, meskipun tidak ada file yang dihapus atau diganti namanya. Oleh karena itu, untuk menghindari pesan error penuh berikutnya, setel ke nilai yang lebih besar dari nol, atau terapkan error sistem otomatis untuk membersihkan atau mengarsipkan file log lama yang tersimpan.

BufferMessage

Jika streaming HTTP diaktifkan untuk proxy, pesan permintaan/respons tidak di-buffer. Jika Anda ingin membuat log konten yang mengharuskan pesan alur diuraikan, lalu tetapkan BufferMessage ke true. Lihat jendela "Streaming yang diaktifkan" tab sampel sebagai contoh. Default: false

Syslog

Tujuan syslog. Untuk mengirim {i>syslog<i} ke Splunk, Sumo Logic, atau Loggly, lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.

Message

Membuat pesan yang akan dikirim ke {i>syslog<i}, menggabungkan teks dengan variabel untuk ditangkap informasi yang Anda inginkan. Lihat Contoh.

Catatan: Variabel respons akan tidak tersedia di PostClientFlow mengikuti Alur Error. Menggunakan variabel pesan untuk mencatat informasi respons baik untuk situasi {i>error<i} dan keberhasilan. Lihat juga Catatan penggunaan.

Host Nama host atau alamat IP server tempat syslog harus dikirim. Jika Anda tidak menyertakan elemen ini, defaultnya adalah {i>localhost<i}.
Port Port tempat syslog berjalan. Jika Anda tidak menyertakan elemen ini, defaultnya adalah 514.
Protocol TCP atau UDP (default). Meskipun UDP lebih berperforma tinggi, Protokol TCP menjamin pengiriman log pesan ke server {i>syslog<i}. Untuk mengirim syslog pesan melalui TLS/SSL, hanya TCP yang didukung.
FormatMessage

true atau false (default)

Opsional, tetapi <FormatMessage>true</FormatMessage> wajib ada untuk digunakan dengan Loggly.

Elemen ini memungkinkan Anda mengontrol format konten buatan Apigee yang ditambahkan ke untuk membuat pesan email baru. Jika diatur ke benar (true), pesan {i>syslog<i} diawali dengan sejumlah karakter yang tetap, yang memungkinkan Anda untuk memfilter informasi tersebut dari pesan. Berikut contoh untuk konfigurasi format:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee-Edge - - - Message starts here

Informasi yang dibuat Apigee mencakup:

  • <14> - Skor prioritas (lihat Protokol Syslog) yang didasarkan pada tingkat log dan tingkat fasilitas pesan.
  • 1 - Versi syslog saat ini.
  • Tanggal dengan selisih UTC (UTC = +0000).
  • UUID pemroses pesan.
  • "Apigee-Edge - - - "

Jika ditetapkan ke salah (default), pesan tidak akan ditambahkan dengan yang telah diperbaiki karakter.

PayloadOnly

true atau false (default)

Elemen ini menetapkan format pesan yang dihasilkan Apigee agar hanya memuat isi pesan syslog, tanpa karakter tambahan yang ditentukan oleh FormatMessage.

Jika Anda tidak menyertakan elemen ini atau membiarkannya kosong, nilai defaultnya adalah false.

Lihat FormatMessage.

DateFormat

Opsional.

String template pemformatan yang akan digunakan untuk memformat stempel waktu setiap pesan log. Secara default, Apigee menggunakan yyyy-MM-dd'T'HH:mm:ss.SSSZ. Perilaku template ini dijelaskan dalam dokumentasi untuk Class SimpleDateFormat Java.

SSLInfo

Memungkinkan Anda mencatat pesan melalui SSL/TLS. Gunakan dengan sub-elemen <Enabled>true</Enabled>.

Jika Anda tidak menyertakan elemen ini atau membiarkannya kosong, nilai defaultnya adalah false (tidak TLS/SSL).

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Anda dapat mengonfigurasi tag &lt;SSLInfo&gt; dengan cara yang sama dapat dilakukan di TargetEndpoint, termasuk mengaktifkan TLS/SSL dua arah, seperti yang dijelaskan dalam Referensi konfigurasi proxy API. Hanya protokol TCP yang didukung.

logLevel

Opsional.

Nilai yang valid: INFO (default), ALERT, WARN, ERROR

Menyetel tingkat informasi tertentu untuk disertakan dalam log pesan.

Jika menggunakan elemen FormatMessage (menyetelnya ke benar), Setelan logLevel memengaruhi skor prioritas yang dihitung (angka di dalam tanda kurung sudut) dalam informasi yang dihasilkan Apigee yang ditambahkan ke pesan.

Skema


Catatan penggunaan

Saat melampirkan kebijakan MessageLogging ke alur proxy API, pertimbangkan untuk menempatkannya di Respons ProxyEndpoint, dalam alur khusus yang disebut PostClientFlow. PostClientFlow dieksekusi setelah respons dikirim ke klien yang meminta, yang memastikan bahwa semua metrik tersedia untuk logging. Untuk mengetahui detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.

PostClientFlow istimewa dalam dua hal:

  1. Fungsi ini hanya dijalankan sebagai bagian dari alur respons.
  2. Ini adalah satu-satunya alur yang dieksekusi setelah proxy memasuki status error.

Karena dijalankan terlepas dari apakah {i>proxy<i} berhasil atau gagal, Anda dapat menempatkan Kebijakan MessageLogging di PostClientFlow dan dijamin selalu dieksekusi.

Gambar Trace berikut menunjukkan kebijakan MessageLogging yang dijalankan sebagai bagian dari PostClientFlow, setelah DefaultFaultRule dijalankan:

Dalam contoh ini, kebijakan Verify API Key menyebabkan kesalahan karena tombol.

Di bawah ini adalah definisi ProxyEndpoint yang menyertakan PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Edge mencatat pesan sebagai teks sederhana, dan Anda dapat mengonfigurasi logging agar menyertakan variabel, seperti tanggal dan waktu saat permintaan atau respons diterima, identitas pengguna pada permintaan, alamat IP sumber asal permintaan dikirim, dan seterusnya. Pesan log edge secara asinkron, artinya tidak ada latensi yang mungkin disebabkan oleh pemblokiran pemanggilan ke API Anda.

Kebijakan MessageLogging menulis pesan yang dicatat dalam memori ke buffer. Pencatat pesan membaca pesan dari buffer, lalu menulis ke tujuan yang Anda konfigurasi. Masing-masing tujuan memiliki buffer-nya sendiri.

Jika kecepatan tulis ke {i>buffer<i} meningkat melebihi kecepatan baca, {i>buffer<i} akan meluber dan pencatatan log akan gagal. Jika hal ini terjadi, Anda mungkin menemukan pesan yang berisi hal berikut di log file:

Log message size exceeded. Increase the max message size setting

Jika Anda mengalami masalah ini di Edge untuk Private Cloud 4.15.07 dan versi sebelumnya, temukan message-logging.properties dan gunakan solusi ini:

Tingkatkan properti max.log.message.size.in.kb (nilai default = 128 KB) di bagian File message-logging.properties.

Untuk Edge untuk Private Cloud 4.16.01 dan yang lebih baru, tetapkan properti conf/message-logging.properties+max. log.message.size.in.kb di file /opt/apigee/customer/application/message-processor.properties dan mulai ulang Message Processor. Perhatikan bahwa properti ini awalnya dikomentari secara default.

Catatan: Pesan respons variabel di Edge tidak tersedia dari Alur Error. Variabel-variabel ini juga bukan tersedia di PostClientFlow jika alur sebelumnya adalah Alur Error. Jika Anda ingin mencatat respons informasi dari PostClientFlow, gunakan objek message. Anda dapat gunakan objek ini untuk mendapatkan header dan informasi lain dari respons, terlepas dari adalah {i>error<i}. Lihat Pesan variabel untuk mengetahui informasi selengkapnya dan contoh.

Mengontrol pesan log stempel waktu di Edge untuk Private Cloud

Secara default, stempel waktu di semua pesan log memiliki format:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Default di seluruh sistem ini dapat diganti untuk tujuan syslog menggunakan Elemen DateFormat. Perilaku template ini dijelaskan di dokumentasi untuk class SimpleDateFormat Java. Menurut definisi tersebut, yyyy akan diganti dengan tahun yang terdiri dari 4 digit, MM akan diganti dengan angka bulan 2 digit, dan seterusnya. Format di atas dapat menghasilkan string dengan format ini:

2022-09-28T22:38:11.721+0000

Anda dapat menggunakan konfigurasi conf_system_apigee.syslogger.dateFormat di Edge Message Processor untuk mengontrol format tersebut. Misalnya, mengubah pesan format menjadi:

yy/MM/dd'T'HH:mm:ss.SSSZ

..mengganti tanda hubung dengan garis miring dan dipersingkat menjadi tahun 2 digit, akan mencatat stempel waktu dalam bentuk:

22/09/28T22:38:11.721+0000

Untuk mengubah format:

  1. Buka file message-processor.properties di . Jika file tidak ada, buat file tersebut:
    &gt; vi /opt/apigee/customer/application/message-processor.properties
  2. Tetapkan properti sesuai keinginan:
    conf_system_apigee.syslogger.dateFormat=yy/MM/dd&#39;T&#39;HH:mm:ss.SSSZ
  3. Simpan perubahan.
  4. Pastikan file properti dimiliki oleh 'apigee' pengguna:
    &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Mulai ulang Pemroses Pesan Edge:
    &gt; /opt/apigee/apigee-service/bin/apigee-service edge-message-processor mulai ulang

Catat lokasi file di Edge untuk Private Cloud

Edge untuk Private Cloud 4.16.01 dan yang lebih baru

Secara default, log pesan Private Cloud berada di direktori berikut di Message Node pemroses:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Anda dapat mengubah lokasi log {i>default<i} dengan memodifikasi properti di message-logging.properties di Pemroses Pesan:

  • bin_setenv_data_dir - Menetapkan jalur root untuk penyimpanan file log. Misalnya, bin_setenv_data_dir=/opt/apigee/var/log
  • conf_message-logging_log.root.dir - Jika Anda tetapkan ini ke jalur relatif, seperti conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.

    Jika Anda menyetelnya ke jalur absolut, seperti conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, pesan log akan disimpan di /opt/apigee/var/log/messages/messagelog/. Jalur absolut lebih diprioritaskan daripada bin_setenv_data_dir.

    Perhatikan bahwa Anda harus mereferensikan properti sebagai conf/message-logging.properties+log.root.dir karena ini secara {i>default <i}dikomentari. Lihat Menyetel token yang saat ini diberi komentar untuk mendapatkan lebih banyak informasi.

Jika Anda ingin menyimpan file log dalam struktur file datar sehingga semua file log ditempatkan di yang sama, tetapkan conf/message-logging.properties+enable.flat.directory.structure ke benar di file {i>message-logging.properties<i}. Pesan disimpan di direktori yang ditentukan oleh properti di atas, dan nama file mengambil bentuk {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Untuk menetapkan properti ini:

  1. Buka file message-processor.properties di . Jika file tidak ada, buat file tersebut:
    &gt; vi /opt/apigee/customer/application/message-processor.properties
  2. Tetapkan properti sesuai keinginan:
    conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
  3. Simpan perubahan.
  4. Pastikan file properti dimiliki oleh 'apigee' pengguna:
    &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Mulai ulang komponen Edge:
    &gt; /opt/apigee/apigee-service/bin/apigee-service edge-message-processor mulai ulang

Edge untuk Private Cloud 4.15.07 dan yang lebih lama

Secara default, log pesan berada di lokasi berikut di pesan prosesor:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Anda dapat mengubah lokasi log {i>default<i} dengan memodifikasi properti berikut di file message-logging.properties di pemroses pesan:

  • data.dir - Menetapkan root untuk penyimpanan file log. Misalnya, data.dir=/opt/apigee4/var/log
  • log.root.dir - Jika Anda menetapkan ini ke jalur relatif, seperti log.root.dir=custom/folder/, jalur tersebut ditambahkan ke lokasi data.dir.

Misalnya, kombinasi dari dua properti akan menetapkan direktori {i>logging<i} pada /opt/apigee4/var/log/custom/folder/messagelog/ (perhatikan bahwa /messagelog ditambahkan secara otomatis).

Jika Anda menetapkannya ke jalur absolut, seperti log.root.dir=/opt/apigee4/var/log/messages, log pesan akan disimpan di {i> /opt/apigee4/var/log/messages/messagelog/<i}. Jalur absolut pada log.root.dir lebih diprioritaskan daripada data.dir.

Jika Anda ingin menyimpan file log dalam struktur file datar sehingga semua file log ditempatkan di direktori yang sama, tetapkan enable.flat.directory.structure properti ke true dalam file message-logging.properties di Message Prosesor. Pesan disimpan di direktori yang ditentukan oleh properti di atas, dan file tersebut nama akan berbentuk {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Nilai default untuk variabel dalam template pesan

Nilai default dapat ditentukan untuk setiap variabel di template pesan secara terpisah. Misalnya, jika variabel request.header.id tidak dapat diselesaikan, nilainya akan diganti dengan nilai unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Nilai default umum dapat ditentukan untuk semua variabel yang belum terselesaikan dengan menetapkan Atribut defaultVariableValue di elemen Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Mengonfigurasi layanan pengelolaan log pihak ketiga

Kebijakan {i>MessageLogging<i} memungkinkan Anda mengirim pesan syslog ke manajemen log pihak ketiga seperti Splunk, Sumo Logic, dan Loggly. Jika Anda ingin mengirim {i> syslog<i} ke salah satu layanan, lihat dokumentasi layanan itu untuk mengkonfigurasi {i>host<i}, porta, dan protokol layanan, kemudian tetapkan elemen Syslog pada kebijakan ini sebagaimana mestinya.

Lihat dokumentasi berikut untuk konfigurasi pengelolaan log pihak ketiga:

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan kesalahan yang dikembalikan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu kesalahan. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Penanganan kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode error Status HTTP Penyebab
steps.messagelogging.StepDefinitionExecutionFailed 500 Lihat string kesalahan.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab Perbaiki
InvalidProtocol Deployment kebijakan MessageLogging dapat gagal dengan error ini jika protokol yang ditentukan dalam elemen <Protocol> tidak valid. Protokol yang valid adalah TCP dan UDP. Untuk mengirim pesan syslog melalui TLS/SSL, hanya TCP yang didukung.
InvalidPort Deployment kebijakan MessageLogging dapat gagal dengan error ini jika nomor port tidak ditentukan dalam elemen <Port> atau tidak valid. Nomor port harus bilangan bulat yang lebih besar dari nol.

Variabel kesalahan

Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Di mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. messagelogging.ML-LogMessages.failed = true

Contoh respons error

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Contoh aturan kesalahan

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>


Variabel flow

Variabel berikut akan diisi jika kebijakan gagal.

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

Topik terkait