[Experimental] Add Endpoint Definitions for zPages

[jajanet]

Note, this is PR to the experimental folder and is not blocking the GA timeline.

This PR starts defining expected data types to be returned from zPages URL endpoints.

Other small changes include:

• linking parts of the spec
• adding key words (e.g. SHOULD, MUST)
• general cleanup of wording/grammar
• adding more small details

Related PR: #767

@SergeyKanzhelev

[SergeyKanzhelev]

I am still somewhat confused as to what the proposal actually is so bare with me if the following is not a correct understanding.

So, if I understand correctly the proposal is to use client-side rendering, which requires a Javascript-enabled client to fetch the data via a call to a JSON endpoint, then render the data into the static html template that is returned earlier by the server.

If the client is not Javascript-capable then they have no way to get an html rendering of the page. The best they get is to fetch purely the data from the JSON endpoint. This is nice for machines, but not so nice for humans if they are using a non JS-enabled browser for whatever reason (it is probably very rare but I can imagine that this may be needed in some cases when the troubleshooting is happening in a limited environment where there is no full-blown browser available.

I wonder if we really want to do this and not do a server-side html rendering instead (in addition to having a data-only JSON endpoint).

Client-side rendering also likely means we need to do the development of the rendering bits (the html template, the Javascript that will fetch and render the data) in a centralized manner and then ask language SDKs to use it in addition to likely mandating language SDKs to server zPage content files (the html, css and js) in a strictly standardized manner (the file names and relative urls need to be the same, etc). The alternate, where each language SDK does this independently is likely not doable since language SDK maintainers do not necessary have the necessary client-side web development experience.

I am not quite sure this is a desirable approach and would like to hear what others think about it.

Server side rendering will require a lot of code re-implementation in different languages and pages would be harder to use as they will be limited to html-only. I think some feedback from @yurishkuro was that perhaps OpenTelemetry should only declare JSON protocol and all the visualization can be vendor specific. At least should be easily extendable. I think static html/JS/css + JSON is a nice alternative that makes this proposal both useful and extendable.

Are we OK to push experimental specs with this approach and see if we will hit the major blocker like many non-JS enabled browsers?

[tigrannajaryan]

Are we OK to push experimental specs with this approach and see if we will hit the major blocker like many non-JS enabled browsers?

This definitely makes a lot of sense as an experiment. It would be great to see what it looks like once implemented in one of language SDKs. I keep forgetting we are discussing an experimental addition here :-)

[SergeyKanzhelev]

Are we OK to push experimental specs with this approach and see if we will hit the major blocker like many non-JS enabled browsers?

This definitely makes a lot of sense as an experiment. It would be great to see what it looks like once implemented in one of language SDKs. I keep forgetting we are discussing an experimental addition here :-)

Experimental also means recording open questions or raised concerns. So very valid thing you are bringing, I just want to understand whether it's blocking PR or need to be recorded as a question for future

[tigrannajaryan]

Experimental also means recording open questions or raised concerns. So very valid thing you are bringing, I just want to understand whether it's blocking PR or need to be recorded as a question for future

Not blocking from my perspective. I would actually prefer to see an experiment like this to be able to make a better decision for the final spec.

[jajanet]

Thanks for the feedback, this is a good discussion. I and other active contributors also agree it'd be a good idea to centralize static files, and it's referenced under the shared static files section.

RE: name voting, I'm not sure what we're doing with the poll as a the name suffix has tied votes. This may be a spec/community meeting conversation?

Looking at the Collector zPages, I'm curious about how this relates to the individual language SDK implementations of zPages. I'm guessing that these zPages are separate with different properties, and 1) the sampling may be less granulated and 2) there's more general overhead to export these in terms of memory/calcutions so individual language implementations will still be preferred (?). Perhaps non-JS enabled browsers could use the zPages there, since it seems server-side only there? It's also not immediately clear to me what zPages are being used in the Collector, and there seems to be some different types (servicez, pipelinez).

[tigrannajaryan]

RE: name voting, I'm not sure what we're doing with the poll as a the name suffix has tied votes. This may be a spec/community meeting conversation?

One possible way is to ask a TC member to tiebreak.

[SergeyKanzhelev]

Definitely can help decide with the name.

As for other comments, @jajanet do you think you can finish this PR addressing those? I know your internship is done, do you need any help to get it thru the finish line?

[jajanet]

@SergeyKanzhelev Thanks for being patient with me, I'll wrap it up in the next couple of days and ping you once I'm done! Do you think we should look into the Collector more to see how it applies to language SDKs for zPages? I can make a note of that if so!

[SergeyKanzhelev]

@SergeyKanzhelev Thanks for being patient with me, I'll wrap it up in the next couple of days and ping you once I'm done! Do you think we should look into the Collector more to see how it applies to language SDKs for zPages? I can make a note of that if so!

If you can look into collector, it would be great!

[jajanet]

@SergeyKanzhelev I added changes according to the conversations, let me know if it looks okay! I'll try to look into the Collector, and at the very least we can make note research needs to be done on it somewhere (proposed below).

How does opening a Github issue for the things that need to be addressed sound? If so, we could remove the TODOs mentioned in this file and it add it there as well. Alternatively, we could add these TODOs all in one large TODO at the bottom of the file along with the other TODOs?

General TODOs to include:

• zPages rename
• Look into how the Collector zPages differ from individual SDK implementations, mostly pros and cons and whether they're significantly functionally different or not
• Define the other zPages used in the Collector

TODOs already mentioned within the zpages.md:

• Review endpoint data types for Tracez
• Define other endpoint data types for other zPages
• Define Proxy/shim layer approach

Possible enhancements to add:

• Add pictures and figures
• Add previous design doc links
• Link the Medium zPages article

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[jajanet]

Gentle nudge @SergeyKanzhelev

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.

[bogdandrutu]

Approving since this is experimental

[SergeyKanzhelev]

There are still a few TODOs and clarifications needed. But I will merge this incremental improvement to the docs now