Metadata-Version: 2.4
Name: br-logging-and-profiling
Version: 0.8.0
Summary: Loguru-based logging facade, correlation IDs, and profiling decorator extracted from Forecasting-sidecar3.
Author: Brais Diaz
License: MIT
Project-URL: Homepage, https://github.com/brais/br-logging-and-profiling
Project-URL: Repository, https://github.com/brais/br-logging-and-profiling
Keywords: logging,profiling,loguru,colorama,ray-id
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: loguru>=0.7.0
Requires-Dist: colorama>=0.4.6
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: gitpython; extra == "dev"
Provides-Extra: profiling
Requires-Dist: pandas>=2.0; extra == "profiling"
Requires-Dist: numpy<2.2,>=1.24; extra == "profiling"

# br_logging_and_profiling

Reusable logging/profiling/tracing package extracted from Forecasting-sidecar3.

## Current state

- Logging: Loguru + colorama via `br_py_log_n_profile.do_log.log_it`
- Profiling: `profile_it` decorator (wall-clock timing, colored console output)
- Correlation IDs: `ray_id` via `contextvars.ContextVar`

## Planned

- `tracing/` module: `init_tracing()`, `traced` decorator (OTel span replacement for `profile_it`), `@counted`/`@timed_metric` for hot-loop metrics
- Backend: Prometheus + Jaeger + Grafana + OTel Collector
- Migration phases: Phase 0 (deps/config) → Phase 1 (core tracing) → Phase 2 (migrate by layer) → Phase 3 (metrics) → Phase 4 (backend stack)

## Install

```bash
pip install br-logging-and-profiling
```

## Development

Clone with submodules, or initialize the shared pre-commit tooling after cloning:

```bash
git submodule update --init --recursive
pip install -r requirements-dev.txt
bash br_pre_commit/install.sh "$PWD"
./pre-commit
pytest -m unit
```

The pre-commit gate runs strict mypy against `examples/`, including the `profile_it` type-preservation example.

### Importer note: `break_on_not_tested` breakpoint

`log_w(NOT_TESTED)` intentionally triggers `breakpoint()` by default to flag untested code paths during interactive development. Under pytest this aborts tests with `bdb.BdbQuit` unless the breakpoint is disabled first.

Always disable it in your test configuration before running pytest:

```python
from br_py_log_n_profile.do_log.log_it import configure

configure(break_on_not_tested=False)
```

This repo does this automatically in `tests/conftest.py`. If you import this package into your own project, add the same call to your `conftest.py` (or set `PYTHONBREAKPOINT=0`) to avoid test failures.

# Changelog

## [0.8.0] - 2026-09-18

### Added

-

### Changed

-

### Fixed

-

* b17de1c (HEAD -> main, origin/main, origin/feat/log_exception-no-return, origin/HEAD, feat/log_exception-no-return) feat(do_log): update log_exception return type to NoReturn
* 55d1921 (origin/feat/configure-global-logger, feat/configure-global-logger) feat(do_log): enable debug level for stdlib logging interception
* c360537 (origin/release/0.6.5, release/0.6.5) chore: remove Zone.Identifier file
* 37f7918 build: bump version to 0.6.5
* fd436be (origin/feat/not-tested-pause-breakpoint, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.7.0] - 2026-09-18

### Added

-

### Changed

-

### Fixed

-

* b17de1c (HEAD -> main, origin/main, origin/feat/log_exception-no-return, origin/HEAD, feat/log_exception-no-return) feat(do_log): update log_exception return type to NoReturn
* 55d1921 (origin/feat/configure-global-logger, feat/configure-global-logger) feat(do_log): enable debug level for stdlib logging interception
* c360537 (origin/release/0.6.5, release/0.6.5) chore: remove Zone.Identifier file
* 37f7918 build: bump version to 0.6.5
* fd436be (origin/feat/not-tested-pause-breakpoint, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.5] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.4] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.3] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.2] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.1] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.6.0] - 2026-09-14

### Added

-

### Changed

-

### Fixed

-

