# Dokumentasi Django 4.2.9.dev20231204082947

# Bagaimana mengkonfigurasi dan menggunakan pencatatan

Lihat juga

- Django logging reference
- Django logging overview

Django menyediakan kerja default logging configuration yang mudah diperpanjang.

## Membuat panggilan pencatatan dasar

Untuk mengirim pesan catatan dari dalam kode anda, anda dapat menempatkan panggilan pencatatan kedalamnya.

Jangan tergoda untuk menggunakan panggilan pencatatan dalam `settings.py`.

The way that Django logging is configured as part of the `setup()` function means that logging calls placed in `settings.py` may not work as expected, because logging will not be set up at that point. To explore logging, use a view function as suggested in the example below.

First, import the Python logging library, and then obtain a logger instance with `logging.getLogger()`. Provide the `getLogger()` method with a name to identify it and the records it emits. A good option is to use `__name__` (see Gunakan namespace pencatat below for more on this) which will provide the name of the current Python module as a dotted path:

    import logging

    logger = logging.getLogger(__name__)

Merupakan konvensi yang baik untuk melakukan deklarasi ini pada tingkat modul.

Kemudian di dalam fungsi, sebagai contoh dalam tampilan, mengirimkan rekaman ke pencatat:

    def some_view(request):
        ...
        if some_risky_state:
            logger.warning("Platform is running at risk")

Ketika kode ini dijalankan, `LogRecord` mengandung pesan itu akan terkirim ke pencatat. Jika anda menggunakan konfigurasi pencatatan awalan Django, pesan akan muncul di konsol.

Tingkatan `WARNING` digunakan dalam contoh diatas adalah satu dari beberapa logging severity levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Jadi, contoh lain mungkin:

    logger.critical("Payment system is not responding")

Penting

Rekaman dengan tingkatan rendah daripada `WARNING` tidak akan muncul dalam konsol secara awalan. Merubah perilaku ini membutuhkan konfigurasi tambahan.

## Menyesuaikan konfigurasi pencatatan

Although Django's logging configuration works out of the box, you can control exactly how your logs are sent to various destinations - to log files, external services, email and so on - with some additional configuration.

Anda dapat mengkonfigurasi

- pencatatan pemetaan, untuk menentukan rekaman mana yang dikirim ke penangan mana
- penangan, untuk menentukan apa yang mereka lakukan dengan rekaman mereka terima
- penyaring, untuk menyediakan kendali tambahan terhadap perpindahan rekaman, dan bahkan merubah rekaman di tempat
- pembentuk, untuk merubah obyek `LogRecord` menjadi string atau bentuk lain untuk dikonsumsi oleh manusia atau sistem lain

Ada beragam cara dari mengkonfigurasi pencatatan. Di Django, pengaturan `LOGGING` adalah yang paling umum digunakan. Pengaturan menggunakan the dictConfig format, dan memperpanjang default logging configuration.

Lihat Mengkonfigurasi catatan untuk penjelasan bagaimana pengaturan penyesuaian anda digabungkan dengan awalan Django.

Lihat `Python logging documentation` untuk rincian cara lain dari konfigurasi pencatatan. Demi kesederhanaan, dokumentasi ini hanya akan mempertimbangkan konfigurasi melalui pengaturan `LOGGING`.

### Konfigurasi pencatatan dasar

Ketika mengkonfigurasi pencatatan, itu masuk akal untuk

#### Membuat sebuah dictionary ``LOGGING`

Dalam `settings.py` anda:

    LOGGING = {
        "version": 1,  # the dictConfig format version
        "disable_existing_loggers": False,  # retain the default loggers
    }

Itu hampir selalu masuk akal untuk mempertahankan dan memperpanjang konfigurasi pencatatan awalan dengan mengatur `disable_existing_loggers` menjadi `False`.

#### Mengkonfigurasi penangan

Contoh ini mengkonfigurasikan penangan tunggal bernama `file`, yang menggunakan Python's `FileHandler` untuk menyimpan catatan tingkatan `DEBUG` dan tertinggi ke berkas `general.log` (di akar proyek):

    LOGGING = {
        # ...
        "handlers": {
            "file": {
                "class": "logging.FileHandler",
                "filename": "general.log",
            },
        },
    }

Kelas-kelas penangan berbeda mengambil pilihan konfigurasi berbeda. Untuk informasi lebih pada ketersediaan kelas-kelas penangan, lihat `AdminEmailHandler` disediakan oleh Django dan beragam `handler classes` disediakan oleh Python.

Tingkat pencatatan dapat juga di setel pada penangan (secara awalan, mereka menerima catatan pesan pada semua tingkatan). Menggunakan contoh diatas, menambahkan:

    {
        "class": "logging.FileHandler",
        "filename": "general.log",
        "level": "DEBUG",
    }

akan menentukan sebuah konfigurasi penangan yang hanya menerima rekaman dari tingkatan `DEBUG` dan lebih tinggi.

#### Mengkonfigurasi pemetaan pencatatan

