Mengonfigurasi agen Logging

Halaman ini memberikan detail mengenai konfigurasi default dan kustom agen Cloud Logging.

Sebagian besar pengguna tidak perlu membaca halaman ini. Baca halaman ini jika:

  • Anda tertarik untuk mempelajari detail teknis mendalam tentang konfigurasi agen Cloud Logging.

  • Anda ingin mengubah konfigurasi agen Cloud Logging.

Konfigurasi default

Agen Logging google-fluentd adalah versi modifikasi dari pengumpul data log fluentd. Agen Logging dilengkapi dengan konfigurasi default; dalam sebagian besar kasus umum, konfigurasi tambahan tidak diperlukan.

Dalam konfigurasi defaultnya, agen Logging mengalirkan log, seperti yang disertakan dalam daftar log default, ke Cloud Logging. Anda dapat mengonfigurasi agen untuk melakukan streaming log tambahan. Untuk mengetahui detailnya, buka Menyesuaikan konfigurasi agen Logging di halaman ini.

Cara Kerja Agen Logging.

Agen Logging menggunakan plugin input fluentd untuk mengambil dan menarik log peristiwa dari sumber eksternal, seperti file pada disk, atau untuk mengurai data log yang masuk. Plugin input dipaketkan dengan agen atau dapat diinstal secara terpisah sebagai gem Ruby; tinjau daftar plugin paket.

Agen membaca data log yang disimpan dalam file log pada instance VM melalui plugin in_tail bawaan fluentd. Setiap data log dikonversi menjadi struktur entri log untuk Cloud Logging. Konten setiap record log sebagian besar dicatat dalam payload entri log, tetapi entri log juga berisi elemen standar seperti stempel waktu dan keseriusan. Agen Logging mengharuskan setiap catatan log diberi tag dengan tag format string; semua kueri dan plugin output cocok dengan kumpulan tag tertentu. Nama log biasanya mengikuti format, projects/[PROJECT-ID]/logs/[TAG]. Misalnya, nama log ini menyertakan tag structured-log:

projects/my-sample-project-12345/logs/structured-log

Plugin output mengubah setiap pesan terstruktur yang diinternalisasi menjadi entri log di Cloud Logging. Payload menjadi payload teks atau JSON.

Bagian berikut di halaman ini membahas konfigurasi default secara mendetail.

Definisi konfigurasi default

Bagian berikut menjelaskan definisi konfigurasi default untuk syslog, plugin input maju, konfigurasi input untuk log aplikasi pihak ketiga, seperti yang ada dalam daftar log default, dan plugin output fluentd Google Cloud.

Lokasi file konfigurasi root

  • Linux: /etc/google-fluentd/google-fluentd.conf

    File konfigurasi root ini juga mengimpor semua file konfigurasi dari folder /etc/google-fluentd/config.d.

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Jika Anda menjalankan agen Logging sebelum v1-5, lokasinya adalah: C:\GoogleStackdriverLoggingAgent\fluent.conf

Konfigurasi Syslog

  • Lokasi file konfigurasi: /etc/google-fluentd/config.d/syslog.conf

  • Description: File ini berisi konfigurasi untuk menentukan syslog sebagai input log.

  • Tinjau repositori konfigurasi.

Nama konfigurasi Jenis Default Deskripsi
format string /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ Format {i>syslog<i}.
path string /var/log/syslog Jalur file {i>syslog<i}.
pos_file string /var/lib/google-fluentd/pos/syslog.pos Jalur file posisi untuk input log ini. fluentd mencatat posisi yang terakhir dibaca ke dalam file ini. Tinjau dokumentasi fluentd mendetail.
read_from_head bool true Apakah akan mulai membaca log dari head file, bukan dari bawah. Tinjau dokumentasi fluentd mendetail.
tag string syslog Tag log untuk input log ini.

Konfigurasi plugin input in_forward

  • Lokasi file konfigurasi: /etc/google-fluentd/config.d/forward.conf

  • Deskripsi: File ini mencakup konfigurasi untuk mengonfigurasi plugin input in_forward fluentd. Plugin input in_forward memungkinkan Anda meneruskan log melalui soket TCP.

  • Tinjau dokumentasi fluentd mendetail untuk plugin ini dan repositori konfigurasi.

Nama konfigurasi Jenis Default Deskripsi
port int 24224 Port yang akan dipantau.
bind string 127.0.0.1 Alamat pengikatan yang akan dipantau. Secara {i>default<i}, hanya koneksi dari localhost yang diterima. Untuk membukanya, konfigurasi ini perlu diubah menjadi 0.0.0.0.

