[WIP] TSP description, vision and guidelines #91

frallax · 2023-04-04T08:47:49Z

My interpretation of the TSP. A tentative description of what it is, what it aims to accomplish and the use cases it aims to solve.

Some initial guidelines to follow when extending the TSP to accomodate new use cases.

abhinava-ericsson · 2023-04-04T19:10:20Z

README.md

+
+The TSP is a RESTful API on top of the HTTP protocol that enables to:
+
+- analyze time series data (e.g. traces and logs);


I think this has been one of the biggest sources of contention:
Is it:

"Analyze time series data (e.g. traces and logs)"
or

"Analyze computational trace and log data (E.g. CPU traces, GPU traces, software logs etc.)"

This will decide what is "domain-specific" (i.e. are Traces/Logs themselves a domain or are GPU traces a domain). Since tsp and the viewer can't be made directly aware of anything domain specific, this choice will dictate the kind of explicit end-points and parameters we can have, v/s, what we need to pass only implicitly as optional embedded parameters.

The choice is also important because if we

Choose 1:
a) tsp will be have the potential to be used in analyzing non trace data. e.g. financial data.
b) We may end up making it difficult (if not impossible) to support some specific trace use case (especially if the use case doesn't fall under draw and navigate chart category)
c) We can defer making the choice 2 later, when we actually find such a use case. But we probably would want to rethink the tsp architecture anyway at that point to reduce complexity.

Choose 2:
a) At some point, probably soon enough, we will end up taking a decision about tsp architecture, which will disallow Choice 1 in the future.
b) If trace analysis and visualization indeed is limited to draw and navigate chart, we may end up over specializing tsp for known trace types.

The goal of the TSP was to show analysis results of the analysis of traces and logs coming from different sources (HW, SW, network) and different layers in applications. They have all in common that they contain events (time-ordered) that have a timestamp and a payload. The payload is domain specific and hence it can contain all kinds of information pertinent to the domain. The TSP doesn't have any restrictions on what the payload has to be.

The TSP provides analysis results in data structures provided by trace server back-ends that do the computations and know about the domain they are analyzing. The data structures of analysis results are like UI models that can easily serialized and visualized. Hence there are data structures for tables, trees, xy-charts, time-graphs (gantt-chart). Since it handles time series many data structures have a common time axis. But it's not limited to that. It can have other x-axis to show other results (distribution charts). It can have tables for summary information like computation statistics.

Because of the nature of time series, time stamps, time ranges have some important role in the TSP.

CPUs, GPUs, processes etc. are specific to the trace data and the back-end implementation that analyses time series data. If these concepts were added into the TSP specification, then we might end up having to add other "concepts" for other use cases (network, spans, and so on).

I think CPU, GPUs, processes should be abstracted in the trace data by using common identifiers that are associated with a given chart element. For example a row can have CPU identifier (key) and a value, an trace event will have a CPU field shown in a table column. With this a trace event can be correlated with a row in another graph.

My interpretation of the TSP. A tentative description of what it is, what it aims to accomplish and the use cases it aims to solve. Some initial guidelines to follow when extending the TSP to accomodate new use cases.

bhufmann · 2023-04-10T14:46:26Z

I haven't had a chance to comment on this PR. I'll provide my feedback in the coming days.

bhufmann

Thanks for this update. I think many things are inline with the current version of the TSP.

One thing is not clear how to enable custom behaviors in the client implementation through the TSP without the client "knowing" what the domain it is that is visualized.

One other thing is not handled in the TSP is how to add customization of the server, e.g. create user defined views through some input definition. Not sure if that is part of the scope of this PR.

bhufmann · 2023-04-05T13:46:15Z

README.md

+## About, why and goals of the TSP:
+
+Similarly to the philosophy behind the Language Server Protocol (LSP),
+the TSP is an open, HTTP-based protocol for use between *analytics or


LSP is a protocol based on json-rpc but it's not HTTP based. On contrary the TSP is a HTTP-based protocol. Please correct.

The idea of TSP comes from the LSP though, in respect of having the domain specific logic on the server side and the TSP transports the relevant data to a client. With that, client implementations can be exchanged as well as sever implementations, as long as they implement the TSP.

bhufmann · 2023-04-05T13:48:28Z

README.md

+
+## What the TSP is:
+
+The TSP is a RESTful API on top of the HTTP protocol that enables to:


It's not RESTFul, even if the initial idea was to have a RESTful API. I suggest to change it to Cloud-API. I have used that term in recent presentation at EclipseCon 2023. I have also seen that term for other applications.

bhufmann · 2023-05-08T17:06:57Z

README.md


 The specification is currently written in **OpenAPI 3.0** and can be pretty-visualized in the [github pages][tspGhPages].

 **👋 Want to help?** Read our [contributor guide][contributing].

+## About, why and goals of the TSP:
+
+Similarly to the philosophy behind the Language Server Protocol (LSP),


"Similarly to the Language Server Protocol (LSP)" instead of "Similarly to the philosophy behind the Language Server Protocol (LSP)"

bhufmann · 2023-05-08T17:08:49Z

README.md

-
-This protocol is built to decouple the backend and frontend of trace analysers, allowing traces to reside and be analysed on the backend, and visual models to be exchanged with a variety of clients.
-
-The protocol is meant to be RESTful, over HTTP.


