# bramble
Tree-based logging for python.
Traditional logging in async python will usually result in confusing, unordered logs. Many different functions and contexts may be logging to the same stream simultaneously, making it difficult to follow execution paths, or determine cause and effect. `bramble` solves this issue by splitting your logs into branches, which are organized in a tree like structure.
This way, you can:
- Follow the logic of your program (async, or otherwise)
- Debug concurrent tasks
- Understand how a final result was composed
## Installing
To install with pip
```shell
pip install bramble
```
#### Extras
If you want to use `bramble`'s Streamlit UI to view the logs that you
create, you should install `bramble` with the `ui` extras.
```shell
pip install bramble[ui]
```
Some backends will also require extras, such as redis.
```shell
pip install bramble[redis]
```
## Basic Usage
### Creating a Logger
Getting started logging with `bramble` is as easy as defining a backend, and then creating a `TreeLogger`. It is recommended to use `TreeLogger` as a context manager.
```python
import bramble
import bramble.backends
logging_backend = bramble.backends.FileWriter("some_folder_path")
with bramble.TreeLogger(logging_backend):
...
```
### Logging
Once a logger has been created, you can begin logging. There are two ways to do
so: First, if you are in the context of a `TreeLogger`, you can simply log
directly.
```python
with bramble.TreeLogger(logging_backend):
bramble.log(message="Some message to log")
```
If you do not wish to use `TreeLogger` as a context manager, you will instead
need to call the logging methods of your `Treelogger`'s branches.
```python
tree_logger = bramble.TreeLogger(logging_backend)
root_branch = tree_logger.root
another_branch = root_branch.branch("new branch")
another_branch.log(message="Some message to log")
```
When logging, the default `MessageType` is `"USER"`. You may also provide arbitrary metadata that you wish to be associated with your message, in a flat dictionary. Accepted value types are: `str`, `int`, `float`, and `bool`.
### Branching
Branching is `bramble`'s core feature. The ability to split your logs, so that they remain correlated and ordered is what allows `bramble` to untangle complex execution paths. Once again, there is a context-based approach, and manual approach.
#### Context-based Branching (Recommended)
Simply decorate any functions that you wish to be a branch point. Any time these functions are called, `bramble` will automatically create a new branch:
```python
@bramble.branch
async def async_fn():
bramble.log("some log message")
sync_fn()
@bramble.branch
def sync_fn():
bramble.log("another log message")
with bramble.TreeLogger(logging_backend):
asyncio.run(async_fn())
```
Each call to a decorated function will result in a unique log branch, and any existing log branches will receive a short message linking to the called function.
If you do not want to branch on a function boundary, or need more granular control, you can also use context based branching with `bramble.fork`.
```python
with bramble.fork("branch_name"):
...
```
#### Manual Branching
If you find yourself needing to manage things by hand, simply branch any existing `LogBranch` object. Each branch must be provided a name.
```python
tree_logger = bramble.TreeLogger(logging_backend)
root_branch = tree_logger.root
another_branch = root_branch.branch("new branch")
another_branch.log(message="Some message to log")
```
### Metadata
Each of `bramble`'s `LogBranch`s supports arbitrary user metadata and tags. Tags make it easier to find and identify branches, and metadata allows to you attach additional information for easy programmatic access later.
#### Using the `@branch` decorator
The easiest way to add tags and metadata to a branch is using the `@branch` decorator. Either use the `tag` and `metadata` keywords, or just place any number of lists and dictionaries as arguments.
```python
@bramble.branch(tags=["tag one", "tag two"])
@bramble.branch(metadata={"item" : "value", "another": 1.0})
@bramble.branch(["a tag"])
@bramble.branch(["a tag"], {"key", 234, "key 2": 215}, ["b tag", "c tag"], {"key_2": 120}) # Dictionary which come after will update previous arguments
```
#### Using `apply`
If you do not know your tags or metadata before runtime, you can still use tags and metadata with your in-context branches. Simply use the `apply` function to apply tags and metadata to all current branches. The interface for this function is almost identical to that of the decorator.
```python
@bramble.branch
async def my_function()
...
bramble.apply(tags=["tag one", "tag two"])
bramble.apply(["a tag"], {"key", 234, "key 2": 215}, ["b tag", "c tag"], {"key_2": 120})
```
#### Manual Tagging and Metadata
The final way to add tags or metadata to a branch is to do so directly. If you have a `LogBranch` object, you can simply call `add_tags` or `add_metadata`.
```python
root = my_logger.root
branch = root.branch("my branch")
branch.add_tags(["tag_one", "tag_two"])
branch.add_metadata({"key": 234})
```
### Demo File
For a complete example of `bramble` in use, please refer to
[`demo.py`](demo.py).
## Advanced Use Cases
### Getting and Setting Context
If you need to manipulate the current logging context directly, you may use `bramble.context`. If you do not supply any arguments, `bramble.context` will provide all of the `LogBranch`s in the current context. If you provide `bramble.context` with `LogBranch`s, then it will create a context manager. Inside this context manager the current logging context will be the supplied branches.
```python
current_context = bramble.context()
next_context = [branch.branch("name") for branch in current_context]
with bramble.context(next_context):
...
with bramble.context(next_context[0]):
...
with bramble.context(next_context[0], next_context[1]):
...
```
### Disabling Logging
If you want to disable `bramble` logging within an active logging context, simply use `bramble.disable`. `bramble.disable` functions both as a standard call, or as a context. If you do not use `bramble.disable` as a context, then simply use `bramble.enable` to reenable logging.
```python
bramble.disable()
bramble.enable()
with bramble.disable():
...
```
Note that only logging is disabled this way. Branches will continue to be created, and the appropriate metadata will still be saved to the logging backend.
## UI
If you install `bramble` with the `ui` extras, `bramble` provides access to a
simple Streamlit UI which you can use to view the logs. Simply use the command `bramble-ui` to run the UI. Currently, you can choose to point the UI at either a file-based or redis
backend.
```
Usage: bramble-ui run [OPTIONS]
Launch the bramble UI to view logs.
Options:
--port INTEGER Port to run the Streamlit app on.
--backend [redis|files] Backend to use. [required]
--redis-host TEXT Redis host (if using redis backend).
--redis-port INTEGER Redis port (if using redis backend).
--filepath PATH Path to log file (if using files backend).
--help Show this message and exit.
```
Once you have launched the UI, you can access it on your local machine via the
port that you provided, in a browser of your choice.
## Best Practices
### Message Types
`bramble` currently supports 3 message types: `SYSTEM`, `USER`, and `ERROR`.
**SYSTEM**
- Branch creation (auto-handled)
- Arguments and return values (handled by either the
user or the `@branch` decorator)
**USER**
- Changes to application state
- External API calls and responses
- Important control flow
**ERROR**
- Exceptions or error conditions (handled by the
user or the `@branch` decorator)
### Branching
Branching should be done whenever entering a new context, as mentioned above. As a general guideline, do not have a logger associated with an object or class,
instead log on the function level.
## Contributing
If you wish to contribute, please install `bramble` with the `dev` extras. We
use the `black` formatter to ensure consistent code, and attempt to keep a
strict 80 character line limit, where possible.
Raw data
{
"_id": null,
"home_page": null,
"name": "bramble",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "async, bramble, branch, log, logging, python, scoped, threading, tree, ui",
"author": null,
"author_email": "Tanner Sims <tannersims@hesitantlyhuman.com>",
"download_url": "https://files.pythonhosted.org/packages/22/00/d59a12085d0737e6b6c1fb78afcda56c5b765d767289f936d3a8fd20d582/bramble-1.2.0.tar.gz",
"platform": null,
"description": "# bramble\nTree-based logging for python.\n\nTraditional logging in async python will usually result in confusing, unordered logs. Many different functions and contexts may be logging to the same stream simultaneously, making it difficult to follow execution paths, or determine cause and effect. `bramble` solves this issue by splitting your logs into branches, which are organized in a tree like structure.\n\nThis way, you can:\n- Follow the logic of your program (async, or otherwise)\n- Debug concurrent tasks\n- Understand how a final result was composed\n\n\n## Installing\nTo install with pip\n```shell\npip install bramble\n```\n\n#### Extras\nIf you want to use `bramble`'s Streamlit UI to view the logs that you\ncreate, you should install `bramble` with the `ui` extras.\n```shell\npip install bramble[ui]\n```\n\nSome backends will also require extras, such as redis.\n```shell\npip install bramble[redis]\n```\n\n## Basic Usage\n### Creating a Logger\nGetting started logging with `bramble` is as easy as defining a backend, and then creating a `TreeLogger`. It is recommended to use `TreeLogger` as a context manager.\n\n```python\nimport bramble\nimport bramble.backends\n\nlogging_backend = bramble.backends.FileWriter(\"some_folder_path\")\nwith bramble.TreeLogger(logging_backend):\n ...\n```\n\n### Logging\nOnce a logger has been created, you can begin logging. There are two ways to do\nso: First, if you are in the context of a `TreeLogger`, you can simply log\ndirectly.\n\n```python\nwith bramble.TreeLogger(logging_backend):\n bramble.log(message=\"Some message to log\")\n```\n\nIf you do not wish to use `TreeLogger` as a context manager, you will instead\nneed to call the logging methods of your `Treelogger`'s branches.\n\n```python\ntree_logger = bramble.TreeLogger(logging_backend)\nroot_branch = tree_logger.root\nanother_branch = root_branch.branch(\"new branch\")\nanother_branch.log(message=\"Some message to log\")\n```\n\nWhen logging, the default `MessageType` is `\"USER\"`. You may also provide arbitrary metadata that you wish to be associated with your message, in a flat dictionary. Accepted value types are: `str`, `int`, `float`, and `bool`.\n\n### Branching\nBranching is `bramble`'s core feature. The ability to split your logs, so that they remain correlated and ordered is what allows `bramble` to untangle complex execution paths. Once again, there is a context-based approach, and manual approach.\n\n#### Context-based Branching (Recommended)\nSimply decorate any functions that you wish to be a branch point. Any time these functions are called, `bramble` will automatically create a new branch:\n\n```python\n@bramble.branch\nasync def async_fn():\n bramble.log(\"some log message\")\n sync_fn()\n\n@bramble.branch\ndef sync_fn():\n bramble.log(\"another log message\")\n\nwith bramble.TreeLogger(logging_backend):\n asyncio.run(async_fn())\n```\n\nEach call to a decorated function will result in a unique log branch, and any existing log branches will receive a short message linking to the called function.\n\nIf you do not want to branch on a function boundary, or need more granular control, you can also use context based branching with `bramble.fork`.\n\n```python\nwith bramble.fork(\"branch_name\"):\n ...\n```\n\n#### Manual Branching\nIf you find yourself needing to manage things by hand, simply branch any existing `LogBranch` object. Each branch must be provided a name.\n\n```python\ntree_logger = bramble.TreeLogger(logging_backend)\nroot_branch = tree_logger.root\nanother_branch = root_branch.branch(\"new branch\")\nanother_branch.log(message=\"Some message to log\")\n```\n\n### Metadata\nEach of `bramble`'s `LogBranch`s supports arbitrary user metadata and tags. Tags make it easier to find and identify branches, and metadata allows to you attach additional information for easy programmatic access later.\n\n#### Using the `@branch` decorator\nThe easiest way to add tags and metadata to a branch is using the `@branch` decorator. Either use the `tag` and `metadata` keywords, or just place any number of lists and dictionaries as arguments.\n\n```python\n@bramble.branch(tags=[\"tag one\", \"tag two\"])\n@bramble.branch(metadata={\"item\" : \"value\", \"another\": 1.0})\n@bramble.branch([\"a tag\"])\n@bramble.branch([\"a tag\"], {\"key\", 234, \"key 2\": 215}, [\"b tag\", \"c tag\"], {\"key_2\": 120}) # Dictionary which come after will update previous arguments\n```\n\n#### Using `apply`\nIf you do not know your tags or metadata before runtime, you can still use tags and metadata with your in-context branches. Simply use the `apply` function to apply tags and metadata to all current branches. The interface for this function is almost identical to that of the decorator.\n\n```python\n@bramble.branch\nasync def my_function()\n ...\n bramble.apply(tags=[\"tag one\", \"tag two\"])\n bramble.apply([\"a tag\"], {\"key\", 234, \"key 2\": 215}, [\"b tag\", \"c tag\"], {\"key_2\": 120})\n```\n\n#### Manual Tagging and Metadata\nThe final way to add tags or metadata to a branch is to do so directly. If you have a `LogBranch` object, you can simply call `add_tags` or `add_metadata`.\n\n```python\nroot = my_logger.root\nbranch = root.branch(\"my branch\")\nbranch.add_tags([\"tag_one\", \"tag_two\"])\nbranch.add_metadata({\"key\": 234})\n```\n\n### Demo File\nFor a complete example of `bramble` in use, please refer to\n[`demo.py`](demo.py).\n\n## Advanced Use Cases\n\n### Getting and Setting Context\nIf you need to manipulate the current logging context directly, you may use `bramble.context`. If you do not supply any arguments, `bramble.context` will provide all of the `LogBranch`s in the current context. If you provide `bramble.context` with `LogBranch`s, then it will create a context manager. Inside this context manager the current logging context will be the supplied branches.\n\n```python\ncurrent_context = bramble.context()\nnext_context = [branch.branch(\"name\") for branch in current_context]\n\nwith bramble.context(next_context):\n ...\n\nwith bramble.context(next_context[0]):\n ...\n\nwith bramble.context(next_context[0], next_context[1]):\n ...\n```\n\n### Disabling Logging\nIf you want to disable `bramble` logging within an active logging context, simply use `bramble.disable`. `bramble.disable` functions both as a standard call, or as a context. If you do not use `bramble.disable` as a context, then simply use `bramble.enable` to reenable logging.\n\n```python\nbramble.disable()\nbramble.enable()\n\nwith bramble.disable():\n ...\n```\n\nNote that only logging is disabled this way. Branches will continue to be created, and the appropriate metadata will still be saved to the logging backend.\n\n## UI\nIf you install `bramble` with the `ui` extras, `bramble` provides access to a\nsimple Streamlit UI which you can use to view the logs. Simply use the command `bramble-ui` to run the UI. Currently, you can choose to point the UI at either a file-based or redis\nbackend.\n\n```\nUsage: bramble-ui run [OPTIONS]\n\n Launch the bramble UI to view logs.\n\nOptions:\n --port INTEGER Port to run the Streamlit app on.\n --backend [redis|files] Backend to use. [required]\n --redis-host TEXT Redis host (if using redis backend).\n --redis-port INTEGER Redis port (if using redis backend).\n --filepath PATH Path to log file (if using files backend).\n --help Show this message and exit.\n```\n\nOnce you have launched the UI, you can access it on your local machine via the\nport that you provided, in a browser of your choice.\n\n\n\n\n\n## Best Practices\n### Message Types\n`bramble` currently supports 3 message types: `SYSTEM`, `USER`, and `ERROR`.\n\n**SYSTEM**\n- Branch creation (auto-handled)\n- Arguments and return values (handled by either the\n user or the `@branch` decorator)\n\n**USER**\n- Changes to application state\n- External API calls and responses\n- Important control flow\n\n**ERROR**\n- Exceptions or error conditions (handled by the\n user or the `@branch` decorator)\n\n### Branching\nBranching should be done whenever entering a new context, as mentioned above. As a general guideline, do not have a logger associated with an object or class,\ninstead log on the function level.\n\n## Contributing\nIf you wish to contribute, please install `bramble` with the `dev` extras. We\nuse the `black` formatter to ensure consistent code, and attempt to keep a\nstrict 80 character line limit, where possible.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tree based logging for async python",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/HesitantlyHuman/bramble",
"Repository": "https://github.com/HesitantlyHuman/bramble"
},
"split_keywords": [
"async",
" bramble",
" branch",
" log",
" logging",
" python",
" scoped",
" threading",
" tree",
" ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "66a1e69b460ac6de161d8757cdee3cdf00db89bc6ebe8be2cebab974a2f05ad4",
"md5": "0f8e9f971f12604e8df929e151fffc41",
"sha256": "ad0a068bdec408bf55626a0626bce2aacb50b1e3ca4326968a6238793ad45864"
},
"downloads": -1,
"filename": "bramble-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f8e9f971f12604e8df929e151fffc41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 31137,
"upload_time": "2025-07-17T18:48:39",
"upload_time_iso_8601": "2025-07-17T18:48:39.418765Z",
"url": "https://files.pythonhosted.org/packages/66/a1/e69b460ac6de161d8757cdee3cdf00db89bc6ebe8be2cebab974a2f05ad4/bramble-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2200d59a12085d0737e6b6c1fb78afcda56c5b765d767289f936d3a8fd20d582",
"md5": "5b8b1d313d733f0c5241baf025ca8703",
"sha256": "4efe7829b76c7a6b3b213efb7045bbf362f9704c02a1edbd3702feb1ada115c6"
},
"downloads": -1,
"filename": "bramble-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "5b8b1d313d733f0c5241baf025ca8703",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 205494,
"upload_time": "2025-07-17T18:48:42",
"upload_time_iso_8601": "2025-07-17T18:48:42.118013Z",
"url": "https://files.pythonhosted.org/packages/22/00/d59a12085d0737e6b6c1fb78afcda56c5b765d767289f936d3a8fd20d582/bramble-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 18:48:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HesitantlyHuman",
"github_project": "bramble",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bramble"
}
JSON
