CubeSandbox Configuration Logging Options: A Complete Guide to CLI and Programmatic Control

CubeSandbox configuration logging options are controlled via CLI flags parsed by the network-agent binary, which initializes the Cubelog package with rotating file writers, configurable log levels, and automatic log rotation based on size and count limits.

TencentCloud's CubeSandbox uses a centralized logging subsystem called Cubelog to provide observability for its lightweight container sandbox engine. Understanding the available CubeSandbox configuration logging options allows operators to control verbosity, storage locations, and retention policies across the network-agent, CubeMaster, and CubeNet components.

Understanding the Cubelog Architecture

The logging infrastructure resides in the cubelog package (github.com/tencentcloud/CubeSandbox/cubelog). This package provides level-aware logging methods and a rotating file writer that ensures log files never grow unbounded. The network-agent binary serves as the primary consumer, initializing the logger during startup via the initLogger function defined in network-agent/cmd/network-agent/logging.go.

CLI Flags for CubeSandbox Logging Configuration

When starting the network-agent, four primary flags control logging behavior:

• -logpath: Directory where log files are stored (default: /data/log/network-agent)
• -log-level: Global verbosity level—debug, info, warn, error, or fatal (default: info)
• -log-roll-num: Maximum number of rotated log files to retain (default: 5)
• -log-roll-size: Maximum size in MiB for each log file before rotation (default: 10)

These flags are parsed in network-agent/cmd/network-agent/main.go and passed to initLogger before any sandbox operations begin.

How the Network-Agent Initializes Logging

The initialization sequence follows a strict order to ensure logs are available before network operations start.

Default Values and Configuration

The logging.go file defines constants for default behavior: defaultLogDir ("/data/log/network-agent"), defaultLogLevel ("info"), defaultLogRollNum (5), and defaultLogRollSize (10). These values provide fallback settings when CLI flags are omitted.

The initLogger Function Implementation

The initLogger function performs five critical steps:

1. Directory creation: Calls os.MkdirAll to ensure the log path exists with appropriate permissions.
2. Level configuration: Converts the string level to an internal constant via CubeLog.StringToLevel(strings.ToUpper(logLevel)) and sets it globally using CubeLog.SetLevel.
3. Module initialization: Invokes CubeLog.Create(logDir) to establish the module-specific directory structure.
4. Writer setup: Configures two rotating file writers via CubeLog.SetTraceOutput and CubeLog.SetOutput—one for request logs (*-req.log) and one for statistical logs (*-stat.log).
5. Standard logger redirection: Wraps the Go standard library logger with a cubeLogStdWriter to capture any log.Printf calls from third-party dependencies.

Log Rotation and File Management

The rotating-file implementation lives in cubelog/logwriter.go. The cubelog.NewRollFileWriter function accepts the target directory, base filename, roll count, and roll size (in MiB). When the active file exceeds the size threshold, the writer automatically renames it with an incremental suffix and creates a fresh file, maintaining the configured maximum number of historical files.

Practical Configuration Examples

Customizing Log Levels and Paths via Command Line

To run the network-agent with debug verbosity, a custom path, and larger log files:

./network-agent \
    -logpath=/var/log/cubesandbox \
    -log-level=debug \
    -log-roll-num=10 \
    -log-roll-size=20

This configuration stores 10 rotated files of 20 MiB each at /var/log/cubesandbox, capturing detailed debug output.

Programmatic Configuration in Go Applications

For standalone tools interacting with CubeSandbox, initialize Cubelog directly:

package main

import (
    CubeLog "github.com/tencentcloud/CubeSandbox/cubelog"
    "os"
    "strings"
)

func initMyLogger(dir, level string, rollNum, rollSize int) error {
    if err := os.MkdirAll(dir, 0o755); err != nil {
        return err
    }
    CubeLog.SetLevel(CubeLog.StringToLevel(strings.ToUpper(level)))
    CubeLog.Create(dir)
    CubeLog.SetTraceOutput(CubeLog.NewRollFileWriter(dir, "mytool-stat", rollNum, rollSize))
    CubeLog.SetOutput(CubeLog.NewRollFileWriter(dir, "mytool-req", rollNum, rollSize))
    return nil
}

func main() {
    _ = initMyLogger("/tmp/cubesandbox", "info", 5, 10)
    CubeLog.Infof("mytool started – logging ready")
}

Structured Logging with Contextual Fields

Components like CubeNet emit structured logs with runtime context. In CubeNet/cubevs/tap.go, warnings include interface details:

logger := CubeLog.WithContext(context.Background())
logger.Warnf("network-agent newTap set mtu failed: name=%s ifindex=%d mtu=%d err=%v",
    tapName, ifIndex, mtu, err)

Key Source Files Reference

• cubelog/logwriter.go: Implements NewRollFileWriter for size-based log rotation.
• network-agent/cmd/network-agent/logging.go: Contains initLogger and CLI flag parsing logic.
• network-agent/cmd/network-agent/main.go: Entry point that invokes logging initialization.
• network-agent/cmd/network-agent/logging_test.go: Unit tests validating log file creation and content.
• CubeNet/cubevs/tap.go: Demonstrates contextual logging for virtual TAP device operations.
• CubeMaster/pkg/templatecenter/template_image.go: Shows logger usage in orchestration workflows.

Summary

• CubeSandbox uses the Cubelog package for centralized logging across all components.
• Configuration occurs via four CLI flags: -logpath, -log-level, -log-roll-num, and -log-roll-size.
• The initLogger function in network-agent/cmd/network-agent/logging.go orchestrates initialization, directory creation, and writer setup.
• Log rotation is handled automatically by cubelog.NewRollFileWriter based on file size and retention count.
• Both request logs (*-req.log) and statistical logs (*-stat.log) are maintained separately for operational clarity.

Frequently Asked Questions

What are the default CubeSandbox logging settings?

By default, CubeSandbox stores logs in /data/log/network-agent at the info level, maintaining 5 rotated files of 10 MiB each. These defaults are defined as constants in network-agent/cmd/network-agent/logging.go.

How do I change the log level in CubeSandbox without restarting?

Currently, CubeSandbox requires a restart of the network-agent binary to apply new log levels. The initLogger function reads flags only at startup, and there is no dynamic reload mechanism exposed in the cubelog package.

Where are CubeSandbox log files stored by default?

The default log directory is /data/log/network-agent, as specified by the defaultLogDir constant. This path stores both request logs (network-agent-req.log) and statistical logs (network-agent-stat.log).

How does log rotation work in the Cubelog package?

The cubelog.NewRollFileWriter function in cubelog/logwriter.go implements size-based rotation. When the active log file exceeds the configured size limit (default 10 MiB), it is renamed with a numeric suffix and a new file is created. The system retains only the specified number of historical files (default 5), deleting older rotations automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}