Mengakses data telemetri real-time untuk ekstensi menggunakan API Telemetri

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

API Telemetri memungkinkan ekstensi Anda menerima data telemetri langsung dari Lambda. Selama inisialisasi dan pemanggilan fungsi, Lambda secara otomatis menangkap telemetri, termasuk log, metrik platform, dan jejak platform. API Telemetri memungkinkan ekstensi untuk mengakses data telemetri ini langsung dari Lambda dalam waktu dekat.

Dalam lingkungan eksekusi Lambda, Anda dapat berlangganan ekstensi Lambda Anda ke aliran telemetri. Setelah berlangganan, Lambda secara otomatis mengirimkan semua data telemetri ke ekstensi Anda. Anda kemudian memiliki fleksibilitas untuk memproses, memfilter, dan mengirimkan data ke tujuan pilihan Anda, seperti bucket Amazon Simple Storage Service (Amazon S3) atau penyedia alat observabilitas bagian ketiga.

Diagram berikut menunjukkan bagaimana Extensions API dan Telemetry API menghubungkan ekstensi ke Lambda dari dalam lingkungan eksekusi. Selain itu, Runtime API menghubungkan runtime dan fungsi Anda ke Lambda.

Ekstensi dapat menggunakan API Telemetri untuk berlangganan tiga aliran telemetri yang berbeda:

Membuat ekstensi menggunakan API Telemetri

Ekstensi Lambda berjalan sebagai proses independen di lingkungan eksekusi. Ekstensi dapat terus berjalan setelah pemanggilan fungsi selesai. Karena ekstensi adalah proses yang terpisah, Anda dapat menulisnya dalam bahasa yang berbeda dari kode fungsi. Kami merekomendasikan menulis ekstensi menggunakan bahasa yang dikompilasi seperti Golang atau Rust. Dengan cara ini, ekstensi adalah biner mandiri yang dapat kompatibel dengan runtime yang didukung.

Diagram berikut menggambarkan proses empat langkah untuk membuat ekstensi yang menerima dan memproses data telemetri menggunakan API Telemetri.

Berikut adalah setiap langkah secara lebih rinci:

Mendaftarkan ekstensi Anda

Sebelum Anda dapat berlangganan data telemetri, Anda harus mendaftarkan ekstensi Lambda Anda. Registrasi terjadi selama fase inisialisasi ekstensi. Contoh berikut menunjukkan permintaan HTTP untuk mendaftarkan ekstensi.

POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register
 Lambda-Extension-Name: lambda_extension_name
{
    'events': [ 'INVOKE', 'SHUTDOWN']
}

Jika permintaan berhasil, pelanggan akan menerima respons keberhasilan HTTP 200. Header respon berisi fileLambda-Extension-Identifier. Badan respons mengandung sifat lain dari fungsi tersebut.

HTTP/1.1 200 OK
Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
    "functionName": "lambda_function",
    "functionVersion": "$LATEST",
    "handler": "lambda_handler",
    "accountId": "123456789012"
}

Untuk informasi selengkapnya, lihat Referensi API ekstensi.

Membuat pendengar telemetri

Ekstensi Lambda Anda harus memiliki listener yang menangani permintaan masuk dari API Telemetri. Kode berikut menunjukkan contoh implementasi pendengar telemetri di Golang:

// Starts the server in a goroutine where the log events will be sent
func (s *TelemetryApiListener) Start() (string, error) {
	address := listenOnAddress()
	l.Info("[listener:Start] Starting on address", address)
	s.httpServer = &http.Server{Addr: address}
	http.HandleFunc("/", s.http_handler)
	go func() {
		err := s.httpServer.ListenAndServe()
		if err != http.ErrServerClosed {
			l.Error("[listener:goroutine] Unexpected stop on Http Server:", err)
			s.Shutdown()
		} else {
			l.Info("[listener:goroutine] Http Server closed:", err)
		}
	}()
	return fmt.Sprintf("http://%s/", address), nil
}

