mirror of
https://gitee.com/pnoker/iot-dc3.git
synced 2026-11-01 10:41:52 +08:00
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.
73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# 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:
|
|
|
|
```java
|
|
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:
|
|
|
|
```java
|
|
log.info("Device registered, tenantId={}, deviceId={}, driverId={}", tenantId, deviceId, driverId);
|
|
```
|
|
|
|
Do not write logs like this:
|
|
|
|
```java
|
|
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:
|
|
|
|
```java
|
|
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:
|
|
|
|
```text
|
|
module/action, tenantId, userId, resource IDs, filters, status/result, durationMs
|
|
```
|
|
|
|
Examples:
|
|
|
|
```java
|
|
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.
|