Menulis dan melihat log

Halaman ini mendeskripsikan log yang tersedia untuk aplikasi App Engine, serta cara menulis, menghubungkan, dan melihat entri log.

App Engine mengumpulkan dua jenis log:

  • Log permintaan: Log permintaan yang dikirim ke aplikasi Anda. Secara default, App Engine otomatis memancarkan entri log untuk setiap permintaan HTTP yang diterima aplikasi.

  • Log aplikasi: Entri log yang dipancarkan oleh aplikasi App Engine berdasarkan entri log yang Anda tulis ke framework atau file yang didukung.

App Engine otomatis mengirim log permintaan dan log aplikasi ke agen Cloud Logging.

Menulis log aplikasi

App Engine otomatis memancarkan log untuk permintaan yang dikirim ke aplikasi Anda, sehingga Anda tidak perlu menulis log permintaan. Bagian ini membahas cara menulis log aplikasi.

Saat Anda menulis log aplikasi dari aplikasi App Engine, log akan otomatis diambil oleh Cloud Logging, selama log ditulis menggunakan metode berikut:

Berintegrasi dengan Cloud Logging

Anda dapat mengintegrasikan aplikasi App Engine dengan Cloud Logging. Pendekatan ini memungkinkan Anda menggunakan semua fitur yang ditawarkan oleh Cloud Logging dan hanya memerlukan beberapa baris kode khusus Google.

Anda dapat menulis log ke Cloud Logging dari aplikasi Python dengan menggunakan pengendali logging Python standar, atau dengan menggunakan library klien Cloud Logging API untuk Python secara langsung. Saat menggunakan pengendali logging Python standar, Anda harus melampirkan pengendali Cloud Logging ke pengendali root Python. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan Cloud Logging untuk Python.

Menulis log terstruktur ke stdout dan stderr

Secara default, App Engine menggunakan library klien Cloud Logging untuk mengirim log. Namun, metode ini tidak mendukung logging terstruktur. Anda hanya dapat menulis log terstruktur menggunakan stdout/stderr. Selain itu, Anda juga dapat mengirim string teks ke stdout dan stderr. Secara default, payload log adalah string teks yang disimpan di kolom textPayload entri log. String ini muncul sebagai pesan di Logs Explorer, command line, dan Cloud Logging API, serta dikaitkan dengan layanan App Engine dan versi yang menampilkannya.

Untuk mendapatkan nilai yang lebih besar dari log, Anda dapat memfilter string ini di Logs Explorer menurut tingkat keparahan. Untuk memfilter string ini, Anda harus memformat string sebagai data terstruktur. Untuk melakukannya, Anda menulis log dalam bentuk satu baris JSON serial. App Engine mengambil dan mengurai baris JSON serial ini, lalu menempatkannya ke kolom jsonPayload entri log, bukan textPayload.

Selama rotasi log, menulis log bervolume tinggi ke stdout dan stderr dapat mengakibatkan pemotongan log atau log yang dihilangkan. Untuk aplikasi dengan throughput tinggi, gunakan library klien Cloud Logging dari aplikasi Anda.

Cuplikan di bawah menunjukkan penulisan log terstruktur tersebut.

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

Log stdout dan stderr dari lingkungan fleksibel dikirim ke Cloud Logging menggunakan agen logging lama yang berjalan di instance mesin virtual. Agen logging berjalan dengan resource terbatas dan log yang ditulis dirotasi setelah melebihi batas 10 MB. Jika tingkat log yang ditulis ke stdout dan stderr lebih besar dari kecepatan log yang dibaca oleh agen logging, log dapat dirotasi sebelum log dikirim ke Cloud Logging. Jika Anda tidak ingin kehilangan log, gunakan Cloud Logging.

Kolom JSON khusus dalam pesan

Apabila Anda menyediakan log yang terstruktur sebagai kamus JSON, beberapa kolom khusus akan dihapus dari jsonPayload dan ditulis ke kolom yang sesuai dalam LogEntry yang dibuat. Hal ini sebagaimana dijelaskan dalam dokumentasi untuk kolom khusus.

Misalnya, jika JSON Anda menyertakan properti severity, maka JSON tersebut akan dihapus dari jsonPayload dan muncul sebagai entri log milik severity. Properti message digunakan sebagai teks tampilan utama entri log jika ada.

Menghubungkan log permintaan dengan log aplikasi

Setelah memformat entri sebagai objek JSON dan memberikan metadata spesifik, Anda dapat mengaktifkan pemfilteran dan korelasi dengan log permintaan. Untuk menghubungkan entri log permintaan dengan entri log aplikasi, Anda memerlukan ID trace permintaan. Ikuti petunjuk untuk menghubungkan pesan log:

  1. Ekstrak ID trace dari header permintaan X-Cloud-Trace-Context.
  2. Dalam entri log terstruktur Anda, tulis ID ke kolom bernama logging.googleapis.com/trace. Untuk mengetahui informasi selengkapnya tentang header X-Cloud-Trace-Context, lihat Memaksa permintaan untuk dilacak.

Untuk melihat log yang terhubung, lihat Melihat entri log yang terhubung di Logs Explorer.

Melihat log

Anda dapat melihat log aplikasi dan log permintaan dengan beberapa cara:

Menggunakan Logs Explorer

