Add UI docs #185

aljesusg · 2018-12-04T11:48:54Z

WIP Add dosc for the UI

Add embedded components

Fix issue #183
Require: jaegertracing/jaeger-ui#286

I do not know exactly what kind of documentation would be the most appropriate for this

cc @tiffon

Demo: https://deploy-preview-185--jaegertracing.netlify.com/docs/next-release/frontend-ui/

aljesusg · 2018-12-04T11:51:13Z

I called interface instead of UI. WDYT @tiffon ?

Demo: https://deploy-preview-185--jaegertracing.netlify.com/docs/next-release/frontend-ui/

yurishkuro · 2018-12-11T22:50:53Z

"interface" is confusing, I would rather call it "Frontend/UI".

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

tiffon

Here are a few suggestions. Let me know what you think.

Thanks!

tiffon · 2018-12-17T21:26:17Z

content/docs/next-release/frontend-ui.md

+weight: 10
+---
+
+Jaeger Web UI is implemented in Javascript using popular open source frameworks like React. Several performance improvements have been released in v1.0 to allow the UI to efficiently deal with large volumes of data, and to display traces with tens of thousands of spans (e.g. we tried a trace with 80,000 spans).


Javascript => JavaScript

I don't think we need the second sentence...?

Ok, I just move the content in docs/1.8/features/#modern-web-ui but I agree with you about remove the second sentence

tiffon · 2018-12-18T00:34:06Z

content/docs/next-release/frontend-ui.md

+
+## Embed Mode
+
+Enhancement to embed mode in Jaeger UI for some components allowing us to integrate it into other applications.


I suggest rephrasing this paragraph to:

Starting with version [TODO], Jaeger UI provides an "embedded" layout mode which is intended to support integrating Jaeger UI into other applications. Currently (as of v0), the approach taken is to remove various UI elements from the page to make the UI better suited for space-constrained layouts.

The embedded mode is induced and configured via URL query parameters.

To enter embedded mode, the uiEmbed=v0 query parameter and value must be added to the URL. For example, the following URL will show the trace with ID abc123 in embedded mode:

https://example.com/trace/abc123?uiEmbed=v0

uiEmbed=v0 is required.

Further, each page supported has an button added that will open the non-embedded page in a new tab.

What do you think?

Here is the markdown:

Starting with version **[TODO]**, Jaeger UI provides an "embedded" layout mode which is intended to support integrating Jaeger UI into other applications. Currently (as of `v0`), the approach taken is to remove various UI elements from the page to make the UI better suited for space-constrained layouts. The embedded mode is induced and configured via URL query parameters. To enter embedded mode, the `uiEmbed=v0` query parameter and value must be added to the URL. For example, the following URL will show the trace with ID `abc123` in embedded mode: ``` https://example.com/trace/abc123?uiEmbed=v0 ``` `uiEmbed=v0` is required. Further, each page supported has an <img src="/static/img/frontend-ui/embed-open-icon.png" style="width: 20px; height:20px;" alt="Embed open window"> button added that will open the non-embedded page in a new tab.

tiffon · 2018-12-18T00:35:15Z

content/docs/next-release/frontend-ui.md

