ref-logging-standards

Logger Instantiation

Each module declares one private module-level logger:

_LOGGER = logging.getLogger(__name__)

Message Format

[server_or_module:function_name] Action: details

Examples:

_LOGGER.info(f"[mcp_systems_server:catalog_tables_list] Invoked: id={id!r}")
_LOGGER.info(f"[mcp_systems_server:session_enterprise_create] Success: id={id!r}")
_LOGGER.error(f"[mcp_systems_server:session_enterprise_create] Failed to create session: {e!r}", exc_info=True)

Log Levels

• DEBUG — detailed operational steps useful for diagnosing behavior (loop iterations, intermediate values)
• INFO — significant events: tool invocation, successful completion, notable state changes
• WARNING — degraded but non-fatal conditions
• ERROR — failures and exceptions; when logging a caught exception, include {e!r} in the message and exc_info=True. {e!r} is the log form only — user-facing strings render per ref-python-coding-practices rule 20; do not swap one form for the other.

When to Log

Add log statements for:

• Entry to any significant operation (Invoked: with key parameters)
• Successful completion (Success: or a summary of what was done)
• Failures and exceptions (Failed to ...: {e!r})

Do not log inside tight loops or use INFO or above for routine intermediate steps — use DEBUG.

Accuracy

Log messages must accurately describe what the code does at that point. A message that says "Invoked" should appear at entry, not mid-function. An INFO message should not appear on an error path.

When refactoring (renaming a function, splitting it, moving code between modules), update the [module:function] prefix and any inline action description in every affected log line. A stale prefix is a documentation bug that survives lint and tests.

Sensitive data

Never log:

• PSKs, auth tokens (resolved auth_token values), passwords, API keys.
• File contents pulled in by ${file:PATH} templating (private keys, credentials).
• Environment-variable values resolved by ${env:VAR} if the variable is known to hold a secret (*_PASSWORD, *_TOKEN, *_KEY, PSK).