Add recommendations for graph legend

[cshinn]

Add recommendations for an in-graph legend.
I tried to keep things relatively small, but there are a lot of different things to display. I've included a couple of options for layouts that might be better for certain screen sizes.
More detailed descriptions including what different text pieces mean could exist on an outside documentation page.

Closes #10

[abonas]

LOVE this! Especially the horizontal layout.
requesting a few more reviews.

[abonas]

From my perspective this is a great design for our current graph requirements. I'm approving this, but I'd like to hear a few more inputs from the team prior to merging.

[jmazzitelli]

The general look/feel is good. I have one comment specifically about the "octagon" description. While today it is technically correct to say that the octagon only really shows up when you got errors in a connection to that target (but notice the description doesn't define what
that "target" is), the octagon truly represents a "service". I think the description for the octagon should say what it represents ("a service"), not that it represents a failed connection to an unknown target. It just so happens that today the octagon only shows up when an error occurs in a request to that service. But hopefully in the near future we'll be able to show octagons (services) receiving successful requests (there are design discussions ongoing about this).

[jshaughn]

Looks nice, I do have a couple of comments:

First, I think for the new legend we may want to actually use a full image as produced from UX. The legend-details.png in the PR is pretty close and it will provide a nice look. It will likely be easier than piecing together all of the small images necessary for this legend, and updates will just be a revision to the image. Not exactly sure what tool is being used, though. BUt we could use a less specialized tool if necessary. It may not do well on a mobile device but then again, neither will a graph of any size.

I agree with Mazz about the Octagon description but have a few more suggestions as well:

• Circle
  • "App/Workload". I suggest removing "Internal" since it's basically assumed.
• Pentagon
  • App/Workload\nExternal Namespace". I suggest adding 'Namespace' to let them know what it's external to, and to move that qualifier to the bottom line.
• Diamond
  • "Traffic Source". Not every traffic source is "Unknown", at least not at the moment. It can be a normal Workload.
• Octagon
  • "Service" or maybe "Requested Service". As mazz points out, it may not always be the destination of failed requests, we may in the future show it on the path to a successful request.

The arrow color thresholds are not correct given the current code (whether the code thresholds are correct is another question):

• Red
  • > 20%
• Orange
  • 0.1-20%
• Green
  • < 0.1%

[abonas]

Right now, the diamond represents 2 things on the graph - a failed request and a traffic source. that might cause confusion.

[jshaughn]

@abonas , The diamond does not represent a failed request. It's only used to represent a traffic source. A traffic source is basically a node that has only outgoing edges. Note that outsider trumps traffic source, so a node will be a pentagon over a diamond. The diamond is most commonly used for the "unknown" node. We may want to discuss the diamond in the next round of graph UX.

[jmazzitelli]

@jshaughn I think @abonas is referring to the little diamonds on the red edges in the traffic animation - the little red diamonds in the animation refers to failed requests. I don't see the confusion myself (that is a little red moving diamond on the edge, whereas the diamond shaped nodes are larger, and not moving, and not on edges - but it is true that the SHAPE is the same between the two (diamond).)

[abonas]

@jshaughn I think @abonas is referring to the little diamonds on the red edges in the traffic animation - the little red diamonds in the animation refers to failed requests. I don't see the confusion myself (that is a little red moving diamond on the edge, whereas the diamond shaped nodes are larger, and not moving, and not on edges - but it is true that the SHAPE is the same between the two (diamond).)

indeed that was exactly what I was referring to @jmazzitelli :)

[jshaughn]

Ah, OK, thanks. I guess that shape is to help in the case of color blindness. I mean, I guess you could say the same for the circle/dots. I think the context is enough to differentiate.

[mwringe]

@josejulio has done some preliminary work with this, there is an animated gif here showing how its working in his pr: https://user-images.githubusercontent.com/3845764/44868584-e25e6b80-ac50-11e8-9108-ace0dbfc5b09.gif

From the discussion today, it looks like we might want to use the long short type and adjust based on the width of the browser. But with @josejulio work, its moveable, and I think the more square type might work better for that.

Any opinions on how we should proceed with this?

@cshinn @serenamarie125 Do we still want the long and narrow kind and adjust based on screen width? Should the legend be moveable or stuck in place?

[cshinn]

Here are a couple of updated images. I've corrected the terminology as discussed above and I've decreased the size of the node shapes which saves us some space

I can product SVG versions of either/both of these or of individual sections if that makes things easier

[mwringe]

An SVG would be awesome :) Thanks

[cshinn]

I've sent out the relevant SVG and I'll update this PR when I get a chance. Then it should be all set

[serenamarie125]

LGTM @cshinn