From 6ca9e5b440d60bee9607b64677217506a307634b Mon Sep 17 00:00:00 2001 From: Ryan McKinley Date: Sat, 11 Feb 2023 15:25:03 -0800 Subject: [PATCH] Schema: fix dashboard revision docs (#63284) --- .../kinds/core/dashboard/schema-reference.md | 52 +++++++++---------- kinds/dashboard/dashboard_kind.cue | 13 +++-- .../raw/dashboard/x/dashboard_types.gen.ts | 14 +++-- pkg/kinds/dashboard/dashboard_types_gen.go | 16 ++++-- 4 files changed, 55 insertions(+), 40 deletions(-) diff --git a/docs/sources/developers/kinds/core/dashboard/schema-reference.md b/docs/sources/developers/kinds/core/dashboard/schema-reference.md index e5696345969..e638cc6dfee 100644 --- a/docs/sources/developers/kinds/core/dashboard/schema-reference.md +++ b/docs/sources/developers/kinds/core/dashboard/schema-reference.md @@ -13,32 +13,32 @@ title: Dashboard kind A Grafana dashboard. -| Property | Type | Required | Description | -|------------------------|-----------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `editable` | boolean | **Yes** | Whether a dashboard is editable or not. Default: `true`. | -| `graphTooltip` | integer | **Yes** | 0 for no shared crosshair or tooltip (default).
1 for shared crosshair.
2 for shared crosshair AND shared tooltip.
Possible values are: `0`, `1`, `2`. Default: `0`. | -| `revision` | int64 | **Yes** | Version of the current dashboard data Default: `-1`. | -| `schemaVersion` | uint16 | **Yes** | Version of the JSON schema, incremented each time a Grafana update brings
changes to said schema.
TODO this is the existing schema numbering system. It will be replaced by Thema's themaVersion Default: `36`. | -| `style` | string | **Yes** | Theme of dashboard.
Possible values are: `dark`, `light`. Default: `dark`. | -| `annotations` | [object](#annotations) | No | TODO docs | -| `description` | string | No | Description of dashboard. | -| `fiscalYearStartMonth` | integer | No | The month that the fiscal year starts on. 0 = January, 11 = December Default: `0`.
Constraint: `>=0 & <12`. | -| `gnetId` | string | No | | -| `id` | integer | No | Unique numeric identifier for the dashboard.
TODO must isolate or remove identifiers local to a Grafana instance...? | -| `links` | [DashboardLink](#dashboardlink)[] | No | TODO docs | -| `liveNow` | boolean | No | TODO docs | -| `panels` | [object](#panels)[] | No | | -| `refresh` | | No | Refresh rate of dashboard. Represented via interval string, e.g. "5s", "1m", "1h", "1d". | -| `snapshot` | [Snapshot](#snapshot) | No | TODO docs | -| `tags` | string[] | No | Tags associated with dashboard. | -| `templating` | [object](#templating) | No | TODO docs | -| `time` | [object](#time) | No | Time range for dashboard, e.g. last 6 hours, last 7 days, etc | -| `timepicker` | [object](#timepicker) | No | TODO docs
TODO this appears to be spread all over in the frontend. Concepts will likely need tidying in tandem with schema changes | -| `timezone` | string | No | Timezone of dashboard. Accepts IANA TZDB zone ID or "browser" or "utc". Default: `browser`. | -| `title` | string | No | Title of dashboard. | -| `uid` | string | No | Unique dashboard identifier that can be generated by anyone. string (8-40) | -| `version` | uint32 | No | Version of the dashboard, incremented each time the dashboard is updated. | -| `weekStart` | string | No | TODO docs | +| Property | Type | Required | Description | +|------------------------|-----------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `editable` | boolean | **Yes** | Whether a dashboard is editable or not. Default: `true`. | +| `graphTooltip` | integer | **Yes** | 0 for no shared crosshair or tooltip (default).
1 for shared crosshair.
2 for shared crosshair AND shared tooltip.
Possible values are: `0`, `1`, `2`. Default: `0`. | +| `schemaVersion` | uint16 | **Yes** | Version of the JSON schema, incremented each time a Grafana update brings
changes to said schema.
TODO this is the existing schema numbering system. It will be replaced by Thema's themaVersion Default: `36`. | +| `style` | string | **Yes** | Theme of dashboard.
Possible values are: `dark`, `light`. Default: `dark`. | +| `annotations` | [object](#annotations) | No | TODO docs | +| `description` | string | No | Description of dashboard. | +| `fiscalYearStartMonth` | integer | No | The month that the fiscal year starts on. 0 = January, 11 = December Default: `0`.
Constraint: `>=0 & <12`. | +| `gnetId` | string | No | For dashboards imported from the https://grafana.com/grafana/dashboards/ portal | +| `id` | integer | No | Unique numeric identifier for the dashboard.
TODO must isolate or remove identifiers local to a Grafana instance...? | +| `links` | [DashboardLink](#dashboardlink)[] | No | TODO docs | +| `liveNow` | boolean | No | When set to true, the dashboard will redraw panels at an interval matching the pixel width.
This will keep data "moving left" regardless of the query refresh rate. This setting helps
avoid dashboards presenting stale live data | +| `panels` | [object](#panels)[] | No | | +| `refresh` | | No | Refresh rate of dashboard. Represented via interval string, e.g. "5s", "1m", "1h", "1d". | +| `revision` | integer | No | This property should only be used in dashboards defined by plugins. It is a quick check
to see if the version has changed since the last time. Unclear why using the version property
is insufficient. | +| `snapshot` | [Snapshot](#snapshot) | No | TODO docs | +| `tags` | string[] | No | Tags associated with dashboard. | +| `templating` | [object](#templating) | No | TODO docs | +| `time` | [object](#time) | No | Time range for dashboard, e.g. last 6 hours, last 7 days, etc | +| `timepicker` | [object](#timepicker) | No | TODO docs
TODO this appears to be spread all over in the frontend. Concepts will likely need tidying in tandem with schema changes | +| `timezone` | string | No | Timezone of dashboard. Accepts IANA TZDB zone ID or "browser" or "utc". Default: `browser`. | +| `title` | string | No | Title of dashboard. | +| `uid` | string | No | Unique dashboard identifier that can be generated by anyone. string (8-40) | +| `version` | uint32 | No | Version of the dashboard, incremented each time the dashboard is updated. | +| `weekStart` | string | No | TODO docs | ### DashboardLink diff --git a/kinds/dashboard/dashboard_kind.cue b/kinds/dashboard/dashboard_kind.cue index 832c30f0231..f399d9a0d38 100644 --- a/kinds/dashboard/dashboard_kind.cue +++ b/kinds/dashboard/dashboard_kind.cue @@ -24,10 +24,11 @@ lineage: seqs: [ title?: string // Description of dashboard. description?: string - - // Version of the current dashboard data - revision: int64 | *-1 @grafanamaturity(NeedsExpertReview) - + // This property should only be used in dashboards defined by plugins. It is a quick check + // to see if the version has changed since the last time. Unclear why using the version property + // is insufficient. + revision?: int64 @grafanamaturity(NeedsExpertReview) + // For dashboards imported from the https://grafana.com/grafana/dashboards/ portal gnetId?: string @grafanamaturity(NeedsExpertReview) // Tags associated with dashboard. tags?: [...string] @grafanamaturity(NeedsExpertReview) @@ -61,7 +62,9 @@ lineage: seqs: [ } @grafanamaturity(NeedsExpertReview) // The month that the fiscal year starts on. 0 = January, 11 = December fiscalYearStartMonth?: uint8 & <12 | *0 - // TODO docs + // When set to true, the dashboard will redraw panels at an interval matching the pixel width. + // This will keep data "moving left" regardless of the query refresh rate. This setting helps + // avoid dashboards presenting stale live data liveNow?: bool @grafanamaturity(NeedsExpertReview) // TODO docs weekStart?: string @grafanamaturity(NeedsExpertReview) diff --git a/packages/grafana-schema/src/raw/dashboard/x/dashboard_types.gen.ts b/packages/grafana-schema/src/raw/dashboard/x/dashboard_types.gen.ts index 108118c5e95..18e8c544351 100644 --- a/packages/grafana-schema/src/raw/dashboard/x/dashboard_types.gen.ts +++ b/packages/grafana-schema/src/raw/dashboard/x/dashboard_types.gen.ts @@ -673,6 +673,9 @@ export interface Dashboard { * The month that the fiscal year starts on. 0 = January, 11 = December */ fiscalYearStartMonth?: number; + /** + * For dashboards imported from the https://grafana.com/grafana/dashboards/ portal + */ gnetId?: string; /** * Configuration of dashboard cursor sync behavior. @@ -688,7 +691,9 @@ export interface Dashboard { */ links?: Array; /** - * TODO docs + * When set to true, the dashboard will redraw panels at an interval matching the pixel width. + * This will keep data "moving left" regardless of the query refresh rate. This setting helps + * avoid dashboards presenting stale live data */ liveNow?: boolean; panels?: Array<(Panel | RowPanel | GraphPanel | HeatmapPanel)>; @@ -697,9 +702,11 @@ export interface Dashboard { */ refresh?: (string | false); /** - * Version of the current dashboard data + * This property should only be used in dashboards defined by plugins. It is a quick check + * to see if the version has changed since the last time. Unclear why using the version property + * is insufficient. */ - revision: number; + revision?: number; /** * Version of the JSON schema, incremented each time a Grafana update brings * changes to said schema. @@ -827,7 +834,6 @@ export const defaultDashboard: Partial = { graphTooltip: DashboardCursorSync.Off, links: [], panels: [], - revision: -1, schemaVersion: 36, style: 'dark', tags: [], diff --git a/pkg/kinds/dashboard/dashboard_types_gen.go b/pkg/kinds/dashboard/dashboard_types_gen.go index b99076b8c7a..fe038480250 100644 --- a/pkg/kinds/dashboard/dashboard_types_gen.go +++ b/pkg/kinds/dashboard/dashboard_types_gen.go @@ -212,8 +212,10 @@ type Dashboard struct { Editable bool `json:"editable"` // The month that the fiscal year starts on. 0 = January, 11 = December - FiscalYearStartMonth *int `json:"fiscalYearStartMonth,omitempty"` - GnetId *string `json:"gnetId,omitempty"` + FiscalYearStartMonth *int `json:"fiscalYearStartMonth,omitempty"` + + // For dashboards imported from the https://grafana.com/grafana/dashboards/ portal + GnetId *string `json:"gnetId,omitempty"` // 0 for no shared crosshair or tooltip (default). // 1 for shared crosshair. @@ -227,15 +229,19 @@ type Dashboard struct { // TODO docs Links *[]Link `json:"links,omitempty"` - // TODO docs + // When set to true, the dashboard will redraw panels at an interval matching the pixel width. + // This will keep data "moving left" regardless of the query refresh rate. This setting helps + // avoid dashboards presenting stale live data LiveNow *bool `json:"liveNow,omitempty"` Panels *[]interface{} `json:"panels,omitempty"` // Refresh rate of dashboard. Represented via interval string, e.g. "5s", "1m", "1h", "1d". Refresh *interface{} `json:"refresh,omitempty"` - // Version of the current dashboard data - Revision int `json:"revision"` + // This property should only be used in dashboards defined by plugins. It is a quick check + // to see if the version has changed since the last time. Unclear why using the version property + // is insufficient. + Revision *int64 `json:"revision,omitempty"` // Version of the JSON schema, incremented each time a Grafana update brings // changes to said schema.