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 ke dalam log. Anda dapat memasang dan mengonfigurasi kebijakan MessageLogging di API untuk mencatat pesan kustom ke dalam log ke disk lokal (khusus Edge untuk Private Cloud) atau ke syslog.
Contoh
{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>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat> </Syslog> <logLevel>ALERT</logLevel> </MessageLogging>
Jenis kebijakan MessageLogging yang umum digunakan adalah saat login ke akun syslog. Jika dikonfigurasi untuk syslog, proxy API akan meneruskan pesan log dari Apigee Edge ke server syslog jarak jauh. Anda harus sudah memiliki 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.
Misalnya, bayangkan Anda perlu mencatat informasi tentang setiap pesan permintaan yang diterima API 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.
Jika memiliki Edge untuk deployment Private Cloud, Anda juga dapat menulis pesan log ke file.
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> <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat> </Syslog> <logLevel>WARN</logLevel> </MessageLogging>
Anda dapat mengirim pesan ke penyedia logging pesan pihak ketiga melalui TLS/SSL dengan menambahkan
blok <SSLInfo>
.
Rotasi file: ukuran
<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>
Rotasi file berdasarkan ukuran file.
Rotasi file: waktu
<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>
Rotasi file berdasarkan waktu.
Rotasi file: waktu & ukuran
<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>
Rotasi file berdasarkan waktu dan ukuran.
Mendukung streaming
<MessageLogging name="LogPolicy"> <File> .... .... </File> <BufferMessage>true</BufferMessage> </MessageLogging>
Logging pesan yang mendukung streaming
Referensi elemen
Gunakan elemen berikut untuk mengonfigurasi jenis kebijakan MessageLogging.
Nama Kolom | Deskripsi Kolom | |
---|---|---|
Tujuan file lokal. (Logging file hanya didukung di Edge untuk deployment Private Cloud.) Untuk mengetahui informasi tentang tempat file disimpan, lihat Lokasi file log di Edge untuk Private Cloud. |
Message |
Bangun pesan yang akan dikirim ke file log, yang menggabungkan teks dengan variabel untuk mengambil informasi yang Anda inginkan. Lihat Contoh. |
FileName |
Nama file log tempat pesan dicatat. | |
FileRotationOptions |
||
rotateFileOnStartup |
Atribut. Nilai yang valid: Jika disetel ke benar (true), file log akan dirotasi setiap kali mesin pesan dimulai ulang. |
|
FileRotationType |
Menentukan kebijakan rotasi (size atau
time ) dari file log. |
|
MaxFileSizeInMB |
(Saat memilih size sebagai jenis rotasi)
Menetapkan ukuran file log yang memicu server untuk memindahkan pesan log ke file
terpisah. Setelah file log mencapai ukuran yang ditentukan, server akan mengganti nama
file log saat ini. |
|
RotationFrequency |
(Saat memilih time sebagai jenis rotasi)
Menetapkan waktu dalam menit yang memicu server untuk memindahkan pesan log ke file
terpisah. Setelah interval yang ditentukan berlalu, file log saat ini diganti namanya. |
|
MaxFilesToRetain |
Menentukan jumlah maksimum file yang akan dipertahankan dalam konteks setelan rotasi. Nilai defaultnya adalah 8. Jika Anda menentukan nol (0), file log akan dipertahankan tanpa batas waktu, tetapi bergantung pada setelan rotasi file, meskipun tidak ada file yang akan dihapus atau diganti namanya. Oleh karena itu, untuk menghindari error penuh disk di masa mendatang, tetapkan nilai ini ke nilai yang lebih besar dari nol, atau terapkan sistem otomatis yang otomatis untuk menghapus atau mengarsipkan file log lama yang masih tersimpan. |
|
BufferMessage |
Jika streaming HTTP diaktifkan untuk proxy Anda, pesan permintaan/respons tidak akan di-buffer. Jika Anda ingin mencatat konten ke dalam log yang mengharuskan pesan alur diurai, tetapkan BufferMessage ke true. Lihat tab contoh "Streaming diaktifkan" sebagai contoh. Default: false |
|
Tujuan {i>syslog<i}. Untuk mengirim syslog ke Splunk, Sumo Logic, atau Loggly, lihat Mengonfigurasi layanan pengelolaan log pihak ketiga. |
Message |
Bangun pesan yang akan dikirim ke syslog, yang menggabungkan teks dengan variabel untuk menangkap informasi yang Anda inginkan. Lihat Contoh. Catatan: Variabel respons tidak akan tersedia di PostClientFlow setelah Alur Error. Gunakan variabel pesan untuk mencatat informasi respons terhadap situasi error dan keberhasilan. Lihat juga Catatan penggunaan. |
Host |
Nama host atau alamat IP server tempat syslog harus dikirim. Jika Anda tidak menyertakan elemen ini, defaultnya adalah localhost. | |
Port |
Porta tempat {i>syslog<i} berjalan. Jika Anda tidak menyertakan elemen ini, defaultnya adalah 514. | |
Protocol |
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 |
Opsional, tetapi Dengan elemen ini, Anda dapat mengontrol format konten buatan Apigee yang ditambahkan di awal pesan. Jika disetel ke benar (true), pesan syslog akan diawali dengan jumlah karakter yang tetap, sehingga Anda dapat 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 |
Elemen ini menyetel 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 |
Opsional. String template pemformatan yang akan digunakan untuk memformat stempel waktu untuk setiap pesan log.
Secara default, Apigee menggunakan |
|
SSLInfo |
Memungkinkan Anda mencatat pesan ke dalam log 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 |
Opsional. Nilai yang valid: Menetapkan tingkat informasi tertentu untuk disertakan dalam log pesan. Jika Anda menggunakan elemen |
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 detail tentang penggunaan PostClientFlow, lihat Referensi konfigurasi proxy API.
PostClientFlow bersifat istimewa karena dua hal:
- Pengujian ini hanya dijalankan sebagai bagian dari alur respons.
- Ini adalah satu-satunya alur yang dieksekusi setelah proxy memasuki status error.
Karena dieksekusi terlepas dari apakah proxy berhasil atau gagal, Anda dapat menempatkan kebijakan MessageLogging di PostClientFlow dan dijamin bahwa kebijakan tersebut selalu dijalankan.
Gambar Trace berikut menunjukkan kebijakan MessageLogging yang dijalankan sebagai bagian dari PostClientFlow, setelah DefaultFaultRule dijalankan:
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>
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 asal permintaan dikirim, dan sebagainya. Pesan log Edge secara asinkron, artinya tidak ada latensi yang mungkin disebabkan oleh pemblokiran pemanggilan yang diperkenalkan ke API Anda.
Kebijakan MessageLogging menulis pesan yang dicatat dalam memori ke buffer. Message logger membaca pesan dari buffer, lalu menulis ke tujuan yang dikonfigurasi. Setiap tujuan memiliki buffering-nya sendiri.
Jika kecepatan tulis ke buffer meningkat melebihi kecepatan baca, buffer overflow dan logging akan gagal. Jika hal ini terjadi, Anda mungkin menemukan pesan yang berisi hal berikut dalam 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 versi yang lebih lama, cari
file message-logging.properties
dan gunakan solusi ini:
Tingkatkan properti max.log.message.size.in.kb
(nilai default = 128 KB) dalam
file message-logging.properties
.
Untuk Edge untuk Private Cloud 4.16.01 dan yang lebih baru, tetapkan properti conf_message-logging_max.log.message.size.in.kb
di file /opt/apigee/customer/application/message-processor.properties dan mulai ulang Message Processor.
Catatan: Variabel pesan respons di Edge tidak tersedia dari Alur Error. 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, terlepas dari apakah terjadi error atau tidak. Lihat Variabel pesan untuk mengetahui informasi selengkapnya dan contohnya.
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
Nilai default 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 angka bulan 2 digit, dan seterusnya.
Format di atas mungkin menghasilkan string dengan 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 tahun 2 digit, mencatat stempel waktu dalam bentuk:
22/09/28T22:38:11.721+0000
Untuk mengubah format:
- Buka file message-processor.properties di editor. Jika file tersebut tidak ada, buat file tersebut:
> vi /opt/apigee/customer/application/message-processor.properties - Setel properti sesuai keinginan:
conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ - Simpan perubahan.
- Pastikan file properti dimiliki oleh pengguna 'apigee':
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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 di file message-logging.properties pada Message Processors:
- 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 menetapkannya 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 menetapkannya ke jalur absolut, seperticonf/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 diutamakan daripadabin_setenv_data_dir
.
Perhatikan bahwa Anda harus mereferensikan properti sebagai conf/message-logging.properties+log.root.dir karena properti ini diberi komentar secara default. Lihat Menyetel token yang saat ini dijadikan komentar untuk mengetahui informasi selengkapnya.
Jika Anda ingin menyimpan file log dalam struktur file datar sehingga semua file log dimasukkan ke dalam direktori yang sama, tetapkan conf/message-logging.properties+enable.flat.directory.structure ke true pada 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 menetapkan properti ini:
- Buka file message-processor.properties di editor. Jika file tersebut tidak ada, buat file tersebut:
> vi /opt/apigee/customer/application/message-processor.properties - Tetapkan properti sesuai keinginan:
conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages - Simpan perubahan.
- Pastikan file properti dimiliki oleh pengguna 'apigee':
> chown apigee:apigee /opt/apigee/customer/application/message-processor.properties - 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 pada file message-logging.properties pada pemroses pesan:
- data.dir - Menetapkan jalur root untuk penyimpanan file log. Misalnya, data.dir=/opt/apigee4/var/log
- log.root.dir - Jika Anda menetapkannya ke jalur relatif, seperti log.root.dir=custom/folder/, jalur tersebut akan ditambahkan ke lokasi data.dir.
Misalnya, kombinasi dari kedua properti tersebut akan menetapkan direktori logging di /opt/apigee4/var/log/custom/folder/messagelog/ (perhatikan bahwa /messagelog ditambahkan secara otomatis).
Jika Anda menetapkannya 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 dimasukkan dalam direktori yang sama, tetapkan propertienable.flat.directory.structure ke true pada file message-logging.properties di Message Processors. Pesan disimpan di direktori yang ditentukan oleh properti di atas, dan nama filenya memiliki bentuk {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.
Nilai default untuk variabel dalam template pesan
Nilai default dapat ditentukan untuk setiap variabel di 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 sebagaimana mestinya.
Lihat dokumentasi berikut untuk konfigurasi pengelolaan log pihak ketiga:
- Splunk (pilih versi produk)
Lihat juga postingan Komunitas Apigee ini: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html -
Logika
Sumo
- Lihat juga postingan Komunitas Apigee ini: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
- Untuk contoh lengkap penggunaan Sumo Logic sebagai layanan logging, lihat postingan Komunitas Apigee berikut. Solusi ini menggunakan satu kebijakan JavaScript untuk membuat permintaan POST HTTP ke Sumo Logic HTTP Source Collector: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
- 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 ke Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge 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. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Penyebab | Perbaiki |
---|---|---|
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 diisi saat kebijakan gagal.
messagelogging.failed
messagelogging.{stepdefinition-name}.failed
Topik terkait
- Variabel yang diekspos oleh Edge: Referensi variabel