Konfigurasi input log aplikasi pihak ketiga

  • Lokasi file konfigurasi: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

  • Description: Direktori ini mencakup file konfigurasi untuk menentukan file log aplikasi pihak ketiga sebagai input log. Setiap file, kecuali syslog.conf dan forward.conf, mewakili satu aplikasi (misalnya, apache.conf untuk aplikasi Apache).

  • Tinjau repositori konfigurasi.

Nama konfigurasi Jenis Default Deskripsi
format1 string Bervariasi per aplikasi Format log. Tinjau dokumentasi fluentd mendetail.
path string Bervariasi per aplikasi Jalur file log. Beberapa jalur dapat ditentukan, dipisahkan dengan ','. * dan format strftime dapat disertakan untuk menambahkan/menghapus file smartwatch secara dinamis. Tinjau dokumentasi fluentd mendetail.
pos_file string Bervariasi per aplikasi Jalur file posisi untuk input log ini. fluentd mencatat posisi yang terakhir dibaca ke dalam file ini. Tinjau dokumentasi fluentd mendetail).
read_from_head bool true Apakah akan mulai membaca log dari head file, bukan dari bawah. Tinjau dokumentasi fluentd mendetail.
tag string Bervariasi; nama aplikasi. Tag log untuk input log ini.

1 Jika Anda menggunakan stanza <parse>, tentukan format log menggunakan @type.

Konfigurasi plugin output fluentd Google Cloud

  • Lokasi file konfigurasi:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Jika Anda menjalankan agen Logging sebelum v1-5, lokasinya adalah: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Deskripsi: File ini menyertakan opsi konfigurasi untuk mengontrol perilaku plugin output fluentd Google Cloud.

  • Buka repositori konfigurasi.

Nama konfigurasi Jenis Default Deskripsi
buffer_chunk_limit string 512KB Saat data log masuk, rekaman log yang tidak dapat ditulis ke komponen downstream dengan cukup cepat akan didorong ke antrean potongan. Konfigurasi ini menetapkan batas ukuran setiap potongan. Secara default, kami menetapkan batas potongan secara konservatif agar tidak melebihi ukuran potongan yang disarankan, yaitu 5 MB per permintaan tulis di Logging API. Entri log dalam permintaan API bisa 5X - 8X kali lebih besar dari ukuran log asli dengan semua metadata tambahan terlampir. Potongan buffer akan dihapus jika salah satu dari dua kondisi terpenuhi:
1. flush_interval melakukan tendangan.
2. Ukuran buffer mencapai buffer_chunk_limit.
flush_interval string 5s Saat data log masuk, rekaman log yang tidak dapat ditulis ke komponen downstream dengan cukup cepat akan didorong ke antrean potongan. Konfigurasi menetapkan berapa lama sebelum kita harus mengosongkan buffer potongan. Potongan buffer akan dihapus jika salah satu dari dua kondisi terpenuhi:
1. flush_interval melakukan tendangan.
2. Ukuran buffer mencapai buffer_chunk_limit.
disable_retry_limit bool false Menerapkan batas jumlah percobaan ulang untuk penghapusan potongan buffer yang gagal. Tinjau spesifikasi mendetail di retry_limit, retry_wait, dan max_retry_wait.
retry_limit int 3 Jika bagian buffer gagal dihapus, fluentd akan mencoba kembali secara default di lain waktu. Konfigurasi ini menetapkan berapa banyak percobaan ulang yang harus dilakukan sebelum melepaskan satu potongan buffer yang bermasalah.
retry_wait int 10s Jika bagian buffer gagal dihapus, fluentd akan mencoba kembali secara default di lain waktu. Konfigurasi ini menetapkan interval tunggu dalam detik sebelum percobaan ulang pertama. Interval waktu tunggu dua kali lipat pada setiap percobaan ulang berikutnya (20 dtk, 40 dtk,...) hingga retry_ limit atau max_retry_wait tercapai.
max_retry_wait int 300 Jika bagian buffer gagal dihapus, fluentd akan mencoba kembali secara default di lain waktu. Interval tunggu berlipat ganda pada setiap percobaan ulang berikutnya (20 dtk, 40 dtk,...) Konfigurasi ini menetapkan maksimum interval tunggu dalam detik. Jika interval tunggu mencapai batas ini, penggandaan akan berhenti.
num_threads int 8 Jumlah flush log simultan yang dapat diproses oleh plugin output.
use_grpc bool true Apakah akan menggunakan gRPC, bukan REST/JSON, untuk berkomunikasi dengan Logging API. Dengan mengaktifkan gRPC, penggunaan CPU biasanya lebih rendah
grpc_compression_algorithm enum none Jika menggunakan gRPC, tetapkan skema kompresi mana yang akan digunakan. Dapat berupa none atau gzip.
partial_success bool true Apakah akan mendukung keberhasilan sebagian untuk penyerapan log. Jika true, entri log yang tidak valid dalam kumpulan lengkap akan dihapus, dan entri log yang valid berhasil diserap ke dalam Logging API. Jika false, kumpulan lengkap akan dihapus jika berisi entri log yang tidak valid.
enable_monitoring bool true Jika ditetapkan ke true, agen Logging akan mengekspor telemetri internal. Lihat Telemetri plugin output untuk mengetahui detailnya.
monitoring_type string opencensus Jenis pemantauan. Opsi yang didukung adalah opencensus dan prometheus. Lihat Telemetri plugin output untuk mengetahui detailnya.
autoformat_stackdriver_trace bool true Jika ditetapkan ke true, rekaman aktivitas akan diformat ulang jika nilai kolom payload terstruktur logging.googleapis.com/trace cocok dengan format traceId ResourceTrace. Detail pemformatan otomatis dapat ditemukan di Kolom khusus dalam payload terstruktur di halaman ini.