+    uiEmbed=v0
+```
+
+![Embed Search Traces](/img/frontend-ui/embed-search-traces.png)


The image URLs need /static/ prepended.

The images will also need to be updated whenever we land on a final layout and design.

tiffon · 2018-12-18T00:41:45Z

content/docs/next-release/frontend-ui.md

+
+##### Optionally
+
+We can use an extra options in the embed mode :


Suggest rephrasing as:

The following query parameter can be used to configure the layout of the search page:

uiSearchHideGraph=1

Do not display the scatter plot above the search results

tiffon · 2018-12-18T00:42:47Z

content/docs/next-release/frontend-ui.md

+
+![Embed Search Traces](/img/frontend-ui/embed-search-traces.png)
+
+We have a button in this kind of view that redirect us to the search traces page in the Jaeger Site <img src="/img/frontend-ui/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.  


This ^ can be removed if it is added to the section above "EmbedMode" intro section.

tiffon · 2018-12-18T00:43:58Z

content/docs/next-release/frontend-ui.md

+    service=jaeger-query&
+    start=1543917759557000&
+    uiEmbed=v0&
+    uiSearchHideGraph=1s


Looks like a typo, =1s

tiffon · 2018-12-18T00:44:52Z

content/docs/next-release/frontend-ui.md

+
+We have a button in this kind of view that redirect us to the search traces page in the Jaeger Site <img src="/img/frontend-ui/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.  
+
+##### Optionally


Suggest renaming this title to "Configuration options"

tiffon · 2018-12-18T00:45:10Z

content/docs/next-release/frontend-ui.md

+
+![Embed Trace view](/img/frontend-ui/embed-trace-view-with-back-button.png)
+
+We have a new button in this kind of view that redirect us to the trace page in the Jaeger Site <img src="/img/interface/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.


This ^ can be removed if it is added to the section above "EmbedMode" intro section.

tiffon · 2018-12-18T00:45:22Z

content/docs/next-release/frontend-ui.md

+
+We have a new button in this kind of view that redirect us to the trace page in the Jaeger Site <img src="/img/interface/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.
+
+##### Optionally


Suggest renaming this title to "Configuration options"

tiffon · 2018-12-18T00:50:52Z

content/docs/next-release/frontend-ui.md

+
+##### Optionally
+
+We can use an extra options in the embed mode :


I suggest rephrasing to the following and adding images after summarizing the query parameters.

The following query parameters can be used to configure the layout of the trace page:

uiTimelineCollapseTitle=1

The trace header starts out collapsed, which hides the summary and minimap

uiTimelineHideMinimap=1

Removes the minimap, entirely, regardless of whether the trace header is expanded or not

uiTimelineHideSummary=1

Removes the trace summary information (number of services, etc.), entirely, regardless of whether the trace header is expanded or not

aljesusg · 2018-12-18T14:34:26Z

@tiffon I did the changes. I added the images about trace embed that you uploaded in your jaegertracing/jaeger-ui#286 and I added the images to the public/ too. Anyway We should wait until the merge of jaegertracing/jaeger-ui#286

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

tiffon · 2018-12-20T07:54:47Z

Thanks, @aljesusg, the changes look great! jaegertracing/jaeger-ui#286 is merged. 👍

aljesusg · 2018-12-20T07:55:20Z

Great !!!

yurishkuro · 2018-12-21T21:03:01Z

Wouldn't it better to consolidate the configuration options from https://www.jaegertracing.io/docs/1.8/deployment/ into this new page as well, and link to it from Deployment?

aljesusg · 2018-12-22T17:44:03Z

As you want, if you think it's better to make the change I can do it but ...I think that it could be confuse for the user have the deployment manual (components) with the documentation about the UI and how to use/work it. What do you think ? @tiffon @yurishkuro

tiffon · 2018-12-22T18:21:07Z

I was thinking these docs would be for users. So, I agree that it could be confusing to move the UI config docs to this section. But, linking the other way seems like it would work. If we add a section to the UI docs called "Administration" (or something), we can link to the UI config docs in Deployment.

aljesusg · 2018-12-24T08:22:21Z

So What do you think about to change the first sentence to something like

Jaeger Web UI is implemented in JavaScript using popular open source frameworks like React. 
Check the [administration](/docs/next-release/deployment#query-service-ui) documentation to configure the UI.

Or What was your idea?

yurishkuro · 2018-12-24T16:57:57Z

I was thinking these docs would be for users.

@tiffon someone deploying jaeger is also a "user". If you are talking about real end users who actually use the UI to investigate traces, then this document is clearly not for them - why would they care about embedding and the internal API to control the embedding? In fact, I almost want to argue that having documentation for end users is an anti-pattern - it would mean the UI is poorly designed and non-intuitive. End users may need a tutorial mode in the UI that walks them through the UI elements.

Or What was your idea?

@aljesusg my proposal was to move UI section from Deployment to this doc, and only leave a link in the Deployment. I think both configuration and embedding are part of the UI deployment story, and this doc should be a sub-document of the Deployment (similar to how Client Features doc is sub-doc of Client Libraries).

tiffon · 2018-12-30T10:35:42Z

@yurishkuro Yes, I was referring to folks using the UI. You're right, people deploying Jaeger are also users. I would tend to think of them as administrators, but they're definitely users, either way.

real end users who actually use the UI to investigate traces, then this document is clearly not for them

Great point. I do think the "Jaeger UI" section is the right place for the docs on embedding, though.

In fact, I almost want to argue that having documentation for end users is an anti-pattern - it would mean the UI is poorly designed and non-intuitive.

I don't see how having documentation means the UI is poorly designed and non-intuitive. For instance, Gmail has docs and I'd say it's very easy to use. Same with GitHub.

As an aside: I think there is very little likelihood that documentation would make up for a confusing UI, so I don't see docs as running the risk of enabling a bad UI.

End users may need a tutorial mode in the UI that walks them through the UI elements.

I'd say step-by-step guides in the UI would be great for introducing features but unmanageable for a full tutorial or introduction to the UI. For that, I think taking inspiration from something like this Chrome overview would be great.

I think both configuration and embedding are part of the UI deployment story

Seems like integrating the UI into another product is not a sub-topic of deploying Jaeger. For instance, the Studio team (a reference internal to Uber) doesn't need to know anything about deploying Jaeger if they only plan to embed it.

@aljesusg, you're consuming the embed functionality, are you also involved in deploying Jaeger?

aljesusg · 2019-01-02T11:10:47Z

no @tiffon, only consuming from Kiali project

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

aljesusg · 2019-01-02T11:20:32Z

I moved the docs to deployment @yurishkuro https://deploy-preview-185--jaegertracing.netlify.com/docs/next-release/deployment/#frontend-ui but I think that we should add the index to the frontend docs like the deployment, I saw that in client features is disable but I think that we have so information in the UI docs. What do you think?

yurishkuro · 2019-01-02T18:23:15Z

content/docs/next-release/deployment.md

----- | -------  | ---
-16686 | HTTP     | **/api/*** endpoints and Jaeger UI at **/**
-16687 | HTTP     | Health check at **/**
-


I think text up to here should remain in the Deployment, with the same title "Query Service & UI". The new page is only about the UI configuration.

renamed thanks

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

yurishkuro · 2019-01-03T17:21:40Z

content/docs/next-release/frontend-ui.md

+Port  | Protocol | Function
+----- | -------  | ---
+16686 | HTTP     | **/api/*** endpoints and Jaeger UI at **/**
+16687 | HTTP     | Health check at **/**


please don't remove this section above from the deployment doc. It refers to query-service, a microservice in Jaeger, and logically belongs to deployment. The rest of this doc refers to customization / configuration of the UI.

Changed, sorry but I didn't not understand correctly

I added a commit with the change that I wanted.

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

Signed-off-by: Yuri Shkuro <ys@uber.com>

yurishkuro

Is this ready to be merged? Are the images final?

aljesusg · 2019-01-04T09:15:48Z

Yes, the images are final from @tiffon PR with the last changes

yurishkuro · 2019-01-04T13:09:38Z

thanks!

aljesusg · 2019-01-04T13:50:46Z

Thanks @yurishkuro & @tiffon

aljesusg added 2 commits December 12, 2018 09:32

Add UI docs

8de3085

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

Rename to Frontend/UI

5e95f7f

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

aljesusg force-pushed the embed_feature branch from 4578c3a to 5e95f7f Compare December 12, 2018 08:35

aljesusg changed the title ~~WIP Add UI docs~~ Add UI docs Dec 12, 2018

tiffon suggested changes Dec 18, 2018

View reviewed changes

aljesusg force-pushed the embed_feature branch from f588cf6 to 67f49ba Compare December 18, 2018 14:34

Comments addresed

8adf7a8

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

aljesusg force-pushed the embed_feature branch from 67f49ba to 8adf7a8 Compare December 18, 2018 14:38

Crop header in img

73a2e06

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

tiffon approved these changes Dec 20, 2018

View reviewed changes

Moved frontend ui docs to deployment section

dd9c0db

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

yurishkuro reviewed Jan 2, 2019

View reviewed changes

rename title to query service & ui

0f5409c

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

yurishkuro reviewed Jan 3, 2019

View reviewed changes

comments addresed

8179a0c

Signed-off-by: Alberto Gutierrez <aljesusg@gmail.com>

aljesusg force-pushed the embed_feature branch from de422d2 to 8179a0c Compare January 3, 2019 17:29

Rearrange the docs, fix formatting

8249577

Signed-off-by: Yuri Shkuro <ys@uber.com>

ghost assigned yurishkuro Jan 4, 2019

ghost added the review label Jan 4, 2019

yurishkuro approved these changes Jan 4, 2019

View reviewed changes

yurishkuro merged commit eb3e259 into jaegertracing:master Jan 4, 2019

ghost removed the review label Jan 4, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add UI docs #185

Add UI docs #185

aljesusg commented Dec 4, 2018 •

edited

Loading

aljesusg commented Dec 4, 2018 •

edited

Loading

yurishkuro commented Dec 11, 2018

tiffon left a comment

tiffon Dec 17, 2018

aljesusg Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018

tiffon Dec 18, 2018 •

edited

Loading

aljesusg commented Dec 18, 2018

tiffon commented Dec 20, 2018

aljesusg commented Dec 20, 2018

yurishkuro commented Dec 21, 2018

aljesusg commented Dec 22, 2018

tiffon commented Dec 22, 2018 via email

aljesusg commented Dec 24, 2018

yurishkuro commented Dec 24, 2018 •

edited

Loading

tiffon commented Dec 30, 2018

aljesusg commented Jan 2, 2019

aljesusg commented Jan 2, 2019

yurishkuro Jan 2, 2019

aljesusg Jan 3, 2019 •

edited

Loading

yurishkuro Jan 3, 2019

aljesusg Jan 3, 2019

yurishkuro Jan 4, 2019

yurishkuro left a comment

aljesusg commented Jan 4, 2019

yurishkuro commented Jan 4, 2019

aljesusg commented Jan 4, 2019


		## Embed Mode

		Enhancement to embed mode in Jaeger UI for some components allowing us to integrate it into other applications.


		##### Optionally

		We can use an extra options in the embed mode :


		![Embed Search Traces](/img/frontend-ui/embed-search-traces.png)

		We have a button in this kind of view that redirect us to the search traces page in the Jaeger Site <img src="/img/frontend-ui/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.


		![Embed Trace view](/img/frontend-ui/embed-trace-view-with-back-button.png)

		We have a new button in this kind of view that redirect us to the trace page in the Jaeger Site <img src="/img/interface/embed-open-icon.png" style="width: 20px; height:20px; display:inline;" alt="Embed open window">.

Add UI docs #185

Add UI docs #185

Conversation

aljesusg commented Dec 4, 2018 • edited Loading

aljesusg commented Dec 4, 2018 • edited Loading

yurishkuro commented Dec 11, 2018

tiffon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tiffon Dec 18, 2018 • edited Loading

Choose a reason for hiding this comment

aljesusg commented Dec 18, 2018

tiffon commented Dec 20, 2018

aljesusg commented Dec 20, 2018

yurishkuro commented Dec 21, 2018

aljesusg commented Dec 22, 2018

tiffon commented Dec 22, 2018 via email

aljesusg commented Dec 24, 2018

yurishkuro commented Dec 24, 2018 • edited Loading

tiffon commented Dec 30, 2018

aljesusg commented Jan 2, 2019

aljesusg commented Jan 2, 2019

Choose a reason for hiding this comment

aljesusg Jan 3, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yurishkuro left a comment

Choose a reason for hiding this comment

aljesusg commented Jan 4, 2019

yurishkuro commented Jan 4, 2019

aljesusg commented Jan 4, 2019

aljesusg commented Dec 4, 2018 •

edited

Loading

aljesusg commented Dec 4, 2018 •

edited

Loading

tiffon Dec 18, 2018 •

edited

Loading

yurishkuro commented Dec 24, 2018 •

edited

Loading

aljesusg Jan 3, 2019 •

edited

Loading