Merge pull request #1242 from EDCD/enhancement/trace-logging-args

TRACE: Rationalise trace-related CL args & update docs.

Contributing.md

@@ -408,28 +408,26 @@ In addition to that we utilise one of the user-defined levels as:
   command-line argument and `.bat` file for users to enable it.  It cannot be
   selected from Settings in the UI.
 
-  As well as just using bare `logger.trace(...)` you can also gate it to only
-  log if asked to at invocation time by utilising the `--trace-on ...`
-  command-line argument.  e.g.
- `EDMarketConnector.py --trace --trace-on edsm-cmdr-events`.  Note how you
-  still need to include `--trace`.
+  **Do not use a bare `logger.trace(...)` call** unless you're 100% certain 
+  it's only temporary **and will be removed before any code merge**.  In 
+  that case you would utilise `EDMarketConnector.py --trace` to see the output.
 
-  `--trace-on` stores its arguments in `config.trace_on`.
-  To make use of `--trace-on`, you can either check `config.trace_on` yourself:
-  
-    ```python
-      import config
-      if 'my-trace-rule' in config.trace_on:
-        logger.trace('my log message')
-    ```
-
-  or you can use the helper method provided on `logger`:
+  Instead, you should gate any TRACE logging using the `trace_if()` helper 
+  method provided on `logger`:
 
     ```python
       logger.trace_if('my-trace-rule', 'my-log-message')
     ```
+
+  This would then be triggered by running EDMarketConnector with the 
+  appropriate command-line arguments:
+
+      EDMarketConnector.py --trace-on my-trace-rule
   
-  This way you can set up TRACE logging that won't spam just because `--trace` is used.
+  Note that you do **not** also need to specify `--trace`, that's implied.
+  
+  This way you can set up TRACE logging that won't spam just because `--trace`
+  is used.
 
 ---
 

EDMarketConnector.py

@@ -76,9 +76,15 @@ if __name__ == '__main__':  # noqa: C901
         action='store_true',
     )
 
+    parser.add_argument(
+        '--trace-on',
+        help='Mark the selected trace logging as active. "*" or "all" is equivalent to --trace-all',
+        action='append',
+    )
+
     parser.add_argument(
         "--trace-all",
-        help="Disable trace-on functionality (show any and all trace messages, regardless of trace-on gates)",
+        help='Force trace level logging, with all possible --trace-on values active.',
         action='store_true'
     )
 
@@ -105,12 +111,6 @@ if __name__ == '__main__':  # noqa: C901
         action='append',
     )
 
-    parser.add_argument(
-        '--trace-on',
-        help='Mark the selected trace logging as active. * or all will ensure that every possible trace log appears (in the same way as --trace-all)',
-        action='append',
-    )
-
     auth_options = parser.add_mutually_exclusive_group(required=False)
     auth_options.add_argument('--force-localserver-for-auth',
                               help='Force EDMC to use a localhost webserver for Frontier Auth callback',
@@ -130,11 +130,13 @@ if __name__ == '__main__':  # noqa: C901
     args = parser.parse_args()
 
     level_to_set: Optional[int] = None
-    if args.trace:
+    if args.trace or args.trace_on:
         level_to_set = logging.TRACE  # type: ignore # it exists
+        logger.info('Setting TRACE level debugging due to either --trace or a --trace-on')
 
-    if args.trace_all or '*' in args.trace_on or 'all' in args.trace_on:
+    if args.trace_all or (args.trace_on and ('*' in args.trace_on or 'all' in args.trace_on)):
         level_to_set = logging.TRACE_ALL  # type: ignore # it exists
+        logger.info('Setting TRACE_ALL level debugging due to either --trace-all or a --trace-on *|all')
 
     if level_to_set is not None:
         logger.setLevel(level_to_set)