Konfigurasi pemantauan

Telemetri plugin output

Opsi enable_monitoring mengontrol apakah plugin output fluentd Google Cloud mengumpulkan telemetri internal atau tidak. Jika ditetapkan ke true, agen Logging akan melacak jumlah entri log yang diminta untuk dikirim ke Cloud Logging serta jumlah entri log sebenarnya yang berhasil diserap oleh Cloud Logging. Jika ditetapkan ke false, tidak ada metrik yang akan dikumpulkan oleh plugin output.

Opsi monitoring_type mengontrol cara telemetri ini diekspos oleh agen. Lihat daftar metrik berikut.

Jika ditetapkan ke prometheus, agen Logging akan menampilkan metrik dalam format Prometheus di endpoint Prometheus (localhost:24231/metrics secara default; lihat konfigurasi plugin prometheus dan prometheus_monitor untuk mengetahui detail tentang cara menyesuaikannya). Di VM Compute Engine, agar metrik tersebut ditulis ke Monitoring API, Agen Monitoring juga harus diinstal dan berjalan.

Jika ditetapkan ke opencensus (default sejak v1.6.25), agen Logging secara langsung menulis metrik responsnya sendiri ke Monitoring API. Peran roles/monitoring.metricWriter mengharuskan Anda diberikan ke akun layanan default Compute Engine, meskipun agen Monitoring tidak diinstal.

Metrik berikut ditulis ke Monitoring API oleh agen Monitoring dan agen Logging dalam mode opencensus:

  • agent.googleapis.com/agent/uptime dengan label version: Waktu beroperasi agen Logging.
  • agent.googleapis.com/agent/log_entry_count dengan label response_code: Jumlah entri log yang ditulis oleh Agen Logging.
  • agent.googleapis.com/agent/log_entry_retry_count dengan label response_code: Jumlah entri log yang ditulis oleh Agen Logging.
  • agent.googleapis.com/agent/request_count dengan label response_code: Jumlah permintaan API dari Agen Logging.

Metrik ini dijelaskan secara lebih mendetail di halaman Metrik agen.

Selain itu, metrik Prometheus berikut diekspos oleh plugin output dalam mode prometheus:

  • uptime dengan label version: Waktu beroperasi agen Logging.
  • stackdriver_successful_requests_count dengan label grpc dan code: Jumlah permintaan yang berhasil ke Logging API.
  • stackdriver_failed_requests_count dengan label grpc dan code: Jumlah permintaan yang gagal ke Logging API, yang dikelompokkan berdasarkan kode error.
  • stackdriver_ingested_entries_count dengan label grpc dan code: Jumlah entri log yang diserap oleh Logging API.
  • stackdriver_dropped_entries_count dengan label grpc dan code: Jumlah entri log yang ditolak oleh Logging API.
  • stackdriver_retried_entries_count dengan label grpc dan code: Jumlah entri log yang gagal diserap oleh plugin output fluentd Google Cloud karena terjadi error sementara dan dicoba lagi.

Konfigurasi plugin prometheus dan prometheus_monitor

  • Lokasi file konfigurasi: /etc/google-fluentd/google-fluentd.conf

  • Deskripsi: File ini menyertakan opsi konfigurasi untuk mengontrol perilaku plugin prometheus dan prometheus_monitor. Plugin prometheus_monitor memantau infrastruktur inti Fluentd. Plugin prometheus mengekspos metrik, termasuk metrik dari plugin prometheus_monitor dan plugin dari plugin google_cloud di atas melalui port lokal dalam format Prometheus. Lihat detail selengkapnya di https://docs.fluentd.org/deployment/monitoring-prometheus.

  • Buka repositori konfigurasi.