// http_handler handles the requests coming from the Telemetry API.
// Everytime Telemetry API sends log events, this function will read them from the response body
// and put into a synchronous queue to be dispatched later.
// Logging or printing besides the error cases below is not recommended if you have subscribed to
// receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for
// the printed lines which may create an infinite loop.
func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) {
	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		l.Error("[listener:http_handler] Error reading body:", err)
		return
	}

	// Parse and put the log messages into the queue
	var slice []interface{}
	_ = json.Unmarshal(body, &slice)

	for _, el := range slice {
		s.LogEventsQueue.Put(el)
	}

	l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len())
	slice = nil
}

Menentukan protokol tujuan

Saat berlangganan untuk menerima telemetri menggunakan API Telemetri, Anda dapat menentukan protokol tujuan selain URI tujuan:

{
    "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
    }
}

Lambda menerima dua protokol untuk menerima telemetri:

Sebelum berlangganan untuk menerima telemetri, buat pendengar HTTP lokal atau port TCP. Selama penyetelan, perhatikan hal berikut ini:

Mengkonfigurasi penggunaan memori dan buffering

Penggunaan memori di lingkungan eksekusi tumbuh secara linier dengan jumlah pelanggan. Langganan mengkonsumsi sumber daya memori karena masing-masing membuka buffer memori baru untuk menyimpan data telemetri. Penggunaan memori buffer berkontribusi pada konsumsi memori secara keseluruhan di lingkungan eksekusi.

Saat berlangganan untuk menerima telemetri melalui API Telemetri, Anda memiliki opsi untuk menyangga data telemetri dan mengirimkannya ke pelanggan dalam batch. Untuk mengoptimalkan penggunaan memori, Anda dapat menentukan konfigurasi buffering:

{
    "buffering": {
        "maxBytes": 256*1024,
        "maxItems": 1000,
        "timeoutMs": 100
    }
}

Saat menyiapkan buffering, ingatlah poin-poin ini:

Mengirim permintaan berlangganan ke API Telemetri

Ekstensi Lambda dapat berlangganan untuk menerima data telemetri dengan mengirimkan permintaan berlangganan ke API Telemetri. Permintaan berlangganan harus berisi informasi tentang jenis acara yang Anda inginkan untuk berlangganan ekstensi. Selain itu, permintaan dapat berisi informasi tujuan pengiriman dan konfigurasi buffering.

Sebelum mengirim permintaan berlangganan, Anda harus memiliki ID ekstensi (Lambda-Extension-Identifier). Saat mendaftarkan ekstensi dengan Extensions API, Anda mendapatkan ID ekstensi dari respons API.

Langganan terjadi selama fase inisialisasi ekstensi. Contoh berikut menunjukkan permintaan HTTP untuk berlangganan ketiga aliran telemetri: telemetri platform, log fungsi, dan log ekstensi.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1
{
   "schemaVersion": "2022-12-13",
   "types": [
        "platform",
        "function",
        "extension"
   ],
   "buffering": {
        "maxItems": 1000,
        "maxBytes": 256*1024,
        "timeoutMs": 100
   },
   "destination": {
        "protocol": "HTTP",
        "URI": "http://sandbox.localdomain:8080"
   }
}

Jika permintaan berhasil, maka pelanggan menerima respons sukses HTTP 200.

HTTP/1.1 200 OK
"OK"

Pesan API Telemetri Masuk

Setelah berlangganan menggunakan API Telemetri, ekstensi secara otomatis mulai menerima telemetri dari Lambda melalui permintaan POST. Setiap badan permintaan POST berisi array Event objek. Masing-masing Event memiliki skema berikut:

{
   time: String,
   type: String,
   record: Object
}

Tabel berikut merangkum semua jenis Event objek, dan menautkan ke referensi Event skema API Telemetri untuk setiap jenis peristiwa.