{"id":15722516,"url":"https://github.com/insality/defold-log","last_synced_at":"2025-10-03T15:59:27.546Z","repository":{"id":224190754,"uuid":"762659769","full_name":"Insality/defold-log","owner":"Insality","description":"Context logger with performance metrics for Defold","archived":false,"fork":false,"pushed_at":"2025-03-07T20:17:01.000Z","size":659,"stargazers_count":28,"open_issues_count":4,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T19:45:19.115Z","etag":null,"topics":["defold","defold-extension","defold-library","defold-module","log","logger","logging"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Insality.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"insality","ko_fi":"insality","buy_me_a_coffee":"insality"}},"created_at":"2024-02-24T10:33:28.000Z","updated_at":"2025-02-17T21:08:16.000Z","dependencies_parsed_at":"2024-03-27T19:51:10.618Z","dependency_job_id":"573e6745-9e3d-4efc-b5a9-8d6850af6bc1","html_url":"https://github.com/Insality/defold-log","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.0625,"last_synced_commit":"fbd11476dc09a90f7e8a96529998a2b87e383ede"},"previous_names":["insality/defold-log"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Insality","download_url":"https://codeload.github.com/Insality/defold-log/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067773,"owners_count":21207395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-extension","defold-library","defold-module","log","logger","logging"],"created_at":"2024-10-03T22:08:16.066Z","updated_at":"2025-10-03T15:59:27.533Z","avatar_url":"https://github.com/Insality.png","language":"Lua","funding_links":["https://github.com/sponsors/insality","https://ko-fi.com/insality","https://buymeacoffee.com/insality","https://www.buymeacoffee.com/insality"],"categories":[],"sub_categories":[],"readme":"![](media/logo.png)\n\n[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/insality) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/insality) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/insality)\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/tag/insality/defold-log?style=for-the-badge\u0026label=Release)](https://github.com/Insality/defold-log/tags)\n\n# Log\n\n**Log** - is a single file Lua library for [Defold](https://defold.com/) game engine, enabling efficient logging for game development. It simplifies debugging and monitoring by allowing developers to generate detailed logs that can be adjusted for different stages of development.\n\n## Features\n\n- **Log Levels**: Includes TRACE, DEBUG, INFO, WARN, and ERROR for varied detail in logging.\n- **Build-specific Logging**: Allows changing log verbosity between debug and release builds.\n- **Detailed Context**: Supports logging with additional information for context, such as variable values or state information.\n- **Format Customization**: Allows customizing the log message format.\n- **Performance Tracking**: Provides features to log execution time and memory use.\n\n## Setup\n\n### [Dependency](https://www.defold.com/manuals/libraries/)\n\nOpen your `game.project` file and add the following line to the dependencies field under the project section:\n\n**[Log](https://github.com/Insality/defold-log/archive/refs/tags/6.zip)**\n\n```\nhttps://github.com/Insality/defold-log/archive/refs/tags/6.zip\n```\n\n### Library Size\n\n\u003e **Note:** The library size is calculated based on the build report per platform\n\n| Platform         | Library Size |\n| ---------------- | ------------ |\n| HTML5            | **2.55 KB**  |\n| Desktop / Mobile | **4.29 KB**  |\n\n### Configuration [Optional]\n\nYou have the option to configure logging preferences directly within your `game.project` file. This allows you to customize the log message format, log levels, and other settings based on your project's requirements.\n\nThis is a default configuration for the Log module, all fields are optional, and this is a default value:\n\n```ini\n[log]\nlevel = TRACE\nlevel_release = ERROR\ninfo_block = %levelname[%logger]\nmessage_block = %space%message: %context %tab\u003c%function\u003e\nlogger_block_width = 14\nmax_log_length = 1024\ninspect_depth = 1\n```\n\nThis configuration section for `game.project` defines various settings:\n\n| Setting             | Description                                                                                                                                                                                                 | Default Value     |\n|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------- |\n| **level**           | Sets the default logging level for development builds. In this case, `TRACE` and above levels will be logged, providing detailed information for debugging and monitoring.                                   | `TRACE`             |\n| **level_release**   | Determines the logging level for release builds, where `ERROR` and above levels will be logged, focusing on warnings and errors that are critical for a production environment. Use `FATAL` to silence all logs. | `ERROR`             |\n| **info_block**      | Defines the format of the info block in log messages, which includes the log level and logger name in this configuration.                                                                                     | `%levelname[%logger]` |\n| **message_block**   | Sets the format for the message block, including the actual log message, any context provided, and the function from which the log was called.                                                               | `%space%message: %context %tab\u003c%function\u003e` |\n| **logger_block_width** | Defines the width of the logger block in log messages. This helps in aligning log messages for better readability. Default is 14.                                                                          | `14` |\n| **max_log_length**  | The maximum length of the log message. If the message exceeds this length, it will be truncated. Default is 1024.                                                                                            | `1024` |\n| **inspect_depth**   | The maximum depth of nested tables to inspect when logging. Default is 1.                                                                                                                                    | `1` |\n\nIn the `[log]` configuration section for `game.project`, the `info_block` and `message_block` fields allow for dynamic content based on specific placeholders. These placeholders get replaced with actual log information at runtime, providing structured and informative log messages.\n\n#### Info Block Placeholders\n\n| Placeholder          | Description                                                                                                                                                                                                 |\n|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **%logger**          | The name of the logger instance producing the log message. Helps in identifying the source of the log message.                                                                                               |\n| **%levelname**       | The name of the log level (e.g., DEBUG, INFO, WARN, etc.). Provides clarity on the severity or nature of the log message. Should be placed at the beginning of the log message for color highlighting in the Defold Console. |\n| **%levelshort**      | The short name of the log level (e.g., D, I, W, E). Provides a compact representation of the log level. But Defold Console will be not able to highlight it.                                                 |\n| **%time_tracking**   | The time elapsed since the last entry in this logger instance. Time tracking will be enabled, if this placeholder is used.                                                                                   |\n| **%memory_tracking** | The memory allocated since the last entry in this logger instance. Memory tracking will be enabled, if this placeholder is used.                                                                             |\n| **%chronos_tracking**| The time elapsed since the last entry in this logger instance. Chronos extension will be used, if this placeholder is used.                                                                                  |\n\n#### Message Block Placeholders\n\n| Placeholder  | Description                                                                                                                                                                                                 |\n|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **%tab**     | A tab character for formatting log messages.                                                                                                                                                                |\n| **%space**   | A space character for formatting log messages. Usually used before or end of the message, where you can't use just space in game.project.                                                                         |\n| **%message** | The actual log message content. This is the primary information you want to log.                                                                                                                            |\n| **%context** | Any additional context provided along with the log message. It can be useful for providing extra information relevant to the log message (e.g., variable values, state information).                        |\n| **%function**| The function name or location from where the log message was generated. Helps in pinpointing where in the codebase a particular log message is coming from, aiding in debugging.                             |\n\n\n#### Output Prefabs\n\n```ini\n[log]\ninfo_block = %levelname[%logger]\nmessage_block = %space%message: %context %tab\u003c%function\u003e\n```\n\n**Preview:**\n\n```\nDEBUG:[game.logger     ] Debug message: {debug: message, value: 2} \t\u003cexample/example.gui_script:17\u003e\n```\n\n---\n\n```ini\n[log]\ninfo_block = %levelname| %time_tracking | %memory_tracking | %logger\nmessage_block = | %tab%message: %context %tab\u003c%function\u003e\n```\n\n**Preview:**\n\n```\nDEBUG:| 166.71ms |   2.4kb | game.logger      |\tDelayed message: just string \t\u003cexample/example.gui_script:39\u003e\n```\n\n### Memory Tracking\n\nTo enable memory tracking, add `%memory_tracking` to the `info_block` in the `game.project` file:\n\n```ini\ninfo_block = %levelname| %memory_tracking | %logger\n```\n\nThis will include memory tracking information in the log messages, showing the memory allocated since the last entry in this logger instance.\n\n\u003eDEBUG:|   2.4kb | game.logger      |\tDelayed message: just string \t\u003cexample/example.gui_script:39\u003e`.\n\nWorks only in debug mode, automatically disabled in release mode.\n\n\n### Time Tracking\n\nTo enable time tracking, add `%time_tracking` to the `info_block` in the `game.project` file:\n\n```ini\ninfo_block = %levelname| %time_tracking | %logger\n```\n\nThis will include time tracking information in the log messages, showing the time elapsed since the last entry in this logger instance.\n\n\u003eDEBUG:|  0.01ms | game.logger      |\tDelayed message: just string \t\u003cexample/example.gui_script:39\u003e`.\n\n\n### Using High Resolution Timer Extension\n\nThe Log module can utilize the Chronos extension for Defold to enable time tracking with microsecond or better precision (`QueryPerformanceCounter` on Windows). This is optional.\n\nIf you want to use the extension, add the following line to the dependencies field in your `game.project` file:\n\n**[defold-chronos](https://github.com/d954mas/defold-chronos)**\n```\nhttps://github.com/d954mas/defold-chronos/archive/refs/tags/1.0.1.zip\n```\n\nThen to use the high-resolution timer, you need to add `%chronos_tracking` to the `info_block` in the `game.project` file:\n\n```ini\n[log]\ninfo_block = %levelname| %chronos_tracking | %logger\n```\n\nThis will include time tracking information in the log messages, showing the time elapsed since the last entry in this logger instance.\n\n\u003eDEBUG:|  0.00001ms | game.logger      |\tDelayed message: just string \t\u003cexample/example.gui_script:39\u003e`.\n\n\n### Using Native UTF8 Extension\n\nThe Log module can utilize the native UTF8 extension for Defold to handle UTF-8 strings. This is optional but recommended for better performance.\n\nIf you want to use the native UTF8 extension, add the following line to the dependencies field in your `game.project` file:\n\n**[defold-utf8](https://github.com/d954mas/defold-utf8)**\n```\nhttps://github.com/d954mas/defold-utf8/archive/master.zip\n```\n\nThe Log module automatically detects the presence of the native UTF8 extension and uses it if available. If the extension is not present, the Log module will use the built-in Lua string functions.\n\n### Default view\n\n![Default view](media/logs_example.png)\n\n## API Documentation\n\n### Quick API Reference\n\n```lua\nlocal log = require(\"log.log\")\nlog:trace(message, [data])\nlog:debug(message, [data])\nlog:info(message, [data])\nlog:warn(message, [data])\nlog:error(message, [data])\n\n-- Create a new logger instance with a specific logger name.\n-- Default logger name is file name of the current script.\nlocal logger = log.get_logger([logger_name], [force_logger_level_in_debug])\nlogger:trace(message, [data])\nlogger:debug(message, [data])\nlogger:info(message, [data])\nlogger:warn(message, [data])\nlogger:error(message, [data])\n\n-- There is short version of this\nlocal logger = require(\"log.log\")()\nlocal logger = require(\"log.log\")([name], [level])\n```\n\n### Setup and Initialization\n\nTo start using the Log module in your project, you first need to import it. This can be done with the following line of code:\n\n```lua\nlocal log = require(\"log.log\")\n```\n\n\u003e The log module itself is logger instance with name equals to `project.title`. All `logger` methods can be invoked on `log` module itself. But general practice it to create a specific logger for each module.\n\n### Core Functions\n\n**log.get_logger**\n---\n```lua\nlog.get_logger([logger_name], [force_logger_level_in_debug])\n```\nCreate a new logger instance with an optional forced log level for debugging purposes.\n\n- **Parameters:**\n  - `logger_name`: A string representing the name of the logger. Default is file name of the current script.\n  - `force_logger_level_in_debug` (optional): A string representing the forced log level when in debug mode (e.g., \"DEBUG\", \"INFO\").\n\n- **Return Value:** A new logger instance.\n\n- **Usage Example:**\n\n```lua\nlocal my_logger = log.get_logger(\"game.logger\")\n```\n\n### Logger Instance Methods\n\nOnce a logger instance is created, you can use the following methods to log messages at different levels. Each logging method allows including optional data for context, which can be especially useful for debugging. However, note that passing data can lead to additional memory allocation, which might impact performance.\n\n**logger:trace**\n---\n```lua\nlogger:trace(message, [data])\n```\nLog a message at the TRACE level. Trace is typically used to log the start and end of functions or specific events. While it's not recommended to pass data to trace due to potential memory allocation, sometimes it can be useful for in-depth debugging.\n\n- **Parameters:**\n  - `message`: The log message.\n  - `data` (optional): Additional data to include with the log message.\n\n- **Usage Example:**\n\n```lua\nmy_logger:trace(\"Trace message\")\n\n-- TRACE:[game.logger     ]\tTrace message:  \t\u003cexample/example.gui_script:55\u003e\n-- TRACE:|   0.01ms |   0.4kb | game.logger     | \tTrace message:  \t\u003cexample/example.gui_script:54\u003e\n```\n\n**logger:debug**\n---\n```lua\nlogger:debug(message, [data])\n```\nLog a message at the DEBUG level. Debug is suitable for detailed system information that could be helpful during development to track down unexpected behavior.\n\n- **Usage Example:**\n\n```lua\nmy_logger:debug(\"Debug message\", { key = \"value\" })\n\n-- DEBUG:[game.logger     ]\tDebug message: {key: value} \t\u003cexample/example.gui_script:56\u003e\n-- DEBUG:|   0.00ms |   0.1kb | game.logger     | \tDebug message: {key: value} \t\u003cexample/example.gui_script:55\u003e\n```\n\n**logger:info**\n---\n```lua\nlogger:info(message, [data])\n```\nLog a message at the INFO level. Info is used for general system information under normal operation.\n\n- **Usage Example:**\n\n```lua\nmy_logger:info(\"Info message\", { key = \"value\" })\n\n-- INFO: [game.logger     ]\tInfo message: {key: value} \t\u003cexample/example.gui_script:57\u003e\n-- INFO: |   0.00ms |   0.1kb | game.logger     | \tInfo message: {key: value} \t\u003cexample/example.gui_script:56\u003e\n```\n\n**logger:warn**\n---\n```lua\nlogger:warn(message, [data])\n```\nLog a message at the WARN level. Warn is intended for potentially harmful situations that could require attention.\n\n- **Usage Example:**\n\n```lua\nmy_logger:warn(\"Warn message\", { key = \"value\" })\n\n-- WARN: [game.logger     ]\tWarn message: {key: value} \t\u003cexample/example.gui_script:58\u003e\n-- WARN: |   0.00ms |   0.1kb | game.logger     | \tWarn message: {key: value} \t\u003cexample/example.gui_script:57\u003e\n```\n\n**logger:error**\n---\n```lua\nlogger:error(message, [data])\n```\nLog a message at the ERROR level. Error indicates serious issues that have occurred and should be addressed immediately.\n\n- **Usage Example:**\n\n```lua\nmy_logger:error(\"Error message\", {error = \"file not found\"})\n\n-- ERROR:[game.logger     ]\tError message: {key: value} \t\u003cexample/example.gui_script:59\u003e\n-- ERROR:|   0.00ms |   0.1kb | game.logger     | \tError message: {key: value} \t\u003cexample/example.gui_script:58\u003e\n```\n\nThese methods provide a comprehensive logging solution, allowing you to capture detailed information about your application's behavior, performance, and issues across different stages of development.\n\n\n## Usage Examples\n\n### Basic Logging\n\n```lua\nlocal log = require(\"log.log\")\n\n-- Create logger instances for different components of your game\nlocal logger = log.get_logger(\"game.logger\")\n\nfunction init(self)\n    logger:trace(\"init\")\n    logger:debug(\"Debugging game start\", { level = 1, start = true })\n    logger:info(\"Game level loaded\")\n    logger:warn(\"Unexpected behavior detected\", \"context_can_be_any_type\")\n    logger:error(\"Critical error encountered\", { error = \"out of memory\" })\nend\n\n```\n\n### Use Cases\n\nRead the [Use Cases](USE_CASES.md) file for detailed examples of how to use the Log module in different scenarios.\n\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n\n## Issues and Suggestions\n\nFor any issues, questions, or suggestions, please [create an issue](https://github.com/Insality/defold-log/issues).\n\nTo contribute, please look for issues tagged with `[Contribute]`, solve them, and submit a PR focusing on performance and code style for efficient and maintainable enhancements. Your contributions are greatly appreciated!\n\n\n## 👏 Contributors\n\n\u003ca href=\"https://github.com/Insality/defold-log/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=insality/defold-log\"/\u003e\n\u003c/a\u003e\n\n\n## Changelog\n\n\u003cdetails\u003e\n\n### **V1**\n- Initial release\n\n### **V2**\n- Add chronos extension support\n\n### **V3**\n- [#1] Add inspect_depth settings to game.project\n- [#2] Add max_log_length settings to game.project\n\n### **V4**\n- Now log module can be used as logger itself\n\n### **V5**\n- Add `FATAL` level for silent all logs\n\t- Designed for release builds\n- Now logger name is optional, by default it's file name of the current script.\n- Changed default Log module settings\n\t- Improved visualization and color highlighting in Defold Console\n- Removed time and memory tracking options from `game.project`\n\t- Now it's possible to use `%time_tracking` and `%memory_tracking` placeholders in `info_block` to track time and memory usage.\n\t- For time tracking with chronos extension, use the `%chronos_tracking` placeholder.\n\n### **V6**\n- Add shortcuts to create logger instance:\n```lua\nlocal log = require(\"log.log\")\nlocal logger = log.get_logger(\"name\")\nlocal logger = log.get_logger(\"name\", \"TRACE\")\n\nlocal logger = require(\"log.log\")()\nlocal logger = require(\"log.log\")(\"name\")\nlocal logger = require(\"log.log\")(\"name\", \"TRACE\")\n```\n- Add auto-name for loggers from log.* interface, it will match the file name of the current script.\nSo now the shortest way to use log module is:\n```lua\nlocal log = require(\"log.log\")\n\nlog:trace(\"Hello, world!\", { key = \"value\" })\nlog:info(\"Hello, world!\")\nlog:erro(\"Hello, world!\")\n```\n\n\u003c/details\u003e\n\n\n## ❤️ Support the Project ❤️\n\nYour support motivates me to keep creating and maintaining projects for **Defold**. Consider supporting if you find my projects helpful and valuable.\n\n[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/insality) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/insality) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/insality)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsality%2Fdefold-log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsality%2Fdefold-log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsality%2Fdefold-log/lists"}