Sequence diagram - Provide updated design

dannycohen commented 10 years ago

Following several offline / email discussions
The goal of this task is to provide a design for sequence style diagram
Previous (outdated) designs:
- Sequence (group collapsed): http://glui.me/?i=80oxd8hkb2t9198/2013-08-05_at_20.13__(1).png/
- Sequence (group expanded): http://glui.me/?i=cnrldz623s44m79/2013-08-05_at_20.13_.png/
- Sequence (no time scale): http://glui.me/?i=vhsx88pwe05r7pp/2013-08-05_at_20.10_.png/
- Timeline: http://glui.me/?i=jxqgi7amo1bpg01/2013-08-05_at_20.08_.png/
The goal of the design is to include the following visual data:
1. Movement of messages between endpoints
  - (for current version, this will include endpoint name only per sequence column, not endpoint+machine name)
2. Object Type of message (e.g. "OrderAccepted")
3. Type of message (i.e. Event / Command, with the appropriate icon)
4. Time stamp indication of:
  - message sent time
  - message delivery / queue time (potential gap between the time the message sent and the processing started)
  - message processing started
  - message processing ended
5. Tooltips for entities and arrows, including performance numbers (Critical time, Processing time, delivery time, see here)
6. Grouping of related message (pub/sub of one message to multiple endpoints; visual will support both expanded and collapsed views)
7. Status of messages (similar visual language as Message Flow)
8. On-hover highlighting of message route (similar visual language as Message Flow and ServiceMatrix on-hover highlighting of message arrows)
9. Toggling Endpoint data (quesitonable, given the nature of the interaction, but may be required in order to include the specific sending / processing machine that hosts the endpoints)
10. Toggling Timeline stretch (TBD: the ability to expand the sequence to approximately indicate timespan; see comment below).
11. Zoom in/out
12. Possible miniaturized navigation window (e.g. this)

dannycohen commented 10 years ago

Toggling Timeline stretch

Building on the saying that "all models are wrong, but some are useful", the goal of timeline stretch is not to be perfectly accurate in its time representation, but to help the user grasp the timeline involved in message processing.
I suggest we define the sequence diagram by default as not representing time, and each message separated by the same space from its predecessor / successor messages
Once the timeline stretch is toggled on, the separating space will be multiplicated by the amount of time separating the messages.
That amount of separating time can be defined and calculated dynamically (or by user preferences)
For example:
- We can define that 1 seconds = 10 pixels
- Therefore, for each second separating the messages, we add 10 pixels to the space between them
- These parameters (1 second and 10 Pixels) can be configurable (Options, dynamically by the user or by code analysis of the timescale involved).

Thoughts ?

dannycohen commented 10 years ago

@HEskandari, @joaquinjares - FYI and you're welcome to comment. We will be doing a larger review before moving to implement (This is not a v1 feature; it will be added in a later minor release).

sergioc commented 10 years ago

Here we go. See below a checklist of of features from the sequence diagram. Timeline stretch will come in the next episode ;-)

[x] Movement of messages between endpoints (for current version, this will include endpoint name only per sequence column, not endpoint+machine name)
[x] Object Type of message (e.g. "OrderAccepted")
[x] Type of message (i.e. Event / Command, with the appropriate icon)
[x] message sent time
[x] message delivery / queue time (potential gap between the time the message sent and the processing started)
[x] message processing started
[x] message processing ended
[x] Tooltips for entities and arrows, including performance numbers (Critical time, Processing time, delivery time, see here)
[ ] Grouping of related message (pub/sub of one message to multiple endpoints; visual will support both expanded and collapsed views)
[x] Status of messages (similar visual language as Message Flow)
[x] On-hover highlighting of message route (similar visual language as Message Flow and ServiceMatrix on-hover highlighting of message arrows)
[x] Toggling Endpoint data (quesitonable, given the nature of the interaction, but may be required in order to include the specific sending / processing machine that hosts the endpoints)
[ ] Toggling Timeline stretch (TBD: the ability to expand the sequence to approximately indicate timespan; see comment below).
[ ] Zoom in/out
[ ] Possible miniaturized navigation window (e.g. this)
[ ] Indicate messages' association with Sagas

