Skip to main content
Version: master

Pantavisor Log Sockets

Overview: Storage → Logs explains how the log server fits together, how containers are expected to log, and what each sink is for.

SocketPathTypeCreatedRemoved
pv-ctrl-log<PV_SYSTEM_RUNDIR>/pv-ctrl-logSOCK_STREAMLog server startLog server stop
pv-fd-log<PV_SYSTEM_RUNDIR>/pv-fd-logSOCK_STREAMLog server startLog server stop
log.sock<PV_SYSTEM_RUNDIR>/pv-plat-log/<container>/log.sock, bind-mounted at /dev/log in the containerSOCK_DGRAM, mode 0666Container start, when dev-log allows itContainer stop, or a failed start
/dev/log/dev/log (Pantavisor's own)SOCK_DGRAM, mode 0666Log server start, when PV_LOG_AUTO_DEVLOG is enabledClosed at log server stop; the socket file is left in place

<PV_SYSTEM_RUNDIR> is set by PV_SYSTEM_RUNDIR (default /pv).

Protocol detection​

pv-ctrl-log and every /dev/log socket accept the same protocols. The parser is picked per message, trying each row in order:

First bytesProtocol
<NNN>1 … (digit 1 right after the closing >)RFC 5424
<NNN>… (any other character after the closing >)RFC 3164
Valid JSON objectJSON
Only level=/src=/message= pairs, all three presentKey-Value
Binary struct pv_ls_msgLegacy binary

A message that matches a protocol but fails to parse is dropped with a WARN.

Platform attribution​

The platform is the folder name under the log directory.

ProtocolReceived onPlatform
Legacy binaryanyThe platform field of the message
RFC 3164, RFC 5424, JSON, Key-Valuea container's log.sockThe container owning the socket
RFC 3164, RFC 5424, JSON, Key-ValuePantavisor's /dev/logpantavisor
RFC 3164, RFC 5424, JSON, Key-Valuepv-ctrl-logThe sender's cgroup; unknown-platform if it cannot be resolved

Log levels​

LevelLegacy valueJSON / Key-Value level
FATAL0FATAL
ERROR1ERROR
WARN2WARN
WALL3WALL
INFO4INFO
DEBUG5DEBUG
TRACE6TRACE
note

WALL was added at 3, so INFO/DEBUG/TRACE moved up by one (previously 3/4/5). Senders that hardcode the old numeric levels must update.

JSON and Key-Value level names are case-insensitive. ALL is valid for PV_LOG_LEVEL but not as a message level: such a message is dropped.

pv-ctrl-log​

Stream socket for sending log messages. Accepts every protocol in Protocol detection.

Legacy Protocol (code = 0)​

struct pv_ls_msg {
int code;
int len;
char buf[0];
};
FieldValue
code0 LEGACY; 256 CMD, internal, rejected unless sent by Pantavisor's PID
lenLength of buf
buflevel\0platform\0source\0data
buf partContent
levelLegacy value from Log levels, as a string ("4" for INFO)
platformContainer name or pantavisor
sourceLog source, e.g. a process or module name
dataMessage text

JSON Protocol​

Sent as-is, not wrapped in pv_ls_msg.

{ "version": "0", "level": "INFO", "src": "myapp", "message": "Connection established" }
FieldRequiredValue
versionYes"0"; any other value is rejected
levelYesA name from Log levels
srcYesLog source
messageYesMessage text

Key-Value Protocol​

Sent as-is, not wrapped in pv_ls_msg.

level=INFO src=myapp message="hello world"
KeyRequiredValue
levelYesA name from Log levels
srcYesLog source
messageYesMessage text

Keys can come in any order. There is no version key. An unquoted value ends at the first whitespace, so quote any value containing spaces; \" escapes a quote inside a quoted value.

pv-fd-log​

Hands a file descriptor to Pantavisor, which then polls it and logs what it reads.

Subscription Protocol​

Send with sendmsg, passing the file descriptor as SCM_RIGHTS and a 4-element iovec:

iov IndexTypeMax LengthDescription
iov[0]string50 bytesPlatform name (container name)
iov[1]string50 bytesSource name (e.g. stdout)
iov[2]int4 bytesLog level for messages from this FD
iov[3]int4 bytesAction: 1 subscribe, 0 unsubscribe
ActionSCM_RIGHTS fdEffect
Subscribe (1)The fd to pollPolled into <PV_LOG_DIR>/<revision>/<platform>/, path per Filetree paths. Replaces any fd already subscribed for the same platform/source pair
Unsubscribe (0)Can be -1Stops polling and closes Pantavisor's copy of the fd for that platform/source pair

/dev/log​

Per-container datagram socket, listed in the table at the top of this page. Accepts every protocol in Protocol detection; RFC 3164 and RFC 5424 need no configuration.

ConditionResult
Container name empty, ., .., or containing /, \ or "No socket; Pantavisor logs a WARN

Per-container control​

Set dev-log in <container>/run.json to override PV_LOG_AUTO_DEVLOG for that container:

{
"#spec": "service-manifest-run@1",
"dev-log": true
}
PV_LOG_AUTO_DEVLOGdev-logContainer gets log.sock and /dev/log
1 (default)not setYes
1trueYes
1falseNo
0not setNo
0trueYes
0falseNo

RFC 3164​

<PRI>Mmm dd HH:MM:SS HOSTNAME APP[PID]: message
<34>May 15 16:48:18 mydevice myapp[1234]: Connection established
RFC 3164 fieldPantavisor attributeNotes
PRI severity bitslvlSee Priority and Facility
Timestamptimestrptime("%b %d %H:%M:%S")
HOSTNAME—Discarded
APPsrc[PID] suffix stripped; unknown-app if missing
Message textlog dataEverything after APP[PID]:
—platSee Platform attribution

RFC 5424​

<PRI>1 TIMESTAMP HOSTNAME APP PROCID MSGID STRUCTURED-DATA MSG
<34>1 2026-05-15T16:48:18Z mydevice myapp 1234 - - Connection established
RFC 5424 fieldPantavisor attributeNotes
PRI severity bitslvlSee Priority and Facility
TIMESTAMPtimestrptime("%Y-%m-%dT%H:%M:%S"); fractional seconds dropped; nil (-) → current time
HOSTNAME—Discarded
APPsrcunknown-app if missing
PROCID, MSGID, STRUCTURED-DATA—Accepted, not stored
MSGlog dataEverything after STRUCTURED-DATA
—platSee Platform attribution

Priority and Facility​

PRI = facility × 8 + severity

Severitysyslog namePantavisor level
0EMERGFATAL
1ALERTFATAL
2CRITERROR
3ERRERROR
4WARNINGWARN
5NOTICEINFO
6INFOINFO
7DEBUGDEBUG
Facility codeNameDescription
0kernKernel messages
1userUser-level messages
3daemonSystem daemons
16LOCAL0Recommended for container applications

Log server outputs​

Set with PV_LOG_SERVER_OUTPUTS, a comma-separated list; sinks combine freely and unknown tokens are dropped with a warning. See Output types for when to use each.

With PV_LOG_CAPTURE set to 0 no sink is active, whatever PV_LOG_SERVER_OUTPUTS says; only the error logs of an update are still kept, under the trail, and reported with its progress.

ValueDestination
filetreeOne file per source under <PV_LOG_DIR>/<revision>/<container>/. Default
singlefileAll logs as JSON lines in <PV_LOG_DIR>/<revision>/pv.log
stdoutStandard output, processed by the log server
stdout.pantavisorStandard output, Pantavisor's own messages only
stdout.containersStandard output, container messages only
stdout_directStandard output, bypassing the log server. Also auto-enabled before the server starts and after it stops, and always passes FATAL through
nullsink/dev/null

Filetree paths​

How filetree turns a message's src into a path under <PV_LOG_DIR>/<revision>/<container>/, for any protocol. Leading and trailing / are stripped first.

src after strippingStored at
No / (e.g. myapp, from /myapp/)<container>/syslog/<src>
Contains / (e.g. lxc/console.log)<container>/<src>
Empty, .., or containing ../ or /..<container>/syslog/unknown-src
Any, when the platform is pantavisorpantavisor/pantavisor.log; src is not used

Only filetree builds paths from src; singlefile and the stdout* sinks store it as a field.

Console alerts​

Pantavisor's own messages mirrored to /dev/console, one line each; enabled by default. Overview: Storage → Console alerts.

ActionSetting
Disable at bootPV_LOG_CONSOLE_ALERTS=0
Disable at runtimepvcontrol usrmeta save PV_LOG_CONSOLE_ALERTS 0 — applies from the next message
Revert to the boot valuepvcontrol usrmeta delete PV_LOG_CONSOLE_ALERTS

Line format​

[ 6.217276] [PANTAVISOR] [platforms] WALL: platform 'awconnect' status is now STARTING
FieldContent
[ 6.217276]Seconds since boot (CLOCK_MONOTONIC), dmesg-style: 5 digits, 6 decimals
[PANTAVISOR]Fixed tag
[platforms]The emitting Pantavisor module
WALLLevel name: WALL, ERROR or FATAL
platform 'awconnect' …The message, without the (function:line) prefix of the log files. Whole line capped at 1024 bytes; truncated lines end in ...

Alert sources​

SourceEmitted whenLevel
platformsA container changes status, one line per transitionWALL
any Pantavisor moduleIt logs an errorERROR or FATAL
container logsNever mirrored, whatever their level—

Relation to logging​

ConditionConsole alertLog outputs
Level allowed by PV_LOG_LEVEL, no stdout output shows itprintedlogged
Level allowed by PV_LOG_LEVEL, a stdout output shows itskippedlogged
Level filtered out by PV_LOG_LEVELprintednot logged
PV_LOG_CONSOLE_ALERTS=0never printedfollows PV_LOG_LEVEL
LevelValueLogged when PV_LOG_LEVEL ≥
FATAL0always
ERROR11

Default PV_LOG_LEVEL is 0: only FATAL is logged, and all alerts still reach the console.

Outputs that count as "a stdout output shows it" (second row of the first table):

OutputLog server runningNot running (before start, after stop)
stdoutskips the alertskips the alert
stdout.pantavisorskips the alert—
stdout_directskips the alertskips the alert
stdout.containers——

Timestamp formats​

Every sink except nullsink prefixes each line with a timestamp.

KeySink
PV_LOG_FILETREE_TIMESTAMP_FORMATfiletree
PV_LOG_SINGLEFILE_TIMESTAMP_FORMATsinglefile
PV_LOG_STDOUT_TIMESTAMP_FORMATstdout*
PrefixMeaning
golang:<constant>One of the Go time layout constants below
strftime:<format>Any strftime(3) format, e.g. strftime:%d, %T %Y
golang: constantExample
golang:Layout01/02 03:04:05PM '06 -0700
golang:RubyDateMon Jan 02 15:04:05 -0700 2006
golang:ANSICMon Jan _2 15:04:05 2006
golang:RFC822Z02 Jan 06 15:04 -0700
golang:RFC1123ZMon, 02 Jan 2006 15:04:05 -0700

PV_LOG_TIMESTAMP selects the clock behind the tsec field:

Valuetsec
relative (default)Seconds since boot
absoluteUnix epoch