eclipse-cdt-cloud / trace-server-protocol Goto Github PK

There appears to be an inconsistency between the reference trace-server and the openapi specification. The examples below are done using trace-compass-incubator built from commit 4b14d71637df2cedecd48d4287851315418a2d31.

According to the openapi specification, the POST to import a trace is
supposed to look like:

curl -i --header "Content-Type: application/json" --header "Accept: application/json" --request POST --data '{"uri":"/home/<redacted>/builds/tsp-python-client/tracecompass-test-traces/ctf/src/main/resources/context-switches/context-switches-ust"}' http://localhost:8080/tsp/api/traces

But that gives back a response like:

HTTP/1.1 400 Bad Request
Server: Jetty(12.0.9)
Date: Fri, 19 Jul 2024 14:26:12 GMT
Content-Type: text/plain
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: origin, content-type, accept, authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, HEAD
Vary: Accept-Encoding
Content-Length: 443

Unrecognized field "uri" (class org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters), not marked as ignorable (2 known properties: "parameters", "filters"])
 at [Source: REDACTED (`StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION` disabled); line: 1, column: 9] (through reference chain: org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters["uri"])

What you actually need to send is:

curl -i --header "Content-Type: application/json" --header "Accept: application/json" --request POST --data '{"parameters": {"uri":"/home/<redacted>/builds/tsp-python-client/tracecompass-test-traces/ctf/src/main/resources/context-switches/context-switches-ust"}}' http://localhost:8080/tsp/api/traces

Which returns:

HTTP/1.1 200 OK
Server: Jetty(12.0.9)
Date: Fri, 19 Jul 2024 14:28:05 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: origin, content-type, accept, authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, HEAD
Vary: Accept-Encoding
Content-Length: 268

{"name":"context-switches-ust","path":"/home/<redacted>/builds/tsp-python-client/tracecompass-test-traces/ctf/src/main/resources/context-switches/context-switches-ust","UUID":"8f0b3517-e95f-31c5-ba70-ee889f8883c0","nbEvents":0,"start":0,"end":0,"indexingStatus":"CLOSED"}

The openapi specification is missing the wrapping "parameters" object in
the request body schema that the server requires.

The same applies to opening an experiment where this fails with a 400:

curl -i --header "Content-Type: application/json" --header "Accept: application/json" --request POST --data '{"traces":["8f0b3517-e95f-31c5-ba70-ee889f8883c0"], "name": "broken"}' http://localhost:8080/tsp/api/experiments

But this works:

curl -i --header "Content-Type: application/json" --header "Accept: application/json" --request POST --data '{"parameters": {"traces":["8f0b3517-e95f-31c5-ba70-ee889f8883c0"], "name": "broken"}}' http://localhost:8080/tsp/api/experiments

So there are two main issues with the specification here:

1. The request body schema for "putTrace" aka POST to /traces is missing "parameters"
2. The request body schema for "postExperiment" aka POST to /experiments is missing "parameters"

the tsp-typescript-client tries to convert to json any response they get from the server. But some of the error messages, like when putting an invalid trace, return as text strings.

This causes like this in the theia-trace-extension:

Uncaught (in promise) SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data
openTrace tsp-client.ts:55
tryOpen trace-manager.ts:76

We should either:

1- Document all error messages to be json, like {message: string} in the protocol and have the server return them this way

or

2- Have the tsp-typescript-client verify the response code before trying to convert to json and have the consumers do likewise whe processing responses

What do you think?

Right now the TSP specification contains currently supported and used APIs as well as proposed APIs.

• It's not clear what is actually used and supported and what is a proposal.
• Split the TSP yaml description into 2 files:

1. Currently implemented and supported APIs
2. Future, proposed APIs (+ APIs of bullet 1)

• Check if https://github.com/swagger-api/swagger-core can be used to automatically generate 1's.

Trees are useful for showing aggregations and summaries, such as statistics. The TSP currently doesn't have a generic API for such data structure.

Things to consider:

• API for trees with columns.
• API to query column descriptors to describe the table column (name/tooltip)
• Align APIs for trees in timegraph, XY etc.

Having such an action will automatically update the gh-pages branch after each update in master branch. This will make sure that the formatted trace server protocol page on https://theia-ide.github.io/trace-server-protocol/ is in sync with master branch.

Should the labels be returned as a formatted string? Or wouldn't it make more sense to return it as raw data and let the client format them, by giving it a hint using the dataType and unit (like for the axis data).

For large numbers, like sum of time, it would make more sense as the raw data can be used for sorting, but we can still visualize them in human friendly manner, using the hints. If we decide to go this way, the EntryHeader object will have to be updated to support dataType and units.

What do you think?

The branch gh-pages populates the web-page [1] to provide human readable version of the TSP. After each commit to master master should be automatically merged to gh-pages to avoid manual steps.

[1] https://theia-ide.github.io/trace-server-protocol/

The trace-server (built from incubator
4b14d71637df2cedecd48d4287851315418a2d31) returns XY model data which
is inconsistent with the openapi specification.

