# Alchemy Logging (alog) - Python
The `alog` framework provides tunable logging with easy-to-use defaults and power-user capabilities. The mantra of `alog` is **"Log Early And Often"**. To accomplish this goal, `alog` makes it easy to enable verbose logging at develop/debug time and trim the verbosity at production run time.
## Setup
To use the `alog` module, simply install it with `pip`:
```sh
pip install alchemy-logging
```
## Channels and Levels
The primary components of the framework are **channels** and **levels** which allow for each log statement to be enabled or disabled when appropriate.
1. **Levels**: Each logging statement is made at a specific level. Levels provide sequential granularity, allowing detailed debugging statements to be placed in the code without clogging up the logs at runtime. The sequence of levels and their general usage is as follows:
1. `off`: Disable the given channel completely
1. `fatal`: A fatal error has occurred. Any behavior after this statement should be regarded as undefined.
1. `error`: An unrecoverable error has occurred. Any behavior after this statement should be regarded as undefined unless the error is explicitly handled.
1. `warning`: A recoverable error condition has come up that the service maintainer should be aware of.
1. `info`: High-level information that is valuable at runtime under moderate load.
1. `trace`: Used to log begin/end of functions for debugging code paths.
1. `debug`: High-level debugging statements such as function parameters.
1. `debug1`: High-level debugging statements.
1. `debug2`: Mid-level debugging statements such as computed values.
1. `debug3`: Low-level debugging statements such as computed values inside loops.
1. `debug4`: Ultra-low-level debugging statements such as data dumps and/or statements inside multiple nested loops.
1. **Channels**: Each logging statement is made to a specific channel. Channels are independent of one another and allow for logical grouping of log messages by functionality. A channel can be any string. A channel may have a specific **level** assigned to it, or it may use the configured default level if it is not given a specific level filter.
Using this combination of **Channels** and **Levels**, you can fine-tune what log statements are enabled when you run your application under different circumstances.
## Usage
### Configuration
```py
import alog
if __name__ == "__main__":
alog.configure(default_level="info", filters="FOO:debug,BAR:off")
```
In this example, the channel `"FOO"` is set to the `debug` level, the channel `"BAR"` is fully disabled, and all other channels are set to use the `INFO` level.
In addition to the above, the `configure` function also supports the following arguments:
* `formatter`: May be `"pretty"`, `"json"`, or any class derived from `AlogFormatterBase`
* `thread_id`: Bool indicating whether or not to include a unique thread ID with the logging header (`pretty`) or structure (`json`).
* `handler_generator`: This allows users to provide their own output handlers and replace the standard handler that sends log messages to `stderr`. See [the `logging` documentation](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers) for details.
### Logging Functions
For each log level, there are two functions you can use to create log lines: The standard `logging` package function, or the corresponding `alog.use_channel(...).<level>` function. The former will always log to the `root` channel while the later requires that
a channel string be specified via `use_channel()`.
```py
import alog
import logging
def foo(age):
alog.use_channel("FOO").debug3(
"Debug3 line on the FOO channel with an int value %d!", age
)
logging.debug("debug line on the MAIN channel")
```
### Channel Log
In a given portion of code, it often makes sense to have a common channel that is used by many logging statements. Re-typing the channel name can be cumbersome and error-prone, so the concept of the **Channel Log** helps to eliminate this issue. To create a Channel Log, call the `use_channel` function. This gives you a handle to a channel log which has all of the same standard log functions as the top-level `alog`, but without the requirement to specify a channel. For example:
```py
import alog
log = alog.use_channel("FOO")
def foo(age):
log.info("Hello Logging World! I am %d years old", age)
```
**NOTE**: In this (python) implementation, this is simply a wrapper around `logging.getLogger()`
### Extra Log Information
There are several other types of information that `alog` supports adding to log records:
#### Log Codes
This is an optional argument to all logging functions which adds a specified code to the record. It can be useful for particularly high-profile messages (such as per-request error summaries in a server) that you want to be able to track in a programmatic way. The only requirement for a `log_code` is that it begin with `<` and end with `>`. The log code always comes before the `message`. For example:
```py
ch = alog.use_channel("FOO")
ch.debug("<FOO80349757I>", "Logging is fun!")
```
#### Dict Data
Sometimes, it's useful to log structured key/value pairs in a record, rather than a plain-text message, even when using the `pretty` output formatter. To do this, simply use a `dict` in place of a `str` in the `message` argument to the logging function. For example:
```py
ch = alog.use_channel("FOO")
ch.debug({"foo": "bar"})
```
When a `dict` is logged with the `json` formatter enabled, all key/value pairs are added as key/value pairs under the top-level `message` key.
### Log Contexts
One of the most common uses for logging is to note events when a certain block of code executes. To facilitate this, `alog` has the concept of log contexts. The two primary contexts that `alog` supports are:
* `ContextLog`: This [contextmanager](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) logs a `START:` message when the context starts and an `END:` message when the context ends. All messages produced within the same thread inside of the context will have an incremented level of indentation.
```py
import alog
alog.configure("debug2")
log = alog.use_channel("DEMO")
with alog.ContextLog(log.info, "Doing some work"):
log.debug("Deep in the muck!")
```
```
2021-07-29T19:09:03.819422 [DEMO :INFO] BEGIN: Doing some work
2021-07-29T19:09:03.820079 [DEMO :DBUG] Deep in the muck!
2021-07-29T19:09:03.820178 [DEMO :INFO] END: Doing some work
```
* `ContextTimer`: This [contextmanager](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) starts a timer when the context begins and logs a message with the duration when the context ends.
```py
import alog
import time
alog.configure("debug2")
log = alog.use_channel("DEMO")
with alog.ContextTimer(log.info, "Slow work finished in: "):
log.debug("Starting the slow work")
time.sleep(1)
```
```
2021-07-29T19:12:00.887949 [DEMO :DBUG] Starting the slow work
2021-07-29T19:12:01.890839 [DEMO :INFO] Slow work finished in: 0:00:01.002793
```
### Function Decorators
In addition to arbitrary blocks of code that you may wish to scope or time, a very common use case for logging contexts is to provide function tracing. To this end, `alog` provides two useful function decorators:
* `@logged_function`: This [decorator](https://www.python.org/dev/peps/pep-0318/) wraps the `ContextLog` and provides a `START`/`END` scope where the message is prepopulated with the name of the function.
```py
import alog
alog.configure("debug")
log = alog.use_channel("DEMO")
@alog.logged_function(log.trace)
def foo():
log.debug("This is a test")
foo()
```
```
2021-07-29T19:16:40.036119 [DEMO :TRCE] BEGIN: foo()
2021-07-29T19:16:40.036807 [DEMO :DBUG] This is a test
2021-07-29T19:16:40.036915 [DEMO :TRCE] END: foo()
```
* `@timed_function`: This [decorator](https://www.python.org/dev/peps/pep-0318/) wraps the `ContextTimer` and performs a scoped timer on the entire function.
```py
import alog
import time
alog.configure("debug")
log = alog.use_channel("DEMO")
@alog.timed_function(log.trace)
def foo():
log.debug("This is a test")
time.sleep(1)
foo()
```
```
2021-07-29T19:19:47.468428 [DEMO :DBUG] This is a test
2021-07-29T19:19:48.471788 [DEMO :TRCE] 0:00:01.003284
```
## Tip
- Visual Studio Code (VSCode) users can take advantage of [alchemy-logging extension](https://marketplace.visualstudio.com/items?itemName=Gaurav-Kumbhat.alog-code-generator) that provides automatic log code generation and insertion.
Raw data
{
"_id": null,
"home_page": "https://github.com/IBM/alchemy-logging",
"name": "alchemy-logging",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "logging",
"author": "Gabe Goodhart",
"author_email": "gabe.l.hart@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f0/2a/950fc0f382a65023e64301d9a3a24458b0f7d9be45df7ca7bd242bee4f8a/alchemy-logging-1.5.0.tar.gz",
"platform": null,
"description": "# Alchemy Logging (alog) - Python\nThe `alog` framework provides tunable logging with easy-to-use defaults and power-user capabilities. The mantra of `alog` is **\"Log Early And Often\"**. To accomplish this goal, `alog` makes it easy to enable verbose logging at develop/debug time and trim the verbosity at production run time.\n\n## Setup\nTo use the `alog` module, simply install it with `pip`:\n\n```sh\npip install alchemy-logging\n```\n\n## Channels and Levels\nThe primary components of the framework are **channels** and **levels** which allow for each log statement to be enabled or disabled when appropriate.\n\n1. **Levels**: Each logging statement is made at a specific level. Levels provide sequential granularity, allowing detailed debugging statements to be placed in the code without clogging up the logs at runtime. The sequence of levels and their general usage is as follows:\n\n 1. `off`: Disable the given channel completely\n 1. `fatal`: A fatal error has occurred. Any behavior after this statement should be regarded as undefined.\n 1. `error`: An unrecoverable error has occurred. Any behavior after this statement should be regarded as undefined unless the error is explicitly handled.\n 1. `warning`: A recoverable error condition has come up that the service maintainer should be aware of.\n 1. `info`: High-level information that is valuable at runtime under moderate load.\n 1. `trace`: Used to log begin/end of functions for debugging code paths.\n 1. `debug`: High-level debugging statements such as function parameters.\n 1. `debug1`: High-level debugging statements.\n 1. `debug2`: Mid-level debugging statements such as computed values.\n 1. `debug3`: Low-level debugging statements such as computed values inside loops.\n 1. `debug4`: Ultra-low-level debugging statements such as data dumps and/or statements inside multiple nested loops.\n\n1. **Channels**: Each logging statement is made to a specific channel. Channels are independent of one another and allow for logical grouping of log messages by functionality. A channel can be any string. A channel may have a specific **level** assigned to it, or it may use the configured default level if it is not given a specific level filter.\n\nUsing this combination of **Channels** and **Levels**, you can fine-tune what log statements are enabled when you run your application under different circumstances.\n\n## Usage\n\n### Configuration\n\n```py\nimport alog\n\nif __name__ == \"__main__\":\n alog.configure(default_level=\"info\", filters=\"FOO:debug,BAR:off\")\n```\n\nIn this example, the channel `\"FOO\"` is set to the `debug` level, the channel `\"BAR\"` is fully disabled, and all other channels are set to use the `INFO` level.\n\nIn addition to the above, the `configure` function also supports the following arguments:\n\n* `formatter`: May be `\"pretty\"`, `\"json\"`, or any class derived from `AlogFormatterBase`\n* `thread_id`: Bool indicating whether or not to include a unique thread ID with the logging header (`pretty`) or structure (`json`).\n* `handler_generator`: This allows users to provide their own output handlers and replace the standard handler that sends log messages to `stderr`. See [the `logging` documentation](https://docs.python.org/3/library/logging.handlers.html#module-logging.handlers) for details.\n\n### Logging Functions\nFor each log level, there are two functions you can use to create log lines: The standard `logging` package function, or the corresponding `alog.use_channel(...).<level>` function. The former will always log to the `root` channel while the later requires that\na channel string be specified via `use_channel()`.\n\n```py\nimport alog\nimport logging\n\ndef foo(age):\n alog.use_channel(\"FOO\").debug3(\n \"Debug3 line on the FOO channel with an int value %d!\", age\n )\n logging.debug(\"debug line on the MAIN channel\")\n```\n\n### Channel Log\nIn a given portion of code, it often makes sense to have a common channel that is used by many logging statements. Re-typing the channel name can be cumbersome and error-prone, so the concept of the **Channel Log** helps to eliminate this issue. To create a Channel Log, call the `use_channel` function. This gives you a handle to a channel log which has all of the same standard log functions as the top-level `alog`, but without the requirement to specify a channel. For example:\n\n```py\nimport alog\n\nlog = alog.use_channel(\"FOO\")\n\ndef foo(age):\n log.info(\"Hello Logging World! I am %d years old\", age)\n```\n\n**NOTE**: In this (python) implementation, this is simply a wrapper around `logging.getLogger()`\n\n### Extra Log Information\n\nThere are several other types of information that `alog` supports adding to log records:\n\n#### Log Codes\n\nThis is an optional argument to all logging functions which adds a specified code to the record. It can be useful for particularly high-profile messages (such as per-request error summaries in a server) that you want to be able to track in a programmatic way. The only requirement for a `log_code` is that it begin with `<` and end with `>`. The log code always comes before the `message`. For example:\n\n```py\nch = alog.use_channel(\"FOO\")\nch.debug(\"<FOO80349757I>\", \"Logging is fun!\")\n```\n\n#### Dict Data\n\nSometimes, it's useful to log structured key/value pairs in a record, rather than a plain-text message, even when using the `pretty` output formatter. To do this, simply use a `dict` in place of a `str` in the `message` argument to the logging function. For example:\n\n```py\nch = alog.use_channel(\"FOO\")\nch.debug({\"foo\": \"bar\"})\n```\n\nWhen a `dict` is logged with the `json` formatter enabled, all key/value pairs are added as key/value pairs under the top-level `message` key.\n\n### Log Contexts\nOne of the most common uses for logging is to note events when a certain block of code executes. To facilitate this, `alog` has the concept of log contexts. The two primary contexts that `alog` supports are:\n\n* `ContextLog`: This [contextmanager](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) logs a `START:` message when the context starts and an `END:` message when the context ends. All messages produced within the same thread inside of the context will have an incremented level of indentation.\n\n```py\nimport alog\n\nalog.configure(\"debug2\")\nlog = alog.use_channel(\"DEMO\")\n\nwith alog.ContextLog(log.info, \"Doing some work\"):\n log.debug(\"Deep in the muck!\")\n```\n\n```\n2021-07-29T19:09:03.819422 [DEMO :INFO] BEGIN: Doing some work\n2021-07-29T19:09:03.820079 [DEMO :DBUG] Deep in the muck!\n2021-07-29T19:09:03.820178 [DEMO :INFO] END: Doing some work\n```\n\n* `ContextTimer`: This [contextmanager](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) starts a timer when the context begins and logs a message with the duration when the context ends.\n\n```py\nimport alog\nimport time\n\nalog.configure(\"debug2\")\nlog = alog.use_channel(\"DEMO\")\n\nwith alog.ContextTimer(log.info, \"Slow work finished in: \"):\n log.debug(\"Starting the slow work\")\n time.sleep(1)\n```\n\n```\n2021-07-29T19:12:00.887949 [DEMO :DBUG] Starting the slow work\n2021-07-29T19:12:01.890839 [DEMO :INFO] Slow work finished in: 0:00:01.002793\n```\n\n### Function Decorators\nIn addition to arbitrary blocks of code that you may wish to scope or time, a very common use case for logging contexts is to provide function tracing. To this end, `alog` provides two useful function decorators:\n\n* `@logged_function`: This [decorator](https://www.python.org/dev/peps/pep-0318/) wraps the `ContextLog` and provides a `START`/`END` scope where the message is prepopulated with the name of the function.\n\n```py\nimport alog\n\nalog.configure(\"debug\")\nlog = alog.use_channel(\"DEMO\")\n\n@alog.logged_function(log.trace)\ndef foo():\n log.debug(\"This is a test\")\n\nfoo()\n```\n\n```\n2021-07-29T19:16:40.036119 [DEMO :TRCE] BEGIN: foo()\n2021-07-29T19:16:40.036807 [DEMO :DBUG] This is a test\n2021-07-29T19:16:40.036915 [DEMO :TRCE] END: foo()\n```\n\n* `@timed_function`: This [decorator](https://www.python.org/dev/peps/pep-0318/) wraps the `ContextTimer` and performs a scoped timer on the entire function.\n\n```py\nimport alog\nimport time\n\nalog.configure(\"debug\")\nlog = alog.use_channel(\"DEMO\")\n\n@alog.timed_function(log.trace)\ndef foo():\n log.debug(\"This is a test\")\n time.sleep(1)\n\nfoo()\n```\n\n```\n2021-07-29T19:19:47.468428 [DEMO :DBUG] This is a test\n2021-07-29T19:19:48.471788 [DEMO :TRCE] 0:00:01.003284\n```\n\n## Tip\n- Visual Studio Code (VSCode) users can take advantage of [alchemy-logging extension](https://marketplace.visualstudio.com/items?itemName=Gaurav-Kumbhat.alog-code-generator) that provides automatic log code generation and insertion.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A wrapper around the logging package to provide Alchemy Logging functionality",
"version": "1.5.0",
"project_urls": {
"Homepage": "https://github.com/IBM/alchemy-logging"
},
"split_keywords": [
"logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec930c3073f2a18173d5486abf74dd28d9157e36e159092535e12379333c2f89",
"md5": "a5410c177ff1d4db81b5bfc71a4b67df",
"sha256": "459ee641c00553175a38f47587ff654ca544985626938e097cb6f85325bd241e"
},
"downloads": -1,
"filename": "alchemy_logging-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5410c177ff1d4db81b5bfc71a4b67df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18765,
"upload_time": "2024-10-24T20:51:37",
"upload_time_iso_8601": "2024-10-24T20:51:37.115338Z",
"url": "https://files.pythonhosted.org/packages/ec/93/0c3073f2a18173d5486abf74dd28d9157e36e159092535e12379333c2f89/alchemy_logging-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f02a950fc0f382a65023e64301d9a3a24458b0f7d9be45df7ca7bd242bee4f8a",
"md5": "909e1093e55d8b8649f147877bce25ea",
"sha256": "ef87de99898f1e62c7cae99e4d2ed4c02c32ccf4c21d6c7a08d93af2bc9945cc"
},
"downloads": -1,
"filename": "alchemy-logging-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "909e1093e55d8b8649f147877bce25ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20433,
"upload_time": "2024-10-24T20:51:38",
"upload_time_iso_8601": "2024-10-24T20:51:38.865813Z",
"url": "https://files.pythonhosted.org/packages/f0/2a/950fc0f382a65023e64301d9a3a24458b0f7d9be45df7ca7bd242bee4f8a/alchemy-logging-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 20:51:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM",
"github_project": "alchemy-logging",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "alchemy-logging"
}
JSON