Untuk mengirim rekaman ke penangan ini, konfigurasikan pemetaan pencatatan untuk menggunakannya sebagai contoh:

    LOGGING = {
        # ...
        "loggers": {
            "": {
                "level": "DEBUG",
                "handlers": ["file"],
            },
        },
    }

The mapping's name determines which log records it will process. This configuration (`''`) is unnamed. That means that it will process records from all loggers (see Gunakan namespace pencatat below on how to use the mapping name to determine the loggers for which it will process records).

Itu akan meneruskan pesan dari tingkatan `DEBUG` dan lebih tinggi ke penangan bernama `file`.

Catat bahwa pencatat dapat meneruskan pesan ke banyan penangan, jadi hubungan diantara pencatat dan penangan adalah many-to-many.

Jika anda menjalankan:

    logger.debug("Attempting to connect to API")

dalam kode anda, anda akan menemukan bahwa pesan dalam berkas `general.log` di akar dari proyek.

#### Konfigurasikan pemformat

Secara awalan, keluaran catatan akhir mengandung pesan bagian dari tiap `log record`. Gunakan pembentuk jika anda ingin menyertakan data tambahan. Nawa awal dan tentukan bentukan anda - contoh ini menentukan nama bentukan `verbose` dan `simple`:

    LOGGING = {
        # ...
        "formatters": {
            "verbose": {
                "format": "{name} {levelname} {asctime} {module} {process:d} {thread:d} {message}",
                "style": "{",
            },
            "simple": {
                "format": "{levelname} {message}",
                "style": "{",
            },
        },
    }

Katakunci `style` mengizinkan anda menentukan `{` for `str.format()` atau `$` untuk bentukan `string.Template` ; awalan adalah `$`.

Lihat atribut LogRecord attributes for the `LogRecord` anda dapat sertakan.

Untuk memberlakukan pembentuk untuk penangan, tambah masukan `formatter` pada dictionary penangan mengacu pada pembentuk berdasarkan nama, sebagai contoh:

    "handlers": {
        "file": {
            "class": "logging.FileHandler",
            "filename": "general.log",
            "formatter": "verbose",
        },
    }

#### Gunakan namespace pencatat

The unnamed logging configuration `''` captures logs from any Python application. A named logging configuration will capture logs only from loggers with matching names.

Namespace dari instance pencatat ditentukan menggunakan `getLogger()`. Sebagai contoh dalam `views.py` dari `my_app`:

    logger = logging.getLogger(__name__)

will create a logger in the `my_app.views` namespace. `__name__` allows you to organize log messages according to their provenance within your project's applications automatically. It also ensures that you will not experience name collisions.

Sebuah pemetaan pencatatan bernama `my_app.views` akan mengambil rekaman dari pencatat ini:

    LOGGING = {
        # ...
        "loggers": {
            "my_app.views": {...},
        },
    }

A logger mapping named `my_app` will be more permissive, capturing records from loggers anywhere within the `my_app` namespace (including `my_app.views`, `my_app.utils`, and so on):

    LOGGING = {
        # ...
        "loggers": {
            "my_app": {...},
        },
    }

Anda dapat juga menentukan namespace pencatat secara eksplisit:

    logger = logging.getLogger("project.payment")

dan atur pemetaan pencatatan yang sesuai.

##### Menggunakan hierarki dan propagasi pencatatan

Logger naming is hierarchical. `my_app` is the parent of `my_app.views`, which is the parent of `my_app.views.private`. Unless specified otherwise, logger mappings will propagate the records they process to their parents - a record from a logger in the `my_app.views.private` namespace will be handled by a mapping for both `my_app` and `my_app.views`.

Untuk mengelola perilaku ini, setel kunci propagasi pada pemetaan anda tentukan:

    LOGGING = {
        # ...
        "loggers": {
            "my_app": {
                # ...
            },
            "my_app.views": {
                # ...
            },
            "my_app.views.private": {
                # ...
                "propagate": False,
            },
        },
    }

`propagate` awalan adalah `True`. Di contoh ini, catatan dari `my_app.views.private` tidak akan ditangani oleh orang tua, tetapi catatan `my_app.views` akan.

### Mengkonfigurasikan pencatatan responsif

Logging is most useful when it contains as much information as possible, but not information that you don't need - and how much you need depends upon what you're doing. When you're debugging, you need a level of information that would be excessive and unhelpful if you had to deal with it in production.

You can configure logging to provide you with the level of detail you need, when you need it. Rather than manually change configuration to achieve this, a better way is to apply configuration automatically according to the environment.

Sebagai contoh, anda dapat mensetel variabel lingkungan `DJANGO_LOG_LEVEL` dengan tepat di lingkungan pengembangan dan pementasan, dan memanfaatkannya di pemetaan pencatatan:

    "level": os.getenv("DJANGO_LOG_LEVEL", "WARNING")

- sehingga kecuali lingkungan menentukan tingkat catatan yang lebih rendah, konfigurasi ini hanya akan meneruskan rekaman dari kerasnya``WARNING`` dan diatasnya untuk penangannya.

Pilihan lain dalam konfigurasi (seperti pilihan `level` atau `formatter` dari penangan) dapat dikelola dengan cara yang sama.