* fd436be (HEAD -> main, origin/main, origin/feat/not-tested-pause-breakpoint, origin/HEAD, feat/not-tested-pause-breakpoint) chore(deps): update br_pre_commit submodule
* 7ab2ccd docs: document and disable breakpoint for "not tested" warnings
* b695fce fix(do_log): add breakpoint trigger for "Not tested!" warning messages
* 9d513af (origin/refactor/migrate-release-tooling-to-submodule, refactor/migrate-release-tooling-to-submodule) chore(deps): update br_pypi_publisher submodule to 49f8081
* 73de132 refactor: migrate release tooling to submodule and cleanup scripts
* 53aa6cd (origin/feat/log_exception, feat/log_exception) chore(scripts): replace bash release script with python implementation
* efb1191 ci(release): implement automated GitHub Actions release workflow
* ae5c734 chore: release v0.5.2
* bf65cb6 build: bump version to 0.5.1
* e162665 chore(profiling): update version comment to 0.6.0
* 11f80ba docs(examples): add decorated version of format_value to profile_it_type_preservation
* d086869 ci(dev): implement pre-commit workflow and typing verification
* 149037d chore: release v0.5.0
* a0165b4 chore: release v0.4.0
* 3ccac3e build(release): bump version to 0.3.0 and update publishing script
* d490196 feat(do_log): add log_exception function
* 0263bac chore: release v0.2.0
* d07de79 fix(profiling): preserve decorated signatures
* 76a964e feat: allow SKIP_NO_COMMIT_TO_MAIN env var for automated releases
* 8eaa318 chore: release v0.1.1
* e7c72e3 docs: update migration report with PyPI publication and Forecasting-sidecar3 dependency update
* 345a752 docs: add detailed migration report
* 5e1c1fd docs: update CHANGELOG with detailed 0.1.0 release notes
* 79c7c8e feat: add unit tests for br_py_log_n_profile and fix pre-commit formatting
* 40edcd0 chore: remove Forecasting-sidecar3-specific project-decisions skill from all agent mirrors
* 32ff2a4 feat: initial project scaffold with package, pre-commit, tests, and skills
* 67463aa first commit


## [0.5.2] - 2026-09-09

### Added

-

### Changed

-

### Fixed

-

## [0.5.1] - 2026-09-09

### Added

-

### Changed

-

### Fixed

-

## [0.5.0] - 2026-09-09

### Added

-

### Changed

-

### Fixed

-

## [0.4.0] - 2026-09-08

### Added

-

### Changed

-

### Fixed

-

## [0.3.0] - 2026-09-08

### Added

-

### Changed

-

### Fixed

-

## [0.2.1] - 2026-09-08

### Added

-

### Changed

-

### Fixed

-

## [0.2.0] - 2026-09-06

### Added

-

### Changed

-

### Fixed

-

## [0.1.1] - 2026-09-05

### Added

-

### Changed

-

### Fixed

-

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2026-09-05

### Added

- Initial package structure extracted from Forecasting-sidecar3/app/helper/logging/
- `br_py_log_n_profile.do_log.log_it` — Loguru-based logging facade with Loguru + colorama + stdlib `logging` interception
- `br_py_log_n_profile.do_log.ray_id` — ContextVar-based correlation ID (`get_ray_id`, `set_ray_id`, `ray_id`)
- `br_py_log_n_profile.profiling.base` — `profile_it` timing decorator with color-coded duration buckets
- Package-level re-exports in `br_py_log_n_profile.__init__` preserving the legacy `helper.logging` public surface
- pyproject.toml with ruff/mypy/pytest config matching Forecasting-sidecar3 standards
- Pre-commit hooks (ruff format/lint, mypy, pytest unit gate, skill-file sync)
- Incremental ratchet gate for mypy/ruff/loc
- Contract tests validating installed package public API surface
- Compatibility shims in Forecasting-sidecar3/app/helper/logging/ re-exporting from installed package
- Wheel/sdist build artifacts in `dist/`

### Changed

- Forecasting-sidecar3 `app/helper/logging/` modules now re-export from `br_py_log_n_profile` instead of containing original implementations
- All legacy import paths (`from helper.logging import ...`, `from helper.logging.do_log import ...`, etc.) continue to work unchanged
- Forecasting-sidecar3 `pytest.ini` registers `contract` marker for new contract tests

### Fixed

- numpy constraint pinned to `<2.2` for TensorFlow 2.19.0 compatibility
