89 lines
3.1 KiB
Markdown
89 lines
3.1 KiB
Markdown
# esm-logging
|
|
|
|
A quasi-port of the Python standard library
|
|
[logging](https://docs.python.org/3/library/logging.html) module to
|
|
ECMAScript. Browser-compatible, zero dependencies.
|
|
|
|
## Why?
|
|
|
|
Logging is important. It is important for debugging purposes, leading to
|
|
faster and more resilient development, for traceability leading to better
|
|
security. Most logging libraries I've discovered didn't satisfy me, introduced
|
|
weird concepts and all in all just weren't great. Other programming language
|
|
ecosystems offer way nicer logging facilities. Take Rust for example, or...
|
|
Python! Python has PEP, giving it a very structured approach towards
|
|
implementing new features and that's also how its logging facilities came to be
|
|
([PEP 282](https://peps.python.org/pep-0282/)). Python's logging facilities
|
|
are implemented by the [logging](https://docs.python.org/3/library/logging.html)
|
|
module, which is part of the standard library and has been since 2002. It was
|
|
originally authored by Vinay Sajip.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @administratrix/esm-logging
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```javascript
|
|
import * as logging from '@administratrix/esm-logging';
|
|
|
|
// one-shot configuration: sets up a console handler on the root logger
|
|
logging.config.basicConfig({ level: logging.log_level.INFO });
|
|
|
|
// create a logger for this module
|
|
const logger = logging.manager.MANAGER.getLogger('myapp');
|
|
|
|
logger.info('Application started');
|
|
logger.warning('Something looks off');
|
|
logger.error('Something went wrong');
|
|
```
|
|
|
|
## Concepts
|
|
|
|
The logging system is built around four core components:
|
|
|
|
- **Loggers** expose the interface that application code uses directly.
|
|
- **Handlers** send log records to the appropriate destination (console,
|
|
stderr, custom writable streams).
|
|
- **Formatters** control the layout of log records in the final output.
|
|
- **Filters** provide fine-grained control over which records to output.
|
|
|
|
Loggers are organized in a dot-separated hierarchy. A logger named `app.db`
|
|
is a child of the logger named `app`. Log records propagate up the hierarchy,
|
|
so a handler attached to `app` will also receive records from `app.db`.
|
|
|
|
## Log levels
|
|
|
|
| Constant | Value | Purpose |
|
|
|------------|-------|------------------------------------------|
|
|
| `CRITICAL` | 50 | A serious error, the program may not continue |
|
|
| `ERROR` | 40 | An error that prevented some operation |
|
|
| `WARNING` | 30 | Something unexpected, but the software still works |
|
|
| `INFO` | 20 | Confirmation that things work as expected |
|
|
| `DEBUG` | 10 | Detailed diagnostic information |
|
|
| `NOTSET` | 0 | All messages are processed |
|
|
|
|
## Documentation
|
|
|
|
See [docs/](docs/README.md) for the full user guide and
|
|
[docs/logging-cookbook.md](docs/logging-cookbook.md) for recipes and patterns.
|
|
|
|
API reference can be generated with TypeDoc:
|
|
|
|
```bash
|
|
npm run build/doc
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
- [x] quasi-port of the logging module with minimal adaptation
|
|
- [x] add documentation
|
|
- [ ] add support for asynchronous calls
|
|
- [ ] implement Open Cybersecurity Schema Framework (OCSF) formatter
|
|
- [ ] implement browser local storage handler as a replacement for file handler
|
|
|
|
## License
|
|
|
|
UNLICENSED
|