Node logs and exec

Use logs agent to stream Edgelet daemon logs and exec agent to open an interactive shell on the edge host through a Controller-managed debug microservice.

Both commands need a namespace connected to a Controller (connect or control plane deploy) and an Edgelet node name known to the Controller.

Command name

The CLI subcommand is logs (plural), not log: potctl logs agent NAME.

Prerequisites

Requirement	logs agent	exec agent
Namespace config under ~/.iofog/v3	Yes	Yes
Controller API reachable	Remote node: yes	Yes
Edgelet node registered on Controller	Yes	Yes
Edgelet daemon RUNNING	Recommended (remote stream)	Required
RBAC / auth roles	Controller session	SRE-class access for node exec (Controller enforces)

Sync before remote logs: the CLI calls SyncAgentInfo so the local namespace cache matches Controller Agent records.

Edgelet log stream (logs agent)

Purpose

Tail Edgelet daemon logs on the node, not arbitrary application microservice logs. For workload logs use logs microservice.

Syntax

potctl logs agent AGENT_NAME -n NAMESPACE [flags]

Flags

Flag	Default	Description
--tail	100	Lines to fetch first (1–5000)
--follow	true	Keep streaming new lines
--since	(empty)	Start time RFC3339 / ISO 8601 (e.g. 2024-01-01T00:00:00Z)
--until	(empty)	End time RFC3339

Set --follow=false for a one-shot snapshot (still subject to remote vs local behavior below).

How it works

Remote Edgelet node (kind: Agent)

1. Resolve agent UUID from the Controller.
2. Open a WebSocket log session via SDK DialFogLogs with tail options.
3. Print LogMessageLine frames to stdout until stop, error, or connection end.

The Controller may relay logs across HA replicas. If relay is unavailable you may see messages about log session relay or server draining. Retry or use another controller replica.

Local Edgelet node (kind: LocalAgent)

1. Read namespace-stored LocalAgent spec (container engine from agent config).
2. Fetch logs from the local Edgelet container (GetLogsByName on the Edgelet container name).
3. Print stdout and stderr once to the terminal.

Important: --tail, --follow, --since, and --until apply to the remote DialFogLogs path. They are not passed to the local container engine path today. Local logs agent is effectively a full container log dump from the engine API.

Examples

# Follow last 100 lines (default)
potctl logs agent edge-01 -n my-ecn

# Snapshot only, last 500 lines
potctl logs agent edge-01 -n my-ecn --follow=false --tail=500

# Time window (remote)
potctl logs agent edge-01 -n my-ecn --since=2026-01-01T00:00:00Z --until=2026-01-02T00:00:00Z

Troubleshooting

Symptom	Likely cause
Agent not in namespace config	Deploy or connect did not persist the node; run describe agent
Timeout waiting for agent	Node offline or network path to Edgelet broken
Relay / draining errors	Controller HA or rollout. Retry.
Local: empty or error	Edgelet container not running on this machine

Interactive debug shell (exec agent)

Purpose

Open a terminal session into a debug container on the edge node. The CLI connects through the Controller exec WebSocket API to a system microservice named like debug, debug-<agentName>, or debug-<agentUUID> under application system-<agentName>.

This is node-level debug exec (SRE), not exec microservice (Developer workload exec).

Syntax

potctl exec agent AGENT_NAME [DEBUG_IMAGE] -n NAMESPACE

Argument	Description
AGENT_NAME	Controller agent name
DEBUG_IMAGE	Optional OCI image for the debug container when auto-provisioning

If omitted, Controller or catalog defaults apply when fog debug exec is provisioned.

How it works

Auto-provision (default path)

exec agent calls ensureDebugExecReady:

1. Fail fast if agent DaemonStatus is not RUNNING.
2. Look for an existing debug system microservice on that agent.
3. If missing, call AttachExecToAgent (same API as attach exec agent) with optional image.
4. Poll every 2s (max 60 attempts) until microservice status is RUNNING.
5. DialSystemMicroserviceExecWithOptions and hand off to an interactive terminal (raw TTY on Unix).

If debug was already provisioned but stopped, the CLI waits for RUNNING again.

Manual provision (optional)

Provision without opening a shell first:

potctl attach exec agent edge-01 -n my-ecn
potctl attach exec agent edge-01 ghcr.io/org/debug:1.0 -n my-ecn

Then:

potctl exec agent edge-01 -n my-ecn

Remove the debug workload when finished:

potctl detach exec agent edge-01 -n my-ecn

detach exec agent calls DetachExecFromAgent on the agent UUID and removes fog debug exec resources.

Session behavior

• Spinner stops before the interactive session; stdin/stdout attach to the WebSocket exec stream.
• Status lines from the session may print via SDK callbacks.
• Exit closes the session; the CLI prints success when the session ends cleanly.
• Concurrent exec limits: the Controller may return 409. At most 3 concurrent exec sessions per microservice (message surfaced by the CLI).

Examples

# Auto-provision debug container if needed, then shell
potctl exec agent edge-01 -n my-ecn

# Custom debug image on first provision
potctl exec agent edge-01 ghcr.io/org/debug:latest -n my-ecn

Troubleshooting

Symptom	Likely cause
Agent is not running	Start Edgelet or fix the node before exec
Timeout waiting for debug container	Image pull failure, agent disk, or catalog/registry
Insufficient permissions	User lacks SRE (node exec) role on Controller
Only SRE for system MS	Expected for system microservice exec path
Relay / draining errors	Same HA considerations as logs
Debug microservice not found (older flows)	Run attach exec agent or use exec agent (auto-provisions)

Compare: logs vs exec vs microservice logs/exec

Command	Target	Transport	Interactive
logs agent	Edgelet daemon	DialFogLogs (remote) or local container logs	No (stream to stdout)
exec agent	Debug system container on node	DialSystemMicroserviceExec	Yes (shell)
logs microservice	App microservice	DialMicroserviceLogs / system variant	No
exec microservice	Running app microservice	DialMicroserviceExec	Yes

See also

• Attach and detach - move nodes between ECNs
• Upgrade and rollback - fleet Edgelet version changes
• Setup Edgelet nodes - remote deploy and LocalAgent
• potctl logs - CLI reference
• potctl exec agent - CLI reference
• Edgelet troubleshooting - on-host connectivity and MS health
• Observe and troubleshoot

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!