Skip to content

Commit 0e5a11c

Browse files
April-Yjjespressif-bot
April-Yjj
authored and
espressif-bot
committed
docs: Update translation
1 parent dbfb248 commit 0e5a11c

File tree

2 files changed

+313
-217
lines changed

2 files changed

+313
-217
lines changed

‎docs/en/api-reference/system/log.rst‎

Lines changed: 115 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ Log level settings control which logs are included in the binary and their visib
6868

6969
Example for the application: if the **log level** is set to **Warning** and the **maximum log level** is set to **Debug**, the binary will include log messages of levels **Error**, **Warning**, **Info**, and **Debug**. However, at runtime, only log messages of levels **Error** and **Warning** will be outputted unless the log level is explicitly changed using :cpp:func:`esp_log_level_set`. The log level can be adjusted, increased or decreased, depending on the user's needs.
7070

71-
**Maximum Log Level** Setting
71+
``Maximum Log Level`` Setting
7272
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7373

7474
The ``LOG_LOCAL_LEVEL`` definition allows you to override the **maximum log level** for a specific source file or component without modifying the Kconfig options. It effectively sets the **maximum log level** locally, enabling or excluding specific logs in the binary.
@@ -105,13 +105,13 @@ Example: Set the log level to ``ERROR`` for all components (global setting):
105105
106106
Adjusting log output per module (tag) depends on :ref:`CONFIG_LOG_TAG_LEVEL_IMPL`, which is enabled by default. If this feature is not required, you can disable it to reduce code size and improve performance:
107107

108-
Example: Set the log level to ``WARNING`` only for the Wi-Fi component (module-specific setting).
108+
Example: Set the log level to ``WARNING`` only for the Wi-Fi component (module-specific setting):
109109

110110
.. code-block:: c
111111
112112
esp_log_level_set("wifi", ESP_LOG_WARN);
113113
114-
Using Logging Library
114+
Use Logging Library
115115
---------------------
116116

117117
In each C file that uses the logging functionality, define the ``TAG`` variable.
@@ -203,7 +203,7 @@ The logging system supports the following formatting options, applicable for bot
203203
- **System time (HH:MM:SS.sss)** `(14:31:18.532)`: Displays time in hours, minutes, seconds, and milliseconds.
204204
- **System time (YY-MM-DD HH:MM:SS.sss)** `(2023-08-15 14:31:18.532)`: Similar to the above, but also includes the date.
205205
- **Unix time in milliseconds** `(1692099078532)`: Displays Unix time in milliseconds.
206-
- For **Log V2**, the :ref:`CONFIG_LOG_TIMESTAMP_SUPPORT` option enables runtime support for adding timestamp output to specific logs, files, or components, even if global timestamp is disabled. To enable the **Milliseconds since boot** timestamp for a specific context use ``ESP_LOG_TIMESTAMP_DISABLED``.
206+
- For **Log V2**, the :ref:`CONFIG_LOG_TIMESTAMP_SUPPORT` option enables runtime support for adding timestamp output to specific logs, files, or components, even if global timestamp is disabled. To enable the **Milliseconds since boot** timestamp for a specific context, use ``ESP_LOG_TIMESTAMP_DISABLED``.
207207

208208
- **Tag**: Displays a user-defined identifier for the source module.
209209

@@ -292,17 +292,17 @@ There are three settings that control the ability to change the log level at run
292292

293293
- Reducing memory consumption:
294294

295-
- **IRAM**: ~260 bytes
296-
- **DRAM**: ~264 bytes
297-
- **Flash**: ~1 KB
295+
- **IRAM**: about 260 bytes
296+
- **DRAM**: about 264 bytes
297+
- **Flash**: about 1 KB
298298

299299
- Boosting log operation performance by up to 10 times.
300300

301301
- **Tag-Level Checks** (:ref:`CONFIG_LOG_TAG_LEVEL_IMPL`, default **Cache + Linked List**): Determines how per-tag log level checks are performed, affecting memory usage and lookup speed:
302302

303303
- **None**: Disables per-tag log level checks entirely, reducing overhead but removing runtime flexibility.
304304

