Menggunakan Ekstensi Lambda API untuk membuat ekstensi

Penulis fungsi Lambda menggunakan ekstensi untuk mengintegrasikan Lambda Anda dengan alat pilihan mereka untuk pemantauan, pengamatan, keamanan, dan pengaturan. Penulis fungsi dapat menggunakan ekstensi dari AWS, AWS Mitra, dan proyek sumber terbuka. Untuk informasi selengkapnya tentang penggunaan ekstensi, lihat Memperkenalkan AWS Lambda Ekstensi di Blog AWS Komputasi. Bagian ini menjelaskan cara menggunakan Ekstensi LambdaAPI, siklus hidup lingkungan eksekusi Lambda, dan referensi Ekstensi Lambda. API

Sebagai pembuat ekstensi, Anda dapat menggunakan Ekstensi Lambda API untuk mengintegrasikan secara mendalam ke dalam lingkungan eksekusi Lambda. Ekstensi Anda dapat mendaftar untuk fungsi dan peristiwa siklus hidup lingkungan eksekusi. Menanggapi peristiwa ini, Anda dapat memulai proses baru, menjalankan logika, dan mengontrol serta berpartisipasi dalam semua fase siklus hidup Lambda: inisialisasi, invokasi, dan penonaktifan. Selain itu, Anda dapat menggunakan Runtime Logs API untuk menerima aliran log.

Ekstensi berjalan sebagai proses independen di lingkungan eksekusi dan dapat terus berjalan setelah invokasi fungsi diproses sepenuhnya. Karena ekstensi berjalan sebagai proses, Anda dapat menulisnya dalam bahasa yang berbeda dari fungsi. Sebaiknya terapkan ekstensi eksternal menggunakan bahasa terkompilasi. Dalam hal ini, ekstensi adalah biner mandiri yang kompatibel dengan runtime yang didukung. Semua ekstensi Runtime Lambda dukungan. Jika Anda menggunakan bahasa nonkompilasi, pastikan Anda memasukkan waktu pengoperasian yang kompatibel di ekstensi.

Lambda juga mendukung ekstensi internal. Ekstensi internal berjalan sebagai thread terpisah dari proses runtime. Runtime memulai dan menghentikan ekstensi internal. Cara alternatif untuk berintegrasi dengan lingkungan Lambda adalah dengan menggunakan variabel lingkungan dan skrip wrapper khusus bahasa. Anda dapat menggunakan ini untuk mengonfigurasi lingkungan runtime dan memodifikasi perilaku startup proses runtime.

Anda dapat menambahkan ekstensi ke fungsi dengan dua cara. Untuk fungsi yang di-deploy sebagaiarsip file .zip, Anda men-deploy ekstensi sebagai lapisan. Untuk fungsi yang didefinisikan sebagai gambar kontainer, Anda menambahkan ekstensi ke gambar kontainer Anda.

Siklus hidup lingkungan eksekusi Lambda

Siklus hidup lingkungan eksekusi mencakup fase-fase berikut:

Setiap fase dimulai dengan peristiwa dari Lambda ke runtime dan ke semua ekstensi terdaftar. Runtime dan setiap ekstensi sinyal selesai dengan mengirimkan Next API permintaan. Lambda membekukan lingkungan eksekusi saat waktu proses telah selesai dan tidak ada kejadian yang tertunda.

Fase inisialisasi

Selama fase Extension init, setiap ekstensi perlu mendaftarkan dengan Lambda untuk menerima kejadian. Lambda menggunakan nama file ekstensi lengkap untuk memvalidasi bahwa ekstensi telah menyelesaikan sekuens bootstrap. Oleh karena itu, setiap Register API panggilan harus menyertakan Lambda-Extension-Name header dengan nama file lengkap ekstensi.

Anda dapat mendaftarkan hingga 10 ekstensi untuk satu fungsi. Batas ini diberlakukan melalui Register API panggilan.

Setelah setiap ekstensi mendaftar, Lambda memulai fase Runtime init. Proses runtime memanggil functionInit untuk memulai fase Function init.

