Kebijakan MessageLogging

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

Apa

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

Sample

Sistem

<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 jenis kebijakan MessageLogging adalah login ke akun syslog. Ketika dikonfigurasi untuk syslog, proxy API akan meneruskan pesan log dari Apigee Edge ke server syslog jarak jauh. Anda harus memiliki server syslog yang tersedia. Jika tidak, layanan pengelolaan log publik, seperti Splunk, Sumo Logic, dan Loggly, akan tersedia. lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.

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

Jika memiliki Edge untuk deployment Cloud Pribadi, Anda juga dapat menulis pesan log ke file.

Sistem 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 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 diaktifkan untuk 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 deployment Private Cloud.) Untuk mengetahui informasi tempat file disimpan, lihat Lokasi file log di Edge untuk Private Cloud.

Message Build pesan yang akan dikirim ke file log, yang menggabungkan teks dengan variabel untuk mengambil informasi yang Anda inginkan. Lihat Contoh.
FileName Nama file log tempat pesan dicatat.
FileRotationOptions
rotateFileOnStartup

Atribut. Nilai valid: true/false

Jika disetel ke benar, file log akan dirotasi setiap kali mesin pesan dimulai ulang.

FileRotationType Menentukan kebijakan rotasi (size atau time) 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 akan mengganti nama file log saat ini.
RotationFrequency (Saat memilih time sebagai jenis rotasi) Tentukan waktu dalam menit yang memicu server untuk memindahkan pesan log ke file yang terpisah. Setelah interval yang ditentukan berlalu, file log saat ini akan diganti namanya.
MaxFilesToRetain

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

Jika Anda menentukan nol (0), file log akan dipertahankan tanpa batas waktu, tetapi tunduk pada setelan rotasi file, meskipun tidak ada file yang dihapus atau diganti namanya. Oleh karena itu, untuk menghindari error penuh disk pada masa mendatang, tetapkan nilai ini ke nilai yang lebih besar dari nol, atau terapkan sistem otomatis dan permanen untuk menghapus atau mengarsipkan file log tersimpan yang lebih lama.

BufferMessage

Jika streaming HTTP diaktifkan untuk proxy, pesan permintaan/respons tidak akan di-buffer. Jika Anda ingin mencatat log konten yang memerlukan pesan flow untuk diurai, tetapkan BufferMessage ke true. Lihat tab contoh "Diaktifkan untuk streaming" sebagai contoh. Default: false

Syslog

Tujuan syslog. Untuk mengirim syslog ke Splunk, Sumo Logic, atau Loggly, lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.

Message

Build pesan yang akan dikirim ke syslog, dengan menggabungkan teks dengan variabel untuk mengambil informasi yang Anda inginkan. Lihat Contoh.

Catatan: Variabel respons tidak akan tersedia di PostClientFlow setelah Error Flow. Gunakan variabel pesan untuk mencatat informasi respons terkait error dan situasi berhasil. Lihat juga Catatan penggunaan.

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

true atau false (default)

Bersifat opsional, tetapi <FormatMessage>true</FormatMessage> diperlukan untuk digunakan dengan Loggly.

Elemen ini memungkinkan Anda mengontrol format konten yang dihasilkan Apigee yang ditambahkan sebelum pesan. Jika disetel ke benar, pesan syslog diawali dengan jumlah karakter tetap, yang memungkinkan Anda memfilter informasi tersebut dari pesan. Berikut ini contoh untuk format tetap:

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

Informasi yang dihasilkan Apigee mencakup:

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

Jika disetel ke salah (false), pesan tidak akan diawali dengan karakter tetap tersebut.

PayloadOnly

true atau false (default)

Elemen ini menetapkan format pesan yang dihasilkan Apigee agar hanya berisi 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 digunakan untuk memformat stempel waktu untuk 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 salah (tidak ada TLS/SSL).

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

Anda dapat mengonfigurasi tag <SSLInfo> dengan cara yang sama seperti pada 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

Tetapkan tingkat informasi tertentu untuk disertakan dalam log pesan.

Jika Anda menggunakan elemen FormatMessage (menetapkannya ke true), setelan logLevel akan memengaruhi skor prioritas yang dihitung (angka di dalam tanda kurung sudut) dalam informasi yang dihasilkan Apigee yang ditambahkan sebelum pesan.

Skema


Catatan penggunaan

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

PostClientFlow bersifat khusus dengan dua cara:

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

Karena dijalankan terlepas dari apakah proxy berhasil atau gagal, Anda dapat menempatkan kebijakan MessageLogging di PostClientFlow dan dijamin bahwa kebijakan selalu berjalan.

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

Dalam contoh ini, kebijakan Verify API Key menyebabkan kesalahan karena kunci tidak valid.