305-
- **Linked List**: Enables per-tag log level settings using a linked list-only implementation (no cache). This method searches through all tags in the linked list to determine the log level, which may result in slower lookups for a large number of tags but consumes less memory compared to the **cache** approach. The linked list approach performs full string comparisons of log tags to identify the appropriate log level. Unlike **Cache**, it does not rely on tag pointer comparisons, making it suitable for dynamic tag definitions. Select this option if you prioritize memory savings, need to enable or disable logs for specific modules, or want to use tags defined as variables. Selecting this option automatically enables **Dynamic Log Level Control**. The linked list entries are allocated on the heap during the execution of ``ESP_LOGx`` macros when a new tag is encountered.
305+
- **Linked List**: Enables per-tag log level settings using a linked list-only implementation (no cache). This method searches through all tags in the linked list to determine the log level, which may result in slower lookups for a large number of tags but consumes less memory compared to the **Cache** approach. The linked list approach performs full string comparisons of log tags to identify the appropriate log level. Unlike **Cache**, it does not rely on tag pointer comparisons, making it suitable for dynamic tag definitions. Select this option if you prioritize memory savings, need to enable or disable logs for specific modules, or want to use tags defined as variables. Selecting this option automatically enables **Dynamic Log Level Control**. The linked list entries are allocated on the heap during the execution of ``ESP_LOGx`` macros when a new tag is encountered.
306306

307307
- **Cache + Linked List** (Default): It is a hybrid mode that combines caching with a **linked list** for log tag level checks. This hybrid approach offers a balance between speed and memory usage. The cache stores recently accessed log tags and their corresponding log levels, providing faster lookups for frequently used tags. The cache approach compares the tag pointers, which is faster than performing full string comparisons. For less frequently used tags, the **linked list** is utilized to search for the log level. This option may not work properly when dynamic tag definitions are used, as it relies on tag pointer comparisons in the cache, which are not suitable for dynamically defined tags. This hybrid approach improves the efficiency of log level retrieval by leveraging the speed of caching for common tags and the memory efficiency of a linked list for less frequently used tags. Selecting this option automatically enables **Dynamic Log Level Control**.
308308

@@ -402,85 +402,136 @@ The logging system provides macros for logging buffer data. These macros can be
402402
403403
The number of lines in the output depends on the size of the buffer.
404404

405+
405406
Performance and Measurements
406407
----------------------------
407408

408409
When logging is used in a task, the task stack must be configured with at least 2 KB of space to ensure sufficient memory for logging operations.
409410

410411
The following measurements were performed using tests inside the log component with default settings (the maximum and default log levels were set to INFO, color support was disabled, without master log and timestamps were enabled) across different chips:
411412

412-
- ``Performance measurements for log APIs``.
413-
- ``Stack usage for log APIs``.
413+
- Performance measurements for log APIs
414+
- Stack usage for log APIs
414415

415416
``esp_rom_printf`` and ``esp_rom_vprintf`` produce similar results. Similarly, ``vprintf`` and ``printf`` yield comparable outcomes. Hence, only one of each pair is included in the tables below.
416417

417-
**Stack Usage (bytes):**
418-
419-
+-------------------+-------+---------+---------+
420-
| Function | ESP32 | ESP32C2 | ESP32C3 |
421-
+===================+=======+=========+=========+
422-
| esp_rom_printf | 128 | 192 | 192 |
423-
+-------------------+-------+---------+---------+
424-
| ESP_EARLY_LOGI V1 | 128 | 192 | 192 |
425-
+-------------------+-------+---------+---------+
426-
| ESP_EARLY_LOGI V2 | 336 | 324 | 324 |
427-
+-------------------+-------+---------+---------+
428-
| ESP_DRAM_LOGI V1 | 128 | 192 | 192 |
429-
+-------------------+-------+---------+---------+
430-
| ESP_DRAM_LOGI V2 | 336 | 324 | 324 |
431-
+-------------------+-------+---------+---------+
432-
| vprintf | 1168 | 384 | 1344 |
433-
+-------------------+-------+---------+---------+
434-
| ESP_LOGI V1 | 1184 | 384 | 1344 |
435-
+-------------------+-------+---------+---------+
436-
| ESP_LOGI V2 | 1152 | 592 | 1504 |
437-
+-------------------+-------+---------+---------+
418+
.. list-table:: Stack Usage (bytes)
419+
:header-rows: 1
420+
421+
* - Function
422+
- ESP32
423+
- ESP32C2
424+
- ESP32C3
425+
* - esp_rom_printf
426+
- 128
427+
- 192
428+
- 192
429+
* - ESP_EARLY_LOGI V1
430+
- 128
431+
- 192
432+
- 192
433+
* - ESP_EARLY_LOGI V2
434+
- 336
435+
- 324
436+
- 324
437+
* - ESP_DRAM_LOGI V1
438+
- 128
439+
- 192
440+
- 192
441+
* - ESP_DRAM_LOGI V2
442+
- 336
443+
- 324
444+
- 324
445+
* - vprintf
446+
- 1168
447+
- 384
448+
- 1344
449+
* - ESP_LOGI V1
450+
- 1184
451+
- 384
452+
- 1344
453+
* - ESP_LOGI V2
454+
- 1152
455+
- 592
456+
- 1504
438457

