Antipola: Memanggil kebijakan MessageLogging beberapa kali dalam 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 dalam log ke Cloud logging atau endpoint syslog. Semua informasi penting terkait permintaan API seperti parameter input, payload permintaan, kode respons, pesan error (jika ada), dan sebagainya, dapat dicatat dalam log untuk referensi berikutnya atau untuk proses debug. Meskipun kebijakan ini menggunakan proses latar belakang untuk melakukan logging, ada beberapa syarat ketika menggunakan kebijakan tersebut.

Antipola

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

Mari kita jelaskan hal ini 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 dalam PraAlur ProxyEndpoint. Kebijakan LogRequestInfo dijalankan di latar belakang segera setelah proxy API menerima permintaan, dan kebijakan LogResponseInfo dieksekusi setelah proxy menerima respons dari server target, tetapi sebelum proxy menampilkan respons ke klien API. Tindakan ini akan menghabiskan resource sistem tambahan karena dua koneksi TLS berpotensi dibuat.

Selain itu, ada kebijakan MessageLogging bernama "LogErrorInfo" yang dieksekusi hanya 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

Pada contoh konfigurasi kebijakan berikut, data dicatat ke dalam log 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 menempati memori sistem dan siklus CPU tambahan, yang menyebabkan masalah performa dalam skala besar. Efek negatif serupa terjadi jika menggunakan MessageLogging untuk mencatat log 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 hal ini akan menyebabkan tekanan balik pada prosesor pesan, yang mengakibatkan pemrosesan permintaan yang lambat dan berpotensi mengalami error 504 Gateway Timeout atau latensi tinggi.

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

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

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

    Dalam kedua kasus tersebut, kebijakan LogErrorInfo akan dieksekusi dan hanya mencatat informasi terkait 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; tindakan ini akan membuatnya tersedia untuk kebijakan MessageLogging yang dijalankan nanti.
  • Gunakan satu kebijakan MessageLogging untuk mencatat semua data yang diperlukan di PostClientFlow, yang dieksekusi 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 untuk dipisahkan dari fungsi API sebenarnya, termasuk penanganan error. Oleh karena itu, memanggilnya di PostClientFlow, yang berada di luar pemrosesan permintaan/respons, berarti API akan selalu mencatat data ke dalam log, terlepas dari apakah API berhasil atau tidak.

Berikut adalah contoh yang memanggil 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, penting untuk menetapkan variabel woeid dan weather.response* secara eksplisit menggunakan kebijakan ExtractVariables atau JavaScript.

Bacaan lebih lanjut