# robocorp-log
`robocorp-log` is a library which provides comprehensible logging for Python with a focus on Python automation, where detailed information on what happened and why a failure occurs is of vital importance.
> Note: The format of the log is not a part of the API and should not be relied upon as it can change even between minor versions.
## Why
Although Python logging is flexible it may be hard to analyze the logging afterwards and visualize it. Also, the format may end up using a big amount of disk space and it may be tedious to add logging calls to all places of interest.
## How
`robocorp-log` improves those aspects by using a structured format which enables using less disk space while also providing a viewer (`log.html`) for the generated content.
Also, it provides utilities to setup logging so that logging is done automatically without having to explicitly add calls to add content to the logging (although it's still possible to do so when needed).
### Usage
It's recommended that `robocorp-log` is used through `robocorp-tasks` as `robocorp-tasks` will configure `robocorp-log` in a streamlined way, where you just need to worry about marking the entry point method with a `@tasks` decorator and it'll automatically setup the auto-logging and provide the log result in `output/log.html`.
#### Configuring with pyproject.toml
`robocorp-tasks` takes care of customizing `robocorp-log` through `pyproject.toml`.
See the `robocorp-tasks` project for more information (`robocorp-log` only provides the core logging structure and different libraries may customize it in different ways).
Although the setup is done through `robocorp-tasks`, there are still some APIs in `robocorp.log` which are interesting to use such as:
- Utility methods to add a log message as `critical`, `warn`, `info`, `debug`, `exception`
- Utility method to add an `html` message (using the `html` method). Note that the `html` method is tested for images with base64 contents in the `log.html`, other structures must be manually checked as they can break the layout. Also, keep in mind that the provided html will be sanitized.
- Supressing logging through `suppress_variables`, `suppress_methods`, `suppress`.
- Hiding sensitive data (automatically based on variable or argument names with names registered in `add_sensitive_variable_name` and `add_sensitive_variable_name_pattern`) or by passing the value to be hidden to `hide_from_output`.
### Caveats
The auto import mode is done by having a pre-import hook which will change the AST at runtime. This mostly works, but there are a couple of caveats to keep in mind:
1. Debuggers may end up stepping into the `robocorp-log` code in
many places even if such code isn't in the source code (you may want to configure the debugger you're using to skip calls into `robocorp.log` as that's usually just an implementation detail).
2. The logging needs to be fully setup prior to importing any module that should be automatically logged.
3. Working with coroutines (`async`, `await` and `greenlet`) is not supported.
## Guides
- [Dealing with sensitive data](https://github.com/robocorp/robocorp/blob/master/log/docs/guides/00-sensitive-data.md)
- [The `.robolog` format](https://github.com/robocorp/robocorp/blob/master/log/docs/guides/01-robolog-format.md)
## API Reference
Explore our [API](https://github.com/robocorp/robocorp/blob/master/log/docs/api/README.md) for extensive documentation.
## Changelog
A list of releases and corresponding changes can be found in the [changelog](https://github.com/robocorp/robocorp/blob/master/log/docs/CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/robocorp/robocorp/",
"name": "robocorp-log",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Fabio Z.",
"author_email": "fabio@robocorp.com",
"download_url": "https://files.pythonhosted.org/packages/2e/5a/e3f731c51ebdfdb73b11aba704216655e8968dc744e40f85db22a0ff7e47/robocorp_log-2.9.3.tar.gz",
"platform": null,
"description": "# robocorp-log\n\n`robocorp-log` is a library which provides comprehensible logging for Python with a focus on Python automation, where detailed information on what happened and why a failure occurs is of vital importance.\n\n> Note: The format of the log is not a part of the API and should not be relied upon as it can change even between minor versions.\n\n## Why\n\nAlthough Python logging is flexible it may be hard to analyze the logging afterwards and visualize it. Also, the format may end up using a big amount of disk space and it may be tedious to add logging calls to all places of interest.\n\n## How\n\n`robocorp-log` improves those aspects by using a structured format which enables using less disk space while also providing a viewer (`log.html`) for the generated content.\n\nAlso, it provides utilities to setup logging so that logging is done automatically without having to explicitly add calls to add content to the logging (although it's still possible to do so when needed).\n\n### Usage\n\nIt's recommended that `robocorp-log` is used through `robocorp-tasks` as `robocorp-tasks` will configure `robocorp-log` in a streamlined way, where you just need to worry about marking the entry point method with a `@tasks` decorator and it'll automatically setup the auto-logging and provide the log result in `output/log.html`.\n\n#### Configuring with pyproject.toml\n\n`robocorp-tasks` takes care of customizing `robocorp-log` through `pyproject.toml`. \nSee the `robocorp-tasks` project for more information (`robocorp-log` only provides the core logging structure and different libraries may customize it in different ways).\n\nAlthough the setup is done through `robocorp-tasks`, there are still some APIs in `robocorp.log` which are interesting to use such as:\n\n- Utility methods to add a log message as `critical`, `warn`, `info`, `debug`, `exception`\n\n- Utility method to add an `html` message (using the `html` method). Note that the `html` method is tested for images with base64 contents in the `log.html`, other structures must be manually checked as they can break the layout. Also, keep in mind that the provided html will be sanitized.\n \n- Supressing logging through `suppress_variables`, `suppress_methods`, `suppress`.\n\n- Hiding sensitive data (automatically based on variable or argument names with names registered in `add_sensitive_variable_name` and `add_sensitive_variable_name_pattern`) or by passing the value to be hidden to `hide_from_output`.\n \n### Caveats\n\nThe auto import mode is done by having a pre-import hook which will change the AST at runtime. This mostly works, but there are a couple of caveats to keep in mind:\n\n1. Debuggers may end up stepping into the `robocorp-log` code in\nmany places even if such code isn't in the source code (you may want to configure the debugger you're using to skip calls into `robocorp.log` as that's usually just an implementation detail).\n\n2. The logging needs to be fully setup prior to importing any module that should be automatically logged.\n\n3. Working with coroutines (`async`, `await` and `greenlet`) is not supported.\n\n## Guides\n\n- [Dealing with sensitive data](https://github.com/robocorp/robocorp/blob/master/log/docs/guides/00-sensitive-data.md)\n- [The `.robolog` format](https://github.com/robocorp/robocorp/blob/master/log/docs/guides/01-robolog-format.md)\n\n## API Reference\n\nExplore our [API](https://github.com/robocorp/robocorp/blob/master/log/docs/api/README.md) for extensive documentation.\n\n## Changelog\n\nA list of releases and corresponding changes can be found in the [changelog](https://github.com/robocorp/robocorp/blob/master/log/docs/CHANGELOG.md).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Automatic trace logging for Python",
"version": "2.9.3",
"project_urls": {
"Homepage": "https://github.com/robocorp/robocorp/",
"Repository": "https://github.com/robocorp/robocorp/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7e9c77a0ff8d7e86c285b3ee4489dd779d569265df1c6e263562e76bedebf583",
"md5": "24c7712c57dbbaed79509e9c826087e4",
"sha256": "ef365b5c67c392835cd1af10f898e4ed37b7058e075dc7957bf0cd44653d7100"
},
"downloads": -1,
"filename": "robocorp_log-2.9.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24c7712c57dbbaed79509e9c826087e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 350506,
"upload_time": "2024-09-26T13:05:14",
"upload_time_iso_8601": "2024-09-26T13:05:14.252425Z",
"url": "https://files.pythonhosted.org/packages/7e/9c/77a0ff8d7e86c285b3ee4489dd779d569265df1c6e263562e76bedebf583/robocorp_log-2.9.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2e5ae3f731c51ebdfdb73b11aba704216655e8968dc744e40f85db22a0ff7e47",
"md5": "15c03463166b08f6a0b140e479c15d75",
"sha256": "ecde32a50489af16a9f4941452d729298d809fcf212772559c93965854cdef17"
},
"downloads": -1,
"filename": "robocorp_log-2.9.3.tar.gz",
"has_sig": false,
"md5_digest": "15c03463166b08f6a0b140e479c15d75",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 341511,
"upload_time": "2024-09-26T13:05:16",
"upload_time_iso_8601": "2024-09-26T13:05:16.055050Z",
"url": "https://files.pythonhosted.org/packages/2e/5a/e3f731c51ebdfdb73b11aba704216655e8968dc744e40f85db22a0ff7e47/robocorp_log-2.9.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-26 13:05:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robocorp",
"github_project": "robocorp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "robocorp-log"
}
JSON
