Edgelet logging

Structured lifecycle logging for Process Manager, container engines, and EdgeletAPI. Events are written as top-level JSON fields in Edgelet daemon logs.

Field schema

Field	Description
timestamp	Log time
level	debug / info / warn / error
module	Logger module name (e.g. Container Manager, Edgelet API Handler)
message	Short human-readable summary
event	Stable event name (see catalog below)
operationId	Correlation UUID for one deploy/update/remove
engine	docker, podman, or edgelet
msUUID	Microservice UUID
containerId	Runtime container ID
sandboxId	CRI pod sandbox ID (edgelet engine)
image	Image reference used
phase	Sub-phase: pull, create, start, stop, remove
result	ok, failed, skipped
durationMs	Phase duration in milliseconds
reasonCode	Stable failure/drift code for alerting
source	task, reconcile, shutdown, runtime_watch, api, watchdog
error	Truncated error text (max 512 chars)

Never logged: registry passwords, env values, JWT/bearer tokens.

EdgeletAPI access logs

Event	When
edgeletapi.access	Authorized request (method, path, status, duration)
edgeletapi.reject	Auth or RBAC rejection
edgeletapi.debug	Verbose handler diagnostics (LOG_LEVEL=debug)

Process Manager event catalog

Event	When
pm.started / pm.stopped	Process Manager lifecycle
task.enqueued / task.started / task.completed / task.failed / task.retry	Task queue
reconcile.cycle / reconcile.decision	Monitor tick
container.pulling → container.removed	Container lifecycle phases
container.runtime.event	External runtime signal (source=runtime_watch)
shutdown.drain	Graceful shutdown

Log levels

Level	Use
info	Production default
warn	Degraded but continuing
error	Operation failed
debug	Reconcile internals, CRI substeps, EdgeletAPI handler detail

Set via config logLevel or environment (LOG_LEVEL=info). See Configuration reference.

Log files (rotated)

When logDirectory is configured (default /var/log/edgelet/):

systemd unit	Basename	Active file
edgelet.service	edgelet	edgelet.0.log
edgelet-containerd.service	edgelet-containerd	edgelet-containerd.0.log

Runtime split (embedded engine): edgelet gets 60% of logLimit, edgelet-containerd gets 40%.

Hot reload: logLevel, logLimit, and logFileCount apply on config reload without rotating the active file. Control plane reloads via SIGHUP / edgelet system reload. Changing logDirectory requires a process restart.

Microservice logs under logDirectory/containers/ use separate per-UUID series.

journald

sudo journalctl -u edgelet -f
sudo journalctl -u edgelet-containerd -f
sudo journalctl -u edgelet --since "30 min ago" | jq -r 'select(.event!=null) | .event'

Example queries

Failed tasks (Loki-style):

{job="edgelet"} | json | event="task.failed"

Correlate one deploy operation:

{job="edgelet"} | json | operationId="<OPERATION_ID>"

EdgeletAPI rejections:

{job="edgelet"} | json | event="edgeletapi.reject"

Reason codes

Code	Meaning
PULL_FAILED	Registry pull failed
CREATE_FAILED	Container create failed
START_FAILED	Container start failed
NON_RESTARTABLE_EXIT	Terminal CRI exit; recreate required
RUNTIME_DRIFT	Stale DB vs runtime
TASK_EXHAUSTED_RETRIES	Task failed 5 times

See also

• Troubleshooting — daemon startup and disk space
• Configuration — edgelet config --log-level

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

Edit this page on GitHub!