feat: display CDA server stack traces in debug mode

Author: krowvin

cwmscli/__main__.py

@@ -10,7 +10,11 @@
 from cwmscli.load import __main__ as load
 from cwmscli.usgs import usgs_group
 from cwmscli.utils.click_help import add_version_to_help_tree
-from cwmscli.utils.friendly_errors import to_user_facing_error
+from cwmscli.utils.friendly_errors import (
+    cda_stack_trace,
+    format_cda_stack_trace,
+    to_user_facing_error,
+)
 from cwmscli.utils.logging import (
     LoggingConfig,
     apply_logging_policies,
@@ -111,9 +115,19 @@ def main() -> None:
     except SystemExit:
         raise
     except click.ClickException as e:
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(e.exit_code)
         e.show()
         raise SystemExit(e.exit_code)
     except Exception as e:
+        # The environment switch supports failures before Click configures logging.
+        # Once CLI setup has run, --log-level DEBUG enables the same behavior.
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+
         if is_cert_verify_error(e) and not debug:
             # Keep this short, no stack trace.
             logging.error(
@@ -122,14 +136,20 @@ def main() -> None:
             click.echo(ssl_help_text(), err=True)
             raise SystemExit(2)
 
-        if not debug:
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(1)
+        else:
             friendly_error = to_user_facing_error(e)
             if friendly_error is not None:
                 logging.debug("Suppressed traceback for CLI exception", exc_info=e)
                 friendly_error.show()
                 raise SystemExit(friendly_error.exit_code)
 
-        # If debug is enabled (or it's not a cert verify error), keep the normal failure behavior.
+        # Preserve raw exception behavior when debug is enabled but CDA did not
+        # provide a server stack trace.
         raise
 
 

cwmscli/utils/friendly_errors.py

@@ -1,10 +1,20 @@
 from __future__ import annotations
 
 import json
+from dataclasses import dataclass
 from typing import Iterable, Optional, Set
 
 import click
 
+from cwmscli.utils import colors
+
+
+@dataclass(frozen=True)
+class CdaStackTrace:
+    message: Optional[str]
+    incident_identifier: Optional[str]
+    lines: tuple[str, ...]
+
 
 class UserFacingError(click.ClickException):
     def __init__(
@@ -58,6 +68,84 @@ def _response_json_field(response, field: str) -> Optional[str]:
     return str(value)
 
 
+def _response_json(response) -> Optional[dict]:
+    text = _response_text(response)
+    if not text:
+        return None
+    try:
+        payload = json.loads(text)
+    except Exception:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def cda_stack_trace(exc: BaseException) -> Optional[CdaStackTrace]:
+    """Extract a CDA-provided server stack trace from an exception chain."""
+
+    for candidate in _walk_exception_chain(exc):
+        response = getattr(candidate, "response", None)
+        if response is None:
+            continue
+
+        payload = _response_json(response)
+        if payload is None:
+            continue
+
+        details = payload.get("details")
+        if not isinstance(details, dict):
+            continue
+
+        stack_trace_lines = details.get("stackTraceLines")
+        if not isinstance(stack_trace_lines, list):
+            continue
+
+        lines = tuple(str(line) for line in stack_trace_lines if line is not None)
+        if not lines:
+            continue
+
+        message = payload.get("message")
+        incident_identifier = payload.get("incidentIdentifier")
+        return CdaStackTrace(
+            message=str(message) if message not in (None, "") else None,
+            incident_identifier=(
+                str(incident_identifier)
+                if incident_identifier not in (None, "")
+                else None
+            ),
+            lines=lines,
+        )
+
+    return None
+
+
+def format_cda_stack_trace(stack_trace: CdaStackTrace) -> str:
+    """Format a CDA-provided server stack trace for terminal output."""
+
+    heading = colors.err("CDA server stack trace")
+    if stack_trace.incident_identifier:
+        heading += (
+            " "
+            + colors.c("(incidentIdentifier: ", "yellow", bright=True)
+            + colors.c(stack_trace.incident_identifier, "cyan", bright=True)
+            + colors.c(")", "yellow", bright=True)
+        )
+
+    output = [heading]
+    if stack_trace.message:
+        output.append(colors.warn(stack_trace.message))
+
+    for index, line in enumerate(stack_trace.lines):
+        stripped = line.lstrip()
+        if index == 0 or stripped.startswith("Caused by:"):
+            output.append(colors.err(line))
+        elif stripped.startswith("at ") or stripped.startswith("..."):
+            output.append(colors.c(line, "cyan"))
+        else:
+            output.append(colors.dim(line))
+
+    return "\n".join(output)
+
+
 def _trim_message(message: str) -> str:
     message = message.strip()
     if not message:

docs/cli/api_arguments.rst

@@ -91,10 +91,16 @@ Example:
 If you were looking for a ``--debug-level`` flag, use ``--log-level DEBUG``
 instead.
 
+When CDA returns ``details.stackTraceLines`` in an authenticated error response,
+debug mode displays that server stack trace with terminal-friendly formatting.
+The trace is only available when CDA is configured to return it and the
+authenticated user has CDA's ``SHOW STACK TRACE`` role. Normal log levels keep
+the concise user-facing error and incident identifier.
+
 For certain exception paths, ``cwms-cli`` also checks ``CWMS_CLI_DEBUG``. When
 that environment variable is set to ``1``, ``true``, ``yes``, or ``on``, the
-CLI keeps the normal exception behavior instead of suppressing some friendly
-error handling paths.
+CLI enables the same debug exception behavior. If CDA does not provide a server
+stack trace, cwms-cli keeps the raw local exception behavior for diagnosis.
 
 See also
 --------

tests/cli/test_main_error_handling.py

@@ -1,4 +1,5 @@
 import json
+import logging
 import sys
 
 import pytest
@@ -14,14 +15,17 @@ def __init__(
         *,
         reason="",
         url="https://example.test/cwms-data/resource",
-        incident=None
+        incident=None,
+        stack_trace_lines=None,
     ):
         self.status_code = status_code
         self.reason = reason
         self.url = url
         payload = {"message": message}
         if incident is not None:
             payload["incidentIdentifier"] = incident
+        if stack_trace_lines is not None:
+            payload["details"] = {"stackTraceLines": stack_trace_lines}
         self.text = json.dumps(payload)
         self.content = self.text.encode("utf-8")
 
@@ -139,3 +143,99 @@ def fake_cli(*args, **kwargs):
 
     with pytest.raises(RuntimeError, match="boom"):
         cli_main.main()
+
+
+def test_main_formats_cda_stack_trace_when_debug_env_enabled(monkeypatch, capsys):
+    from cwms.api import ApiError
+
+    def fake_cli(*args, **kwargs):
+        raise ApiError(
+            _FakeResponse(
+                400,
+                "Text 'not-a-date' could not be parsed at index 0",
+                reason="Bad Request",
+                incident="trace-123",
+                stack_trace_lines=[
+                    "java.time.format.DateTimeParseException: invalid date",
+                    "\tat cwms.cda.helpers.DateUtils.parseUserDate(DateUtils.java:91)",
+                ],
+            )
+        )
+
+    monkeypatch.setattr(cli_main, "cli", fake_cli)
+    monkeypatch.setattr(sys, "argv", ["cwms-cli", "dummy"])
+    monkeypatch.setenv("CWMS_CLI_DEBUG", "1")
+
+    with pytest.raises(SystemExit) as exc:
+        cli_main.main()
+
+    captured = capsys.readouterr()
+    assert exc.value.code == 1
+    assert "CDA server stack trace" in captured.err
+    assert "incidentIdentifier: trace-123" in captured.err
+    assert "java.time.format.DateTimeParseException" in captured.err
+    assert "DateUtils.parseUserDate" in captured.err
+    assert "Traceback (most recent call last)" not in captured.err
+
+
+def test_main_log_level_debug_formats_cda_stack_trace(monkeypatch, capsys):
+    from cwms.api import ApiError
+
+    previous_level = logging.getLogger().level
+
+    def fake_cli(*args, **kwargs):
+        logging.getLogger().setLevel(logging.DEBUG)
+        raise ApiError(
+            _FakeResponse(
+                500,
+                "System Error",
+                incident="trace-456",
+                stack_trace_lines=["java.lang.RuntimeException: boom"],
+            )
+        )
+
+    monkeypatch.setattr(cli_main, "cli", fake_cli)
+    monkeypatch.setattr(sys, "argv", ["cwms-cli", "--log-level", "DEBUG", "dummy"])
+    monkeypatch.delenv("CWMS_CLI_DEBUG", raising=False)
+
+    try:
+        with pytest.raises(SystemExit) as exc:
+            cli_main.main()
+    finally:
+        logging.getLogger().setLevel(previous_level)
+
+    captured = capsys.readouterr()
+    assert exc.value.code == 1
+    assert "CDA server stack trace" in captured.err
+    assert "java.lang.RuntimeException: boom" in captured.err
+
+
+def test_main_debug_finds_cda_stack_behind_click_exception(monkeypatch, capsys):
+    from cwms.api import ApiError
+
+    def fake_cli(*args, **kwargs):
+        try:
+            raise ApiError(
+                _FakeResponse(
+                    500,
+                    "System Error",
+                    incident="trace-789",
+                    stack_trace_lines=["java.lang.NullPointerException: missing"],
+                )
+            )
+        except ApiError:
+            raise click.ClickException("Friendly command error") from None
+
+    monkeypatch.setattr(cli_main, "cli", fake_cli)
+    monkeypatch.setattr(sys, "argv", ["cwms-cli", "dummy"])
+    monkeypatch.setenv("CWMS_CLI_DEBUG", "1")
+
+    with pytest.raises(SystemExit) as exc:
+        cli_main.main()
+
+    captured = capsys.readouterr()
+    assert exc.value.code == 1
+    assert "CDA server stack trace" in captured.err
+    assert "incidentIdentifier: trace-789" in captured.err
+    assert "java.lang.NullPointerException: missing" in captured.err
+    assert "Friendly command error" not in captured.err