How does my XY Chart look?

[esnible]

I am a Jsonnet novice and this is my first time using Grafonnet.

I am attaching a version of my Grafonnet. Please let me know if I am abusing concepts such as + vs .. I request a style review.
Is this what Grafonnet to create an XYChart should look like?

• I was unable to define my data source with type safety. I had hoped to both create and use the data source but failed.
• I found many TODOs in https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md which made it hard to understand parameter types.
• I struggled to know when to use with... as part of Grafonnet field names.
• Should be defining my own functions such as json_field() or finding them in Grafonnet's libsonnet?

Here is my current version:

// Import https://grafana.github.io/grafonnet/API
local g = import 'g.libsonnet';

// Create an alias for the xyChart, to save typing
// See https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md
local xyChart = g.panel.xyChart;

// A JSON API field.  language is jsonpath|jsonata.  Name is what to call it on a chart.
local json_field(jsonPath, language="jsonpath", name="") = {
    "jsonPath": jsonPath,
    "language": language,
    "name": name
};

local dashboard = g.dashboard.withPanels([

  // See https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md
  xyChart.new('My XY Chart')

  // Grafonnet doesn't yet define the JSON datasource, create UID manually later
  + xyChart.withDatasource({
        "type": "marcusolsson-json-datasource",
        "uid": "<TODO>"
  })

  // Configure the XY Chart
  + xyChart.withFieldConfig(
    xyChart.fieldConfig.defaults.withCustom(
        xyChart.options.series.withAxisCenteredZero(false)
        + xyChart.options.series.withAxisColorMode("text")
        + xyChart.options.series.withAxisLabel("")
        + xyChart.options.series.withAxisPlacement("auto")
        + xyChart.options.series.withHideFrom({
              "legend": false,
              "tooltip": false,
              "viz": false
            })
        + xyChart.options.series.scaleDistribution.withType("linear")
        + xyChart.options.series.withShow("points")
    )
  )
  // Our target is a marcusolsson-json-datasource, we have no Grafonnet for that;
  // use a combo of JSON and our own functions.
  + xyChart.queryOptions.withTargets([
          {
          "cacheDurationSeconds": 300,
          "datasource": {
            "type": "marcusolsson-json-datasource",
            // "uid": "<TODO>"
          },
          "fields": [
            json_field("$.items[*].name"),
            json_field("$.items[*].myX", name="MyX"),
            json_field("$.items[*].myY", name="MyY"),
            json_field("$.items[*].severity"),
            json_field("$.items[*].riskScore"),
            json_field("$.items[*].latest"),
          ],
          "method": "GET",
          "queryParams": "",
          "refId": "A",
          "urlPath": ""
        }
])
  + xyChart.standardOptions.color.withMode("continuous-BlYlRd")
  + xyChart.standardOptions.tresholds.withMode("absolute")
  + xyChart.standardOptions.tresholds.withSteps([
              { "color": "green", "value": null },
              { "color": "#EAB839", "value": 50 },
              { "color": "red", "value": 75 }
  ])
  + xyChart.options.legend.withDisplayMode('list')
  + xyChart.options.legend.withPlacement("bottom")
  + xyChart.options.legend.withShowLegend(true)
  + xyChart.options.dims.withExclude('riskScore')
  + xyChart.options.withSeries([
    xyChart.options.series.pointColor.withField("severity")
    + xyChart.options.series.pointSize.withField("riskScore")
      + xyChart.options.series.pointSize.withFixed(50.5)
      + xyChart.options.series.pointSize.withMax(23)
      + xyChart.options.series.pointSize.withMin(4)
    + xyChart.options.series.withX("MyX")
    + xyChart.options.series.withY("MyY")
  ])
  + xyChart.options.withSeriesMapping("manual")
  + xyChart.options.withTooltip({ "mode": "single", "sort": "none" })
  + xyChart.gridPos.withW(12)
  + xyChart.gridPos.withH(8)
  + xyChart.gridPos.withX(0)
  + xyChart.gridPos.withY(0),
]);

dashboard

[Duologic]

I was unable to define my data source with type safety. I had hoped to both create and use the data source but failed.

Jsonnet is a dynamic language, by default it does not provide type safety.

However, I've been looking into parameter validation a little while ago, it would allow us to validate the input of the functions against the JSON schema. This is promising but very early and immature, I plan to test it in smaller projects first. There is no timeline to implement this in Grafonnet.

I found many TODOs in https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md which made it hard to understand parameter types.

The docstrings are coming from the upstream schema, the developers in grafana/grafana have a lot on their plate and the TODOs originate from the code there. It'll come eventually. Also note the experimental notice on the README, meaning this is still a best-effort at this point.

I struggled to know when to use with... as part of Grafonnet field names.

Most functions will start with with..., see the docs. We just rendered the library with support for the language server, installing this in your IDE might help find the right functions.

Should be defining my own functions such as json_field() or finding them in Grafonnet's libsonnet?

I'm not sure what json_field is, is that specific to xyChart? I don't know that plugin but if so, the schema for xyChart may not be complete, meaning that Grafonnet can't know about it either.

[esnible]

I am not criticizing Grafonnet. It is great! I used it last week to create a 29,000-line JSON dashboard from a 600 line description.

By type safety I meant runtime type safety.

It might be easy to improve the documentation. For example, https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md#fn-optionsserieswithscaledistribution shows the complete documentation of withScaleDistribution(value) as "TODO docs"

It would be very handy to have docs also say "See https://github.com/grafana/grok/blob/main/jsonnet/v10.0.0/kinds/composable/xychart/panelcfg/x/xychart_types_gen.json#L225"

The Grok knows its a string. It knows that string has four possible values. A link to the Grok json or even an HTML rendering of the type and enum values would be helpful -- even if extensive documentation was provided in the description field by the Grafana devs.

As a Grafana user, I've seen the UI which gives "Linear", "Logarithmic", and "Symlog" for this setting. The Grok has "linear", "log", "ordinal", and "symlog". A new Grafonnet developer struggles to understand this. I will check out the language server support.

[Duologic]

Interesting, enums should show up in the docs as "Accepted values for ...". This is a bug.

[Duologic]

Ah, here it is, it's a property of the scaleDistrubution called 'type': https://github.com/grafana/grafonnet/blob/main/docs/API/panel/xyChart/index.md#fn-optionsseriesscaledistributionwithtype

[Duologic]

We've been working on the docs and now the type information for function arguments gets surfaced a bit better, have a look here: https://grafana.github.io/grafonnet/API/panel/xyChart/options/series.html#fn-scaledistributionwithtype