Antipola: Memanggil kebijakan MessageLogging beberapa kali di proxy API

Anda sedang melihat dokumentasi Apigee dan Apigee Hybrid.
Lihat dokumentasi Apigee Edge.

Kebijakan MessageLogging Apigee memungkinkan developer Proxy API mencatat pesan kustom ke Cloud Logging atau endpoint syslog. Setiap informasi penting yang terkait dengan permintaan API, seperti parameter input, payload permintaan, kode respons, pesan error (jika ada), dan sebagainya, dapat dicatat untuk referensi atau proses debug di kemudian hari. Meskipun kebijakan menggunakan proses latar belakang untuk melakukan logging, ada peringatan saat menggunakan kebijakan ini.

Antipola

Kebijakan MessageLogging menyediakan cara yang efisien untuk mendapatkan informasi selengkapnya tentang permintaan API dan men-debug masalah apa pun yang terjadi pada permintaan API. Namun, menggunakan kebijakan MessageLogging yang sama lebih dari sekali atau memiliki beberapa kebijakan MessageLogging yang mencatat data dalam potongan di proxy API yang sama dalam alur selain PostClientFlow dapat menimbulkan implikasi yang merugikan. Hal ini karena Apigee membuka koneksi ke endpoint eksternal untuk kebijakan MessageLogging. Jika kebijakan menggunakan TLS melalui TCP, seperti pada endpoint syslog, ada overhead tambahan untuk membuat koneksi TLS.

Mari kita jelaskan hal ini dengan bantuan Proxy API contoh.

Proxy API

Dalam contoh berikut, kebijakan MessageLogging bernama "LogRequestInfo" ditempatkan di alur Permintaan, dan kebijakan MessageLogging lain bernama "LogResponseInfo" ditambahkan ke alur Respons. Keduanya ada di ProxyEndpoint PreFlow. Kebijakan LogRequestInfo dijalankan di latar belakang segera setelah proxy API menerima permintaan, dan kebijakan LogResponseInfo dijalankan setelah proxy menerima respons dari server target, tetapi sebelum proxy menampilkan respons ke klien API. Hal ini akan menggunakan resource sistem tambahan karena dua koneksi TLS berpotensi dibuat.

Selain itu, ada kebijakan MessageLogging bernama "LogErrorInfo" yang hanya dijalankan jika terjadi error selama eksekusi proxy API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  ...
<FaultRules>
    <FaultRule name="fault-logging">
        <Step>
            <Name>LogErrorInfo</Name>
        </Step>
    </FaultRule>
</FaultRules>
<PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LogRequestInfo</Name>
      </Step>
    </Request>
  </PreFlow>
  <PreFlow name="PreFlow">
    <Response>
      <Step>
        <Name>LogResponseInfo</Name>
      </Step>
    </Response>
  </PreFlow>
  ...
</ProxyEndpoint>

Kebijakan Message Logging

Dalam konfigurasi kebijakan contoh berikut, data dicatat ke server log pihak ketiga menggunakan TLS melalui TCP. Jika lebih dari satu kebijakan ini digunakan dalam proxy API yang sama, overhead untuk membuat dan mengelola koneksi TLS akan menggunakan siklus CPU dan memori sistem tambahan, sehingga menyebabkan masalah performa dalam skala besar. Efek negatif serupa terjadi jika menggunakan MessageLogging untuk mencatat ke endpoint Cloud Logging.

Kebijakan LogRequestInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogRequestInfo">
  <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>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

Kebijakan LogResponseInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogResponseInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

Kebijakan LogErrorInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogErrorInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>ERROR</logLevel>
</MessageLogging>

Dampak

  • Peningkatan overhead jaringan karena membuat koneksi ke endpoint log beberapa kali selama alur Proxy API.
  • Jika server syslog lambat atau tidak dapat menangani volume tinggi yang disebabkan oleh beberapa panggilan syslog, maka akan menyebabkan tekanan balik pada pemroses pesan, sehingga menghasilkan pemrosesan permintaan yang lambat dan berpotensi menyebabkan latensi tinggi atau error 504 Gateway Timeout.

  • Jika kebijakan MessageLogging ditempatkan di alur selain alur PostClient, ada kemungkinan informasi tidak dicatat, karena kebijakan MessageLogging tidak akan dieksekusi jika terjadi kegagalan sebelum eksekusi kebijakan ini.

    Dalam contoh ProxyEndpoint sebelumnya, informasi tidak akan dicatat dalam keadaan berikut:

    • Jika ada kebijakan yang ditempatkan sebelum kebijakan LogRequestInfo dalam alur permintaan yang gagal.
      atau
    • Jika server target gagal dengan error apa pun (HTTP 4XX, 5XX). Dalam situasi ini, saat respons berhasil tidak ditampilkan, kebijakan LogResponseInfo tidak akan dieksekusi.

    Dalam kedua kasus tersebut, kebijakan LogErrorInfo akan dijalankan dan hanya mencatat informasi yang terkait dengan error.

Praktik terbaik

  • Dalam alur proxy, gunakan satu atau beberapa instance kebijakan ExtractVariables atau kebijakan JavaScript untuk menetapkan semua variabel alur yang akan dicatat ke dalam variabel konteks; hal ini akan membuatnya tersedia untuk kebijakan MessageLogging yang dijalankan nanti.
  • Gunakan satu kebijakan MessageLogging untuk mencatat semua data yang diperlukan di PostClientFlow, yang dijalankan tanpa syarat.
  • Jika Anda menggunakan syslog, gunakan protokol UDP jika pengiriman pesan yang dijamin ke server syslog tidak diperlukan dan TLS/SSL tidak wajib.

Kebijakan MessageLogging dirancang agar tidak terikat dengan fungsi API sebenarnya, termasuk penanganan error. Oleh karena itu, memanggilnya di PostClientFlow, yang berada di luar pemrosesan permintaan/respons, berarti data akan selalu dicatat terlepas dari apakah API berhasil atau tidak.

Berikut adalah contoh pemanggilan Kebijakan MessageLogging di PostClientFlow:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 ...
<PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>LogInfo</Name>
            </Step>
        </Response>
</PostClientFlow>
 ...

Berikut contoh kebijakan MessageLogging, LogInfo, yang mencatat semua data:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

Karena variabel respons tidak tersedia di PostClientFlow setelah Alur Error, penting untuk menetapkan variabel woeid dan weather.response* secara eksplisit menggunakan kebijakan ExtractVariables atau JavaScript.

Bacaan lebih lanjut