Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Mengakses data telemetri real-time untuk ekstensi menggunakan API Telemetri 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 pihak 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, Telemetri, dan Runtime APIs terhubung ke proses di lingkungan eksekusi.](http://docs.aws.amazon.com/id_id/lambda/latest/dg/images/telemetry-api-concept-diagram.png) **penting** API Telemetri Lambda menggantikan API Lambda Logs. **Meskipun API Log tetap berfungsi penuh, kami sarankan hanya menggunakan API Telemetri di masa mendatang.** Anda dapat berlangganan ekstensi Anda ke aliran telemetri menggunakan API Telemetri atau API Log. Setelah berlangganan menggunakan salah satu dari ini APIs, setiap upaya untuk berlangganan menggunakan API lain mengembalikan kesalahan. **Persyaratan versi skema Instans Terkelola Lambda** Instans Terkelola Lambda hanya mendukung versi `2025-01-29` skema API Telemetri. Saat berlangganan aliran telemetri untuk fungsi Instans Terkelola, Anda **harus** menggunakannya `"schemaVersion": "2025-01-29"` dalam permintaan langganan. Menggunakan versi skema sebelumnya akan mengakibatkan peristiwa ditolak oleh Lambda. Versi `2025-01-29` skema kompatibel ke belakang dan dapat digunakan dengan fungsi Lambda Managed Instances dan Lambda (default). Sebaiknya gunakan versi ini untuk semua ekstensi baru guna memastikan kompatibilitas di kedua model penerapan. Ekstensi dapat menggunakan API Telemetri untuk berlangganan tiga aliran telemetri yang berbeda: + **Telemetri platform** — Log, metrik, dan jejak, yang menjelaskan peristiwa dan kesalahan yang terkait dengan siklus hidup runtime lingkungan eksekusi, siklus hidup ekstensi, dan pemanggilan fungsi. + **Log fungsi** - Log khusus yang dihasilkan oleh kode fungsi Lambda. + **Log ekstensi** - Log khusus yang dihasilkan oleh kode ekstensi Lambda. **catatan** Lambda mengirimkan log dan metrik ke CloudWatch, dan melacak ke X-Ray (jika Anda telah mengaktifkan penelusuran), bahkan jika ekstensi berlangganan aliran telemetri. **Topics** + [Membuat ekstensi menggunakan API Telemetri](#telemetry-api-creating-extensions) + [Mendaftarkan ekstensi Anda](#telemetry-api-registration) + [Membuat pendengar telemetri](#telemetry-api-listener) + [Menentukan protokol tujuan](#telemetry-api-destination) + [Mengkonfigurasi penggunaan memori dan buffering](#telemetry-api-buffering) + [Mengirim permintaan berlangganan ke API Telemetri](#telemetry-api-subscription) + [Pesan API Telemetri Masuk](#telemetry-api-messages) + [Referensi API Telemetri Lambda](telemetry-api-reference.md) + [Referensi skema API Telemetri Lambda `Event`](telemetry-schema-reference.md) + [Mengonversi objek API `Event` Telemetri Lambda ke Span OpenTelemetry](telemetry-otel-spans.md) + [Menggunakan Lambda Logs API](runtimes-logs-api.md) ## 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. ![Daftarkan ekstensi Anda, buat pendengar, berlangganan streaming, lalu dapatkan telemetri.](http://docs.aws.amazon.com/id_id/lambda/latest/dg/images/telemetry-api-creation-steps.png) Berikut adalah setiap langkah secara lebih rinci: 1. Daftarkan ekstensi Anda menggunakan[Menggunakan API Ekstensi Lambda untuk membuat ekstensi](runtimes-extensions-api.md). Ini memberi Anda`Lambda-Extension-Identifier`, yang Anda perlukan dalam langkah-langkah berikut. Untuk informasi selengkapnya tentang cara mendaftarkan ekstensi Anda, lihat[Mendaftarkan ekstensi Anda](#telemetry-api-registration). 1. Buat pendengar telemetri. Ini bisa berupa server HTTP atau TCP dasar. Lambda menggunakan URI pendengar telemetri untuk mengirim data telemetri ke ekstensi Anda. Untuk informasi selengkapnya, lihat [Membuat pendengar telemetri](#telemetry-api-listener). 1. Menggunakan Subscribe API di API Telemetri, berlangganan ekstensi Anda ke aliran telemetri yang diinginkan. Anda akan memerlukan URI pendengar telemetri Anda untuk langkah ini. Untuk informasi selengkapnya, lihat [Mengirim permintaan berlangganan ke API Telemetri](#telemetry-api-subscription). 1. Dapatkan data telemetri dari Lambda melalui pendengar telemetri. Anda dapat melakukan pemrosesan kustom data ini, seperti mengirimkan data ke Amazon S3 atau ke layanan observabilitas eksternal. **catatan** [Lingkungan eksekusi fungsi Lambda dapat dimulai dan berhenti beberapa kali sebagai bagian dari siklus hidupnya.](runtimes-extensions-api.md#runtimes-extensions-api-lifecycle) Secara umum, kode ekstensi Anda berjalan selama pemanggilan fungsi, dan juga hingga 2 detik selama fase shutdown. Kami merekomendasikan pengelompokan telemetri saat sampai ke pendengar Anda. Kemudian, gunakan peristiwa `Invoke` dan `Shutdown` siklus hidup untuk mengirim setiap batch ke tujuan yang diinginkan. ## Mendaftarkan ekstensi Anda Sebelum Anda dapat berlangganan data telemetri, Anda harus mendaftarkan ekstensi Lambda Anda. Registrasi terjadi selama [fase inisialisasi ekstensi](runtimes-extensions-api.md#runtimes-extensions-api-reg). 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 file`Lambda-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](runtimes-extensions-api.md#runtimes-extensions-registration-api). ## 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: + **HTTP (direkomendasikan)** - Lambda mengirimkan telemetri ke titik akhir HTTP lokal (`http://sandbox.localdomain:${PORT}/${PATH}`) sebagai larik catatan dalam format JSON. Parameter `$PATH` bersifat opsional. Lambda hanya mendukung HTTP, bukan HTTPS. Lambda mengirimkan telemetri melalui permintaan POST. + **TCP** — Lambda mengirimkan telemetri ke port TCP dalam format JSON (NDJSON) yang dibatasi [Newline](https://github.com/ndjson/ndjson-spec). **catatan** Kami sangat menyarankan menggunakan HTTP daripada TCP. Dengan TCP, platform Lambda tidak dapat mengakui kapan mengirimkan telemetri ke lapisan aplikasi. Oleh karena itu, jika ekstensi Anda macet, Anda mungkin kehilangan telemetri. HTTP tidak memiliki batasan ini. Sebelum berlangganan untuk menerima telemetri, buat pendengar HTTP lokal atau port TCP. Selama penyetelan, perhatikan hal berikut ini: + Lambda mengirimkan telemetri hanya ke tujuan yang berada di dalam lingkungan eksekusi. + Lambda mencoba lagi untuk mengirim telemetri (dengan backoff) tanpa adanya pendengar, atau jika permintaan POST mengalami kesalahan. Jika pendengar telemetri mogok, ia melanjutkan menerima telemetri setelah Lambda memulai ulang lingkungan eksekusi. + Lambda mencadangkan port 9001. Tidak ada pembatasan atau rekomendasi nomor port lainnya. ## 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 } } ``` | Parameter | Deskripsi | Default dan batas | | --- | --- | --- | | `maxBytes` | Volume maksimum telemetri (dalam byte) untuk buffer dalam memori. | standar: 262.144
Minimal: 262.144
Maksimal: 1.048.576 | | `maxItems` | Jumlah maksimum peristiwa untuk buffer dalam memori. | Default: 10.000
Minimal: 1.000
Maksimum: 10.000. | | `timeoutMs` | Waktu maksimum (dalam milidetik) untuk buffer batch. | Default: 1.000
Minimal: 25
Maksimal: 30.000 | Saat menyiapkan buffering, ingatlah poin-poin ini: + Jika salah satu aliran input ditutup, Lambda akan menyiram log. Misalnya, ini dapat terjadi jika runtime mogok. + Setiap pelanggan dapat menyesuaikan konfigurasi buffering mereka dalam permintaan berlangganan mereka. + Saat menentukan ukuran buffer untuk membaca data, antisipasi menerima muatan sebesar`2 * maxBytes + metadataBytes`, di mana `maxBytes` merupakan komponen penyiapan buffering Anda. Untuk mengukur jumlah yang `metadataBytes` perlu dipertimbangkan, tinjau metadata berikut. Lambda menambahkan metadata yang mirip dengan ini ke setiap catatan: ``` { "time": "2022-08-20T12:31:32.123Z", "type": "function", "record": "Hello World" } ``` + Jika pelanggan tidak dapat memproses telemetri masuk dengan cukup cepat, atau jika kode fungsi Anda menghasilkan volume log yang sangat tinggi, Lambda mungkin akan menjatuhkan catatan untuk menjaga pemanfaatan memori tetap terbatas. Ketika ini terjadi, Lambda mengirimkan acara. `platform.logsDropped` ## 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](#telemetry-api-destination) dan [konfigurasi buffering](#telemetry-api-buffering). Sebelum mengirim permintaan berlangganan, Anda harus memiliki ID ekstensi (`Lambda-Extension-Identifier`). Saat [mendaftarkan ekstensi dengan Extensions API](#telemetry-api-registration), Anda mendapatkan ID ekstensi dari respons API. Langganan terjadi selama [fase inisialisasi ekstensi](runtimes-extensions-api.md#runtimes-extensions-api-reg). 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": "2025-01-29", "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 } ``` + `time`Properti menentukan kapan platform Lambda menghasilkan acara. Ini berbeda dengan saat peristiwa itu benar-benar terjadi. Nilai string `time` adalah stempel waktu dalam format ISO 8601. + `type`Properti mendefinisikan jenis acara. Tabel berikut menjelaskan semua nilai yang mungkin. + `record`Properti mendefinisikan objek JSON yang berisi data telemetri. Skema objek JSON ini tergantung pada. `type` **Pemesanan acara dengan pemanggilan bersamaan** Untuk [Instans Terkelola Lambda](lambda-managed-instances.md), beberapa pemanggilan fungsi dapat dijalankan secara bersamaan dalam lingkungan eksekusi yang sama. Dalam hal ini, urutan `platform.start` dan `platform.report` acara tidak dijamin antara pemanggilan bersamaan yang berbeda. Ekstensi harus menangani peristiwa dari beberapa pemanggilan yang berjalan secara paralel dan tidak boleh mengasumsikan urutan berurutan. Untuk mengaitkan peristiwa dengan benar ke pemanggilan tertentu, ekstensi harus menggunakan `requestId` bidang yang ada dalam acara platform ini. Setiap pemanggilan memiliki ID permintaan unik yang tetap konsisten di semua peristiwa untuk pemanggilan itu, memungkinkan ekstensi untuk menghubungkan peristiwa dengan benar bahkan ketika mereka tiba di luar pesanan. Tabel berikut merangkum semua jenis `Event` objek, dan menautkan ke [referensi `Event` skema API Telemetri](telemetry-schema-reference.md) untuk setiap jenis peristiwa. | Kategori | Tipe peristiwa | Deskripsi | Skema catatan acara | | --- | --- | --- | --- | | Acara platform | `platform.initStart` | Inisialisasi fungsi dimulai. | [`platform.initStart`](telemetry-schema-reference.md#platform-initStart)skema | | Acara platform | `platform.initRuntimeDone` | Inisialisasi fungsi selesai. | [`platform.initRuntimeDone`](telemetry-schema-reference.md#platform-initRuntimeDone)skema | | Acara platform | `platform.initReport` | Laporan inisialisasi fungsi. | [`platform.initReport`](telemetry-schema-reference.md#platform-initReport)skema | | Acara platform | `platform.start` | Pemanggilan fungsi dimulai. | [`platform.start`](telemetry-schema-reference.md#platform-start)skema | | Acara platform | `platform.runtimeDone` | Runtime selesai memproses acara dengan keberhasilan atau kegagalan. | [`platform.runtimeDone`](telemetry-schema-reference.md#platform-runtimeDone)skema | | Acara platform | `platform.report` | Laporan pemanggilan fungsi. | [`platform.report`](telemetry-schema-reference.md#platform-report)skema | | Acara platform | `platform.restoreStart` | Pemulihan runtime dimulai. | [`platform.restoreStart`](telemetry-schema-reference.md#platform-restoreStart)skema | | Acara platform | `platform.restoreRuntimeDone` | Pemulihan runtime selesai. | [`platform.restoreRuntimeDone`](telemetry-schema-reference.md#platform-restoreRuntimeDone)skema | | Acara platform | `platform.restoreReport` | Laporan pemulihan runtime. | [`platform.restoreReport`](telemetry-schema-reference.md#platform-restoreReport)skema | | Acara platform | `platform.telemetrySubscription` | Ekstensi berlangganan API Telemetri. | [`platform.telemetrySubscription`](telemetry-schema-reference.md#platform-telemetrySubscription)skema | | Acara platform | `platform.logsDropped` | Lambda menjatuhkan entri log. | [`platform.logsDropped`](telemetry-schema-reference.md#platform-logsDropped)skema | | Log fungsi | `function` | Sebuah baris log dari kode fungsi. | [`function`](telemetry-schema-reference.md#telemetry-api-function)skema | | Log ekstensi: | `extension` | Sebuah baris log dari kode ekstensi. | [`extension`](telemetry-schema-reference.md#telemetry-api-extension)skema |