pnoker
bca6d7aedc
Set up an end-to-end documentation site so contributors and users have a unified, searchable, and publishable entry point for project docs. - Add mkdocs.yml: Chinese-first language, light/dark palette, tabbed navigation, indexed sections, glightbox for diagrams, and pymdownx.snippets so community pages can pull from root governance files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md) without duplicating content. - Add requirements-docs.txt pinning mkdocs-material and mkdocs-glightbox. - Build the docs/ skeleton: index, quickstart, guide, architecture, development, modules, community. Migrate the seven generic manuals from dc3/doc/ (QUICKSTART, ENVIRONMENT, LOGGING, TROUBLESHOOTING, MODULES, DRIVER-AUTHORING, TESTING) and rewire their cross-doc links. CHANGE.md, TITLE.md, and USAGE.md stay in dc3/doc/ because docker-ci.yml depends on them; the docs site references them via mkdocs snippets to keep a single source of truth. - Add .github/workflows/docs.yml that builds with --strict on push to release and deploys via actions/deploy-pages. - Rewrite dc3/doc/README.md as a migration pointer to the new site and to the three retained release-flow files. Verification: mkdocs build --strict passes locally; snippets render correctly; GitHub Pages already enabled in workflow mode via gh api.
2.7 KiB
Logging Guidelines
This project uses human-readable console logs and structured JSON file logs. Application log messages should follow the same wording and argument style across modules so operators can search, filter, and correlate events reliably.
Message Style
Use English, parameterized SLF4J messages, and stable event names:
log.debug("Agentic tool invoked, tool={}, tenantId={}, deviceId={}", toolName, tenantId, deviceId);
log.warn("Agentic tool failed, tool={}, tenantId={}, deviceId={}", toolName, tenantId, deviceId, e);
Avoid string concatenation and String.format in log statements:
log.info("Device registered, tenantId={}, deviceId={}, driverId={}", tenantId, deviceId, driverId);
Do not write logs like this:
log.info("Device registered: " + deviceId);
log.error("Failed to register device: {}", e.getMessage());
Levels
trace: very high-frequency diagnostics, disabled by default.debug: request details, tool invocation, query filters, and branch decisions useful during troubleshooting.info: lifecycle events, startup summaries, successful long-running job summaries, and important state transitions.warn: recoverable failures, invalid client input, retries, degraded behavior, or external dependency failures handled by fallback behavior.error: unrecoverable failures that require operator attention or break the current operation.
When logging a caught exception, pass the exception object unless the stack trace is intentionally suppressed:
log.warn("Point read command failed, tenantId={}, deviceId={}, pointId={}", tenantId, deviceId, pointId, e);
Context Fields
Prefer key-value arguments in this order when they apply:
module/action, tenantId, userId, resource IDs, filters, status/result, durationMs
Examples:
log.info("Agentic skills loaded, count={}, skills={}", loaded.size(), loaded);
log.debug("Agentic chat request received, mode={}, model={}, messageCount={}, conversationIdPresent={}, skill={}, tenantId={}, userId={}",
mode, model, messageCount, conversationIdPresent, skill, tenantId, userId);
Do not log secrets, bearer tokens, passwords, full authorization headers, raw private payloads, or arbitrary request
bodies at info. For potentially sensitive command values, log derived metadata such as length or presence instead of
the raw value.
Format
dc3-common-log configures:
- console logs with Spring Boot's colored pattern for local debugging;
- rolling file logs with JSON fields for machine parsing, including timestamp, logger, thread, level, MDC, message, and stack trace.
Keep this split intentional: code should standardize message wording and structured placeholders, while appenders decide the physical output format.