InitFase selesai setelah runtime dan setiap ekstensi terdaftar menunjukkan penyelesaian dengan mengirimkan permintaan. Next API

Fase invokasi

Ketika fungsi Lambda dipanggil sebagai respons terhadap permintaan NextAPI, Lambda mengirimkan Invoke acara ke runtime dan ke setiap ekstensi yang terdaftar untuk acara tersebut. Invoke

Selama invokasi, ekstensi eksternal berjalan secara paralel dengan fungsi. Ekstensi ini juga terus berjalan setelah fungsi selesai. Ini memungkinkan Anda menangkap informasi diagnostik atau mengirim log, metrik, dan jejak ke lokasi pilihan Anda.

Setelah menerima respon fungsi dari runtime, Lambda mengembalikan respon ke klien, bahkan jika ekstensi masih berjalan.

InvokeFase berakhir setelah runtime dan semua ekstensi memberi sinyal bahwa mereka dilakukan dengan mengirim Next API permintaan.

Muatan peristiwa: Peristiwa yang dikirim ke runtime (dan fungsi Lambda) memuat seluruh permintaan, header (seperti RequestId), dan muatan. Kejadian yang dikirim ke setiap ekstensi berisi metadata yang menjelaskan konten kejadian. Peristiwa siklus hidup ini mencakup jenis peristiwa, waktu fungsi times out (deadlineMs), Amazon Resource Name (ARN) fungsi yang dipanggilrequestId, dan header penelusuran.

Ekstensi yang ingin mengakses badan acara fungsi dapat menggunakan in-runtime SDK yang berkomunikasi dengan ekstensi. Pengembang fungsi menggunakan in-runtime SDK untuk mengirim payload ke ekstensi saat fungsi dipanggil.

Berikut adalah contoh muatan:

{
    "eventType": "INVOKE",
    "deadlineMs": 676051,
    "requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
    "invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",
    "tracing": {
        "type": "X-Amzn-Trace-Id",
        "value": "Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
    }
 }          

Batas durasi: Pengaturan batas waktu fungsi membatasi durasi seluruh Invoke fase. Misalnya, jika Anda mengatur waktu fungsi habis sebagai 360 detik, fungsi dan semua ekstensi harus selesai dalam 360 detik. Perhatikan bahwa tidak ada fase pasca-invokasi yang independen. Durasi adalah total waktu yang dibutuhkan untuk runtime Anda dan semua pemanggilan ekstensi Anda selesai dan tidak dihitung sampai fungsi dan semua ekstensi selesai berjalan.

Dampak performa dan pengeluaran tambahan ekstensi: Ekstensi dapat memengaruhi performa fungsi. Sebagai penulis ekstensi, Anda memiliki kontrol atas dampak kinerja dari ekstensi Anda. Misalnya, jika ekstensi Anda melakukan operasi komputasi intensif, durasi fungsi meningkat karena ekstensi dan kode fungsi berbagi sumber daya yang sama. CPU Selain itu, jika ekstensi Anda melakukan operasi ekstensif setelah invokasi fungsi selesai, durasi fungsi meningkat karena fase Invoke berlanjut hingga semua sinyal ekstensi selesai.

Untuk membantu mengidentifikasi dampak performa yang muncul karena ekstensi di fase Invoke, Lambda mengeluarkan metrik PostRuntimeExtensionsDuration. Metrik ini mengukur waktu kumulatif yang dihabiskan antara permintaan runtime dan Next API permintaan ekstensi terakhir. Next API Untuk mengukur peningkatan memori yang digunakan, gunakan metrik MaxMemoryUsed. Untuk informasi selengkapnya tentang fungsi metrik, lihat Lihat metrik untuk fungsi Lambda.

Pengembang fungsi dapat menjalankan versi fungsi yang berbeda secara berdampingan untuk memahami dampak ekstensi tertentu. Kami merekomendasikan agar penulis ekstensi memublikasikan konsumsi sumber daya yang diharapkan untuk mempermudah pengembang fungsi dalam memilih ekstensi yang sesuai.