Anda dapat melihat log aplikasi dan permintaan menggunakan Logs Explorer:

  1. Buka Logs Explorer di Google Cloud konsol:

    Buka Logs Explorer

  2. Pilih project yang ada di bagian atas halaman. Google Cloud

  3. Di Jenis Resource, pilih Aplikasi GAE.

Anda dapat memfilter Logs Explorer berdasarkan layanan, versi, dan kriteria lainnya di App Engine. Anda juga dapat menelusuri log untuk menemukan entri tertentu. Lihat Menggunakan Logs Explorer untuk mengetahui detailnya.

Jika Anda mengirim entri teks sederhana ke output standar, Anda tidak dapat menggunakan Logs Viewer untuk memfilter entri aplikasi menurut tingkat keparahan. Anda juga tidak dapat melihat log aplikasi mana yang sesuai dengan permintaan tertentu. Anda masih dapat menggunakan jenis pemfilteran lain di Logs Explorer, seperti teks dan stempel waktu.

Melihat entri log yang terhubung di Logs Explorer

Di Logs Explorer, untuk melihat entri log turunan yang terhubung dengan entri log induk, luaskan entri log.

Misalnya, untuk menampilkan entri log permintaan App Engine dan entri log aplikasi, lakukan hal berikut:

  1. Di panel navigasi Google Cloud konsol, pilih Logging, lalu pilih Logs Explorer:

    Buka Logs Explorer

  2. Di Jenis Resource, pilih Aplikasi GAE.

  3. Untuk melihat dan menghubungkan log permintaan, di Nama Log, pilih request_log. Atau, untuk menghubungkan berdasarkan log permintaan, klik Hubungkan berdasarkan , lalu pilih request_log.

    Mengorelasikan log

  4. Di panel Hasil kueri, untuk meluaskan entri log, klik Luaskan. Saat diperluas, setiap log permintaan akan menampilkan log aplikasi terkait.

Setelah membuat filter untuk log, setiap log permintaan akan menampilkan log aplikasi yang sesuai sebagai log turunan. Logs Explorer mencapai hal ini dengan menghubungkan kolom trace di log aplikasi dan log permintaan tertentu, dengan asumsi aplikasi menggunakan library google-cloud-logging.

Gambar berikut menampilkan log aplikasi yang dikelompokkan berdasarkan kolom trace:

Entri log aplikasi disusun bertingkat dalam entri log permintaan.

Menggunakan Google Cloud CLI

Untuk melihat log App Engine dari command line, gunakan perintah berikut:

gcloud app logs tail

Untuk mengetahui informasi selengkapnya, lihat tail log aplikasi gcloud.

Membaca log secara terprogram

Jika ingin membaca log secara terprogram, Anda dapat menggunakan salah satu metode berikut:

Kebijakan harga, kuota, dan retensi log

Untuk mengetahui informasi tentang harga yang berlaku bagi log permintaan dan aplikasi, lihat Harga untuk Cloud Logging.

Untuk mengetahui kebijakan retensi log dan ukuran maksimum entri log, baca Kuota dan batas. Jika ingin menyimpan log untuk jangka waktu yang lebih lama, Anda dapat mengekspor log Anda ke Cloud Storage. Anda juga dapat mengekspor log ke BigQuery dan Pub/Sub untuk diproses lebih lanjut.

Mengelola penggunaan resource log

Anda dapat mengontrol jumlah aktivitas logging dari log aplikasi dengan menulis lebih banyak atau lebih sedikit entri dari kode aplikasi Anda. Log permintaan dibuat secara otomatis. Jadi, untuk mengelola jumlah entri log permintaan yang terkait dengan aplikasi Anda, gunakan fitur pengecualian log dari Cloud Logging.

Masalah umum

Berikut beberapa masalah logging di runtime generasi kedua:

  • Terkadang entri log aplikasi tidak berkorelasi dengan log permintaan. Hal ini terjadi saat pertama kali aplikasi Anda menerima permintaan dan saat App Engine menulis pesan status ke log aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat https://issuetracker.google.com/issues/138365527.

  • Saat Anda merutekan log dari sink log ke Cloud Storage, tujuan Cloud Storage hanya berisi log permintaan. App Engine menulis log aplikasi ke folder yang berbeda.

  • BigQuery gagal menyerap log karena kolom @type dalam log permintaan. Hal ini mengganggu deteksi skema otomatis, karena BigQuery tidak mengizinkan @type dalam nama kolom. Untuk mengatasi masalah ini, Anda harus menentukan skema secara manual, dan menghapus kolom @type dari log permintaan.

  • Jika Anda menggunakan REST API logging, thread latar belakang akan menulis log ke Cloud Logging. Jika thread utama tidak aktif, instance tidak akan mendapatkan waktu CPU, yang menyebabkan thread latar belakang berhenti. Waktu pemrosesan log tertunda. Pada suatu titik, instance akan dihapus dan log yang belum dikirim akan hilang. Untuk menghindari kehilangan log, gunakan salah satu opsi berikut:

    • Konfigurasi Cloud Logging SDK untuk menggunakan gRPC. Dengan gRPC, log akan segera dikirim ke Cloud Logging. Namun, hal ini dapat meningkatkan batas CPU yang diperlukan.
    • Kirim pesan log ke Cloud Logging menggunakan stdout/stderr. Pipeline ini berada di luar instance App Engine dan tidak dibatasi.

Langkah berikutnya