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

> Master CubeSandbox configuration logging with our guide. Learn CLI and programmatic control for rotating files, log levels, and automatic rotation to streamline your operations.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-13

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
./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:

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeNet/cubevs/tap.go), warnings include interface details:

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelog/logwriter.go): Implements `NewRollFileWriter` for size-based log rotation.
- [`network-agent/cmd/network-agent/logging.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/cmd/network-agent/logging.go): Contains `initLogger` and CLI flag parsing logic.
- [`network-agent/cmd/network-agent/main.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/cmd/network-agent/main.go): Entry point that invokes logging initialization.
- [`network-agent/cmd/network-agent/logging_test.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/cmd/network-agent/logging_test.go): Unit tests validating log file creation and content.
- [`CubeNet/cubevs/tap.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeNet/cubevs/tap.go): Demonstrates contextual logging for virtual TAP device operations.
- [`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.