Docker supports an endpoint for getting/streaming
Does that mean getting and streaming? It might help to make this clearer as to not confuse the reader from the beginning. Maybe "getting" is good enough at this point in the document, even if technically the client is "streamimg" them.
Recent changes to the Docker cli for Docker version 1.13.0 have increased the priority of implementing the /events endpoint at least minimally, as the cli now depends on /events to gather the exit code for the docker run command and users will get errors and the wrong exit code for every docker run with the new version until this is implemented.
That sentence is a bit long. I think it would help make it clearer if it was split up in several parts. Something like:
"Recent changes to the Docker cli for Docker version 1.13.0 have increased the priority of implementing the /events endpoint at least minimally. For instance, the cli now depends on /events to gather the exit code for the docker run command. As a result, until that endpoint is implemented, users will get errors and the wrong exit code for every docker run with the new docker client version."
At the time of this writing Docker's documentation for events is here
Clicking on "here" does not bring me to the system events documentation. It brings me to a section entitled "Get data usage information".
Since docker run calls /events after /create, we don't see the create event in this stream. We also don't see the attach that happens before the start.
This sentence is a bit confusing to me. Why don't we see the "attach" event? You mention it's because it happens before start, does that mean that "docker run" calls "/events" after "start"?
The since filter works similarly in that it looks at the list of events since the daemon last started.
Why is there a "--since" command line option to docker events if "--until" also "gives you all data since the daemon last started"? I think there's something I'm missing.
Since these events also include additional details about the event (the exitCode for example in the case of a die event), it's also possible that at different layers of the stack it will be more difficult to have access to the required additional information. Especially in a timely manner.
What do you mean by "more difficult"? Can you illustrate that with a concreate example?
What is required here just for docker run (to resolve DOCKER-996) is at minimum that we must have: the ability to output a die event any time a container exits the die event must include the exit code
Is "die" the only event we need to support for now to get rid of all error messages? It's not clear from the sentence above whether it's the case.
As mentioned in the previous section, this problem is significantly complicated by the distributed nature of attach for docker containers in sdc-docker.
I think the "previous" section is the one for which I added a comment that things weren't clear and lacked concrete examples.
"Properties of a solution" and "Triton changefeed"
It seems that the section about "Triton changefeed" presents how it can't be a solution, at least for now, is that correct? Then it's a bit confusing to have that section under "Properties of a solution". Maybe it'd be better to move that under a "Limitations of the current implementation" (or a name along those lines) section?
However there are a few things to consider here.
Changefeed operates on VMAPI which is itself a cache of the VM data which ultimately belongs to a CN. This means that when Changefeed emits an event, it is telling you when the cache of the current state was updated, not when the event itself occurred on the CN. Additionally, Changefeed only tells you that something changed, not what changed or the new value, this means that you must separately query VMAPI to find the current cached state which might be different from the state immediately following a change since there could be intervening changes.
I think this paragraph would benefit from being split into several numbered points. Otherwise it's a bit confusing to follow and to refer to each of the concepts later in the text.
Even if we did, since VMAPI itself may miss events as the load from the CN works similarly
By "the load from the CN works similarly", do you mean that events happening on a given CN are coallesced at the vm-agent level? Anyway, it might help to be a bit more detailed here, as it's not clear what it means.
Until we've resolved ZAPI-690
The link to ZAPI-690 doesn't work (ticket is not public).
If we were to modify this mechanism such that it appends a line to the file on each exit, instead of overwriting the file, we would be able to have an accurate record of all exits. If we did this and exposed it via cn-agent in a way that sdc-docker could consume, we would have everything we need to implement the die events, including for history (back the point where the CN was booted onto a supporting platform).
Would we need to store the timestamps for each exit in that file (to support docker events --until/--since)? Also, I guess that sdc-docker would be notified of changes to these files (and thus of exit/die events) via an OS-level file event handling mechanism? If so, is there a chance that some file change events would be missed?