Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Kebijakan MessageLogging dapat digunakan untuk mencatat pesan kustom ke dalam log ke Cloud Logging atau syslog. Anda dapat menggunakan informasi dalam log untuk berbagai tugas, seperti melacak masalah di lingkungan runtime API.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Ada dua cara untuk menggunakan kebijakan MessageLogging:
- Elemen
<CloudLogging>
mencatat pesan ke Cloud Logging. Untuk menggunakan metode ini, Anda harus mengaktifkan Cloud Logging API untuk project Google Cloud Anda. Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan API untuk project Google Cloud, lihat Mengaktifkan dan Menonaktifkan Layanan. - Elemen
<Syslog>
mencatat pesan ke syslog, protokol standar untuk mengirim log sistem atau pesan peristiwa ke server tertentu. Untuk menggunakan metode ini, Anda harus menyediakan server {i>syslog<i}. Jika tidak, Anda dapat menggunakan layanan pengelolaan log publik, seperti Splunk, Sumo Logic, dan Loggly. Lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.
Catatan: Anda tidak dapat menggunakan elemen <CloudLogging>
dan elemen
<Syslog>
dalam kebijakan yang sama.
Elemen <MessageLogging>
Menentukan kebijakan <MessageLogging>
.
Nilai default | Lihat tab Kebijakan Default di bawah |
Wajib? | Diperlukan |
Jenis | JENIS |
Elemen Induk | t/a |
Elemen Turunan | <CloudLogging> <Syslog> <logLevel> |
Elemen <MessageLogging>
menggunakan sintaksis berikut:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1"> <DisplayName>Message Logging-1</DisplayName> <Syslog> <!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. --> <Message>Some message for syslog</Message> <Host>localhost</Host> <Port>514</Port> </Syslog> <CloudLogging> <!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. --> <LogName>projects/{organization.name}/logs/{log.id}</LogName> <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message> <Labels> <Label> <Key>key1</Key> <Value>value1</Value> </Label> <Label> <Key>key2</Key> <Value>value2</Value> </Label> </Labels> <ResourceType>gce_instance</ResourceType> </CloudLogging> <logLevel>ALERT</logLevel> </MessageLogging>
Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
continueOnError |
false | Opsional | Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
|
enabled |
true | Opsional | Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur. |
async |
false | Tidak digunakan lagi | Atribut ini sudah tidak digunakan lagi. |
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <MessageLogging>
:
Nama Kolom | Deskripsi Kolom |
---|---|
CloudLogging |
Konfigurasi pesan untuk dicatat ke logging Cloud. |
Syslog |
Konfigurasi pesan untuk dicatat ke |
Sampel
CloudLogging
<MessageLogging name="LogToCloudLogging"> <CloudLogging> <LogName>projects/{organization.name}/logs/{log.id}</LogName> <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message> <Labels> <Label> <Key>key1</Key> <Value>value1</Value> </Label> <Label> <Key>key2</Key> <Value>value2</Value> </Label> </Labels> <ResourceType>gce_instance</ResourceType> </CloudLogging> </MessageLogging>
Contoh ini mengilustrasikan penggunaan
template pesan. Karena elemen Message
berisi variabel flow
{"{message.queryparam.key}": "{message.queryparam.value}"}
saat seseorang memanggil proxy dengan nilai
message.queryparam.key = "fruit"
dan
message.queryparam.value = "apple"
, entri log yang dihasilkan akan menjadi
{"fruit": "apple"}
.
{i>Syslog<i}
<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>yyMMdd-HH:mm:ss.SSS</DateFormat> </Syslog> <logLevel>ALERT</logLevel> </MessageLogging>
Dalam contoh ini, anggaplah Anda perlu mencatat informasi tentang setiap pesan permintaan yang diterima API Anda dari aplikasi konsumen ke dalam log. 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, bersama dengan nilai untuk parameter kueri pada pesan permintaan. Format stempel waktu akan mirip dengan 230704-13:42:17.376
, sesuai dengan format yang ditentukan dalam elemen DateFormat
.
Syslog 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> </Syslog> <logLevel>WARN</logLevel> </MessageLogging>
Anda dapat mengirim pesan ke penyedia logging pesan pihak ketiga melalui TLS/SSL dengan menambahkan
blok <SSLInfo>
.
Referensi elemen turunan
Bagian berikut menjelaskan elemen turunan <MessageLogging>.
<CloudLogging>
Gunakan elemen <CloudLogging>
untuk mencatat pesan ke dalam log ke Cloud Logging.
Nama Kolom | Wajib? | Deskripsi |
---|---|---|
LogName |
Ya | Nama log. Nama log harus dalam format
projects/{PROJECT_ID}/logs/{LOG_ID} .
Anda dapat menggunakan variabel sebagai pengganti {PROJECT_ID} dan {LOG_ID} . |
Message |
Ya |
Pesan yang akan dicatat. Pesan memiliki atribut |
Label |
Tidak | Label yang akan dilampirkan ke pesan log, jika ada.
Properti ini akan berupa pasangan nilai kunci seperti berikut:
<Label> <Key>key1</Key> <Value>value1</Value> </Label> |
ResourceType |
Tidak (setelan defaultnya adalah global) | Mewakili resource yang dipantau yang menghasilkan log. |
Authentication untuk Cloud Logging
Untuk menggunakan elemen <CloudLogging>
, Anda harus men-deploy proxy API untuk menggunakan autentikasi Google. Apigee akan menggunakan kredensial yang sesuai dengan identitas akun layanan yang Anda tentukan dalam permintaan keluar ke Cloud Logging. Untuk mengetahui detail selengkapnya, lihat Menggunakan Autentikasi Google.
Akun layanan yang Anda lampirkan ke proxy API pada waktu deployment harus memiliki peran dengan izin logging.logEntries.create
. Guna mengetahui informasi selengkapnya tentang peran Identity and Access Management (IAM) untuk
<CloudLogging>
,
lihat Panduan kontrol akses.
<Syslog>
Gunakan elemen <Syslog>
untuk mengonfigurasi pesan yang akan dicatat ke dalam log ke syslog
.
Saat Anda menggunakan <Syslog>
, proxy API akan meneruskan pesan log dari Apigee ke server syslog jarak jauh. Untuk menggunakan metode ini, Anda harus menyediakan server {i>syslog<i}. Jika tidak, layanan pengelolaan log publik, seperti Splunk, Sumo Logic, dan Loggly, akan tersedia. Lihat Mengonfigurasi layanan pengelolaan log pihak ketiga.
Nama Kolom | Wajib? | Deskripsi Kolom |
---|---|---|
Message |
Ya |
Pesan yang akan dicatat. Pesan memiliki atribut |
Host |
Tidak | Nama host atau alamat IP server tujuan pengiriman syslog. Jika Anda tidak menyertakan elemen ini, defaultnya adalah localhost. |
Port |
Tidak | Porta tempat {i>syslog<i} berjalan. Jika Anda tidak menyertakan elemen ini, defaultnya adalah 514. |
Protocol |
Tidak | TCP atau UDP (default). Meskipun UDP memiliki performa yang lebih baik, protokol TCP menjamin pengiriman log pesan ke server syslog. Untuk mengirim pesan syslog melalui TLS/SSL, hanya TCP yang didukung. |
FormatMessage |
Tidak, tetapi <FormatMessage>true</FormatMessage> diperlukan
untuk digunakan dengan Loggly. |
Elemen ini memungkinkan Anda mengontrol format konten buatan Apigee yang ditambahkan di awal pesan. Jika disetel ke benar (true), pesan syslog akan ditambahkan dengan jumlah karakter tetap, yang memungkinkan Anda memfilter informasi tersebut dari pesan. Berikut ini contoh untuk format tetap:
Informasi yang dihasilkan Apigee mencakup:
Jika ditetapkan ke false (salah) (default), pesan tidak akan diawali dengan karakter tetap tersebut. |
PayloadOnly |
Tidak |
Elemen ini menetapkan format pesan yang dihasilkan Apigee agar hanya memuat isi pesan syslog, tanpa karakter tambahan yang ditentukan oleh FormatMessage. Jika Anda tidak menyertakan elemen ini atau membiarkannya kosong, nilai defaultnya adalah Lihat FormatMessage. |
DateFormat |
Tidak |
String template pemformatan yang akan digunakan untuk memformat stempel waktu untuk setiap pesan log.
Secara default, Apigee menggunakan |
SSLInfo |
Tidak |
Memungkinkan Anda mencatat pesan melalui SSL/TLS. Gunakan dengan
sub-elemen Jika Anda tidak menyertakan elemen ini atau membiarkannya kosong, nilai defaultnya adalah false (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>
Nilai yang valid untuk elemen <logLevel>
adalah: INFO
(default), ALERT
, WARN
, ERROR
.
Menetapkan tingkat informasi tertentu yang akan disertakan dalam log pesan.
Jika Anda menggunakan elemen FormatMessage (menyetelnya ke true), setelan
<logLevel>
akan memengaruhi skor prioritas yang dihitung
(angka di dalam tanda kurung siku) dalam informasi yang dihasilkan Apigee yang ditambahkan
ke pesan.
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 dicatat. Untuk mengetahui detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.
PostClientFlow bersifat spesial karena dua hal:
- Respons hanya dijalankan sebagai bagian dari alur respons.
- 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 tersebut selalu dijalankan.
Image Debug berikut menampilkan kebijakan MessageLogging yang dijalankan sebagai bagian dari PostClientFlow, setelah DefaultFaultRule dieksekusi:
Dalam contoh ini, kebijakan Verify API Key menyebabkan kesalahan karena kunci yang tidak valid.
Di bawah ini adalah definisi ProxyEndpoint yang menyertakan PostClientFlow:
<ProxyEndpoint name="default"> ... <PostClientFlow> <Response> <Step> <Name>Message-Logging-1</Name> </Step> </Response> </PostClientFlow> ... </ProxyEndpoint>
Apigee 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 asal permintaan dikirim, dan sebagainya.
Apigee mencatat pesan secara asinkron: respons ditampilkan saat log masih ditulis. Akibatnya, tidak ada latensi yang diperkenalkan ke API Anda dengan memblokir pemanggilan. Mungkin ada situasi ketika log tidak ditulis tanpa menampilkan error, tetapi peristiwa ini jarang terjadi.
Kebijakan MessageLogging menulis pesan yang dicatat dalam memori ke buffer. Logger pesan membaca pesan dari buffer, lalu menulis ke tujuan yang Anda konfigurasi. Setiap tujuan memiliki buffer-nya sendiri.
Jika kecepatan operasi tulis ke buffer meningkat melebihi kecepatan baca, buffer overflow dan logging akan gagal. Jika hal ini terjadi, Anda mungkin akan menemukan salah satu pesan berikut dalam file log:
- Menggunakan
<CloudLoggingg>
:steps.messagelogging.TooManyPendingLoggingRequest
- Menggunakan
<Syslog>
:Log message size exceeded. Increase the max message size setting
Tingkatkan properti max.log.message.size.in.kb
(nilai default = 128 KB) dalam
file message-logging.properties
.
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 setel elemen Syslog pada kebijakan ini dengan semestinya.
Lihat dokumentasi berikut untuk konfigurasi pengelolaan log pihak ketiga:
- Splunk (pilih versi produk)
Lihat juga postingan Komunitas Apigee ini: Log messages into Splunk -
Logika
Summo
- Lihat juga postingan Komunitas Apigee ini: Menyiapkan Logging dengan Sumo Logic
- Untuk contoh lengkap penggunaan Sumo Logic sebagai layanan logging, lihat Postingan Komunitas Apigee berikut. Solusi ini menggunakan kebijakan JavaScript tunggal untuk membuat permintaan POST HTTP ke Sumo Logic HTTP Source Collector: Logging ke Sumo Logic menggunakan JavaScript dan HTTP
- Loggly
Saat menggunakan Loggly,<FormatMessage>true</FormatMessage>
diperlukan dalam kebijakan sebagai turunan dari elemen<Syslog>
.
Lihat juga postingan Komunitas Apigee ini untuk mengetahui informasi selengkapnya tentang logging pesan untuk Login: Login ke Login
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Penyebab |
---|---|---|
steps.messagelogging.StepDefinitionExecutionFailed |
500 |
Lihat string kesalahan. |
steps.messagelogging.InvalidGoogleCloudLogName |
500 |
Error ini ditampilkan jika LogName tidak dievaluasi ke format projects/{project}/logs/{logid} yang valid. |
steps.messagelogging.InvalidJsonMessage |
500 |
Error ini ditampilkan jika nilai atribut contentType telah dipilih sebagai application/json , tetapi nilai pesan yang sebenarnya bukanlah string JSON yang valid. |
steps.messagelogging.TooManyPendingLoggingRequest |
500 |
Error ini ditampilkan jika ada lebih dari 2.500 permintaan tertunda yang belum ditulis ke Cloud Logging. Batas 2.500 ditujukan untuk setiap pod runtime Apigee. Misalnya, jika traffic didistribusikan ke dua instance pod runtime Apigee, batas efektifnya adalah 5.000 permintaan. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaikan |
---|---|---|
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. |
build |
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. |
build |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "StepDefinitionExecutionFailed" |
messagelogging.policy_name.failed |
policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan 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 alur
Variabel berikut akan diisi jika kebijakan tidak berfungsi.
messagelogging.failed
messagelogging.{stepdefinition-name}.failed
Topik terkait
- Variabel yang diekspos oleh Apigee: Referensi variabel flow