Gunakan plugin logstash-input-oss untuk baca data dari OSS - Elasticsearch

Plug-in logstash-input-oss menghubungkan Alibaba Cloud Logstash ke Object Storage Service (OSS) melalui Simple Message Queue (formerly MNS) (SMQ). Ketika objek OSS diperbarui, SMQ mengirimkan notifikasi ke plug-in tersebut, yang kemudian memicu Logstash untuk membaca data terbaru dari OSS.

logstash-input-oss adalah plug-in open source. Untuk informasi lebih lanjut, lihat repositori GitHub.

Cara kerja

Objek OSS dibuat atau diperbarui (misalnya, melalui PutObject atau AppendObject).
OSS mengirimkan notifikasi event ke antrian SMQ.
Plug-in menerima notifikasi SMQ dan mengekstraksi kunci objek.
Logstash membaca seluruh data dalam objek tersebut dan mengirimkannya ke tahap berikutnya melalui pipeline.

Catatan penggunaan

Setelah menerima notifikasi SMQ, Logstash menyinkronkan seluruh data dalam objek terkait — bukan hanya delta-nya.
Objek dalam format .gz atau .gzip diproses sebagai gzip. Semua format lain diproses sebagai teks biasa.
Objek dalam format biner (seperti .jar atau .bin) mungkin dibaca sebagai karakter acak (garbled).

Prasyarat

Sebelum memulai, pastikan Anda telah:

Menginstal plug-in logstash-input-oss. Lihat Instal atau hapus plug-in Logstash.
Mengaktifkan OSS dan SMQ, dengan bucket OSS berada di wilayah yang sama dengan antrian atau topik SMQ. Lihat Aktifkan OSS dan Aktifkan SMQ dan otorisasi pengguna RAM untuk mengakses SMQ.
Mengonfigurasi aturan notifikasi event di OSS. Lihat Konfigurasi aturan notifikasi event.

Buat pipeline

Buat pipeline menggunakan file konfigurasi seperti yang dijelaskan dalam Gunakan file konfigurasi untuk mengelola pipeline. Konfigurasikan parameter pada bagian Parameter, lalu simpan dan deploy pipeline tersebut.

Contoh berikut membaca data dari bucket OSS dan menuliskannya ke Alibaba Cloud Elasticsearch.

input {
  oss {
    endpoint => "oss-cn-hangzhou-internal.aliyuncs.com"
    bucket => "zl-ossou****"
    access_key_id => "******"
    access_key_secret => "*********"
    prefix => "file-sample-prefix"
    mns_settings => {
      endpoint => "******.mns.cn-hangzhou-internal.aliyuncs.com"
      queue => "aliyun-es-sample-mns"
    }
    codec => json {
      charset => "UTF-8"
    }
  }
}

output {
  elasticsearch {
    hosts => ["http://es-cn-***.elasticsearch.aliyuncs.com:9200"]
    index => "aliyun-es-sample"
    user => "elastic"
    password => "changeme"
  }
}

Penting

Titik akhir SMQ harus berupa titik akhir internal dan tidak boleh diawali dengan http. Penggunaan titik akhir eksternal akan menyebabkan error.

Parameter

Parameter wajib

Parameter	Tipe	Deskripsi
`endpoint`	string	Titik akhir yang digunakan untuk mengakses OSS. Lihat Wilayah, titik akhir, dan port terbuka.
`bucket`	string	Nama bucket OSS.
`access_key_id`	string	ID AccessKey Akun Alibaba Cloud Anda.
`access_key_secret`	string	Rahasia AccessKey Akun Alibaba Cloud Anda.
`mns_settings`	hash	Konfigurasi SMQ. Lihat Sub-parameter mns_settings.

Parameter opsional

