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 kustom ke disk lokal (khusus Edge untuk Private Cloud) atau ke syslog.

Contoh

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

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

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

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

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

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

Referensi elemen

Gunakan elemen berikut untuk mengonfigurasi jenis kebijakan MessageLogging.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

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

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 mengetahui detail tentang cara menggunakan PostClientFlow, lihat Referensi konfigurasi proxy API.

PostClientFlow bersifat khusus dalam dua hal:

1. Fungsi 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 akan selalu dijalankan.

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

Dalam contoh ini, kebijakan Verifikasi Kunci API menyebabkan kesalahan karena kunci tidak valid.

Di bawah ini 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 dari tempat permintaan dikirim, dan sebagainya. Pesan log Edge secara asinkron, yang berarti tidak ada latensi yang mungkin disebabkan oleh pemblokiran panggilan yang diperkenalkan 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. Setiap tujuan memiliki buffer sendiri.

Pengguna mungkin mengalami penundaan dalam menerima pesan log yang dikirim ke endpoint syslog baru. Hal ini disebabkan oleh perilaku "cold start" yang dimaksudkan dalam kebijakan. Saat tujuan logging baru dikonfigurasi, selain tujuan logging yang ada, Pemroses Pesan (MP) dapat mengantrekan 1.000 pesan log dalam memori terlebih dahulu sebelum mengirimkannya. Hal ini dapat menyebabkan penundaan awal di lingkungan dengan traffic rendah. Penundaan awal ini tidak dapat diamati untuk workload produksi biasa, karena pesan akan terakumulasi dengan cepat. Setelah nilai minimum terpenuhi, pesan log akan dikirim sesuai harapan. Melakukan mulai ulang secara halus pada Pemroses Pesan juga dapat memicu pengiriman pesan yang diantrekan saat pesan tersebut dikeluarkan dari antrean.

Jika kecepatan penulisan ke buffer meningkat melebihi kecepatan pembacaan, buffer akan meluap dan logging akan gagal. Jika hal ini terjadi, Anda mungkin menemukan pesan yang berisi hal berikut di 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.properties+max. log.message.size.in.kb dalam file /opt/apigee/customer/application/message-processor.properties dan mulai ulang Message Processor. Perhatikan bahwa properti ini awalnya dikomentari secara default.

Catatan: Variabel response message variables di Edge tidak tersedia dari Error Flow. 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 lain dari respons, baik ada kesalahan maupun tidak. Lihat Variabel pesan untuk mengetahui informasi dan contoh selengkapnya.

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 di seluruh sistem ini dapat diganti untuk tujuan syslog menggunakan elemen DateFormat. Perilaku template ini dijelaskan dalam dokumentasi untuk class SimpleDateFormat Java. Menurut definisi tersebut, yyyy akan diganti dengan tahun 4 digit, MM akan diganti dengan nomor bulan 2 digit, dan seterusnya. Format di atas dapat menghasilkan string dalam bentuk ini:

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

Anda dapat menggunakan properti conf_system_apigee.syslogger.dateFormat di 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 memperpendek menjadi tahun 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 tidak ada, buat file:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Tetapkan properti sesuai keinginan:
   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 Edge Message Processor:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Lokasi file log 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 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 mengubah properti dalam file 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 menyetel 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 menyetel ini 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 diprioritaskan daripada bin_setenv_data_dir.
  
  Perhatikan bahwa Anda harus mereferensikan properti sebagai conf/message-logging.properties+log.root.dir karena properti tersebut dikomentari secara default. Lihat Menetapkan token yang saat ini dikomentari untuk mengetahui informasi selengkapnya.

Jika Anda ingin menyimpan file log dalam struktur file 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 menyetel properti ini:

1. Buka file message-processor.properties di editor. Jika file 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 restart

Edge untuk Private Cloud 4.15.07 dan 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 dalam file message-logging.properties di pemroses pesan:

• data.dir - Menetapkan jalur 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 akan ditambahkan ke lokasi data.dir.

Misalnya, kombinasi kedua properti akan menetapkan direktori logging di /opt/apigee4/var/log/custom/folder/messagelog/ (perhatikan bahwa /messagelog ditambahkan secara otomatis).

Jika Anda menyetelnya 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 datar sehingga semua file log ditempatkan dalam direktori yang sama, tetapkan properti enable.flat.directory.structure ke benar (true) dalam file message-logging.properties di Pemroses Pesan. Pesan disimpan di direktori yang ditentukan oleh properti di atas, dan nama file menggunakan format {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 diselesaikan 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 untuk mengonfigurasi host, port, dan protokol layanan, lalu tetapkan elemen Syslog pada kebijakan ini dengan tepat.

Lihat dokumentasi berikut untuk konfigurasi pengelolaan log pihak ketiga:

• Splunk (pilih versi produk)
  Lihat juga postingan Komunitas Apigee ini: Log messages into Splunk
• Sumo Logic
  • Lihat juga postingan Komunitas Apigee ini: Setting up logging with Sumo Logic, which host should I use?
  • Untuk contoh lengkap yang menggunakan Sumo Logic sebagai layanan logging, lihat postingan Komunitas Apigee berikut. Solusi ini menggunakan satu kebijakan JavaScript untuk membuat permintaan HTTP POST ke Sumo Logic HTTP Source Collector: Logging to Sumo Logic using JavaScript and HTTP
• Loggly
  Saat menggunakan Loggly, <FormatMessage>true</FormatMessage> diperlukan dalam kebijakan sebagai turunan elemen <Syslog>.
  Lihat juga postingan Komunitas Apigee ini untuk mengetahui informasi selengkapnya tentang logging pesan ke Loggly: Log pesan ke Loggly

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.

Error saat deployment

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

Variabel kesalahan

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

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 alur

Variabel berikut diisi saat kebijakan gagal.

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

Topik terkait

• Variabel yang diekspos oleh Edge: Referensi variabel