I agree to remove this sentence since the protocol is not fully RESTful. I commented more below.

bhufmann · 2023-05-08T17:10:14Z

README.md

@@ -1,15 +1,105 @@
 # trace-server-protocol

-Specification of the Trace Server Protocol
-
-This protocol is built to decouple the backend and frontend of trace analysers, allowing traces to reside and be analysed on the backend, and visual models to be exchanged with a variety of clients.


I actually like this sentence. It describes what the idea of the protocol is as well as the separation of front-end and back-end and their responsibilities.

bhufmann · 2023-05-10T18:38:43Z

TSP-examples.md

+     "end": 222222222,
+     "nbTimes": 1982}, 
+   "requested_intervals": 
+        [ThreadA*,FunctionB*,BankTransactionC*]


The proposed solution for that is to provide a filter data structure to the back-end which will be applied when querying data from the back-end (here states).

bhufmann · 2023-05-10T18:40:34Z

TSP-examples.md

+}
+```
+
+## Filter states (a.k.a. intervals) of the chart with fullsearch


Yeah, we are still struggling with this. The reason why there is a full search is for performance reasons. Having to search the whole data set can be slow. So, it's proposed to allow for query only sampled data instead of the whole data set in the requested interval.

bhufmann · 2023-05-10T18:42:27Z

TSP-examples.md

+  {"requested_timerange": 
+    {"start": 111111111,
+     "end": 222222222,
+     "nbTimes": inf}, // or "max", however give the idea that we are trying to get all possible samples


we still need to have the actual number of states to be returned here. We still want to have one single state per time, but the type of state might change that is returned for a given time after applying the filter.

Hence we need another parameter to indicate full (deep or inf) search.

bhufmann · 2023-05-10T18:48:37Z

TSP-examples.md

+```
+cli (ask): GET tsp/api/experiments/{expUUID}/outputs/<chart-type>/<chart-id>/tree
+           {"parameters":{"table_row": 1, "table_col":1]}}
+srv (ret): {"data":[{"start": 1234, "end": 2345, "label": "ThreadA"}]}


So, this is an on-demand query of the min or max duration which would be ok. The front-end would need to be instructed in some way when and when not to fetch this on-demand information. With your suggestion, a column with header 'Max' or 'Min' would have a special meaning and would instruct the client implementation to ask for the min and max duration.

What is currently, implemented is that a data provider for such a tree can have columns of type "Time Range". This indicates that the cells have time range data in a special format that can be parsed as start and end time. How would you indicate to the client implementation to provide the UI action as well as do the remote call?

The introducing of Time Range data type can be re-used in other places. Any "Time Range" values can be used to "Select", "zoom" or "navigate" to.

Both solutions are valid.

bhufmann · 2023-05-10T18:53:40Z

TSP-examples.md

+```
+cli (ask): POST tsp/api/experiments/{expUUID}/outputs/<chart-type>
+           {"parameters":{"outputId/chart-id":"my.custom.chart", "include":[{"Device": "CPU0"},...]}}
+```


Right now the API of the virtual table sends the column IDs to the back-end (requested-items) to request only certain columns to be returned. For data-tree tables, I think it's not possible to remove columns in the back-end call.

To show a new table instead of updating the existing is the client implementation choice. Both options could be provided.

marco-miller requested a review from bhufmann April 4, 2023 17:01

abhinava-ericsson reviewed Apr 4, 2023

View reviewed changes

[WIP] TSP description, vision and guidelines

28d304f

My interpretation of the TSP. A tentative description of what it is, what it aims to accomplish and the use cases it aims to solve. Some initial guidelines to follow when extending the TSP to accomodate new use cases.

frallax force-pushed the tsp-vision-fx branch from 62151ab to 28d304f Compare April 10, 2023 14:37

bhufmann requested changes May 10, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] TSP description, vision and guidelines #91

[WIP] TSP description, vision and guidelines #91

frallax commented Apr 4, 2023

abhinava-ericsson Apr 4, 2023 •

edited

Loading

bhufmann May 8, 2023

bhufmann commented Apr 10, 2023

bhufmann left a comment

bhufmann Apr 5, 2023

bhufmann Apr 5, 2023

bhufmann May 8, 2023

bhufmann May 8, 2023

bhufmann May 8, 2023

bhufmann May 10, 2023

bhufmann May 10, 2023

bhufmann May 10, 2023

bhufmann May 10, 2023

bhufmann May 10, 2023


		The TSP is a RESTful API on top of the HTTP protocol that enables to:

		- analyze time series data (e.g. traces and logs);


		## What the TSP is:

		The TSP is a RESTful API on top of the HTTP protocol that enables to:


		This protocol is built to decouple the backend and frontend of trace analysers, allowing traces to reside and be analysed on the backend, and visual models to be exchanged with a variety of clients.

		The protocol is meant to be RESTful, over HTTP.

[WIP] TSP description, vision and guidelines #91

Are you sure you want to change the base?

[WIP] TSP description, vision and guidelines #91

Conversation

frallax commented Apr 4, 2023

abhinava-ericsson Apr 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bhufmann commented Apr 10, 2023

bhufmann 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

abhinava-ericsson Apr 4, 2023 •

edited

Loading