Parameter	Tipe	Default	Deskripsi
`prefix`	string	—	Memfilter objek berdasarkan awalan nama. Logstash hanya membaca objek yang namanya diawali dengan nilai ini. Bukan ekspresi reguler. Gunakan parameter ini untuk membaca dari direktori tertentu dalam bucket.
`additional_oss_settings`	hash	—	Pengaturan tambahan klien OSS. Sub-parameter yang didukung: `secure_connection_enabled` (aktifkan koneksi aman) dan `max_connections_to_oss` (jumlah maksimum koneksi ke OSS).
`delete`	boolean	`false`	Apakah objek yang telah diproses dihapus dari bucket OSS sumber setelah dibaca.
`backup_to_bucket`	string	—	Nama bucket OSS tempat objek yang telah diproses dibackup.
`backup_to_dir`	string	—	Direktori lokal tempat file yang telah diproses dibackup.
`backup_add_prefix`	string	—	Awalan yang ditambahkan ke kunci objek setelah pemrosesan. Kunci tersebut adalah path lengkap termasuk nama objek di OSS. Gunakan parameter ini untuk menyimpan backup di folder tertentu dalam bucket yang sama atau berbeda.
`include_object_properties`	boolean	—	Apakah properti objek OSS (`last_modified`, `content_type`, dan `metadata`) disertakan dalam `[@metadata][oss]`. Jika tidak diatur, hanya `[@metadata][oss][key]` yang tersedia.
`exclude_pattern`	string	—	Ekspresi reguler Ruby yang mencocokkan kunci objek yang akan dilewati. Misalnya, `"\/logs\/debug\/"` mengecualikan semua objek yang memiliki `/logs/debug/` dalam path-nya.

Sub-parameter mns_settings

Sub-parameter	Wajib	Default	Deskripsi
`endpoint`	Ya	—	Titik akhir SMQ. Harus berupa titik akhir internal dan tidak boleh mencantumkan `http`.
`queue`	Ya	—	Nama antrian SMQ.
`poll_interval_seconds`	Tidak	`10`	Waktu tunggu maksimum (dalam detik) untuk permintaan ReceiveMessage saat antrian kosong. Lihat ReceiveMessage.
`wait_seconds`	Tidak	—	Waktu tunggu polling maksimum (dalam detik) untuk permintaan ReceiveMessage.

Metadata objek

Ketika include_object_properties diaktifkan, plug-in mengekspos bidang-bidang berikut dalam [@metadata][oss]. Gunakan bidang-bidang ini pada tahap filter atau output untuk memperkaya event atau menerapkan logika kondisional.

Bidang	Tipe	Deskripsi
`[@metadata][oss][key]`	string	Kunci objek lengkap (path) di OSS. Selalu tersedia, terlepas dari pengaturan `include_object_properties`.
`[@metadata][oss][last_modified]`	string	Timestamp saat objek terakhir dimodifikasi. Tersedia ketika `include_object_properties` bernilai `true`.
`[@metadata][oss][content_type]`	string	Tipe MIME objek. Tersedia ketika `include_object_properties` bernilai `true`.
`[@metadata][oss][metadata]`	hash	Metadata kustom yang ditentukan pengguna dan dilampirkan pada objek. Tersedia ketika `include_object_properties` bernilai `true`.

FAQ

Mengapa plug-in ini berbasis SMQ alih-alih melakukan polling langsung ke OSS?

Event pembaruan objek OSS terintegrasi secara mulus dengan SMQ, sehingga mekanisme notifikasi berbasis pesan menjadi pilihan yang alami. Alternatifnya — menggunakan API ListObjects — memerlukan pelacakan objek yang sudah dan belum diproses dalam penyimpanan lokal. Seiring bertambahnya jumlah objek, performa ListObjects menurun. Ekosistem penyimpanan objek yang lebih luas (termasuk komunitas open source Amazon S3) juga telah beralih dari ListObjects ke mekanisme notifikasi berbasis pesan.

Apa yang terjadi jika Logstash dipicu saat OSS masih menulis data ke objek?

Plug-in mencatat di antrian SMQ objek mana saja yang telah ditulis dan mengirimkannya melalui pipeline Logstash. Data yang belum selesai ditulis ke OSS akan tetap dilanjutkan penulisannya. Saat Logstash dipicu berikutnya, plug-in akan membaca sisa data tersebut dari OSS.

Elasticsearch:Gunakan plug-in logstash-input-oss