# Dokumentasi Django 5.2.8

# Bagaimana mengelola pelaporan kesalahan

Ketika anda sedang menjalankan situs umum anda harus selalu mematikan pengaturan `DEBUG`. Itu akan membuat peladen anda berjalan lebih cepat, dan juga akan mencegah pengguna hahat dari melihat rincian dari aplikasi anda yang dapat diungkap dengan kesalahan halaman.

Bagaimanapun, menjalankan dengan `DEBUG` disetel ke `False` berarti anda akan tidak pernah melihat kesalahan dibangkitkan oleh situs anda -- semua orang alih-alih akan melihat halaman-halaman kesalahan umum anda. Anda butuh menjaga jalur kesalahan-kesalahan yang muncul dalam situs yang disebar, sehingga Django dapat dikonfigurasikan untuk membuat laporan dengan rincian tentang kesalahan-kesalahan tersebut.

## Surel laporan

### Kesalahan peladen

Ketika `DEBUG` adalah `False`, Django akan mensurelkan pengguna terdaftar dalam pengaturan `ADMINS` kapanpun kode anda memunculkan pengecualian yang tidak ditangani dan menghasilkan dalam kesalahan peladen dalam (dengan tegas berbicara, untuk setiap tanggapan dengan kode status HTTP 500 atau lebih). Ini memberikan administrator pemberitahuan segera dari pelacakan kebelakang apapun, dan rincian tentang permintaan HTTP yang menyebabkan kesalahan.

Catatan

Agar mengirim surel, Django membutuhkan beberapa pengaturan mengatakannya bagaimana terhubung ke peladen surat anda. Setidaknya, anda akan butuh menentukan `EMAIL_HOST` dan kemungkinan `EMAIL_HOST_USER` dan `EMAIL_HOST_PASSWORD`, meskipun pengaturan lainnya mungkin tidak juga dibutuhkan tergantung pada konfigurasi peladen surat anda. Rundingkan the Django settings documentation untuk daftar penuh dari pengaturan terkait-surel.

By default, Django will send email from `root@localhost`. However, some mail providers reject all email from this address. To use a different sender address, modify the `SERVER_EMAIL` setting.

Untuk mengaktifkan perilaku ini, masukkan alamat surel dari penerima di bagian `ADMINS`.

Lihat juga

Surel kesalahan peladen dikirim menggunakan kerangka pencatatan, jadi anda dapat menyesuaikan perilaku ini dengan customizing your logging configuration.

### kesalahan 404

Django juga dapat dikonfirgasi untuk mengirimkan surel kesalahan tentang tautan yang tidak ditemukan (404 "page not found" errors). Django mengirim surel tentang error 404 ketika:

- `DEBUG` adalah `False`;

- Pengaturan `MIDDLEWARE` anda termasuk `django.middleware.common.BrokenLinkEmailsMiddleware`.

Jika kondisi tersebut bertemu, Django akan surel pengguna terdaftar di pengaturan `MANAGERS` kapanpun kode anda memunculkan 404 dan permintaan mempunyai acuan. Dia tidak mengganggu ke surel untuk 404 yang tidak punya acuan -- yaitu biasanya orang mengetikkan dalam URL rusak atau robot Jaringan rusak. Dia juga mengabaikan 404 ketika acuan sama pada URL yang diminta, sejak perilaku ini dari robot Jaringan rusak juga.

Catatan

`BrokenLinkEmailsMiddleware` harus muncul sebelum middleware lain yang memotong kesalahan 404, seperti `LocaleMiddleware` atau `FlatpageFallbackMiddleware`. Letakkan ke arah atas dari setelan `MIDDLEWARE`.

Anda dapat memberitahu Django untuk menghentikan pelaporan tertentu 404 dengan merubah pengaturan `IGNORABLE_404_URLS`. Dia harus menjadi daftar dari obyek ungkapan biasa tersusun. Sebagai contoh:

    import re

    IGNORABLE_404_URLS = [
        re.compile(r"\.(php|cgi)$"),
        re.compile(r"^/phpmyadmin/"),
    ]