Fase pematian

Ketika Lambda akan mematikan runtime, Lambda mengirimkan Shutdown ke setiap ekstensi eksternal terdaftar. Ekstensi dapat menggunakan waktu ini untuk tugas pembersihan akhir. ShutdownAcara dikirim sebagai tanggapan Next API atas permintaan.

Batas durasi: Durasi maksimum fase Shutdown bergantung pada konfigurasi ekstensi terdaftar:

Untuk fungsi dengan ekstensi eksternal, Lambda mencadangkan hingga 300 md (500 md untuk waktu pengoperasian ekstensi internal) untuk proses waktu pengoperasian dalam melakukan pematian yang lancar. Lambda mengalokasikan sisa batas 2.000 md untuk mematikan ekstensi eksternal.

Jika waktu pengoperasian atau ekstensi tidak merespons kejadian Shutdown dalam batasan, Lambda mengakhiri proses menggunakan sinyal SIGKILL.

Muatan peristiwa: Peristiwa Shutdown tersebut berisi alasan penonaktifan dan waktu yang tersisa dalam milidetik.

shutdownReason mencakup nilai-nilai berikut:

{ 
  "eventType": "SHUTDOWN", 
  "shutdownReason": "reason for shutdown", 
  "deadlineMs": "the time and date that the function times out in Unix time milliseconds" 
}        
      

Izin dan konfigurasi

Ekstensi berjalan di lingkungan eksekusi yang sama dengan fungsi Lambda. Ekstensi juga berbagi sumber daya dengan fungsi, sepertiCPU, memori, dan penyimpanan /tmp disk. Selain itu, ekstensi menggunakan peran AWS Identity and Access Management (IAM) dan konteks keamanan yang sama dengan fungsi.

Sistem file dan izin akses jaringan: Ekstensi berjalan di namespace sistem file dan jaringan yang sama dengan runtime fungsi. Ini berarti ekstensi harus kompatibel dengan sistem operasi terkait. Jika ekstensi memerlukan aturan lalu lintas jaringan keluar, Anda harus menerapkan aturan ini ke konfigurasi fungsi.

Variabel lingkungan: Ekstensi dapat mengakses variabel lingkungan fungsi, kecuali untuk variabel berikut yang spesifik untuk proses runtime:

Penanganan kegagalan

Kegagalan insialisasi: Jika ekstensi gagal, Lambda memulai ulang lingkungan eksekusi untuk memberlakukan perilaku yang konsisten dan mendorong kegagalan cepat untuk ekstensi. Selain itu, untuk beberapa pelanggan, ekstensi tersebut harus memenuhi kebutuhan kritis misi, seperti pencatatan log, keamanan, tata kelola, dan pengumpulan telemetri.

Memanggil kegagalan (seperti kehabisan memori, waktu habis fungsi): Karena ekstensi berbagi sumber daya dengan runtime, kehabisan dapat memengaruhi keduanya. Saat waktu pengoperasian gagal, semua ekstensi dan waktu pengoperasian sendiri ikut serta dalam fase Shutdown. Selain itu, waktu pengoperasian dimulai ulang—baik otomatis sebagai bagian dari invokasi saat ini, atau melalui mekanisme inisialisasi ulang yang ditangguhkan.

Jika ada kegagalan (seperti waktu fungsi habis atau kesalahan waktu pengoperasian) selama Invoke, layanan Lambda akan melakukan reset. Reset berperilaku seperti kejadian Shutdown. Pertama, Lambda mematikan waktu pengoperasian, lalu ia mengirim kejadian Shutdown untuk setiap ekstensi eksternal terdaftar. Kejadian ini mencakup alasan untuk pematian. Jika lingkungan ini digunakan untuk invokasi baru, ekstensi dan waktu pengoperasian diinisialisasi ulang sebagai bagian dari invokasi berikutnya.

Untuk penjelasan lebih rinci tentang diagram sebelumnya, lihatKegagalan selama fase pemanggilan.

