docker-compose events

compose/cli/main.py

@@ -2,6 +2,7 @@
 from __future__ import print_function
 from __future__ import unicode_literals
 
+import json
 import logging
 import re
 import signal
@@ -132,6 +133,7 @@ class TopLevelCommand(DocoptCommand):
  build Build or rebuild services
  config Validate and view the compose file
  create Create services
+ events Receive real time events from containers
  help Get help on a command
  kill Kill containers
  logs View output from containers
@@ -244,6 +246,30 @@ def create(self, project, options):
  do_build=not options['--no-build']
  )
 
+ def events(self, project, options):
+ """
+ Receive real time events from containers.
+
+ Usage: events [options] [SERVICE...]
+
+ Options:
+ --json Output events as a stream of json objects
+ """
+ def format_event(event):
+ attributes = ["%s=%s" % item for item in event['attributes'].items()]
+ return ("{time} {type} {action} {id} ({attrs})").format(
+ attrs=", ".join(sorted(attributes)),
+ **event)
+
+ def json_format_event(event):
+ event['time'] = event['time'].isoformat()
+ return json.dumps(event)
+
+ for event in project.events():
+ formatter = json_format_event if options['--json'] else format_event
+ print(formatter(event))
+ sys.stdout.flush()
+
  def help(self, project, options):
  """
  Get help on a command.

compose/const.py

@@ -6,6 +6,7 @@
 
 DEFAULT_TIMEOUT = 10
 HTTP_TIMEOUT = int(os.environ.get('COMPOSE_HTTP_TIMEOUT', os.environ.get('DOCKER_CLIENT_TIMEOUT', 60)))
+IMAGE_EVENTS = ['delete', 'import', 'pull', 'push', 'tag', 'untag']
 IS_WINDOWS_PLATFORM = (sys.platform == "win32")
 LABEL_CONTAINER_NUMBER = 'com.docker.compose.container-number'
 LABEL_ONE_OFF = 'com.docker.compose.oneoff'

compose/project.py

@@ -1,6 +1,7 @@
 from __future__ import absolute_import
 from __future__ import unicode_literals
 
+import datetime
 import logging
 from functools import reduce
 
@@ -11,6 +12,7 @@
 from .config import ConfigurationError
 from .config.sort_services import get_service_name_from_net
 from .const import DEFAULT_TIMEOUT
+from .const import IMAGE_EVENTS
 from .const import LABEL_ONE_OFF
 from .const import LABEL_PROJECT
 from .const import LABEL_SERVICE
@@ -20,6 +22,7 @@
 from .service import Net
 from .service import Service
 from .service import ServiceNet
+from .utils import microseconds_from_time_nano
 from .volume import Volume
 
 
@@ -267,7 +270,44 @@ def create(self, service_names=None, strategy=ConvergenceStrategy.changed, do_bu
  plans = self._get_convergence_plans(services, strategy)
 
  for service in services:
- service.execute_convergence_plan(plans[service.name], do_build, detached=True, start=False)
+ service.execute_convergence_plan(
+ plans[service.name],
+ do_build,
+ detached=True,
+ start=False)
+
+ def events(self):
+ def build_container_event(event, container):
+ time = datetime.datetime.fromtimestamp(event['time'])
+ time = time.replace(
+ microsecond=microseconds_from_time_nano(event['timeNano']))
+ return {
+ 'time': time,
+ 'type': 'container',
+ 'action': event['status'],
+ 'id': container.id,
+ 'service': container.service,
+ 'attributes': {
+ 'name': container.name,
+ 'image': event['from'],
+ }
+ }
+
+ service_names = set(self.service_names)
+ for event in self.client.events(
+ filters={'label': self.labels()},
+ decode=True
+ ):
+ if event['status'] in IMAGE_EVENTS:
+ # We don't receive any image events because labels aren't applied
+ # to images
+ continue
+
+ # TODO: get labels from the API v1.22 , see github issue 2618
+ container = Container.from_id(self.client, event['id'])
+ if container.service not in service_names:
+ continue
+ yield build_container_event(event, container)
 
  def up(self,
  service_names=None,

compose/utils.py

@@ -88,3 +88,7 @@ def json_hash(obj):
  h = hashlib.sha256()
  h.update(dump.encode('utf8'))
  return h.hexdigest()
+
+
+def microseconds_from_time_nano(time_nano):
+ return int(time_nano % 1000000000 / 1000)

docs/reference/events.md

@@ -0,0 +1,34 @@
+<!--[metadata]>
++++
+title = "events"
+description = "Receive real time events from containers."
+keywords = ["fig, composition, compose, docker, orchestration, cli, events"]
+[menu.main]
+identifier="events.compose"
+parent = "smn_compose_cli"
++++
+<![end-metadata]-->
+
+# events
+
+```
+Usage: events [options] [SERVICE...]
+
+Options:
+ --json Output events as a stream of json objects
+```
+
+Stream container events for every container in the project.
+
+With the `--json` flag, a json object will be printed one per line with the
+format:
+
+```
+{
+ "service": "web",
+ "event": "create",
+ "container": "213cf75fc39a",
+ "image": "alpine:edge",
+ "time": "2015-11-20T18:01:03.615550",
+}
+```

docs/reference/index.md

@@ -14,19 +14,20 @@ parent = "smn_compose_ref"
 The following pages describe the usage information for the [docker-compose](docker-compose.md) subcommands. You can also see this information by running `docker-compose [SUBCOMMAND] --help` from the command line.
 
 * [build](build.md)
+* [events](events.md)
 * [help](help.md)
 * [kill](kill.md)
-* [ps](ps.md)
-* [restart](restart.md)
-* [run](run.md)
-* [start](start.md)
-* [up](up.md)
 * [logs](logs.md)
 * [port](port.md)
+* [ps](ps.md)
 * [pull](pull.md)
+* [restart](restart.md)
 * [rm](rm.md)
+* [run](run.md)
 * [scale](scale.md)
+* [start](start.md)
 * [stop](stop.md)
+* [up](up.md)
 
 ## Where to go next
 

tests/acceptance/cli_test.py

@@ -1,6 +1,8 @@
 from __future__ import absolute_import
 from __future__ import unicode_literals
 
+import datetime
+import json
 import os
 import shlex
 import signal
@@ -855,6 +857,35 @@ def get_port(number, index=None):
  self.assertEqual(get_port(3000, index=2), containers[1].get_local_port(3000))
  self.assertEqual(get_port(3002), "")
 
+ def test_events_json(self):
+ events_proc = start_process(self.base_dir, ['events', '--json'])
+ self.dispatch(['up', '-d'])
+ wait_on_condition(ContainerCountCondition(self.project, 2))
+
+ os.kill(events_proc.pid, signal.SIGINT)
+ result = wait_on_process(events_proc, returncode=1)
+ lines = [json.loads(line) for line in result.stdout.rstrip().split('\n')]
+ assert [e['action'] for e in lines] == ['create', 'start', 'create', 'start']
+
+ def test_events_human_readable(self):
+ events_proc = start_process(self.base_dir, ['events'])
+ self.dispatch(['up', '-d', 'simple'])
+ wait_on_condition(ContainerCountCondition(self.project, 1))
+
+ os.kill(events_proc.pid, signal.SIGINT)
+ result = wait_on_process(events_proc, returncode=1)
+ lines = result.stdout.rstrip().split('\n')
+ assert len(lines) == 2
+
+ container, = self.project.containers()
+ expected_template = (
+ ' container {} {} (image=busybox:latest, '
+ 'name=simplecomposefile_simple_1)')
+
+ assert expected_template.format('create', container.id) in lines[0]
+ assert expected_template.format('start', container.id) in lines[1]
+ assert lines[0].startswith(datetime.date.today().isoformat())
+
  def test_env_file_relative_to_compose_file(self):
  config_path = os.path.abspath('tests/fixtures/env-file/docker-compose.yml')
  self.dispatch(['-f', config_path, 'up', '-d'], None)

tests/unit/project_test.py

@@ -1,6 +1,8 @@
 from __future__ import absolute_import
 from __future__ import unicode_literals
 
+import datetime
+
 import docker
 
 from .. import mock
@@ -197,6 +199,102 @@ def test_use_volumes_from_service_container(self):
  project.get_service('test')._get_volumes_from(),
  [container_ids[0] + ':rw'])
 
+ def test_events(self):
+ services = [Service(name='web'), Service(name='db')]
+ project = Project('test', services, self.mock_client)
+ self.mock_client.events.return_value = iter([
+ {
+ 'status': 'create',
+ 'from': 'example/image',
+ 'id': 'abcde',
+ 'time': 1420092061,
+ 'timeNano': 14200920610000002000,
+ },
+ {
+ 'status': 'attach',
+ 'from': 'example/image',
+ 'id': 'abcde',
+ 'time': 1420092061,
+ 'timeNano': 14200920610000003000,
+ },
+ {
+ 'status': 'create',
+ 'from': 'example/other',
+ 'id': 'bdbdbd',
+ 'time': 1420092061,
+ 'timeNano': 14200920610000005000,
+ },
+ {
+ 'status': 'create',
+ 'from': 'example/db',
+ 'id': 'ababa',
+ 'time': 1420092061,
+ 'timeNano': 14200920610000004000,
+ },
+ ])
+
+ def dt_with_microseconds(dt, us):
+ return datetime.datetime.fromtimestamp(dt).replace(microsecond=us)
+
+ def get_container(cid):
+ if cid == 'abcde':
+ name = 'web'
+ labels = {LABEL_SERVICE: name}
+ elif cid == 'ababa':
+ name = 'db'
+ labels = {LABEL_SERVICE: name}
+ else:
+ labels = {}
+ name = ''
+ return {
+ 'Id': cid,
+ 'Config': {'Labels': labels},
+ 'Name': '/project_%s_1' % name,
+ }
+
+ self.mock_client.inspect_container.side_effect = get_container
+
+ events = project.events()
+
+ events_list = list(events)
+ # Assert the return value is a generator
+ assert not list(events)
+ assert events_list == [
+ {
+ 'type': 'container',
+ 'service': 'web',
+ 'action': 'create',
+ 'id': 'abcde',
+ 'attributes': {
+ 'name': 'project_web_1',
+ 'image': 'example/image',
+ },
+ 'time': dt_with_microseconds(1420092061, 2),
+ },
+ {
+ 'type': 'container',
+ 'service': 'web',
+ 'action': 'attach',
+ 'id': 'abcde',
+ 'attributes': {
+ 'name': 'project_web_1',
+ 'image': 'example/image',
+ },
+ 'time': dt_with_microseconds(1420092061, 3),
+ },
+ {
+ 'type': 'container',
+ 'service': 'db',
+ 'action': 'create',
+ 'id': 'ababa',
+ 'attributes': {
+ 'name': 'project_db_1',
+ 'image': 'example/db',
+ },
+ 'time': dt_with_microseconds(1420092061, 4),
+ },
+ ]
+
  def test_net_unset(self):
  project = Project.from_config('test', Config(None, [
  {