qitech-control/docs/logging.md

Logging and Tracing Configuration

This document describes the logging and tracing system for the QiTech control server, including structured logging, distributed tracing, and different output formats.

Overview

The QiTech control server uses a modular tracing system built on top of the tracing crate, supporting multiple output formats and observability backends. The system is designed to be flexible and configurable through Cargo features.

Features

The logging system supports three main features that can be enabled independently:

• tracing-fmt: Human-readable console output (default)
• tracing-journald: systemd journal integration for production Linux systems
• tracing-otel: OpenTelemetry integration for distributed tracing

Default Configuration

By default, the server uses tracing-fmt for development-friendly console output:

cargo run  # Uses tracing-fmt by default

Feature-Based Configuration

Format Logging (tracing-fmt)

The fmt logger provides structured, human-readable output to the console. This is the default feature and is ideal for development and debugging.

Features:

• Colored output (when supported)
• Thread names and IDs
• Line numbers and file locations
• Configurable time formats (debug vs release)
• Target filtering

Example output:

2025-06-01T10:30:45.123Z INFO server::main: Starting QiTech Control Server
2025-06-01T10:30:45.125Z DEBUG ethercat::init: Initializing EtherCAT master

Usage:

# Default behavior
cargo run

# Explicit feature selection
cargo run --features tracing-fmt --no-default-features

Journal Logging (tracing-journald)

The journald logger integrates with systemd's journal for production Linux deployments. This is the standard logging backend used on NixOS systems and other systemd-based distributions.

Features:

• Native systemd journal integration
• Structured metadata preservation
• System-level log aggregation
• Log rotation and retention policies
• Remote log collection support

Usage:

# Enable journald logging
cargo run --features tracing-journald --no-default-features

# Combined with other features
cargo run --features "tracing-journald,tracing-otel"

Viewing logs on NixOS:

# View all logs from the service
journalctl -u qitech-control-server -f

# Filter by log level
journalctl -u qitech-control-server -p info

# JSON output for structured data
journalctl -u qitech-control-server -o json-pretty

# Follow logs with timestamp
journalctl -u qitech-control-server -f --since "1 hour ago"

OpenTelemetry Tracing (tracing-otel)

OpenTelemetry provides distributed tracing capabilities by exporting traces to observability platforms like Jaeger, Zipkin, or commercial APM solutions.<