Dalam contoh ini, sebuah 404 pada setiap URL berakhiran dengan `.php` atau `.cgi` akan tidak dilaporkan. Juga tidak akan URL apapun dimulai dengan `/phpmyadmin/`.

Contoh berikut menunjukkan bagaimana mengeluarkan beberapa URL biasa yang perambah dan penjilat sering diminta:

    import re

    IGNORABLE_404_URLS = [
        re.compile(r"^/apple-touch-icon.*\.png$"),
        re.compile(r"^/favicon\.ico$"),
        re.compile(r"^/robots\.txt$"),
    ]

(Perhatikan bahwa ini adalah regular expression, jadi kita tuliskan garis miring terbalik di depan titik untuk melepaskannya)

Jika anda suka menyesuaikan perilaku dari `django.middleware.common.BrokenLinkEmailsMiddleware` lebih lanjut (sebagai contoh untuk mengabaikan permintaan datang dari penjilat jaringan), anda harus mensubkelaskannya dan menimpa caranya.

Lihat juga

Kesalahan 404 dicatat menggunakan kerangka pencatatan. Secara awal, rekaman catatan ini diabaikan, tetapi anda dapat menggunakan mereka untuk kesalahan pelaporan dengan menulis sebuah penanganan configuring logging dengan benar.

## Menyaring laporan kesalahan

Peringatan

Menyaring data sensitif adalah masalah sulit, dan hampir tidak mungkin menjamin bahwa data sensitif tidak akan bocor kedalam sebuah laporan kesalahan. Karena itu, laporan kesalahan harus hanya tersedia pada anggota tim yang dapat dipercaya dan harus menghindari perpindahan laporan kesalahan tidak disandikan di internet (seperti melalui surel).

### Menyaring informasi rahasia

Laporan kesalahan sangat membantu untuk memeriksa kesalahan, jadi dia umumnya berguna untuk merekam informasi terkait tentang kesalahan-kesalahan tersebut sebanyak mungkin. Sebagai contoh, secara awal rekaman Django full traceback untuk dimunculkan pengecualian, setiap variabel lokal full traceback, dan attributes `HttpRequest`.

Bagaimanapun, terkadang jenis-jenis informasi tertentu mungkin terlalu sensitif dan dengan demikian mungkin tidak sesuai untuk terus melacak, sebagai contoh, sandi pengguna atau angka kartu kredit. Jadi di tambahaan untuk menyaring pengaturan yang muncul menjadi sensitif seperti digambarkan dalam dokumentasi `DEBUG`, Django menawarkan sekumpulan fungsi penghias untuk membantu anda mengendalikan informasi mana harus disaring dari laporan kesalahan dalam lingkungan produksi (yaitu, dimana `DEBUG` disetel ke `False`): `sensitive_variables()` dan `sensitive_post_parameters()`.