Log ekstensi: Lambda mengirimkan keluaran log ekstensi ke CloudWatch Log. Lambda juga menghasilkan log acara tambahan untuk setiap ekstensi selama Init. Log acara mencatat preferensi nama dan registrasi (peristiwa, konfigurasi) saat berhasil, atau alasan kegagalan saat gagal.

Pemecahan masalah ekstensi

APIReferensi ekstensi

APISpesifikasi Terbuka untuk ekstensi API versi 2020-01-01 tersedia di sini: extensions-api.zip

Anda dapat mengambil nilai API endpoint dari variabel AWS_LAMBDA_RUNTIME_API lingkungan. Untuk mengirim Register permintaan, gunakan awalan 2020-01-01/ sebelum setiap API jalur. Sebagai contoh:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register 

Pendaftaran

Selama Extension init, semua ekstensi perlu mendaftar dengan Lambda untuk menerima kejadian. Lambda menggunakan nama file ekstensi lengkap untuk memvalidasi bahwa ekstensi telah menyelesaikan sekuens bootstrap. Oleh karena itu, setiap Register API panggilan harus menyertakan Lambda-Extension-Name header dengan nama file lengkap ekstensi.

Ekstensi internal dimulai dan dihentikan oleh proses waktu pengoperasian sehingga tidak diizinkan untuk terdaftar untuk kejadian Shutdown.

Jalur – /extension/register

Metode - POST

Minta header

{
    'events': [ 'INVOKE', 'SHUTDOWN']
}             

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler"
}               

{
    "functionName": "helloWorld",
    "functionVersion": "$LATEST",
    "handler": "lambda_function.lambda_handler",
    "accountId": "123456789012"
}

Selanjutnya

Ekstensi mengirim Next API permintaan untuk menerima acara berikutnya, yang dapat berupa Invoke acara atau Shutdown acara. Badan respons berisi payload, yang merupakan JSON dokumen yang berisi data peristiwa.

Ekstensi mengirimkan Next API permintaan untuk memberi sinyal bahwa ia siap menerima acara baru. Ini adalah panggilan blokir.

Jangan mengatur batas waktu pada GET panggilan, karena ekstensi dapat ditangguhkan untuk jangka waktu tertentu sampai ada acara untuk kembali.

Jalur – /extension/event/next

Metode - GET

Kesalahan init

Ekstensi menggunakan metode ini untuk melaporkan kesalahan inisialisasi ke Lambda. Panggil ini saat ekstensi gagal menginisialisasi setelah ia terdaftar. Setelah Lambda menerima kesalahan, tidak ada API panggilan lebih lanjut yang berhasil. Ekstensi harus keluar setelah menerima respon dari Lambda.

Jalur – /extension/init/error

Metode - POST

Bidang ini adalah JSON objek dengan struktur sebagai berikut:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Perhatikan bahwa Lambda menerima nilai apa pun untuk errorType.

Contoh berikut menunjukkan pesan kesalahan fungsi Lambda ketika fungsi tidak dapat mengurai data peristiwa yang disediakan dalam invokasi.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}      

Kesalahan keluar

Ekstensi menggunakan metode ini untuk melaporkan kesalahan ke Lambda sebelum keluar. Panggil ini saat Anda mengalami kegagalan tak terduga. Setelah Lambda menerima kesalahan, tidak ada API panggilan lebih lanjut yang berhasil. Ekstensi harus keluar setelah menerima respon dari Lambda.

Jalur – /extension/exit/error

Metode - POST

Bidang ini adalah JSON objek dengan struktur sebagai berikut:

{
      errorMessage: string (text description of the error),
      errorType: string,
      stackTrace: array of strings
}

Perhatikan bahwa Lambda menerima nilai apa pun untuk errorType.

Contoh berikut menunjukkan pesan kesalahan fungsi Lambda ketika fungsi tidak dapat mengurai data peristiwa yang disediakan dalam invokasi.

{
      "errorMessage" : "Error parsing event data.",
      "errorType" : "InvalidEventDataException",
      "stackTrace": [ ]
}