Skip to content

feat(notifications): add container context and normalize lifecycle events - #1427

Open
snesterkov wants to merge 2 commits into
Finsys:mainfrom
snesterkov:feat/zabbix-resource-context-pr
Open

feat(notifications): add container context and normalize lifecycle events#1427
snesterkov wants to merge 2 commits into
Finsys:mainfrom
snesterkov:feat/zabbix-resource-context-pr

Conversation

@snesterkov

@snesterkov snesterkov commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Summary

This is a follow-up enhancement to the previously merged Zabbix notification integration.

It adds resource context to container notifications and normalizes Docker lifecycle events so external monitoring systems can reliably correlate events with the affected container, environment, Compose stack, and service.

What changed

Container resource context

Container notifications now include additional context when available:

  • environment ID and name
  • container name
  • container ID
  • image
  • Compose stack
  • Compose service

Standalone containers remain standalone and do not get an invented stack or service name.

Normalized lifecycle events

Docker lifecycle actions are normalized into stable notification event types:

  • container_started
  • container_stopped
  • container_exited
  • container_restarted
  • container_oom
  • container_unhealthy
  • container_healthy

The normalization also avoids duplicate or misleading notifications:

  • a normal docker stop produces container_stopped
  • an unexpected die produces container_exited
  • kill is correlated with the following die instead of producing duplicate events
  • oom suppresses the subsequent duplicate die
  • Docker restart stop/start sequences are coalesced into a single container_restarted event

The same lifecycle semantics are used for both direct Docker environments and Hawser environments.

Why

The existing Zabbix notification provider can deliver Dockhand events to external monitoring, but lifecycle events previously lacked enough resource context for reliable per-container alerting and recovery.

These changes make it possible for monitoring systems to:

  • correlate events with a specific container
  • distinguish standalone containers from Compose services
  • automatically recover alerts on start/restart/healthy events
  • detect OOM and unexpected exits without duplicate alerts
  • preserve environment, stack, and service context in monitoring events

Zabbix monitoring template

This PR also includes a Zabbix 7.4 monitoring template for Dockhand.

The template provides:

  • Dockhand environment discovery
  • container discovery
  • per-container state, health, image and restart monitoring
  • lifecycle event handling through history.push
  • automatic problem recovery for start/restart/healthy events
  • local Dockhand container and Docker Engine monitoring through Zabbix Agent 2

Template:

integrations/zabbix/zbx_dockhand_by_http.json

Testing

Added tests for:

  • Compose container resource context
  • standalone container context
  • missing container-name fallback
  • normal stop semantics
  • unexpected exit semantics
  • kill/die deduplication
  • OOM/die deduplication
  • environment/container state isolation
  • restart coalescing
  • health/lifecycle event payloads
  • Zabbix history.push resource context

Targeted test result:

18 pass
0 fail
53 expect() calls

Also verified:

  • git diff --check passes
  • working tree is clean
  • Docker image build completes successfully

Type of change

  • Bug fix: non-breaking change which fixes an issue.
  • New feature / Enhancement: non-breaking change which adds functionality.
  • Breaking change: fix or feature that would cause existing functionality to not work as expected.
  • Other. Please explain:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant