From e959d5bfbbcf6fa7b094faf67a51b04639628ddc Mon Sep 17 00:00:00 2001 From: Emir Muhammad Date: Tue, 28 Apr 2026 11:47:49 +0200 Subject: [PATCH 1/3] Add severity levels Co-authored-by: Copilot --- docs/index.md | 1 + docs/severitylevels.md | 17 +++++++++++++++++ docs_dev/readme_toplevel.md | 1 + mkdocs.yml | 1 + 4 files changed, 20 insertions(+) create mode 100644 docs/severitylevels.md diff --git a/docs/index.md b/docs/index.md index 86e7124..e0ae167 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,6 +15,7 @@ This documentation is split into two sections depending on your role: |---|---| | [Tutorial](./tutorial.md) | Get a working logger running from scratch | | [Concepts & explanation](./explanation.md) | Understand how Python logging and daqpytools work | +| [Severity levels](./severitylevels.md) | Quick reference for `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL` | | [How to use handlers and filters](./how-to/use-handlers.md) | Descriptions and examples for each handler and filter | | [How to route messages](./how-to/route-messages.md) | Direct records to specific handlers using HandlerType and LogHandlerConf | | [How to add handlers at runtime](./how-to/add-handlers-at-runtime.md) | Attach handlers after logger creation; pass kwargs | diff --git a/docs/severitylevels.md b/docs/severitylevels.md new file mode 100644 index 0000000..aaab767 --- /dev/null +++ b/docs/severitylevels.md @@ -0,0 +1,17 @@ +# Severity levels + +Logging messages are grouped by severity so you can decide what should be shown, routed, or ignored. +The names below match the standard Python logging levels used by daqpytools. + +## Overview + +| Level | Typical meaning | When to use it | Example | +|---|---|---|---| +| `DEBUG` | The most detailed diagnostic output. | Use when you need to trace control flow, inspect state, or confirm that everything is wired correctly. Useful for troubleshooting. | A health check is running and you want to confirm the retry behavior. `Health check: attempt 5 at 4s elapsed.` | +| `INFO` | Normal progress information. | Use for messages that help a user understand what command or service is doing without adding noise. | A process manager has started and you want to report normal progress. `Starting process manager for the session.` | +| `WARNING` | Something unexpected happened, but execution can continue. | Use when a fallback is taken, input looks suspicious, or behavior is not ideal but still recoverable. | A command still works, but the old name is being phased out. `Retract partition is deprecated. Please use retract-session instead.` | +| `ERROR` | A problem occurred that must be fixed for the current operation to succeed. | Use when a command failed, a configuration is invalid, or a required dependency is missing. | A log lookup failed because the requested process does not exist. `Bad query for logs: The process corresponding to the query doesn't exist.` | +| `CRITICAL` | An unrecoverable failure. | Use when the process or running instance cannot continue safely. | A dataflow application has hit a fatal fault and stopped running. `Dataflow application segfaulted; process terminated.` | + + +For more information on how these are used in logging, see the [concepts and explanation page](./explanation.md). \ No newline at end of file diff --git a/docs_dev/readme_toplevel.md b/docs_dev/readme_toplevel.md index 81958a7..9ae4527 100644 --- a/docs_dev/readme_toplevel.md +++ b/docs_dev/readme_toplevel.md @@ -17,6 +17,7 @@ Furthermore, a separate API reference set that includes Auto-generated kwargs, t |---|---| | [Tutorial](./user/tutorial.md) | Get a working logger running from scratch | | [Concepts & explanation](./user/explanation.md) | Understand how Python logging and daqpytools work | +| [Severity levels](./user/severitylevels.md) | Quick reference for `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL` | | [How to use handlers and filters](./user/how-to/use-handlers.md) | Descriptions and examples for each handler and filter | | [How to route messages](./user/how-to/route-messages.md) | Direct records to specific handlers using HandlerType and LogHandlerConf | | [How to add handlers at runtime](./user/how-to/add-handlers-at-runtime.md) | Attach handlers after logger creation; pass kwargs | diff --git a/mkdocs.yml b/mkdocs.yml index 0595fe9..a9cd921 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ nav: - User Documentation: - Tutorial: user/tutorial.md - Concepts & explanation: user/explanation.md + - Severity levels: user/severitylevels.md - How-to: - Use handlers and filters: user/how-to/use-handlers.md - Route messages: user/how-to/route-messages.md From 905f48a80025ea2bbed8245c92cca70e4c248ce5 Mon Sep 17 00:00:00 2001 From: Emir Muhammad Date: Wed, 13 May 2026 18:18:25 +0200 Subject: [PATCH 2/3] Update examples --- docs/severitylevels.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/severitylevels.md b/docs/severitylevels.md index aaab767..18e8974 100644 --- a/docs/severitylevels.md +++ b/docs/severitylevels.md @@ -10,8 +10,8 @@ The names below match the standard Python logging levels used by daqpytools. | `DEBUG` | The most detailed diagnostic output. | Use when you need to trace control flow, inspect state, or confirm that everything is wired correctly. Useful for troubleshooting. | A health check is running and you want to confirm the retry behavior. `Health check: attempt 5 at 4s elapsed.` | | `INFO` | Normal progress information. | Use for messages that help a user understand what command or service is doing without adding noise. | A process manager has started and you want to report normal progress. `Starting process manager for the session.` | | `WARNING` | Something unexpected happened, but execution can continue. | Use when a fallback is taken, input looks suspicious, or behavior is not ideal but still recoverable. | A command still works, but the old name is being phased out. `Retract partition is deprecated. Please use retract-session instead.` | -| `ERROR` | A problem occurred that must be fixed for the current operation to succeed. | Use when a command failed, a configuration is invalid, or a required dependency is missing. | A log lookup failed because the requested process does not exist. `Bad query for logs: The process corresponding to the query doesn't exist.` | -| `CRITICAL` | An unrecoverable failure. | Use when the process or running instance cannot continue safely. | A dataflow application has hit a fatal fault and stopped running. `Dataflow application segfaulted; process terminated.` | +| `ERROR` | A problem occurred that must be fixed for the current operation to succeed. | Use when a command failed, a configuration is invalid, or a required dependency is missing. | Drunc not working due to some http variables not being set. `This can happen if you have the webproxy enabled at CERN. Ensure 'http_proxy' and equivalent aren't set` | +| `CRITICAL` | An unrecoverable failure. | Use when the process or running instance cannot continue safely. | An application has died unexpectedly. `Process [uuid] has died with a return code [code].` | For more information on how these are used in logging, see the [concepts and explanation page](./explanation.md). \ No newline at end of file From b29c8c33f308fcc6933153b81f2e35b9f77cfd57 Mon Sep 17 00:00:00 2001 From: PawelPlesniak Date: Tue, 7 Jul 2026 17:11:23 +0200 Subject: [PATCH 3/3] Bump --- docs/severitylevels.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/severitylevels.md b/docs/severitylevels.md index 18e8974..cdbf7e7 100644 --- a/docs/severitylevels.md +++ b/docs/severitylevels.md @@ -2,6 +2,7 @@ Logging messages are grouped by severity so you can decide what should be shown, routed, or ignored. The names below match the standard Python logging levels used by daqpytools. +For more information on how these are used in logging, see the [concepts and explanation page](./explanation.md). ## Overview @@ -13,5 +14,13 @@ The names below match the standard Python logging levels used by daqpytools. | `ERROR` | A problem occurred that must be fixed for the current operation to succeed. | Use when a command failed, a configuration is invalid, or a required dependency is missing. | Drunc not working due to some http variables not being set. `This can happen if you have the webproxy enabled at CERN. Ensure 'http_proxy' and equivalent aren't set` | | `CRITICAL` | An unrecoverable failure. | Use when the process or running instance cannot continue safely. | An application has died unexpectedly. `Process [uuid] has died with a return code [code].` | +The DUNE-DAQ organization has developed primarily using C++, which currently forms the majority of the organization's stack. As such, the definitions of the log levels and how they are treated have been chosen to resemble the C++ standard as closely as possible, as defined in the C++-specific [`logging`](https://dune-daq-sw.readthedocs.io/en/latest/packages/logging/) and [ERS](https://dune-daq-sw.readthedocs.io/en/latest/packages/logging/ers-conventions/#issue-inheritance) documentation. -For more information on how these are used in logging, see the [concepts and explanation page](./explanation.md). \ No newline at end of file +## How various severity levels are treated +In integration testing environments, the presence of warning messages in output logs will cause a test to fail. This is due to the fact that in this scenario, we have the most control over the environment and compute resources available, and it is expected that the defined integration tests fully conform to the unit test selected from the integrationtest repo. Messages more severe, such as error, are treated as failures as well. + +In production testing environments, there are many more variables that cannot be accounted for, including the dependency on hardware status and use and supporting more users concurrently developing and running tests within the cluster, which are beyond the scope of the DAQ developer. Some common warning messages that are caused by the environment and configuration include: + - `Dropped packet error counts X` + - `Trigger is inhibited in run X` + +Because of these uncontrollable environment parameters, some warning messages are not cause tests to fail, but it is critical to consult the relevant working group experts to validate if you are unsure. Messages more severe than warning should be considered as failures regardless of their content. \ No newline at end of file