Berikut adalah definisi ProxyEndpoint yang mencakup 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 untuk menyertakan variabel, seperti tanggal dan waktu saat permintaan atau respons diterima, identitas pengguna pada permintaan, alamat IP sumber tempat permintaan dikirim, dan seterusnya. Edge mencatat pesan secara asinkron, yang berarti bahwa tidak ada latensi yang mungkin disebabkan oleh pemblokiran info yang diperkenalkan ke API Anda.

Kebijakan MessageLogging menulis pesan yang dicatat dalam memori ke buffering. Pencatat pesan membaca pesan dari buffering lalu menulis ke tujuan yang Anda konfigurasikan. Setiap tujuan memiliki buffering sendiri.

Jika kecepatan tulis ke buffering meningkat melebihi kecepatan baca, buffer overflow dan logging akan gagal. Jika hal ini terjadi, Anda mungkin menemukan pesan yang berisi hal berikut dalam file log:

Log message size exceeded. Increase the max message size setting

Jika Anda mengalami masalah ini di Edge untuk Private Cloud 4.15.07 dan yang lebih lama, temukan file message-logging.properties dan gunakan solusi ini:

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

Untuk Edge untuk Private Cloud 4.16.01 dan yang lebih baru, tetapkan properti conf_message-logging_max.log.message.size.in.kb dalam file /opt/apigee/customer/application/message-processor.properties dan mulai ulang Message Processor.

Catatan: Variabel pesan respons di Edge tidak tersedia dari Alur Error. Variabel ini juga tidak tersedia di PostClientFlow jika alur sebelumnya adalah Alur Error. Jika Anda ingin mencatat informasi respons dari PostClientFlow, gunakan objek message. Anda dapat menggunakan objek ini untuk mendapatkan header dan informasi lainnya dari respons, terlepas dari apakah ada error atau tidak. Lihat Variabel pesan untuk informasi selengkapnya dan contoh.

Mengontrol stempel waktu pesan log di Edge untuk Private Cloud

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

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

Default seluruh sistem ini dapat diganti untuk tujuan syslog menggunakan elemen DateFormat. Perilaku template ini dijelaskan dalam dokumentasi untuk class SimpleDateFormat Java. Berdasarkan 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 dari formulir ini:

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

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

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

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

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

Untuk mengubah format:

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

Mencatat lokasi file di Edge untuk Private Cloud

Edge untuk Private Cloud 4.16.01 dan yang lebih baru

Secara default, log pesan Private Cloud terletak di direktori berikut pada node Message Processor:

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

Anda dapat mengubah lokasi log default dengan memodifikasi properti di file message-logging.properties pada Message Processor:

  • 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 menetapkannya 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 menetapkannya ke jalur absolut, seperti conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, log pesan akan disimpan di /opt/apigee/var/log/messages/messagelog/. Jalur absolut lebih diutamakan daripada bin_setenv_data_dir.

    Perhatikan bahwa Anda harus mereferensikan properti sebagai conf/message-logging.properties+log.root.dir karena diberi komentar secara default. Lihat Menetapkan token yang saat ini dikomentari untuk informasi selengkapnya.

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

Untuk menetapkan properti ini:

  1. Buka file message-processor.properties di editor. Jika file tersebut tidak ada, buat file:
    > 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 pengguna 'apigee':
    > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  5. Mulai ulang komponen Edge:
    > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor mulai ulang

Edge untuk Private Cloud 4.15.07 dan versi yang lebih lama

Secara default, log pesan berada di lokasi berikut pada pemroses pesan:

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

Anda dapat mengubah lokasi log default dengan mengubah properti berikut di file message-logging.properties pada pemroses pesan:

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

Misalnya, kombinasi kedua properti tersebut akan menetapkan direktori logging di /opt/apigee4/var/log/custom/folder/messagelog/ (perlu diperhatikan 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 /opt/apigee4/var/log/messages/messagelog/. Jalur absolut di log.root.dir lebih diprioritaskan daripada data.dir.

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

Nilai default untuk variabel dalam template pesan

Nilai default dapat ditentukan untuk setiap variabel dalam 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 pada elemen Message:

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

Mengonfigurasi layanan pengelolaan log pihak ketiga

Kebijakan MessageLogging memungkinkan Anda mengirim pesan syslog ke layanan pengelolaan log pihak ketiga, seperti Splunk, Sumo Logic, dan Loggly. Jika Anda ingin mengirim syslog ke salah satu layanan tersebut, lihat dokumentasi layanan tersebut untuk mengonfigurasi host, port, dan protokol layanan, lalu tetapkan elemen Syslog pada kebijakan ini.

Lihat dokumentasi berikut untuk konfigurasi pengelolaan log pihak ketiga:

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

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

Error 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 jika tidak valid. Nomor port harus berupa 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 Lokasi Contoh
fault.name="fault_name" fault_name adalah nama fault, seperti yang tercantum pada tabel Error runtime di atas. Nama fault adalah bagian terakhir dari kode fault. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name adalah nama kebijakan yang ditentukan oleh pengguna yang melemparkan 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 diisi jika terjadi kegagalan kebijakan.

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

Topik terkait