Video Store example: serviceinsight sequence diagram2-01

W/ Message hovered: serviceinsight sequence diagram2-02

dannycohen commented 10 years ago

@sergioc - Looks good!

A few comments:

Sending vs. Processing Endpoints

I think the visual language does not make it clear enough where the message originated from and where it was processed.

To illustrate, the send message rectangle resides completely in the sending endpoint region:

E.g. SubmitOrder is completely within ECommerce, although it was processed by CustomerRelations. The result, IMO, is that the sending endpoint and delivery is over emphasized , while the processing endpoints and the processing itself (which is, arguably, more prone to interesting problems and as a result is more important for this view) is under-emphasized.

Proposal: What if instead of the Endpoint region / rectangle proposed now, we use an Endpoint "Spine" and build the interaction around that ?

(note that the region / rectangle makes perfect sense for Saga View, since the Saga is the single center of attention. Here, there are multiple endpoints, and none is the single center of attention).

Causal dependency vs. Temporal proximity

We should emphasize causal dependencies more visually. For example, consider this:

Question: Did the BuyersRemorseIsOver message send the OrderAccepted Messages, or was it simply processed immediately before them, so the proximity of the messages makes it look like they are related ?

None Timeline-Stretch view

The above proposal illustrated Timeline overlay on the sequence. This is good but quite advanced. We also need the non-Timeline overlay (i.e. sequence interaction without the timeline overlay, which means that the vertical time bar on the left needs to be hidden when Timeline overlay is turned off.

Thoughts ?

dannycohen commented 10 years ago

@sergioc -

Possible variation on the theme: (warning: Amateurish visual ahead!)

The issues I am trying to highlight in this variation are:

Processing is the straight line while delivery is dashed (Processing is conceptually more interesting, in many cases)
There's terminator indicator (an arrow for sending a message, and a bulb for termination without any additional steps added to the sequence)
Delivery and Processing is done on the Spine of the Endpoint, while the messages themselves reside on the "periphery" of the endpoint
The left periphery of the endpoints is for incoming messages (only their dashed delivery lines), while the right periphery is for sent messages ractangles, even if they are sent to an endpoint that is located to the left of the sending endpoint

Thoughts ?

dannycohen commented 10 years ago

@sergioc - Another possible highlight: When hovering above an endpoint, highlight all the messages sent and received by it.

sergioc commented 10 years ago

Let's go step by step, starting with:

I think the visual language does not make it clear enough where the message originated from and where it was processed.

Agreed somewhat. I place messages on the sending endpoint because both the message itself and the sending endpoint are the cause for that interaction to happen in the first place.

The endpoint area also makes it neater to map and arrange vertical segments of arrows that run side by side with other arrows within the same receiving endpoint.

In your suggestion, the message still seems always attached to the sending endpoint, so I'm not sure what you mean about detaching the message from an endpoint.

dannycohen commented 10 years ago

@sergioc - I take back my comment on "...not make it clear enough where the message originated from and where it was processed". Lets continue with your proposed design and ask for comments from the team.

Any comment regarding other issues I raised ?

Also - We need to think about the connecting lines:

In SM / SI Message Flow, we are using the dotted line to indicate Event and straight line to indicate Command
We need to be consistent on that in the Sequence diagram...
... while at the same time we need to indicate the difference between delivery and processing. Possibly by using difference width of the lines ?

sergioc commented 10 years ago

In SM / SI Message Flow, we are using the dotted line to indicate Event and straight line to indicate Command

We need to be consistent on that in the Sequence diagram...

... while at the same time we need to indicate the difference between delivery and processing. Possibly by using difference width of the lines ?

I think using a dashed line to indicate message delivery works good, since the starting point and length of the first dash no longer get in the way. It also gives a better overview of the delivery lines since they move across 2 dimensions and are a bit more all over:

serviceinsight sequence diagram2-03

We should emphasize causal dependencies more visually.

Isn't that the goal of the flow diagram? Shouldn't we be strict about this and think of the sequence diagram more of a temporal view? If not, removing the timeline and bringing endpoint lanes together should allow to more easily unearth causal dependencies:

serviceinsight sequence diagram2-04