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 ke dalam log untuk referensi di lain waktu atau untuk proses debug. Meskipun kebijakan menggunakan proses latar belakang untuk melakukan logging, ada pengecualian untuk menggunakan kebijakan ini.

Antipola

Kebijakan MessageLogging menyediakan cara yang efisien untuk mendapatkan informasi selengkapnya tentang permintaan API dan men-debug masalah apa pun yang ditemukan dengan 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 memiliki 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, akan ada overhead tambahan untuk membuat koneksi TLS.

Mari kita jelaskan dengan bantuan contoh Proxy API.

Proxy API

Pada contoh berikut, kebijakan MessageLogging bernama "LogRequestInfo" ditempatkan di alur Permintaan, dan kebijakan MessageLogging lain bernama "LogResponseInfo" ditambahkan ke alur Respons. Keduanya berada di PreFlow ProxyEndpoint. 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. Tindakan 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 Logging Pesan

Dalam contoh konfigurasi kebijakan berikut, data dicatat ke server log pihak ketiga menggunakan TLS melalui TCP. Jika lebih dari satu kebijakan ini digunakan di proxy API yang sama, overhead untuk membuat dan mengelola koneksi TLS akan menempati memori sistem dan siklus CPU tambahan, yang menyebabkan masalah performa dalam skala besar. Efek negatif serupa juga 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 API Proxy.
  • Jika server syslog lambat atau tidak dapat menangani volume tinggi yang disebabkan oleh beberapa panggilan syslog, hal ini akan menyebabkan tekanan balik pada pemroses pesan, sehingga menyebabkan pemrosesan permintaan lambat dan berpotensi menyebabkan latensi tinggi atau error 504 Gateway Timeout.

  • Jika kebijakan MessageLogging ditempatkan dalam alur selain alur PostClient, ada kemungkinan bahwa informasi tersebut tidak akan dicatat ke dalam log, karena kebijakan MessageLogging tidak akan dijalankan jika terjadi kegagalan sebelum kebijakan ini dijalankan.

    Dalam contoh ProxyEndpoint sebelumnya, informasi tidak akan dicatat ke dalam log dalam situasi berikut:

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

    Dalam kedua kasus tersebut, kebijakan LogErrorInfo akan dijalankan dan hanya mencatat informasi terkait error ke dalam log.

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; tindakan ini akan membuatnya tersedia untuk kebijakan MessageLogging yang dieksekusi 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 terjamin ke server syslog tidak diperlukan dan TLS/SSL tidak wajib.

Kebijakan MessageLogging dirancang untuk dipisahkan dari fungsi API yang sebenarnya, termasuk penanganan error. Oleh karena itu, memanggilnya di PostClientFlow, yang berada di luar pemrosesan permintaan/respons, berarti data akan selalu dicatat ke dalam log, 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 adalah contoh kebijakan MessageLogging, LogInfo, yang mencatat semua data ke dalam log:

<?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, sebaiknya tetapkan variabel woeid dan weather.response* secara eksplisit menggunakan ExtractVariables atau kebijakan JavaScript.

Bacaan lebih lanjut