Untuk memantau Fluentd, server metrik http Prometheus bawaan diaktifkan secara default. Anda dapat menghapus bagian berikut dari konfigurasi untuk menghentikan endpoint ini agar tidak dimulai:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

Memproses payload

Sebagian besar log yang didukung pada konfigurasi default Agen Logging berasal dari file log dan diserap sebagai payload tidak terstruktur (teks) dalam entri log.

Satu-satunya pengecualian adalah plugin input in_forward, yang juga diaktifkan secara default, hanya menerima log terstruktur dan menyerapnya sebagai payload terstruktur (JSON) dalam entri log. Untuk mengetahui detailnya, baca Data log streaming terstruktur (JSON) melalui plugin in_forward di halaman ini.

Jika baris log adalah objek JSON serial dan opsi detect_json diaktifkan, plugin output akan mengubah entri log menjadi payload terstruktur (JSON). Opsi ini diaktifkan secara default di instance VM yang berjalan di lingkungan fleksibel App Engine dan Google Kubernetes Engine. Opsi ini tidak diaktifkan secara default di instance VM yang berjalan di lingkungan standar App Engine. Setiap JSON yang diuraikan dengan opsi detect_json yang diaktifkan selalu diserap sebagai jsonPayload.

Anda dapat menyesuaikan konfigurasi agen untuk mendukung penyerapan log terstruktur dari resource tambahan. Lihat Data log streaming terstruktur (JSON) ke Cloud Logging untuk mengetahui detailnya.

Payload data log yang di-streaming oleh agen Logging yang dikonfigurasi secara khusus dapat berupa satu pesan teks tidak terstruktur (textPayload) atau pesan JSON terstruktur (jsonPayload).

Kolom khusus dalam payload terstruktur

Saat menerima catatan log terstruktur, agen Logging akan memindahkan kunci apa pun yang cocok dengan tabel berikut ke kolom yang sesuai pada objek LogEntry. Jika tidak, kunci akan menjadi bagian dari kolom LogEntry.jsonPayload. Perilaku ini memungkinkan Anda menetapkan kolom tertentu dalam objek LogEntry, yang ditulis ke Logging API. Misalnya, jika catatan log terstruktur berisi kunci severity, Agen Logging akan mengisi kolom LogEntry.severity.

Kolom log JSON Kolom LogEntry Fungsi agen Cloud Logging Nilai contoh
severity severity Agen Logging mencoba mencocokkan berbagai string tingkat keparahan umum, yang mencakup daftar string LogSeverity yang dikenali oleh Logging API. "severity":"ERROR"
message textPayload (atau bagian dari jsonPayload) Pesan yang muncul di baris entri log di Logs Explorer. "message":"There was an error in the application."

Catatan: message disimpan sebagai textPayload jika ini adalah satu-satunya kolom yang tersisa setelah agen Logging memindahkan kolom dengan tujuan khusus lainnya dan detect_json tidak diaktifkan; jika tidak, message akan tetap berada di jsonPayload. detect_json tidak berlaku untuk lingkungan logging terkelola seperti Google Kubernetes Engine. Jika entri log Anda berisi stack trace pengecualian, stack trace pengecualian harus ditetapkan dalam kolom log JSON message ini agar stack trace pengecualian dapat diuraikan dan disimpan ke Error Reporting.
log (khusus Google Kubernetes Engine lama) textPayload Hanya berlaku untuk Google Kubernetes Engine lama: jika, setelah memindahkan kolom tujuan khusus, hanya tersisa satu kolom log, maka kolom tersebut disimpan sebagai textPayload.
httpRequest httpRequest Data terstruktur dalam format kolom HttpRequest LogEntry. "httpRequest":{"requestMethod":"GET"}
bidang yang terkait dengan waktu, timestamp Untuk mengetahui informasi selengkapnya, lihat Kolom terkait waktu. "time":"2020-10-12T07:20:50.52Z"
logging.googleapis.com/insertId insertId Untuk informasi selengkapnya, lihat insertId di halaman LogEntry. "logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels labels Nilai kolom ini harus berupa catatan terstruktur. Untuk informasi selengkapnya, lihat labels di halaman LogEntry. "logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation operation Nilai kolom ini juga digunakan oleh Logs Explorer untuk mengelompokkan entri log yang terkait. Untuk informasi selengkapnya, lihat operation di halaman LogEntry. "logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation sourceLocation Informasi lokasi kode sumber yang terkait dengan entri log, jika ada. Untuk informasi selengkapnya, lihat LogEntrySourceLocation di halaman LogEntry. "logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId spanId ID span dalam rekaman aktivitas yang terkait dengan entri log. Untuk informasi selengkapnya, lihat spanId di halaman LogEntry. "logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace trace Nama resource trace yang terkait dengan entri log jika ada. Untuk informasi selengkapnya, lihat trace di halaman LogEntry. "logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"