439458
The stack usage differences between **Log V1** and **Log V2** are negligible.
440459

441-
**Performance (without output in microseconds):**
442-
443-
+-------------------+-------+---------+---------+
444-
| Function | ESP32 | ESP32C2 | ESP32C3 |
445-
+===================+=======+=========+=========+
446-
| esp_rom_printf | 1 | 2 | 1 |
447-
+-------------------+-------+---------+---------+
448-
| ESP_EARLY_LOGI V1 | 15 | 24 | 14 |
449-
+-------------------+-------+---------+---------+
450-
| ESP_EARLY_LOGI V2 | 28 | 36 | 25 |
451-
+-------------------+-------+---------+---------+
452-
| ESP_DRAM_LOGI V1 | 6 | 9 | 5 |
453-
+-------------------+-------+---------+---------+
454-
| ESP_DRAM_LOGI V2 | 19 | 22 | 14 |
455-
+-------------------+-------+---------+---------+
456-
| vprintf | 15 | 9 | 7 |
457-
+-------------------+-------+---------+---------+
458-
| ESP_LOGI V1 | 27 | 16 | 12 |
459-
+-------------------+-------+---------+---------+
460-
| ESP_LOGI V2 | 77 | 54 | 40 |
461-
+-------------------+-------+---------+---------+
460+
.. list-table:: Performance (without output in microseconds)
461+
:header-rows: 1
462+
463+
* - Function
464+
- ESP32
465+
- ESP32C2
466+
- ESP32C3
467+
* - esp_rom_printf
468+
- 1
469+
- 2
470+
- 1
471+
* - ESP_EARLY_LOGI V1
472+
- 15
473+
- 24
474+
- 14
475+
* - ESP_EARLY_LOGI V2
476+
- 28
477+
- 36
478+
- 25
479+
* - ESP_DRAM_LOGI V1
480+
- 6
481+
- 9
482+
- 5
483+
* - ESP_DRAM_LOGI V2
484+
- 19
485+
- 22
486+
- 14
487+
* - vprintf
488+
- 15
489+
- 9
490+
- 7
491+
* - ESP_LOGI V1
492+
- 27
493+
- 16
494+
- 12
495+
* - ESP_LOGI V2
496+
- 77
497+
- 54
498+
- 40
462499

463500
If logging to UART is measured, the performance numbers for **Log V1** and **Log V2** are nearly identical. The slight differences in processing overhead introduced by **Log V2** become negligible compared to the time it takes to send logs over UART. Thus, in most practical use cases, the performance impact of switching to **Log V2** will be unnoticeable.
464501

465-
**Memory Usage (bytes):**
502+
**Memory Usage (bytes)**
466503

467504
The following measurements were performed using the ``esp_timer`` example with default settings for ESP32: the maximum and default log levels were set to INFO, color support was disabled, and timestamps were enabled. After enabling the **Log V2** option, the example was rebuilt, and the memory usage differences were compared using the command:
468505

469506
.. code-block:: bash
470507
471508
idf.py size --diff ~/esp/logv2/build_v1
472509
473-
+------------------------+---------------+--------------+---------------+------------+-----------------+
474-
| Version | IRAM | DRAM | Flash Code | Flash Data | App binary size |
475-
+========================+===============+==============+===============+============+=================+
476-
| Log V2 | +1772 | -36 | -956 | -1172 | 181104 (-384) |
477-
+------------------------+---------------+--------------+---------------+------------+-----------------+
478-
479-
+------------------------+-------------------------+
480-
| Version | Bootloader binary size |
481-
+========================+=========================+
482-
| Log V2 | 26272 (+160) |
483-
+------------------------+-------------------------+
510+
.. list-table::
511+
:header-rows: 1
512+
513+
* - Version
514+
- IRAM
515+
- DRAM
516+
- Flash Code
517+
- Flash Data
518+
- App binary size
519+
* - Log V2
520+
- +1772
521+
- –36
522+
- –956
523+
- –1172
524+
- 181104 (–384)
525+
526+
527+
.. list-table::
528+
:header-rows: 1
529+
:align: center
530+
531+
* - Version
532+
- Bootloader binary size
533+
* - Log V2
534+
- 26272 (+160)
484535

485536
Enabling **Log V2** increases IRAM usage while reducing the overall application binary size, Flash code, and data usage.
486537

0 commit comments

Comments
 (0)