Memperkenalkan konteks tersirat dalam LogTape .0

Saya teruja untuk mengumumkan keluaran LogTape 0.7.0, yang memperkenalkan konteks tersirat—ciri baharu yang berkuasa yang menjadikannya lebih mudah berbanding sebelum ini untuk menambah maklumat kontekstual pada log anda di seluruh anda keseluruhan aplikasi.

Apakah konteks tersirat?

Bayangkan anda mengendalikan permintaan HTTP dalam aplikasi anda. Anda mahu setiap mesej log yang dijana semasa pemprosesan permintaan menyertakan ID permintaan, tidak kira di mana dalam pangkalan kod anda log dibuat. Sebelum konteks tersirat, anda perlu:

1. Haruskan ID permintaan melalui setiap panggilan fungsi
2. Buat pembalak baharu dengan konteks untuk setiap modul
3. Atau gunakan pembolehubah global (yang mempunyai masalah mereka sendiri)

Dengan konteks tersirat, anda kini boleh menetapkan konteks pada permulaan pengendali permintaan anda dan setiap mesej log dalam konteks pelaksanaan itu akan menyertakan maklumat tersebut secara automatik. Berikut ialah contoh mudah:

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

Bagaimana ia berfungsi?

Konteks tersirat menggunakan mekanisme storan konteks-tempatan masa jalan yang mendasari (seperti AsyncLocalStorage Node.js) untuk mengekalkan maklumat kontekstual sepanjang pelaksanaan kod anda. Ini bermakna konteks diselenggara dengan betul walaupun merentasi operasi tak segerak.

Untuk mendayakan konteks tersirat dalam aplikasi anda, anda perlu mengkonfigurasi LogTape dengan storan konteks setempat:

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

Konteks dan keutamaan bersarang

Salah satu ciri hebat konteks tersirat ialah ia boleh bersarang. Apabila anda menyusun konteks, konteks dalaman mewarisi dan boleh mengatasi nilai daripada konteks luar:

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

Apabila ia datang untuk menyelesaikan nilai konteks, LogTape mengikut urutan keutamaan yang jelas:

1. Sifat eksplisit dalam mesej log mengambil keutamaan tertinggi
2. Set konteks eksplisit melalui Logger.with() mengambil keutamaan kedua
3. Set konteks tersirat melalui withContext() mengambil keutamaan paling rendah

Sokongan masa jalan

Sehingga Oktober 2024, konteks tersirat disokong dalam:

• Node.js
• Deno
• Bun

Pelayar web belum lagi menyokong konteks tersirat, kerana mereka menunggu pelaksanaan cadangan Konteks Async TC39.

Kes guna

Konteks tersirat amat berharga untuk:

1. Penjejakan Permintaan: Tambahkan ID permintaan, ID pengguna atau ID sesi pada semua log dalam permintaan
2. Pemantauan Transaksi: Jejaki ID transaksi merentas berbilang operasi
3. Konteks Ralat: Pastikan log ralat sentiasa mempunyai maklumat kontekstual yang berkaitan
4. Pemantauan Prestasi: Tambahkan maklumat masa merentas berbilang operasi
5. Konteks Penyewa: Dalam aplikasi berbilang penyewa, jejak maklumat penyewa merentas semua operasi

Amalan terbaik

Apabila menggunakan konteks tersirat, pertimbangkan amalan terbaik ini:

1. Gunakan konteks tersirat untuk maklumat yang benar-benar dimiliki oleh keseluruhan konteks pelaksanaan
2. Pastikan data konteks ringan—ingat ia dibawa sepanjang keseluruhan pelaksanaan
3. Gunakan nama kunci yang bermakna dan konsisten merentas aplikasi anda
4. Pertimbangkan untuk menggunakan TypeScript untuk memastikan ketekalan struktur konteks
5. Dokumenkan struktur konteks yang dijangkakan untuk aplikasi anda

Panduan Migrasi

Jika anda sudah menggunakan LogTape, peningkatan untuk menggunakan konteks tersirat adalah mudah:

1. Kemas kini kepada LogTape 0.7.0
2. Tambahkan storan konteks-tempatan pada konfigurasi LogTape anda
3. Kenal pasti tempat yang konteks diedarkan secara manual
4. Ganti dengan panggilan withContext() pada sempadan yang sesuai

Kesimpulan

Konteks tersirat dalam LogTape 0.7.0 menyediakan cara yang berkesan untuk menambah maklumat kontekstual pada log anda tanpa mengacaukan kod anda atau menghantar konteks secara manual melalui timbunan panggilan anda. Ia amat berharga dalam perkhidmatan web, API dan aplikasi lain yang menjejaki konteks merentas operasi adalah penting.

Saya teruja untuk melihat cara anda akan menggunakan ciri ini untuk meningkatkan pengelogan dan kebolehmerhatian aplikasi anda. Cubalah dan beritahu saya pendapat anda!

Untuk mendapatkan maklumat lanjut, lihat dokumentasi lengkap tentang konteks tersirat.

Atas ialah kandungan terperinci Memperkenalkan konteks tersirat dalam LogTape .0. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!