sensitive_variables(*variables)

  Jika sebuah fungsi (baik sebuah tampilan atau callback umum apapun) dalam kode anda menggunakan variabel lokal rentan mengandung informasi sensitif, anda mungkin mencegah nilai-nilai variabel tersebut dari menjadi disertakan dalam laporan kesalahan menggunakan penghias `sensitive_variables`:

      from django.views.decorators.debug import sensitive_variables

      @sensitive_variables("user", "pw", "cc")
      def process_info(user):
          pw = user.pass_word
          cc = user.credit_card_number
          name = user.name
          ...

  Dalam contoh diatas, nilai-nilai untuk variabel `user`, `pw` dan `cc` akan disembunyikan dan diganti dengan bintang (`**********`) dalam laporan kesalahan, dimana nilai dari variabel `name` akan diungkapkan.

  Untuk secara sistematis menyembunyikan semua variabel lokal dari sebuah fungsi dari laporan kesalahan, jangan menyediakan argumen apapun pada decorator `sensitive_variables`:

      @sensitive_variables()
      def my_function(): ...

  Ketika menggunakan sejumlah dekorator

  Jika variabel anda ingin sembunyikan adalah juga argumen fungsi (sebagai contoh '`user`’ dalam contoh berikut), dan jika fungsi dihiasi mempunyai banyak decorator, kemudian pastikan menempatkan `@sensitive_variables` pda atas dari rantai decorator. Cara ini dia akan juga menyembunyikan argumen fungsi ketika dia mendapatkan dilewati melalui decorator lain:

      @sensitive_variables("user", "pw", "cc")
      @some_decorator
      @another_decorator
      def process_info(user): ...

sensitive_post_parameters(*parameters)

  Jika satu dari tampilan anda menerima sebuah obyek `HttpRequest` dengan `POST parameters` rentan untuk mengandung informasi sensitif, anda mungkin mencegah nilai-nilai dari parameter tersebut dari menjadi disertakan dalam laporan kesalahan menggunakan penghias `sensitive_post_parameters`:

      from django.views.decorators.debug import sensitive_post_parameters

      @sensitive_post_parameters("pass_word", "credit_card_number")
      def record_user_profile(request):
          UserProfile.create(
              user=request.user,
              password=request.POST["pass_word"],
              credit_card=request.POST["credit_card_number"],
              name=request.POST["name"],
          )
          ...

  Dalam contoh diatas, nilai-nilai untuk parameter POST `pass_word` dan `credit_card_number` akan disembunyikan dan diganti dengan bintang (`**********`) dalam laporan kesalahan, dimana nilai dari variabel `name` akan diungkapkan.

  Untuk secara sistematis menyembunyikan semua parameter POST dari sebuah permintaan dalam laporan kesalahan, jangan menyediakan argumen apapun pada decorator `sensitive_variables`:

      @sensitive_post_parameters()
      def my_view(request): ...

  Semua parameter POST adalah sistematis disaring keluar dari laporan kesalahan untuk tampilan `django.contrib.auth.views` tertentu (`login`, `password_reset_confirm`, `password_change`, dan `add_view` dan `user_change_password` dalam admin `auth`) untuk mencegah dari pembocoran dari informasi sensitif seperti sandi pengguna.

### Penyesuaian laporan kesalahan

Semua `sensitive_variables()` dan `sensitive_post_parameters()` lakukan adalah, masing-masing, keterangan dungsi dihiasi dengan nama-nama dari variabel sensitif dan keterangan obyek `HttpRequest` dengan nama-nama dari sensitif parameter POST, sehingga informasi sensitif ini dapat kemudian disaring keluar dari laporan ketika kesalahan muncul. Penyaring sebenarnya dilakukan oleh penyaring laporan kesalahan awal Django: `django.views.debug.SafeExceptionReporterFilter`. Penyaring ini menggunakan keterangan dihiasi untuk mengganti nilai-nilai terhubung dengan bintang (`**********`) ketika laporan kesalahan di buat. Jika anda berharap menimpa atau menyesuaikan perilaku awal ini untuk keseluruhan situs anda, anda butuh menentukan kelas penyaring sendiri dan beritahu Django untuk menggunakannya melalui pengaturan `DEFAULT_EXCEPTION_REPORTER_FILTER`:

    DEFAULT_EXCEPTION_REPORTER_FILTER = "path.to.your.CustomExceptionReporterFilter"

Anda dapat juga mengendalikan cara lebih kecil penyaring mana untuk digunakan dalam tampilan yang diberikan oleh pengaturan atribut `exception_reporter_filter` `HttpRequest`:

    def my_view(request):
        if request.user.is_authenticated:
            request.exception_reporter_filter = CustomExceptionReporterFilter()
        ...

Kelas saringan penyesuaian anda perlu mewarisi dari `django.views.debug.SafeExceptionReporterFilter` dan mungkin menimpa atribut dan metode berikut:

class SafeExceptionReporterFilter
  cleansed_substitute

    Nilai string untuk mengganti nilai sensitif. Secara awalan itu mengganti nilai dari variabel sensitif dengan bintang (`**********`).

  hidden_settings

    Sebuah obyek regular expression tersusun digunakan untuk mencocokkan pengaturan dan nilai `request.META` yang dianggap sensitif. Secara awalan setara pada:

        import re

        re.compile(r"API|AUTH|TOKEN|KEY|SECRET|PASS|SIGNATURE|HTTP_COOKIE", flags=re.IGNORECASE)

    Changed in Django 5.2:

    Istilah `AUTH` telah ditambahkan.

  is_active(request)

    Mengembalikan `True` untuk mengaktivasi penyaringan di `get_post_parameters()` dan `get_traceback_frame_variables()`. Secara awalan penyaring aktif jika `DEBUG` adalah `False`. Catat bahwa nilai sensitif `request.META` selalu disaring bersama dengan nilai sensitif, seperti digambarkan dalam dokumentasi `DEBUG`.

  get_post_parameters(request)

    Mengembalikan dictionary yang disaring dari parameter POST. Nilai sensitif diganti dengan `cleansed_substitute`.

  get_traceback_frame_variables(request, tb_frame)

    Mengembalikan dictionary yang disaring dari variabel lokal untuk untuk kerangka traceback yang diberikan. Nilai sensitif diganti dengan `cleansed_substitute`.

Jika anda butuh menyesuaikan laporan kesalahan melampaui penyaringan anda mungkin menentukan kelas pelapor kesalahan disesuaikan dengan menentukan pengaturan `DEFAULT_EXCEPTION_REPORTER`.

    DEFAULT_EXCEPTION_REPORTER = "path.to.your.CustomExceptionReporter"

Pelapor eksepsi bertanggungjawab untuk menyusun data laporan eksepsi, dan membentuk dia sebagai teks atau HTML yang sesuai. (Pelapoer eksepsi menggunakan `DEFAULT_EXCEPTION_REPORTER_FILTER` ketika menyiapkan data laporan eksepsi.)

Kelas pelapor disesuaikan anda butuh diwarisi dari `django.views.debug.ExceptionReporter`.

class ExceptionReporter
  html_template_path

    Sifat yang mengembalikan `pathlib.Path` mewakili jalur sistem berkas mutlak pada cetakan untuk membangun gambaran HTML dari eksepsi. Awalan pada cetakan disediakan Django.

  text_template_path

    Sifat yang mengembalikan `pathlib.Path` mewakili jalur sistem berkas mutlak pada cetakan untuk membangun gambaran teks-polos dari eksepsi. Awalan pada cetakan disediakan Django.

  get_traceback_data()

    Mengembalikan sebuah dictionary menanggung informasi melacak kembali.

    Ini adalah titik ekstensi utama untuk menyesuaikan laporan pengecualian, sebagai contoh:

        from django.views.debug import ExceptionReporter

        class CustomExceptionReporter(ExceptionReporter):
            def get_traceback_data(self):
                data = super().get_traceback_data()
                # ... remove/add something here ...
                return data

  get_traceback_html()

    Mengembalikan versi HTML dari laporan pengecualian.

    Digunakan untuk versi HTML dari pengawakutu halaman kesalahan HTTP 500.

  get_traceback_text()

    Mengembalikan versi teks polis dari laporan pengecualian.

    Digunakan untuk versi teks polos dari pengawakutu halaman kesalahan HTTP 500 dan laporan surel.

Dengan kelas penyaring, anda dapat mengendalikan dimana kelas pelapor eksepsi digunakan dalam tampilan yang diberikan dengan menyetel atribut `exception_reporter_class` `HttpRequest`:

    def my_view(request):
        if request.user.is_authenticated:
            request.exception_reporter_class = CustomExceptionReporter()
        ...

Lihat juga

Anda dapat juga mengatur penyesuaian pelaporan kesalahan dengan menulis sebuah potongan penyesuaian dari exception middleware. Jika anda melakukan menulis penyesuaian penanganan kesalahan, adalah ide bagus untuk meniru penanganan kesalahan siap pakai Django dan hanya laporan/catatan kesalahan jika setting:DEBUG adalah `False`.