Catatan: Jika tidak menulis ke stdout atau stderr, nilai kolom ini harus diformat sebagai projects/[PROJECT-ID]/traces/[TRACE-ID], sehingga dapat digunakan oleh Logs Explorer dan Trace Viewer untuk mengelompokkan entri log dan menampilkannya sesuai dengan trace. Jika autoformat_stackdriver_trace bernilai benar dan [V] cocok dengan format ResourceTrace traceId, kolom trace LogEntry akan memiliki nilai projects/[PROJECT-ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled Nilai kolom ini harus true atau false. Untuk informasi selengkapnya, lihat traceSampled di halaman LogEntry. "logging.googleapis.com/trace_sampled": false

Kolom terkait waktu

Secara umum, informasi terkait waktu tentang entri log disimpan di kolom timestamp objek LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Jika sumber entri log adalah data terstruktur, Agen Logging akan menggunakan aturan berikut untuk menelusuri kolom dalam entri jsonPayload guna mendapatkan informasi terkait waktu:

  1. Telusuri kolom timestamp yang merupakan objek JSON yang menyertakan kolom seconds dan nanos, yang masing-masing mewakili jumlah detik bertanda tangan dari epoch UTC dan jumlah detik pecahan yang tidak negatif:

    jsonPayload: {
      ...
      "timestamp": {
        "seconds": CURRENT_SECONDS,
        "nanos": CURRENT_NANOS
      }
    }
    
  2. Jika penelusuran sebelumnya gagal, telusuri sepasang kolom timestampSeconds dan timestampNanos:

    jsonPayload: {
      ...
      "timestampSeconds": CURRENT_SECONDS,
      "timestampNanos": CURRENT_NANOS
    }
    
  3. Jika penelusuran sebelumnya gagal, telusuri kolom time yang merupakan string dalam format RFC 3339:

    jsonPayload: {
      ...
      "time": CURRENT_TIME_RFC3339
    }
    

Jika informasi terkait waktu ditemukan, agen Logging akan menggunakan informasi tersebut untuk menetapkan nilai LogEntry.timestamp, dan tidak menyalin informasi tersebut dari data terstruktur ke objek LogEntry.jsonPayload.

Kolom terkait waktu yang tidak digunakan untuk menetapkan nilai kolom LogEntry.timestamp akan disalin dari data terstruktur ke objek LogEntry.jsonPayload. Misalnya, jika data terstruktur berisi objek JSON timestamp dan kolom time, data dalam objek JSON timestamp digunakan untuk menetapkan kolom LogEntry.timestamp. Objek LogEntry.jsonPayload berisi kolom time karena kolom ini tidak digunakan untuk menetapkan nilai LogEntry.timestamp.

Menyesuaikan konfigurasi agen

Selain daftar log default yang di-streaming oleh agen Logging secara default, Anda dapat menyesuaikan agen Logging untuk mengirim log tambahan ke Logging atau menyesuaikan setelan agen dengan menambahkan konfigurasi input.

Definisi konfigurasi di bagian ini hanya berlaku untuk plugin output fluent-plugin-google-cloud dan menentukan cara log ditransformasi dan diserap ke dalam Cloud Logging.

  • Lokasi file konfigurasi utama:

    • Linux: /etc/google-fluentd/google-fluentd.conf
    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Jika Anda menjalankan agen Logging sebelum v1-5, lokasinya adalah: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Deskripsi: File ini menyertakan opsi konfigurasi untuk mengontrol perilaku plugin output fluent-plugin-google-cloud.

  • Tinjau repositori konfigurasi.

Melakukan streaming log dari input tambahan

Anda dapat menyesuaikan agen Logging untuk mengirim log tambahan ke Logging dengan menambahkan konfigurasi input.

Streaming log tidak terstruktur (teks) melalui file log

  1. Dari command prompt Linux, buat file log:

    touch /tmp/test-unstructured-log.log
    
  2. Buat file konfigurasi baru berlabel test-unstructured-log.conf di direktori konfigurasi tambahan /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
    <source>
        @type tail
        <parse>
            # 'none' indicates the log is unstructured (text).
            @type none
        </parse>
        # The path of the log file.
        path /tmp/test-unstructured-log.log
        # The path of the position file that records where in the log file
        # we have processed already. This is useful when the agent
        # restarts.
        pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag unstructured-log
    </source>
    EOF
    

    Alternatif untuk membuat file baru adalah dengan menambahkan informasi konfigurasi ke file konfigurasi yang ada.

  3. Mulai ulang agen untuk menerapkan perubahan konfigurasi:

    sudo service google-fluentd restart
    
  4. Buat catatan log ke dalam file log:

    echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log
    
  5. Periksa Logs Explorer untuk melihat entri log yang diserap:

    {
      insertId:  "eps2n7g1hq99qp"
      labels: {
      compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/unstructured-log"
      receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
      resource: {
      labels: {
        instance_id:  "3914079432219560274"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      textPayload:  "This is a log from the log file at test-unstructured-log.log"
      timestamp:  "2018-03-21T01:47:05.051902169Z"
    }
    

Log terstruktur streaming (JSON) melalui file log

Anda dapat mengonfigurasi agen Logging untuk mewajibkan setiap entri log agar input log tertentu bersifat terstruktur. Anda juga dapat menyesuaikan agen Logging untuk menyerap konten berformat JSON dari file log. Saat agen dikonfigurasi untuk menyerap konten JSON, input harus diformat sehingga setiap objek JSON berada di baris baru:

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

Untuk mengonfigurasi agen Logging untuk menyerap konten berformat JSON, lakukan hal berikut:

  1. Dari command prompt Linux, buat file log:

    touch /tmp/test-structured-log.log
    
  2. Buat file konfigurasi baru berlabel test-structured-log.conf di direktori konfigurasi tambahan /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
    <source>
        @type tail
        <parse>
            # 'json' indicates the log is structured (JSON).
            @type json
        </parse>
        # The path of the log file.
        path /tmp/test-structured-log.log
        # The path of the position file that records where in the log file
        # we have processed already. This is useful when the agent
        # restarts.
        pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
        read_from_head true
        # The log tag for this log input.
        tag structured-log
      </source>
      EOF
    

    Alternatif untuk membuat file baru adalah dengan menambahkan informasi konfigurasi ke file konfigurasi yang ada.

  3. Mulai ulang agen untuk menerapkan perubahan konfigurasi:

    sudo service google-fluentd restart
    
  4. Buat catatan log ke dalam file log:

    echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log
    
  5. Periksa Logs Explorer untuk melihat entri log yang diserap:

    {
      insertId:  "1m9mtk4g3mwilhp"
      jsonPayload: {
      code:  "structured-log-code"
      message:  "This is a log from the log file at test-structured-log.log"
      }
      labels: {
      compute.googleapis.com/resource_name:  "add-structured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/structured-log"
      receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
      resource: {
      labels: {
        instance_id:  "5351724540900470204"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      timestamp:  "2018-03-21T01:53:39.071920609Z"
    }
    

    Di Logs Explorer, filter menurut jenis resource Anda dan logName structured-log.

Untuk opsi tambahan guna menyesuaikan format input log untuk aplikasi pihak ketiga umum, lihat Format Log Umum dan Cara Mengurainya.

Log terstruktur streaming (JSON) melalui plugin in_forward

Selain itu, Anda dapat mengirim log melalui plugin fluentd in_forward. fluentd-cat adalah alat bawaan yang membantu mengirim log dengan mudah ke plugin in_forward. Dokumentasi fluentd berisi detail selengkapnya untuk alat ini.

Untuk mengirim log melalui plugin fluentd in_forward, baca petunjuk berikut:

  1. Jalankan perintah berikut di VM dengan agen Logging yang terinstal:

    echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin
    
  2. Periksa Logs Explorer untuk melihat entri log yang diserap:

    {
      insertId:  "1kvvmhsg1ib4689"
      jsonPayload: {
      code:  "send-log-via-fluent-cat"
      message:  "This is a log from in_forward plugin."
      }
      labels: {
      compute.googleapis.com/resource_name:  "add-structured-log-resource"
      }
      logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
      receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
      resource: {
      labels: {
        instance_id:  "5351724540900470204"
        project_id:  "my-sample-project-12345"
        zone:  "us-central1-c"
      }
      type:  "gce_instance"
      }
      timestamp:  "2018-03-21T02:11:22.717692494Z"
    }
    

Data log terstruktur streaming (JSON) dari kode aplikasi

Anda dapat mengaktifkan konektor dalam berbagai bahasa untuk mengirim log terstruktur dari kode aplikasi. Untuk mengetahui informasi selengkapnya, lihat dokumentasi fluentd. Konektor ini dibuat berdasarkan plugin in_forward.

Menetapkan label entri log

Opsi konfigurasi berikut memungkinkan Anda mengganti label LogEntry dan label MonitoredResource saat menyerap log ke Cloud Logging. Semua entri log dikaitkan dengan resource yang dimonitor. Untuk mengetahui informasi lebih lanjut, tinjau daftar jenis resource yang dimonitor Cloud Logging.

Nama konfigurasi Jenis Default Deskripsi
label_map hash nil label_map (ditentukan sebagai objek JSON) adalah kumpulan nama kolom fluentd yang tidak berurutan yang nilainya dikirim sebagai label, bukan sebagai bagian dari payload terstruktur. Setiap entri dalam peta adalah pasangan {field_name: label_name}. Saat field_name (seperti yang diuraikan oleh plugin input) ditemukan, label dengan label_name yang sesuai akan ditambahkan ke entri log. Nilai kolom digunakan sebagai nilai label. Peta memberi Anda fleksibilitas tambahan dalam menentukan nama label, termasuk kemampuan untuk menggunakan karakter yang tidak sah sebagai bagian dari nama kolom fluentd. Sebagai contoh, buka Menetapkan label dalam entri log terstruktur.
labels hash nil labels (ditetapkan sebagai objek JSON) adalah kumpulan label khusus yang diberikan pada waktu konfigurasi. Fitur ini memungkinkan Anda memasukkan informasi lingkungan tambahan ke dalam setiap pesan atau menyesuaikan label yang terdeteksi secara otomatis. Setiap entri dalam peta adalah pasangan {label_name: label_value}.

Plugin output agen Logging mendukung tiga cara untuk menetapkan label LogEntry:

Menetapkan label dalam entri log terstruktur

Misalkan Anda menulis payload entri log terstruktur seperti ini:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

Dan misalkan Anda ingin menerjemahkan kolom payload env ke label metadata environment. Untuk melakukannya, tambahkan kode berikut ke konfigurasi plugin output di file konfigurasi utama (/etc/google-fluentd/google-fluentd.conf di Linux atau C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf di Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

Setelan label_map di sini mengganti label env dalam payload dengan environment, sehingga entri log yang dihasilkan memiliki label environment dengan nilai production.

Menetapkan label secara statis

Jika Anda tidak memiliki informasi ini dalam payload, dan hanya ingin menambahkan label metadata statis bernama environment, tambahkan kode berikut ke konfigurasi plugin output di file konfigurasi utama (/etc/google-fluentd/google-fluentd.conf di Linux atau C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf di Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

Dalam hal ini, alih-alih menggunakan peta untuk mengganti satu label dengan label lain, kami menggunakan setelan labels untuk melampirkan label dengan nilai literal yang diberikan ke entri log, terlepas dari apakah entri tersebut sudah memiliki label atau belum. Pendekatan ini dapat digunakan meskipun Anda mengirim log yang tidak terstruktur.

Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi labels, label_map, dan setelan agen Logging lainnya, buka Menyetel Label Entri Log di halaman ini.

Mengubah Catatan Log

Fluentd menyediakan plugin filter bawaan yang dapat digunakan untuk mengubah entri log.

Plugin filter yang paling umum digunakan adalah filter_record_transformer. Hal ini memungkinkan Anda untuk:

  • Menambahkan kolom baru ke entri log
  • Memperbarui kolom dalam entri log
  • Menghapus kolom dalam entri log

Beberapa plugin output juga memungkinkan Anda mengubah entri log. Plugin output fluent-plugin-record-reformer menyediakan fungsi yang mirip dengan plugin filter filter_record_transformer, tetapi juga memungkinkan Anda mengubah tag log. Plugin ini diperkirakan akan menggunakan lebih banyak resource: setiap kali tag log diperbarui, tag tersebut akan menghasilkan entri log baru dengan tag baru. Perhatikan bahwa kolom tag dalam konfigurasi bersifat wajib; sebaiknya Anda juga memodifikasi kolom ini untuk menghindari memasuki loop mati.

Plugin output fluent-plugin-detect-exceptions memindai aliran log, baik data log tidak terstruktur (teks) atau data log format JSON, untuk pelacakan tumpukan pengecualian multi-baris. Jika urutan entri log berturut-turut membentuk stack trace pengecualian, entri log akan diteruskan sebagai pesan log gabungan tunggal. Jika tidak, entri log akan diteruskan sebagaimana mestinya.

Definisi konfigurasi lanjutan (non-default)

Jika Anda ingin menyesuaikan konfigurasi agen Logging, selain konfigurasi default, lanjutkan baca halaman ini.

Opsi konfigurasi berikut memungkinkan Anda menyesuaikan mekanisme buffering internal agen Logging.

Nama konfigurasi Jenis Default Deskripsi
buffer_type string buf_memory Kumpulan data yang tidak dapat ditulis ke Logging API dengan cukup cepat akan dikirim ke buffer. Buffer dapat berada di memori atau file sebenarnya. Nilai yang direkomendasikan: buf_file. buf_memory default adalah cepat, tetapi tidak persisten. Ada risiko kehilangan log. Jika buffer_type adalah buf_file, buffer_path juga harus ditentukan.
buffer_path string Ditentukan pengguna Jalur tempat potongan {i>buffer<i} disimpan. Parameter ini wajib ada jika buffer_type adalah file. Konfigurasi ini harus unik untuk menghindari kondisi race.
buffer_queue_limit int 64 Menentukan batas panjang antrean potongan. Saat antrean buffer mencapai jumlah bagian ini, perilaku buffer dikontrol oleh buffer_queue_full_action. Secara default, opsi ini menampilkan pengecualian. Opsi yang dikombinasikan dengan buffer_chunk_limit ini menentukan ruang disk maksimum yang diperlukan fluentd untuk buffering.
buffer_queue_full_action string exception Mengontrol perilaku buffer saat antrean buffer penuh. Nilai yang memungkinkan:
1. exception: Menampilkan BufferQueueLimitError saat antrean penuh. Cara penanganan BufferQueueLimitError bergantung pada plugin input. Misalnya, plugin input in_tail berhenti membaca baris baru sementara plugin input in_forward menampilkan error.
2. block: Mode ini menghentikan thread plugin input hingga kondisi buffer penuh diselesaikan. Tindakan ini bagus untuk kasus penggunaan seperti batch. fluentd tidak merekomendasikan penggunaan tindakan blokir untuk menghindari BufferQueueLimitError. Jika Anda sering menekan BufferQueueLimitError, berarti kapasitas tujuan tidak cukup untuk traffic Anda.
3. drop_oldest_chunk: Mode ini menghapus bagian yang paling lama.

Opsi konfigurasi berikut memungkinkan Anda menentukan project dan kolom tertentu secara manual dari objek MonitoredResource. Nilai ini otomatis dikumpulkan oleh agen Logging; sebaiknya Anda tidak menentukannya secara manual.

Nama konfigurasi Jenis Default Deskripsi
project_id string nil Jika ditentukan, metode ini akan menggantikan project_id yang mengidentifikasi project Google Cloud atau AWS dasar tempat agen Logging dijalankan.
zone string nil Jika ditentukan, ini akan mengganti zona.
vm_id string nil Jika ditentukan, ID VM ini akan diganti.
vm_name string nil Jika ditentukan, nama VM akan diganti.

Opsi konfigurasi plugin output lainnya

Nama konfigurasi Jenis Default Deskripsi
detect_json1 bool false Apakah akan mencoba mendeteksi apakah data log adalah entri log teks dengan konten JSON yang perlu diuraikan. Jika opsi ini adalah true, dan entri log tidak terstruktur (teks) terdeteksi dalam format JSON, entri tersebut akan diuraikan dan dikirim sebagai payload terstruktur (JSON).
coerce_to_utf8 bool true Apakah akan mengizinkan karakter non-UTF-8 di log pengguna. Jika disetel ke true, karakter non-UTF-8 akan diganti dengan string yang ditentukan oleh non_utf8_replacement_string. Jika disetel ke false, karakter non-UTF-8 akan memicu plugin mengalami error.
require_valid_tags bool false Apakah akan menolak entri log dengan tag yang tidak valid. Jika opsi ini disetel ke false, tag akan dibuat valid dengan mengonversi tag non-string menjadi string, dan membersihkan karakter non-UTF-8 atau karakter tidak valid lainnya.
non_utf8_replacement_string string ""(spasi) Jika coerce_to_utf8 disetel ke true, karakter non-UTF-8 akan diganti dengan string yang ditentukan di sini.

1Fitur ini diaktifkan secara default di instance VM yang berjalan di lingkungan fleksibel App Engine dan Google Kubernetes Engine.

Menerapkan konfigurasi agen yang disesuaikan

Dengan menyesuaikan agen Logging, Anda dapat menambahkan file konfigurasi fluentd Anda sendiri:

Instance Linux

  1. Salin file konfigurasi Anda ke direktori berikut:

    /etc/google-fluentd/config.d/
    

    Skrip penginstalan agen Logging mengisi direktori ini dengan file konfigurasi catch-all default. Untuk informasi selengkapnya, lihat Mendapatkan kode sumber agen Logging.

  2. Opsional. Validasi perubahan konfigurasi Anda dengan menjalankan perintah berikut:

    sudo service google-fluentd configtest
    
  3. Mulai ulang agen dengan menjalankan perintah berikut:

    sudo service google-fluentd force-reload
    

Instance Windows

  1. Salin file konfigurasi ke subdirektori config.d dari direktori penginstalan agen. Jika Anda menerima direktori penginstalan default, direktori ini adalah:

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
    
  2. Mulai ulang agen dengan menjalankan perintah berikut dalam shell command line:

    net stop  StackdriverLogging
    net start StackdriverLogging
    

Untuk informasi selengkapnya tentang file konfigurasi fluentd, lihat dokumentasi Sintaksis File Konfigurasi fluentd.