OmniDocLog diperlukan untuk memecahkan masalah kegagalan dokumen, tetapi teks lengkap tidak perlu dicatat.
Log diperlukan untuk menemukan kegagalan terjemahan, namun tidak perlu mencetak seluruh kontrak, nomor ID, atau token unduhan. Log harus menjawab "tugas yang mana, pada langkah mana, dan mengapa gagal" daripada menjadi pustaka dokumen kedua yang tidak memiliki manajemen izin.
Log diperlukan untuk memecahkan masalah kegagalan terjemahan dokumen, namun log tidak perlu berisi teks lengkap kontrak, nomor ID, atau token unduhan. Artikel ini menjelaskan cara membuat log menjawab "tugas mana yang gagal pada langkah mana dan mengapa" tanpa menyalin dokumen pelanggan ke dalam log.
Pembaca yang cocok adalah pengembang serta personel operasi dan pemeliharaan yang bertanggung jawab atas layanan terjemahan dokumen, menghubungkan antarmuka terjemahan, atau memelihara log latar belakang. Setelah membaca, Anda dapat merancang serangkaian bidang daftar putih, memverifikasi bahwa log tidak menampilkan teks asli, dan mengatur periode penyimpanan dan cakupan akses untuk pemecahan masalah.
Contoh tersebut menggunakan sampel sintetis untuk mendemonstrasikan metode pemrosesan, dan kode telah diperiksa di lingkungan yang terisolasi, namun ini tidak mewakili jaminan semua file nyata atau kinerja produk. Sebelum memproses dokumen penting, harap simpan dokumen asli dan pelajari sesuai dengan batasan dan item penerimaan di bawah ini.
Apa yang harus dicatat dalam log pemecahan masalah? Kesimpulan satu kalimat
Log hanya mencatat bidang yang diizinkan seperti ID tugas, tahapan, kategori kesalahan, dan konsumsi waktu, namun tidak mencatat konten dokumen dan kredensial.
| situasi Anda | Praktik yang direkomendasikan | alasan |
|---|---|---|
| Perlu mengetahui tugas mana yang gagal | Mencatat ID tugas internal acak | Kemampuan untuk menemukan masalah tanpa memperlihatkan nama atau jalur file pengguna |
| Perlu menentukan di tahap mana kartu tersebut berada | Catat nama panggung dan waktu yang dibutuhkan | Tidak perlu setiap teks sumber dan terjemahan |
| Permintaan itu ditolak oleh pihak hulu | Catat kategori kesalahan yang dinormalisasi | Konten permintaan lengkap otentikasi kelas satu tidak boleh dimasukkan ke dalam log |
| Perlu kembali ke versi asli untuk pemecahan masalah | Menggunakan referensi dalam sistem yang terkendali | Tautan yang dapat diunduh publik secara permanen berisiko bocor |
Mulailah dengan bidang yang diperbolehkan untuk direkam
Daftar hitam dapat dengan mudah melewatkan bidang sensitif baru. Pendekatan yang lebih bijaksana adalah dengan hanya menampilkan bidang yang dirancang, misalnya:
- ID tugas internal
- Tahap pengolahan
- kategori kesalahan
- memakan waktu
Contoh sintesis di bawah ini menggunakan proyeksi whitelist sehingga teks lengkap dan token yang di input tidak dimasukkan ke dalam log.
Log verifikasi tidak menampilkan teks aslinya.
import io
import json
import logging
ALLOWED = ("job_id", "stage", "error_code", "elapsed_ms")
def log_record(data):
return {key: data[key] for key in ALLOWED if key in data}
stream = io.StringIO()
logger = logging.getLogger("synthetic-document-job")
logger.handlers.clear()
logger.propagate = False
logger.setLevel(logging.INFO)
handler = logging.StreamHandler(stream)
logger.addHandler(handler)
event = {"job_id": "demo-12", "stage": "parse", "error_code": "BAD_CONTAINER",
"elapsed_ms": 42, "document_text": "synthetic confidential clause",
"access_token": "synthetic-secret"}
logger.info(json.dumps(log_record(event), sort_keys=True))
logged = json.loads(stream.getvalue())
assert logged["error_code"] == "BAD_CONTAINER"
assert "document_text" not in logged
assert "synthetic-secret" not in stream.getvalue()
assert set(logged) <= set(ALLOWED)
logger.removeHandler(handler)Contohnya hanya memodifikasi demo logger yang diberi nama sendiri. Tidak disarankan untuk menghapus pengendali global aplikasi di perpustakaan bisnis. Nilai bidang masih perlu diverifikasi panjang dan jenisnya. Jika Anda memasukkan teks lengkap pengguna ke error_code, nama daftar putih saja tidak akan menyelamatkan Anda.
ID Asosiasi menggantikan konten sensitif
Tabel berikut mencantumkan persyaratan umum selama pemecahan masalah, serta rekaman yang direkomendasikan dan tidak direkomendasikan.
| Masalah yang ingin diselidiki | Catatan yang direkomendasikan | Rekam tidak disarankan |
|---|---|---|
| Tugas mana yang gagal | ID tugas internal acak | Nama dan jalur file pengguna lengkap |
| Tahapan mana yang memerlukan waktu? | Tahapan dan memakan waktu | Setiap teks sumber dan terjemahannya |
| Mengapa pihak hulu menolak? | Kategori kesalahan yang dinormalisasi | Lengkapi permintaan dengan header otentikasi |
| Bagaimana menemukan yang asli | Referensi dalam sistem terkendali | Tautan unduhan publik secara permanen |
Periode retensi sama pentingnya dengan cakupan akses
Meskipun tidak ada teks dalam log, kombinasi waktu tugas, bahasa, dan ukuran file dapat mengungkapkan informasi bisnis. Log harus disertai dengan kontrol akses, periode penyimpanan dan prosedur penghapusan.
Saat memecahkan masalah, naikkan level log untuk sementara dan perjelas kapan harus memulihkan untuk menghindari meninggalkan mode debug di lingkungan produksi untuk waktu yang lama.
Integrasi terjemahan juga dapat memiliki log yang jelas dan terkendali
Saat menyambung ke OmniDoc (portal produk), Anda hanya perlu mencatat hubungan antara tugas lokal dan tugas jarak jauh. File yang diunggah oleh pengguna tidak boleh disalin ke log untuk kenyamanan pemecahan masalah.
Laporan masalah yang baik menggambarkan tahap kegagalan dan kondisi pengulangan, sekaligus menjaga dokumen pelanggan hanya mengalir di jalur pemrosesan yang sah.
Referensi: Python logging.
📊 Perbandingan inti
| Jalan | keuntungan | mempertaruhkan |
|---|---|---|
| daftar hitam | Cara penulisannya lugas dan mudah digunakan. | Sangat mudah untuk melewatkan bidang sensitif baru |
| daftar putih | Hanya keluaran bidang yang dirancang dengan batas yang jelas | Bidang perlu direncanakan terlebih dahulu dan panjang serta jenis nilai bidang diverifikasi |
🎯 Metode mana yang cocok untuk Anda?
Jika Anda perlu mencari tugas terjemahan
Mencatat ID tugas internal acak dan tahapan kegagalan, tidak mencatat nama file atau jalur pengguna lengkap.
Jika Anda ingin menangani kesalahan yang dilaporkan oleh antarmuka upstream
Mencatat kelas kesalahan yang dinormalisasi, tidak mencatat permintaan lengkap dengan header autentikasi.
Jika Anda memecahkan masalah online
Tingkatkan level log untuk sementara dan pulihkan segera setelah pemecahan masalah.
Jika Anda ingin mendesain bidang log
Lebih suka memasukkan ke daftar putih dan memverifikasi panjang dan jenis nilai bidang.
❓ Pertanyaan yang Sering Diajukan (FAQ)
1. Bisakah nama file lengkap pengguna dicatat di log?
Tidak direkomendasikan. Nama dan jalur file lengkap tidak disarankan untuk dicatat, dan korelasi ID tugas internal acak dapat digunakan sebagai gantinya.
2. Mengapa tidak disarankan menggunakan daftar hitam untuk memfilter bidang sensitif?
Daftar hitam dengan mudah melewatkan bidang sensitif yang baru muncul, sedangkan daftar putih hanya menampilkan bidang yang dirancang, yang lebih aman.
3. Hanya waktu tugas dan ukuran file yang perlu diatur?
membutuhkan. Kombinasi informasi ini juga dapat mengungkapkan informasi bisnis, dan log harus disertai dengan kontrol akses, periode penyimpanan, dan prosedur penghapusan.
4. Bisakah log debug diaktifkan dalam waktu lama saat pemecahan masalah?
Tidak direkomendasikan. Setelah meningkatkan level log untuk sementara, perlu diketahui kapan harus memulihkannya agar tidak meninggalkan mode debug di lingkungan produksi untuk waktu yang lama.
5. Bisakah handler global dihapus di perpustakaan bisnis?
Tidak direkomendasikan. Contoh ini hanya memodifikasi logger demo yang diberi nama sendiri, dan pengendali global aplikasi tidak boleh dihapus di perpustakaan bisnis.
📝 Ringkasan
Saat memecahkan masalah kegagalan terjemahan, log harus menjawab tugas, tahapan, dan alasan daripada menyimpan konten dokumen. Gunakan bidang daftar putih, referensi terkontrol, dan periode penyimpanan yang jelas untuk menyeimbangkan efisiensi pemecahan masalah dan keamanan dokumen.
