diff --git a/README.md b/README.md index 7dd896e6..1bde44e3 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,107 @@ # OVOS-utils -collection of simple utilities for use across the mycroft ecosystem +`ovos-utils` is a shared utility library for the OpenVoiceOS ecosystem. It provides +logging, process lifecycle management, a testing-friendly fake message bus, event +scheduling, file utilities, network checks, audio playback, and XDG path helpers. +Most OVOS packages, including `ovos-bus-client`, `ovos-config`, and `ovos-workshop`, +depend on it, so most projects get it as a transitive dependency. ## Install ```bash -pip install ovos_utils +pip install ovos-utils ``` -## Commandline scripts -### ovos-logs - Small helper tool to quickly navigate the logs, create slices and quickview errors +## Usage ---------------- -- **ovos-logs slice [options]** +The library exposes many small, independent modules. Import only what you need. +For example, use `FakeBus` to test skill code without a live message bus: - **Slice logs of a given time period. Defaults on the last service start (`-s`) until now (`-u`)** +```python +from ovos_utils.fakebus import FakeBus, FakeMessage - _Different logs can be picked using the `-l` option. All logs will be included if not specified._ - _Optionally the directory where the logs are stored (`-p`) and the file where the slices should be dumped (`-f`) can be specified._ - +bus = FakeBus() - _[ex: `ovos-logs slice`]_ - _Slice all logs from service start up until now._ - - _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25`]_ - _Slice all logs from 17:05:20 until 17:05:25._ - _**no logs in that timeframe in other present logs_ - Screenshot 2023-12-25 185004 - - _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25 -l skills`]_ - _Slice skills.log from 17:05:20 until 17:05:25._ - - _[ex: `ovos-logs slice -s 17:05:20 -u 17:05:25 -f ~/testslice.log`]_ - _Slice the logs from 17:05:20 until 17:05:25 on all log files and dump the slices in the file ~/testslice.log (default: `~/slice_.log`)._ - Screenshot 2023-12-25 190732 --------------- +def on_utterance(message): + print(message.data["utterances"]) -- **ovos-logs list [-e|-w|-d|-x] [options]** +bus.on("recognizer_loop:utterance", on_utterance) +bus.emit(FakeMessage("recognizer_loop:utterance", {"utterances": ["hello"]})) +``` + +See [docs/index.md](docs/index.md) for the full module overview, with links to +detailed pages on logging, process utilities, `FakeBus`, and event handling. + +## Command line: ovos-logs + +`ovos-logs` is a helper tool that slices, lists, and reduces OVOS service logs. + +- **`ovos-logs slice [options]`**. Slice logs for a time period. The default + period runs from the last service start (`-s`) until now (`-u`). Pick specific + logs with `-l` (default: all logs). Set the log directory with `-p` and the + output file with `-f`. + + ```bash + ovos-logs slice + # Slice all logs from the last service start until now. + + ovos-logs slice -s 17:05:20 -u 17:05:25 + # Slice all logs between 17:05:20 and 17:05:25. + + ovos-logs slice -s 17:05:20 -u 17:05:25 -l skills + # Slice only skills.log between 17:05:20 and 17:05:25. + + ovos-logs slice -s 17:05:20 -u 17:05:25 -f ~/testslice.log + # Slice logs between 17:05:20 and 17:05:25 into ~/testslice.log. + # Default output file: ~/slice_.log + ``` + +- **`ovos-logs list [-e|-w|-d|-x] [options]`**. List log lines by severity + (error, warning, debug, exception). Specify at least one level. You can combine + several. Set the time range with `-s` and `-u` (default: last service start + until now). Pick specific logs with `-l` (default: all logs). + + ```bash + ovos-logs list -x + # List EXCEPTION-level lines (with tracebacks) from the last service start until now. - **List logs by severity (error/warning/debug/exception). A log level has to be specified - more than one can be listed** + ovos-logs list -w -e -s 20-12-2023 -l bus -l skills + # List WARNING and ERROR lines from bus.log and skills.log since 20 December 2023. + ``` - _A start and end date can be specified using the `-s` and `-u` options. Defaults to the last service start until now._ - _Different logs can be picked using the `-l` option. All logs will be included if not specified._ - _Optionally, the directory where the logs are stored (`-p`) and the file where the slices should be dumped (`-f`) can be passed as arguments._ +- **`ovos-logs reduce [options]`**. Shrink logs to a target size in bytes, or + remove entries before a given date. Pick specific logs with `-l` (default: all + logs). Set the log directory with `-p`. - _[ex: `ovos-logs list -x`]_ - _List the logs with level EXCEPTION (plus tracebacks) from the last service start until now._ - Screenshot 2023-12-25 184321 - - _[ex: `ovos-logs list -w -e -s 20-12-2023 -l bus -l skills`]_ - _List the logs with level WARNING and ERROR from the 20th of December 2023 until now from the logs bus.log and skills.log._ - Screenshot 2023-12-25 173739 ---------------------- + ```bash + ovos-logs reduce + # Shrink all logs to 0 bytes. -- **ovos-logs reduce [options]** - - **Downsize logs to a given size (in bytes) or remove entries before a given date.** - - _Different logs can be included using the `-l` option. If not specified, all logs will be included._ - _Optionally the directory where the logs are stored (`-p`) can be specified._ - - _[ex: `ovos-logs reduce`]_ - _Downsize all logs to 0 bytes_ + ovos-logs reduce -s 1000000 + # Shrink all logs to about 1 MB, keeping the latest entries. - _[ex: `ovos-logs reduce -s 1000000`]_ - _Downsize all logs to ~1MB (latest logs)_ + ovos-logs reduce -d "1-12-2023 17:00" + # Shrink all logs to entries after the given date and time. - _[ex: `ovos-logs reduce -d "1-12-2023 17:00"`]_ - _Downsize all logs to entries after the specified date/time_ + ovos-logs reduce -s 1000000 -l skills -l bus + # Shrink skills.log and bus.log to about 1 MB each. + ``` - _[ex: `ovos-logs reduce -s 1000000 -l skills -l bus`]_ - _Downsize skills.log and bus.log to ~1MB (latest logs)_ +- **`ovos-logs show -l `**. Print the contents of a log file. ---------------------- + ```bash + ovos-logs show -l bus + # Print the contents of bus.log. + ``` -- **ovos-logs show -l [servicelog]** + The logs shown depend on which log files exist in the log folder. - **Show logs** +## Related projects - _[ex: `ovos-logs show -l bus`]_ - _Show the logs from bus.log._ +- [OpenVoiceOS/ovos-bus-client](https://github.com/OpenVoiceOS/ovos-bus-client). The real message bus client that `FakeBus` and `FakeMessage` stand in for during testing. +- [OpenVoiceOS/ovos-config](https://github.com/OpenVoiceOS/ovos-config). Reads and writes `mycroft.conf`, the configuration file used by `LOG`, `PIDLock`, and the network utilities. +- [OpenVoiceOS/ovos-workshop](https://github.com/OpenVoiceOS/ovos-workshop). The skill framework built on `EventContainer`, `RuntimeRequirements`, and the other utilities in this library. - _[ex: wrong servicelog]_ - _**logs shown depending on the logs present in the folder_ +## License +Apache License 2.0. See [LICENSE](LICENSE). diff --git a/docs/events.md b/docs/events.md index f15edbeb..da06b66a 100644 --- a/docs/events.md +++ b/docs/events.md @@ -85,3 +85,6 @@ from ovos_bus_client.apis.events import EventSchedulerInterface | `shutdown()` | Cancel repeating events and clear all registered handlers | `when` may be a `datetime`, or a positive `int`/`float` representing seconds from now. + +--- +[← FakeBus](fakebus.md) · [Home](index.md) · [Utilities →](utilities.md) diff --git a/docs/fakebus.md b/docs/fakebus.md index 037d770f..a8deeb13 100644 --- a/docs/fakebus.md +++ b/docs/fakebus.md @@ -155,3 +155,6 @@ msg = FakeMessage("skill:action", {"key": "value"}, {"session_id": "abc"}) ## `dig_for_message()` Tries to import and call `ovos_bus_client.message.dig_for_message`. Returns `None` if `ovos-bus-client` is not installed. + +--- +[← Process Utilities](process-utils.md) · [Home](index.md) · [Events →](events.md) diff --git a/docs/log.md b/docs/log.md index 541b81e8..157a2c1b 100644 --- a/docs/log.md +++ b/docs/log.md @@ -141,3 +141,6 @@ Return all configured log directories across all services. ## `get_available_logs(directories) → List[str]` Return a list of log file basenames (e.g. `["audio", "skills", "bus"]`) found in the configured log directories. + +--- +[Home](index.md) · [Process Utilities →](process-utils.md) diff --git a/docs/process-utils.md b/docs/process-utils.md index 4dba1ef1..fdefeddd 100644 --- a/docs/process-utils.md +++ b/docs/process-utils.md @@ -136,3 +136,6 @@ Chainable POSIX signal handler. Each instance installs a user function as the ne ## `reset_sigint_handler()` Reset `SIGINT` to the default Python handler. Needed when starting OVOS services from shell scripts that have modified the signal mask. + +--- +[← Logging](log.md) · [Home](index.md) · [FakeBus →](fakebus.md) diff --git a/docs/utilities.md b/docs/utilities.md index e5d22cc9..d251dcda 100644 --- a/docs/utilities.md +++ b/docs/utilities.md @@ -201,3 +201,6 @@ cache_dir = xdg_cache_home() / "mycroft" # ~/.cache/mycroft | `xdg_data_dirs()` | `XDG_DATA_DIRS` | `[/usr/local/share, /usr/share]` | Environment variable values are only used if they are absolute paths; relative paths fall back to the default. + +--- +[← Events](events.md) · [Home](index.md)