siriusscan--sirius/documentation/dev/development/README.logging-conventions.md

title, description, template, llm_context, categories, tags, related_docs, search_keywords

title	description	template	llm_context	categories	tags	related_docs	search_keywords
Logging Conventions	Project-wide logging standards, level guidelines, and configuration	TEMPLATE.documentation-standard	high	development standards observability	logging slog zap LOG_LEVEL structured-logging	README.development.md README.go-api-sdk.md README.docker-architecture.md	log level LOG_LEVEL slog zap structured logging debug verbosity

Logging Conventions

This document defines the project-wide logging standards for all Sirius services.

Guiding Principles

1. Structured logging only -- all Go services use log/slog (SDK, sirius-api, app-scanner) or go.uber.org/zap (app-agent). Raw log.Print* and fmt.Print* are not used for service logging.
2. Level-gated output -- every service reads the LOG_LEVEL environment variable at startup. Only messages at or above the configured level are emitted.
3. No sensitive data -- connection strings, credentials, tokens, and full request/response bodies must never appear in logs.
4. No debug dumps -- printing entire structs (e.g., %+v on a host or vulnerability object) is prohibited. Log only the identifying fields needed for correlation (IP, ID, name).
5. CLI output is separate -- user-facing CLI tools (e.g., template-cli) use fmt.Print* for deliberate terminal output. This is distinct from service logging.

LOG_LEVEL Configuration

Supported Values

Value	Description
debug	Everything, including per-host scan phases and cache ops
info	Startup, significant events, scan-level progress
warn	Non-fatal issues, degraded behavior, retries
error	Failures that affect results or require attention

Default: info (when LOG_LEVEL is unset or unrecognized).

Per-Environment Defaults

Environment	sirius-api	sirius-engine (scanner)	app-agent
Production (docker-compose.yaml)	error	info	info
Development (docker-compose.dev.yaml)	info	info	info

To temporarily enable debug output during development, override in docker-compose.dev.yaml or pass as an environment variable:

LOG_LEVEL=debug docker compose -f docker-compose.dev.yaml up

Shared Initialization Helpers

SDK (slog) -- go-api/sirius/slogger

Used by sirius-api and app-scanner. Call once at the top of main():

import "github.com/SiriusScan/go-api/sirius/slogger"

func main() {
    slogger.Init()   // configures slog.SetDefault() from LOG_LEVEL
    // ...
}

Helper functions:

• slogger.Level() -- returns the current slog.Level
• slogger.IsDebug() -- returns true when debug logging is active

app-agent (zap) -- internal/config

import "github.com/SiriusScan/app-agent/internal/config"

func main() {
    logger := config.NewLogger()   // reads LOG_LEVEL, returns *zap.Logger
    defer logger.Sync()
    // ...
}

Level Assignment Guidelines

Debug

Use for output that is only useful when actively investigating a specific issue:

• Per-host scan phase progress (Phase 0: Fingerprinting on 10.0.0.1)
• Individual host submission confirmations
• Cache hit/miss details
• Queue message bodies
• HID generation, version detection
• Periodic flush counts

Info

Use for meaningful, scan-level or service-level events:

• Service startup and configuration
• Scan started / scan completed (aggregate)
• Template resolution
• Significant state transitions

Warn

Use when something unexpected happened but the service can continue:

• Failed to sync NSE scripts (will retry)
• Host appears to be down (skipping)
• Failed to update KV store with discovery data
• Deprecated configuration detected

Error

Use when a requested operation failed:

• Failed to create KV store connection
• Invalid scan message (cannot be processed)
• Template not found
• Database query failures
• API submission failures

Structured Key-Value Pairs

Always use structured fields instead of string interpolation:

// Good
slog.Info("Scan completed", "scan_id", scanID, "hosts", hostCount, "vulns", vulnCount)

// Bad
slog.Info(fmt.Sprintf("Scan %s completed: %d hosts, %d vulns", scanID, hostCount, vulnCount))

Common Field Names

Use consistent field names across the project:

Field	Description
error	Error value
ip	Host IP address
scan_id	Scan identifier
host_count	Number of hosts
template_id	Template identifier
queue	Queue name
duration	Operation duration
port_count	Number of ports
script_id	Script identifier

Anti-Patterns

Do Not

• Use log.Panicln or log.Fatalf in HTTP handlers (return proper error responses instead)
• Log entire structs with %+v or %#v
• Log connection strings or credentials
• Use emoji in structured log messages (level already conveys severity)
• Use fmt.Printf for service-level logging (only for CLI user output)
• Create per-request loggers unless adding request-scoped context

Exceptions

• log.Fatalf is acceptable in main() for unrecoverable startup errors (e.g., cannot connect to database)
• fmt.Print* is correct for CLI tools that produce user-facing terminal output
• Test files may use t.Log / t.Logf freely

Migration Checklist

When working on a Go file that still uses log.Print* or fmt.Printf for logging:

1. Replace "log" import with "log/slog"
2. Convert log.Printf("message: %s", val) to slog.Info("message", "key", val)
3. Choose the correct level (see guidelines above)
4. Remove any %+v struct dumps
5. Remove emoji from log messages
6. Verify no sensitive data is logged