The XY endpoint to fetch the model
(https://localhost:8080/tsp/api/experiments/{expUUID}/outputs/XY/{outputId}/xy)
lists in its response schema that yValues is an array of int64, but
the actual values returned by the trace-server are encoded as doubles.

In org.eclipse.tracecompass.incubator, the series is serialized by
SeriesModelSerializer.java which takes in an ISeriesModel and
writes its data to JSON. The relevant part is:

public void serialize(ISeriesModel value, ...)
    ...
    gen.writeObjectField("yValues", value.getData())
    ...

getData is defined by the interface ISeriesModel as:

/**
 * Get the y values
 *
 * @return An array of y values
 */
double[] getData();

A consumer following the specification will attempt to parse the
yValues as an int64 and either fail or truncate the values.

Example of a series:

{
  "seriesId": 2,
  "seriesName": "2",
  "xValues": [
    28170745093,
    28180756897,
    28190770283,
    28200779146,
    28201221406,
    28211228374
  ],
  "yValues": [
    10913.0,
    12613.0,
    12177.0,
    12455.0,
    14821.0,
    17925.0
  ],
  "style": {
    "parentKey": null,
    "values": {
      "series-type": "scatter"
    }
  }
},

To me it makes sense that the yValues should listed as doubles in
the openapi specification, and that that's where the issue lies.

diff --git a/API.yaml b/API.yaml
index af1ee4c..5c36fa4 100644
--- a/API.yaml
+++ b/API.yaml
@@ -2246,8 +2246,8 @@ components:
           type: array
           description: Series' Y values
           items:
-            type: integer
-            format: int64
+            type: number
+            format: double
       description: This model includes the series output style values.
     XYModel:
       required:

Right now the parentId in the EntryModel is specified as optional and if not present it means that the Entry doesn't have a parent. Being optional has the advantage that it only has to be transported if there is a parent.

In the Trace Compass server reference implementation the parentId is always serialized and value -1 is used to indicate that there is no parent. The theia-trace-extension front-end was aligned to the undocumented special value and handling for value -1.

This tracker is to decide on the wanted specification for the parentId field.

Right now the API for trees in time graph chart, tree xy charts, generic trees (see #19) and virtual table are not aligned. This issues is to track the effort to align and generalize such APIs.

• What is a gap state?
• How and when they are supposed to created in the server?
• How they are supposed to be used in the client?
• If they are optional or mandatory? (should be optional, right?)
• What happens if they are absent?

The trace-server (built from incubator 4b14d71637df2cedecd48d4287851315418a2d31) is inconsistent with the openapi specification with regards to the format of OutputElementStyle.

OutputElementStyle is defined in the openapi specification as follows:

OutputElementStyle:
  type: object
  properties:
    parentKey:
      type: string
    values:
      type: object
      additionalProperties:
        type: object

This matches an example JSON like:

"style": {
  "parentKey": "mykey",
  "values": {
    "value0": {"type": 12},
    "value1": {"color": "blue"}
  }
}

What the server actually responds with (xy model for HistogramDataProvider) is JSON like:

"style": {
  "parentKey": null,
  "values": {
    "series-type": "line"
  }
}

or (from latency analysis I believe):

"style": {
  "parentKey": null,
  "values": {
    "series-type": "scatter"
  }
}

Notice how the keys of "values" point to strings and not to objects.

I think the underlying issue is because the openapi specification (and
implementation of OutputElementStyle) is defined in Java as:

public interface OutputElementStyle {
    ...
    Map<String, Object> getValues();
    ...

The Java notion of an Object can mean a lot of things, but a JSON
notion of an Object is more specific and does not include strings.

It appears the values of an OutputElementStyle should rather be
defined as any type. See free-form objects in:
https://swagger.io/docs/specification/data-models/dictionaries/

diff --git a/API.yaml b/API.yaml
index af1ee4c..1060590 100644
--- a/API.yaml
+++ b/API.yaml
@@ -1605,7 +1605,6 @@ components:
         values:
           type: object
           additionalProperties:
-            type: object
             description: Style values or empty map if there are no values. Keys and
               values are defined in https://git.eclipse.org/r/plugins/gitiles/tracecompass/org.eclipse.tracecompass/+/refs/heads/master/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/model/StyleProperties.java
           description: Style values or empty map if there are no values. Keys and

PUT for experiments command should not use actions in payload (see below). To add or remove traces provide a list of traces UUIDs in the payload and the server needs to validate whether traces need to be added or removed from the experiment by comparing the lists of traces on the server and in the command

This endpoint can be used to close the experiment and upon reception of the message, the server can dispose can dispose allocated resources. The Trace Compass server will dispose the experiments and close all state system and index files.

Use PUT for this, because sending this message multiple times will have the same outcome. The api should look as follows.

/tsp/api/experiments/{expUUID}:close

Use this notation with :close as suffix, will allow to create dedicated actions for different behaviours, like deleting trace indexes (e.g. delete supplementary files of Trace Compass server, rename, copy etc)

It would be interesting to get trace specific one shot data,

e.g. :

• Host Name
• CPU architecture (number of cores/bigLITTLE?)
• System Memory
• GPUs available (number of compute cores?)
• Network config
• Storage config
• Program being traced, if known
• Anything immutable on a given trace (on older systems, frequency)

This information can help with Axes ranges as well as giving more context to the user.

the times[] array being passed in the request body should be defined clearly somewhere as well as the rationale of sending a full list instead of start/end/resolution.

The reason being a server may with to erratically poll an element, and this also allows for several punctual unrelated queries to be sent in aggregation.

Quote from the GraphQL webpage:

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools".

It would be interesting to investigate GraphQL for the TSP as alternative to the REST API that is currently be used, to understand the pros and cons when using GraphQL.

Many model objects have an 'tags' attribute (for example XYSeries, LineMode, and others). The types is often and integer int32, in XYSeries, it's an array of int32.

It's probably related to filters, as the Filter tags description says "Tags to be applied on elements that pass this filter".

• The description of the attributes should specify that those tags match the filter tags specified.

• The /filters endpoint should explain the expected mechanic between filters and tags

• Make sure that the types are OK between int or array of ints