diff --git a/docs/sources/as-code/observability-as-code/schema-v2/_index.md b/docs/sources/as-code/observability-as-code/schema-v2/_index.md index 9be869a8391..d588d6a3dcb 100644 --- a/docs/sources/as-code/observability-as-code/schema-v2/_index.md +++ b/docs/sources/as-code/observability-as-code/schema-v2/_index.md @@ -15,8 +15,7 @@ labels: title: JSON schema v2 weight: 500 canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/ -aliases: - - ../../observability-as-code/schema-v2/ # /docs/grafana/next/observability-as-code/schema-v2/ +draft: true --- # Dashboard JSON schema v2 diff --git a/docs/sources/as-code/observability-as-code/schema-v2/annotations-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/annotations-schema.md deleted file mode 100644 index e99e7c2cce6..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/annotations-schema.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -description: A reference for the JSON annotations schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - annotations -labels: - products: - - cloud - - enterprise - - oss -menuTitle: annotations schema -title: annotations -weight: 100 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/annotations-schema/ -aliases: - - ../../../observability-as-code/schema-v2/annotations-schema/ # /docs/grafana/next/observability-as-code/schema-v2/annotations-schema/ ---- - -# `annotations` - -The configuration for the list of annotations that are associated with the dashboard. - -```json - "annotations": [ - { - "kind": "AnnotationQuery", - "spec": { - "builtIn": false, - "datasource": { - "type": "", - "uid": "" - }, - "enable": false, - "hide": false, - "iconColor": "", - "name": "" - } - } - ], -``` - -`AnnotationsQueryKind` consists of: - -- kind: "AnnotationQuery" -- spec: [AnnotationQuerySpec](#annotationqueryspec) - -## `AnnotationQuerySpec` - -| Name | Type/Definition | -| ---------- | ----------------------------------------------------------------- | -| datasource | [`DataSourceRef`](#datasourceref) | -| query | [`DataQueryKind`](#dataquerykind) | -| enable | bool | -| hide | bool | -| iconColor | string | -| name | string | -| builtIn | bool. Default is `false`. | -| filter | [`AnnotationPanelFilter`](#annotationpanelfilter) | -| options | `[string]`: A catch-all field for datasource-specific properties. | - -### `DataSourceRef` - -| Name | Usage | -| ----- | ---------------------------------- | -| type? | string. The plugin type-id. | -| uid? | The specific data source instance. | - -### `DataQueryKind` - -| Name | Type | -| ---- | ------ | -| kind | string | -| spec | string | - -### `AnnotationPanelFilter` - -| Name | Type/Definition | -| -------- | ------------------------------------------------------------------------------ | -| exclude? | bool. Should the specified panels be included or excluded. Default is `false`. | -| ids | `[...uint8]`. Panel IDs that should be included or excluded. | diff --git a/docs/sources/as-code/observability-as-code/schema-v2/layout-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/layout-schema.md deleted file mode 100644 index ca31417bbcf..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/layout-schema.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -description: A reference for the JSON layout schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - layout -labels: - products: - - cloud - - enterprise - - oss -menuTitle: layout schema -title: layout -weight: 400 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/layout-schema/ -aliases: - - ../../../observability-as-code/schema-v2/layout-schema/ # /docs/grafana/next/observability-as-code/schema-v2/layout-schema/ ---- - -# `layout` - -There are four layout options offering two types of panel control: - -**Panel layout options** - -These options control the size and position of panels: - -- [GridLayoutKind](#gridlayoutkind) - Corresponds to the **Custom** option in the UI. You define panel size and panel positions using x- and y- settings. -- [AutoGridLayoutKind](#autogridlayoutkind) - Corresponds to the **Auto grid** option in the UI. Panel size and position are automatically set based on column and row parameters. - -**Panel grouping options** - -These options control the grouping of panels: - -- [RowsLayoutKind](#rowslayoutkind) - Groups panels into rows. -- [TabsLayoutKind](#tabslayoutkind) - Groups panels into tabs. - -## `GridLayoutKind` - -The grid layout allows you to manually size and position grid items by setting the height, width, x, and y of each item. -This layout corresponds to the **Custom** option in the UI. - -Following is the JSON for a default grid layout, a grid layout item, and a grid layout row: - -```json - "kind": "GridLayout", - "spec": { - "items": [ - { - "kind": "GridLayoutItem", - "spec": { - "element": {...}, - "height": 0, - "width": 0, - "x": 0, - "y": 0 - } - }, - { - "kind": "GridLayoutRow", - "spec": { - "collapsed": false, - "elements": [], - "title": "", - "y": 0 - } - }, - ] - } -``` - -`GridLayoutKind` consists of: - -- kind: "GridLayout" -- spec: GridLayoutSpec - - items: GridLayoutItemKind` or GridLayoutRowKind` - - GridLayoutItemKind - - kind: "GridLayoutItem" - - spec: [GridLayoutItemSpec](#gridlayoutitemspec) - - GridLayoutRowKind - - kind: "GridLayoutRow" - - spec: [GridLayoutRowSpec](#gridlayoutrowspec) - -### `GridLayoutItemSpec` - -The following table explains the usage of the grid layout item JSON fields: - -| Name | Usage | -| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| x | integer. Position of the item x-axis. | -| y | integer. Position of the item y-axis. | -| width | Width of the item in pixels. | -| height | Height of the item in pixels. | -| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana//observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. | -| repeat? | [RepeatOptions](#repeatoptions). Configured repeat options, if any | - -#### `RepeatOptions` - -The following table explains the usage of the repeat option JSON fields: - -| Name | Usage | -| ---------- | ---------------------------------------------------- | -| mode | `RepeatMode` - "variable" | -| value | string | -| direction? | Options are `h` for horizontal and `v` for vertical. | -| maxPerRow? | integer | - -### `GridLayoutRowSpec` - -The following table explains the usage of the grid layout row JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| y | integer. Position of the row y-axis | -| collapsed | bool. Whether or not the row is collapsed | -| title | Row title | -| elements | [`[...GridLayoutItemKind]`](#gridlayoutitemspec). Grid items in the row will have their y value be relative to the row's y value. This means a panel positioned at `y: 0` in a row with `y: 10` will be positioned at `y: 11` (row header has a height of 1) in the dashboard. | -| repeat? | [RowRepeatOptions](#rowrepeatoptions) Configured row repeat options, if any

| - - - -#### `RowRepeatOptions` - -| Name | Usage | -| ----- | ------------------------- | -| mode | `RepeatMode` - "variable" | -| value | string | - -## `AutoGridLayoutKind` - -With an auto grid, Grafana sizes and positions your panels for the best fit based on the column and row constraints that you set. -This layout corresponds to the **Auto grid** option in the UI. - -Following is the JSON for a default auto grid layout and a grid layout item: - - - -```json - "kind": "AutoGridLayout", - "spec": { - "columnWidthMode": "standard", - "fillScreen": false, - "items": [ - { - "kind": "AutoGridLayoutItem", - "spec": { - "element": {...}, - } - } - ], - "maxColumnCount": 3, - "rowHeightMode": "standard" - } -``` - -`AutoGridLayoutKind` consists of: - -- kind: "AutoGridLayout" -- spec: [AutoGridLayoutSpec](#autogridlayoutspec) - -### `AutoGridLayoutSpec` - -The following table explains the usage of the auto grid layout JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| maxColumnCount? | number. Default is `3`. | -| columnWidthMode | Options are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`. | -| columnWidth? | number | -| rowHeightMode | Options are: `short`, `standard`, `tall`, and `custom`. Default is `standard`. | -| rowHeight? | number | -| fillScreen? | bool. Default is `false`. | -| items | `AutoGridLayoutItemKind`. Consists of: | - - - -#### `AutoGridLayoutItemSpec` - -The following table explains the usage of the auto grid layout item JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana//observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. | -| repeat? | [AutoGridRepeatOptions](#autogridrepeatoptions). Configured repeat options, if any. | -| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: | - - - -##### `AutoGridRepeatOptions` - -The following table explains the usage of the auto grid repeat option JSON fields: - -| Name | Usage | -| ----- | ------------------------- | -| mode | `RepeatMode` - "variable" | -| value | String | - -##### `ConditionalRenderingGroupSpec` - - - -| Name | Usage | -| ---- | ----- | -| visibility | Options are `show` and `hide` | -| condition | Options are `and` and `or` | -| items | Options are: | - - - -###### `ConditionalRenderingVariableSpec` - -| Name | Usage | -| -------- | ------------------------------------ | -| variable | string | -| operator | Options are `equals` and `notEquals` | -| value | string | - -###### `ConditionalRenderingDataSpec` - -| Name | Type | -| ----- | ---- | -| value | bool | - -###### `ConditionalRenderingTimeRangeSizeSpec` - -| Name | Type | -| ----- | ------ | -| value | string | - -## `RowsLayoutKind` - -The `RowsLayoutKind` is one of two options that you can use to group panels. -You can nest any other kind of layout inside a layout row. -Rows can also be nested in auto grids or tabs. - -Following is the JSON for a default rows layout row: - -```json - "kind": "RowsLayout", - "spec": { - "rows": [ - { - "kind": "RowsLayoutRow", - "spec": { - "layout": { - "kind": "GridLayout", // Can also be AutoGridLayout or TabsLayout - "spec": {...} - }, - "title": "" - } - } - ] - } -``` - -`RowsLayoutKind` consists of: - -- kind: RowsLayout -- spec: RowsLayoutSpec - - rows: RowsLayoutRowKind - - kind: RowsLayoutRow - - spec: [RowsLayoutRowSpec](#rowslayoutrowspec) - -### `RowsLayoutRowSpec` - -The following table explains the usage of the rows layout row JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| title? | Title of the row. | -| collapse | bool. Whether or not the row is collapsed. | -| hideHeader? | bool. Whether the row header is hidden or shown. | -| fullScreen? | bool. Whether or not the row takes up the full screen. | -| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing rows, if any. Consists of: | -| repeat? | [RowRepeatOptions](#rowrepeatoptions). Configured repeat options, if any. | -| layout | Supported layouts are: | - - - -## `TabsLayoutKind` - -The `TabsLayoutKind` is one of two options that you can use to group panels. -You can nest any other kind of layout inside a tab. -Tabs can also be nested in auto grids or rows. - -Following is the JSON for a default tabs layout tab and a tab: - -```json - "kind": "TabsLayout", - "spec": { - "tabs": [ - { - "kind": "TabsLayoutTab", - "spec": { - "layout": { - "kind": "GridLayout", // Can also be AutoGridLayout or RowsLayout - "spec": {...} - }, - "title": "New tab" - } - } - ] - } -``` - -`TabsLayoutKind` consists of: - -- kind: TabsLayout - - spec: TabsLayoutSpec - - tabs: TabsLayoutTabKind - - kind: TabsLayoutTab - - spec: [TabsLayoutTabSpec](#tabslayouttabspec) - -### `TabsLayoutTabSpec` - -The following table explains the usage of the tabs layout tab JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| title? | The title of the tab. | -| layout | Supported layouts are: | -| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: | - - diff --git a/docs/sources/as-code/observability-as-code/schema-v2/librarypanel-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/librarypanel-schema.md deleted file mode 100644 index 45715e15b15..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/librarypanel-schema.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: A reference for the JSON library panel schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - library panel -labels: - products: - - cloud - - enterprise - - oss -menuTitle: LibraryPanelKind schema -title: LibraryPanelKind -weight: 300 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/librarypanel-schema/ -aliases: - - ../../../observability-as-code/schema-v2/librarypanel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/librarypanel-schema/ ---- - -# `LibraryPanelKind` - -A library panel is a reusable panel that you can use in any dashboard. -When you make a change to a library panel, that change propagates to all instances of where the panel is used. -Library panels streamline reuse of panels across multiple dashboards. - -Following is the default library panel element JSON: - -```json - "kind": "LibraryPanel", - "spec": { - "id": 0, - "libraryPanel": { - name: "", - uid: "", - } - "title": "" - } -``` - -The `LibraryPanelKind` consists of: - -- kind: "LibraryPanel" -- spec: [LibraryPanelKindSpec](#librarypanelkindspec) - - libraryPanel: [LibraryPanelRef](#librarypanelref) - -## `LibraryPanelKindSpec` - -The following table explains the usage of the library panel element JSON fields: - -| Name | Usage | -| ------------ | ------------------------------------------------ | -| id | Panel ID for the library panel in the dashboard. | -| libraryPanel | [`LibraryPanelRef`](#librarypanelref) | -| title | Title for the library panel in the dashboard. | - -### `LibraryPanelRef` - -The following table explains the usage of the library panel reference JSON fields: - -| Name | Usage | -| ---- | ------------------ | -| name | Library panel name | -| uid | Library panel uid | diff --git a/docs/sources/as-code/observability-as-code/schema-v2/links-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/links-schema.md deleted file mode 100644 index 9598477354f..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/links-schema.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -description: A reference for the JSON links schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - links -labels: - products: - - cloud - - enterprise - - oss -menuTitle: links schema -title: links -weight: 500 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/links-schema/ -aliases: - - ../../../observability-as-code/schema-v2/links-schema/ # /docs/grafana/next/observability-as-code/schema-v2/links-schema/ ---- - -# `links` - -The `links` schema is the configuration for links with references to other dashboards or external websites. -Following are the default JSON fields: - -```json - "links": [ - { - "asDropdown": false, - "icon": "", - "includeVars": false, - "keepTime": false, - "tags": [], - "targetBlank": false, - "title": "", - "tooltip": "", - "type": "link", - }, - ], -``` - -## `DashboardLink` - -The following table explains the usage of the dashboard link JSON fields. -The table includes default and other fields: - - - -| Name | Usage | -| ----------- | --------------------------------------- | -| title | string. Title to display with the link. | -| type | `DashboardLinkType`. Link type. Accepted values are: | -| icon | string. Icon name to be displayed with the link. | -| tooltip | string. Tooltip to display when the user hovers their mouse over it. | -| url? | string. Link URL. Only required/valid if the type is link. | -| tags | string. List of tags to limit the linked dashboards. If empty, all dashboards will be displayed. Only valid if the type is dashboards. | -| asDropdown | bool. If true, all dashboards links will be displayed in a dropdown. If false, all dashboards links will be displayed side by side. Only valid if the type is dashboards. Default is `false`. | -| targetBlank | bool. If true, the link will be opened in a new tab. Default is `false`. | -| includeVars | bool. If true, includes current template variables values in the link as query params. Default is `false`. | -| keepTime | bool. If true, includes current time range in the link as query params. Default is `false`. | - - diff --git a/docs/sources/as-code/observability-as-code/schema-v2/panel-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/panel-schema.md deleted file mode 100644 index 088ab8eebf4..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/panel-schema.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -description: A reference for the JSON panel schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - panels -labels: - products: - - cloud - - enterprise - - oss -menuTitle: PanelKind schema -title: PanelKind -weight: 200 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/panel-schema/ -aliases: - - ../../../observability-as-code/schema-v2/panel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/panel-schema/ ---- - -# `PanelKind` - -The panel element contains all the information about the panel including the visualization type, panel and visualization configuration, queries, and transformations. -There's a panel element for each panel contained in the dashboard. - -Following is the default panel element JSON: - -```json - "kind": "Panel", - "spec": { - "data": { - "kind": "QueryGroup", - "spec": {...}, - "description": "", - "id": 0, - "links": [], - "title": "", - "vizConfig": { - "kind": "", - "spec": {...}, - } - } -``` - -The `PanelKind` consists of: - -- kind: "Panel" -- spec: [PanelSpec](#panelspec) - -## `PanelSpec` - -The following table explains the usage of the panel element JSON fields: - - - -| Name | Usage | -| ------------ | --------------------------------------------------------------------- | -| data | `QueryGroupKind`, which includes queries and transformations. Consists of: | -| description | The panel description. | -| id | The panel ID. | -| links | Links with references to other dashboards or external websites. | -| title | The panel title. | -| vizConfig | `VizConfigKind`. Includes visualization type, field configuration options, and all other visualization options. Consists of: | -| transparent? | bool. Controls whether or not the panel background is transparent. | - - - -### `QueryGroupSpec` - - - -| Name | Usage | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| queries | `PanelQueryKind`. Consists of: | -| transformations | `TransformationKind`. Consists of: | -| queryOptions | [`QueryOptionsSpec`](#queryoptionsspec) | - - - -#### `PanelQuerySpec` - -| Name | Usage | -| ----------- | --------------------------------- | -| query | [`DataQueryKind`](#dataquerykind) | -| datasource? | [`DataSourceRef`](#datasourceref) | - -##### `DataQueryKind` - -| Name | Type | -| ---- | ------ | -| kind | string | -| spec | string | - -##### `DataSourceRef` - -| Name | Usage | -| ----- | ---------------------------------- | -| type? | string. The plugin type-id. | -| uid? | The specific data source instance. | - -#### `DataTransformerConfig` - -Transformations allow you to manipulate data returned by a query before the system applies a visualization. -Using transformations you can: rename fields, join time series data, perform mathematical operations across queries, or use the output of one transformation as the input to another transformation. - - - -| Name | Usage | -| --------- | ------------------------------------------- | -| id | string. Unique identifier of transformer. | -| disabled? | bool. Disabled transformations are skipped. | -| filter? | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. | -| topic? | `DataTopic`. Where to pull `DataFrames` from as input to transformation. Options are: `series`, `annotations`, and `alertStates`. | -| options | Options to be passed to the transformer. Valid options depend on the transformer id. | - - - -##### `MatcherConfig` - -Matcher is a predicate configuration. -Based on the configuration a set of field or values, it's filtered to apply an override or transformation. -It comes with in id (to resolve implementation from registry) and a configuration that’s specific to a particular matcher type. - -| Name | Usage | -| -------- | -------------------------------------------------------------------------------------- | -| id | string. The matcher id. This is used to find the matcher implementation from registry. | -| options? | The matcher options. This is specific to the matcher implementation. | - -#### `QueryOptionsSpec` - -| Name | Type | -| ----------------- | ------- | -| timeFrom? | string | -| maxDataPoints? | integer | -| timeShift? | string | -| queryCachingTTL? | integer | -| interval? | string | -| cacheTimeout? | string | -| hideTimeOverride? | bool | - -### `VizConfigSpec` - -| Name | Type/Definition | -| ------------- | --------------------------------------- | -| pluginVersion | string | -| options | string | -| fieldConfig | [FieldConfigSource](#fieldconfigsource) | - -#### `FieldConfigSource` - -The data model used in Grafana, namely the _data frame_, is a columnar-oriented table structure that unifies both time series and table query results. -Each column within this structure is called a field. -A field can represent a single time series or table column. -Field options allow you to change how the data is displayed in your visualizations. - - - -| Name | Type/Definition | -| ---------- | ------------------------------------- | -| defaults | [`FieldConfig`](#fieldconfig). Defaults are the options applied to all fields. | -| overrides | The options applied to specific fields overriding the defaults. | -| matcher | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. | -| properties | `DynamicConfigValue`. Consists of: | - - - -##### `FieldConfig` - - - -| Name | Type/Definition | -| ------------------ | --------------------------------------- | -| displayName? | string. The display value for this field. This supports template variables where empty is auto. | -| displayNameFromDS? | string. This can be used by data sources that return an explicit naming structure for values and labels. When this property is configured, this value is used rather than the default naming strategy. | -| description? | string. Human readable field metadata. | -| path? | string. An explicit path to the field in the data source. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name}`. When defined, this value can be used as an identifier within the data source scope, and may be used to update the results. | -| writeable? | bool. True if the data source can write a value to the path. Auth/authz are supported separately. | -| filterable? | bool. True if the data source field supports ad-hoc filters. | -| unit? | string. Unit a field should use. The unit you select is applied to all fields except time. You can use the unit's ID available in Grafana or a custom unit. [Available units in Grafana](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/valueFormats/categories.ts). As custom units, you can use the following formats: | -| decimals? | number. Specify the number of decimals Grafana includes in the rendered value. If you leave this field blank, Grafana automatically truncates the number of decimals based on the value. For example 1.1234 will display as 1.12 and 100.456 will display as 100. To display all decimals, set the unit to `string`. | -| min? | number. The minimum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. | -| max? | number. The maximum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. | -| mappings? | `[...ValueMapping]`. Convert input values into a display string. Options are: [`ValueMap`](#valuemap), [`RangeMap`](#rangemap), [`RegexMap`](#rangemap), [`SpecialValueMap`](#specialvaluemap). | -| thresholds? | `ThresholdsConfig`. Map numeric values to states. Consists of: | -| color? | [`FieldColor`](#fieldcolor). Panel color configuration. | -| links? | `[...]`. The behavior when clicking a result. | -| noValue? | string. Alternative to an empty string. | -| custom? | `{...}`. Specified by the `FieldConfig` field in panel plugin schemas. | - - - -###### `ValueMap` - -Maps text values to a color or different display text and color. -For example, you can configure a value mapping so that all instances of the value 10 appear as Perfection! rather than the number. - - - -| Name | Usage | -| ------- | -------- | -| type | `MappingType` & "value". `MappingType` options are: `value`, `range`, `regex`, and `special`. | -| options | string. [`ValueMappingResult`](#valuemappingresult). Map with ``: `ValueMappingResult`. For example: `{ "10": { text: "Perfection!", color: "green" } }`. | - - - -###### `RangeMap` - -Maps numerical ranges to a display text and color. -For example, if a value is within a certain range, you can configure a range value mapping to display Low or High rather than the number. - - - -| Name | Usage | -| ------- | ---------------------------------------------------------------------------------------------------- | -| type | `MappingType` & "range". `MappingType` options are: `value`, `range`, `regex`, and `special`. | -| options | Range to match against and the result to apply when the value is within the range. Spec:
  • `from` - `float64` or `null`. Min value of the range. It can be null which means `-Infinity`.
  • `to` - `float64` or `null`. Max value of the range. It can be null which means `+Infinity`.
  • `result` - [`ValueMappingResult`](#valuemappingresult) | - - - -###### `RegexMap` - -Maps regular expressions to replacement text and a color. -For example, if a value is `www.example.com`, you can configure a regex value mapping so that Grafana displays www and truncates the domain. - - - -| Name | Usage | -| ------- | --------------------------------------------------------------------------------------------- | -| type | `MappingType` & "regex". `MappingType` options are: `value`, `range`, `regex`, and `special`. | -| options | Regular expression to match against and the result to apply when the value matches the regex. Spec:
    • `pattern` - string. Regular expression to match against.
    • `result` - [`ValueMappingResult`](#valuemappingresult) | - - - -###### `SpecialValueMap` - -Maps special values like Null, NaN (not a number), and boolean values like true and false to a display text and color. -See `SpecialValueMatch` in the following table to see the list of special values. -For example, you can configure a special value mapping so that null values appear as N/A. - - - -| Name | Usage | -| ------- | ----------------------------------------------------------------------------------------------- | -| type | `MappingType` & "special". `MappingType` options are: `value`, `range`, `regex`, and `special`. | -| options | Spec:
      • `match` - `SpecialValueMatch`. Special value to match against. Types are:
        • true
        • false
        • null
        • nan
        • empty
      • `result` - [`ValueMappingResult`](#valuemappingresult) | - - - -###### `ValueMappingResult` - -Result used as replacement with text and color when the value matches. - -| Name | Usage | -| ----- | ----------------------------------------------------------------------------- | -| text | string. Text to display when the value matches. | -| color | string. Color to use when the value matches. | -| icon | string. Icon to display when the value matches. Only specific visualizations. | -| index | int32. Position in the mapping array. Only used internally. | - -###### `FieldColor` - -Map a field to a color. - - - -| Name | Usage | -| ----------- | -------------------------------------------------------------------- | -| mode | [`FieldColorModeId`](#fieldcolormodeid). The main color scheme mode. | -| FixedColor? | string. The fixed color value for fixed or shades color modes. | -| seriesBy? | `FieldColorSeriesByMode`. Some visualizations need to know how to assign a series color from by value color schemes. Defines how to assign a series color from "by value" color schemes. For example for an aggregated data points like a timeseries, the color can be assigned by the min, max or last value. Options are: `min`, `max`, and `last`. | - - - -###### `FieldColorModeId` - -Color mode for a field. -You can specify a single color, or select a continuous (gradient) color schemes, based on a value. -Continuous color interpolates a color using the percentage of a value relative to min and max. -Accepted values are: - - - -| Name | Description | -| --- | ---- | -| thresholds | From thresholds. Informs Grafana to take the color from the matching threshold. | -| palette-classic | Classic palette. Grafana will assign color by looking up a color in a palette by series index. Useful for graphs and pie charts and other categorical data visualizations. | -| palette-classic-by-name | Classic palette (by name). Grafana will assign color by looking up a color in a palette by series name. Useful for Graphs and pie charts and other categorical data visualizations | -| continuous-GrYlRd | Continuous Green-Yellow-Red palette mode | -| continuous-RdYlGr | Continuous Red-Yellow-Green palette mode | -| continuous-BlYlRd | Continuous Blue-Yellow-Red palette mode | -| continuous-YlRd | Continuous Yellow-Red palette mode | -| continuous-BlPu | Continuous Blue-Purple palette mode | -| continuous-YlBl | Continuous Yellow-Blue palette mode | -| continuous-blues | Continuous Blue palette mode | -| continuous-reds | Continuous Red palette mode | -| continuous-greens | Continuous Green palette mode | -| continuous-purples | Continuous Purple palette mode | -| shades | Shades of a single color. Specify a single color, useful in an override rule. | -| fixed | Fixed color mode. Specify a single color, useful in an override rule. | - - diff --git a/docs/sources/as-code/observability-as-code/schema-v2/timesettings-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/timesettings-schema.md deleted file mode 100644 index 8db14212740..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/timesettings-schema.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -description: A reference for the JSON timesettings schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - time settings -labels: - products: - - cloud - - enterprise - - oss -menuTitle: timesettings schema -title: timesettings -weight: 600 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/timesettings-schema/ -aliases: - - ../../../observability-as-code/schema-v2/timesettings-schema/ # /docs/grafana/next/observability-as-code/schema-v2/timesettings-schema/ ---- - -# `timeSettings` - -The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard. - -Following is the JSON for default time settings: - -```json - "timeSettings": { - "autoRefresh": "", - "autoRefreshIntervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ], - "fiscalYearStartMonth": 0, - "from": "now-6h", - "hideTimepicker": false, - "timezone": "browser", - "to": "now" - }, -``` - -`timeSettings` consists of: - -- [TimeSettingsSpec](#timesettingsspec) - -## `TimeSettingsSpec` - -The following table explains the usage of the time settings JSON fields: - - - -| Name | Usage | -| ---- | ----- | -| timezone? | string. Timezone of dashboard. Accepted values are IANA TZDB zone ID, `browser`, or `utc`. Default is `browser`. | -| from | string. Start time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now-6h`. | -| to | string. End time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now`. | -| autoRefresh | string. Refresh rate of dashboard. Represented by interval string. For example: `5s`, `1m`, `1h`, `1d`. No default. In schema v1: `refresh`. | -| autoRefreshIntervals | string. Interval options available in the refresh picker drop-down menu. The default array is `["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"]`. | -|quickRanges? | Selectable options available in the time picker drop-down menu. Has no effect on provisioned dashboard. Defined in the [`TimeRangeOption`](#timerangeoption) spec. In schema v1: `timepicker.quick_ranges`, not exposed in the UI. | -| hideTimepicker | bool. Whether or not the time picker is visible. Default is `false`. In schema v1: `timepicker.hidden`. | -| weekStart? | Day when the week starts. Expressed by the name of the day in lowercase. For example: `monday`. Options are `saturday`, `monday`, and `sunday`. | -| fiscalYearStartMonth | The month that the fiscal year starts on. `0` = January, `11` = December | -| nowDelay? | string. Override the "now" time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. In schema v1: `timepicker.nowDelay`. | - - - -### `TimeRangeOption` - -The following table explains the usage of the time range option JSON fields: - -| Name | Usage | -| ------- | ---------------------------------- | -| display | string. Default is `Last 6 hours`. | -| from | string. Default is `now-6h`. | -| to | string. Default is `now`. | diff --git a/docs/sources/as-code/observability-as-code/schema-v2/variables-schema.md b/docs/sources/as-code/observability-as-code/schema-v2/variables-schema.md deleted file mode 100644 index 549478692f1..00000000000 --- a/docs/sources/as-code/observability-as-code/schema-v2/variables-schema.md +++ /dev/null @@ -1,501 +0,0 @@ ---- -description: A reference for the JSON variables schema used with Observability as Code. -keywords: - - configuration - - as code - - as-code - - dashboards - - git integration - - git sync - - github - - variables -labels: - products: - - cloud - - enterprise - - oss -menuTitle: variables schema -title: variables -weight: 700 -canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/variables-schema/ -aliases: - - ../../../observability-as-code/schema-v2/variables-schema/ # /docs/grafana/next/observability-as-code/schema-v2/variables-schema/ ---- - -# `variables` - -The available variable types described in the following sections: - -- [QueryVariableKind](#queryvariablekind) -- [TextVariableKind](#textvariablekind) -- [ConstantVariableKind](#constantvariablekind) -- [DatasourceVariableKind](#datasourcevariablekind) -- [IntervalVariableKind](#intervalvariablekind) -- [CustomVariableKind](#customvariablekind) -- [SwitchVariableKind](#switchvariablekind) -- [GroupByVariableKind](#groupbyvariablekind) -- [AdhocVariableKind](#adhocvariablekind) - -## `QueryVariableKind` - -Following is the JSON for a default query variable: - -```json - "variables": [ - { - "kind": "QueryVariable", - "spec": { - "current": { - "text": "", - "value": "" - }, - "hide": "dontHide", - "includeAll": false, - "multi": false, - "name": "", - "options": [], - "query": defaultDataQueryKind(), - "refresh": "never", - "regex": "", - "skipUrlSync": false, - "sort": "disabled" - } - } - ] -``` - -`QueryVariableKind` consists of: - -- kind: "QueryVariable" -- spec: [QueryVariableSpec](#queryvariablespec) - -### `QueryVariableSpec` - -The following table explains the usage of the query variable JSON fields: - - - -| Name | Usage | -| ------------ | ---------------------------------------------- | -| name | string. Name of the variable. | -| current | "Text" and a "value" or [`VariableOption`](#variableoption) | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | -| datasource? | [`DataSourceRef`](#datasourceref) | -| query | `DataQueryKind`. Consists of:
        • kind: string
        • spec: string
        | -| regex | string | -| sort | `VariableSort`. Options are:
        • disabled
        • alphabeticalAsc
        • alphabeticalDesc
        • numericalAsc
        • numericalDesc
        • alphabeticalCaseInsensitiveAsc
        • alphabeticalCaseInsensitiveDesc
        • naturalAsc
        • naturalDesc
        | -| definition? | string | -| options | [`VariableOption`](#variableoption) | -| multi | bool. Default is `false`. | -| includeAll | bool. Default is `false`. | -| allValue? | string | -| placeholder? | string | - - - -#### `VariableOption` - -| Name | Usage | -| -------- | -------------------------------------------- | -| selected | bool. Whether or not the option is selected. | -| text | string. Text to be displayed for the option. | -| value | string. Value of the option. | - -#### `DataSourceRef` - -| Name | Usage | -| ----- | ---------------------------------- | -| type? | string. The plugin type-id. | -| uid? | The specific data source instance. | - -## `TextVariableKind` - -Following is the JSON for a default text variable: - -```json - "variables": [ - { - "kind": "TextVariable", - "spec": { - "current": { - "text": "", - "value": "" - }, - "hide": "dontHide", - "name": "", - "query": "", - "skipUrlSync": false - } - } - ] -``` - -`TextVariableKind` consists of: - -- kind: TextVariableKind -- spec: [TextVariableSpec](#textvariablespec) - -### `TextVariableSpec` - -The following table explains the usage of the query variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| query | string | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - -## `ConstantVariableKind` - -Following is the JSON for a default constant variable: - -```json - "variables": [ - { - "kind": "ConstantVariable", - "spec": { - "current": { - "text": "", - "value": "" - }, - "hide": "hideVariable", - "name": "", - "query": "", - "skipUrlSync": true - } - } - ] -``` - -`ConstantVariableKind` consists of: - -- kind: "ConstantVariable" -- spec: [ConstantVariableSpec](#constantvariablespec) - -### `ConstantVariableSpec` - -The following table explains the usage of the constant variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| query | string | -| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - -## `DatasourceVariableKind` - -Following is the JSON for a default data source variable: - -```json - "variables": [ - { - "kind": "DatasourceVariable", - "spec": { - "current": { - "text": "", - "value": "" - }, - "hide": "dontHide", - "includeAll": false, - "multi": false, - "name": "", - "options": [], - "pluginId": "", - "refresh": "never", - "regex": "", - "skipUrlSync": false - } - } - ] -``` - -`DatasourceVariableKind` consists of: - -- kind: "DatasourceVariable" -- spec: [DatasourceVariableSpec](#datasourcevariablespec) - -### `DatasourceVariableSpec` - -The following table explains the usage of the data source variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| pluginId | string | -| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. | -| regex | string | -| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| multi | bool. Default is `false`. | -| includeAll | bool. Default is `false`. | -| allValue? | string | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - -## `IntervalVariableKind` - -Following is the JSON for a default interval variable: - -```json - "variables": [ - { - "kind": "IntervalVariable", - "spec": { - "auto": false, - "auto_count": 0, - "auto_min": "", - "current": { - "text": "", - "value": "" - }, - "hide": "dontHide", - "name": "", - "options": [], - "query": "", - "refresh": "never", - "skipUrlSync": false - } - } - ] -``` - -`IntervalVariableKind` consists of: - -- kind: "IntervalVariable" -- spec: [IntervalVariableSpec](#intervalvariablespec) - -### `IntervalVariableSpec` - -The following table explains the usage of the interval variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| query | string | -| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| auto | bool. Default is `false`. | -| auto_count | integer. Default is `0`. | -| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false` | -| description? | string | - -## `CustomVariableKind` - -Following is the JSON for a default custom variable: - -```json - "variables": [ - { - "kind": "CustomVariable", - "spec": { - "current": defaultVariableOption(), - "hide": "dontHide", - "includeAll": false, - "multi": false, - "name": "", - "options": [], - "query": "", - "skipUrlSync": false - } - } - ] -``` - -`CustomVariableKind` consists of: - -- kind: "CustomVariable" -- spec: [CustomVariableSpec](#customvariablespec) - -### `CustomVariableSpec` - -The following table explains the usage of the custom variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| query | string | -| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| multi | bool. Default is `false`. | -| includeAll | bool. Default is `false`. | -| allValue? | string | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - -## `SwitchVariableKind` - -Following is the JSON for a default switch variable: - -```json - "variables": [ - { - "kind": "SwitchVariable", - "spec": { - "current": "false", - "enabledValue": "true", - "disabledValue": "false", - "hide": "dontHide", - "name": "", - "skipUrlSync": false - } - } - ] -``` - -`SwitchVariableKind` consists of: - -- kind: "SwitchVariable" -- spec: [SwitchVariableSpec](#switchvariablespec) - -### `SwitchVariableSpec` - -The following table explains the usage of the switch variable JSON fields: - - - -| Name | Usage | -| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| current | string. Current value of the switch variable (either `enabledValue` or `disabledValue`). | -| enabledValue | string. Value when the switch is in the enabled state. | -| disabledValue | string. Value when the switch is in the disabled state. | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - - - -## `GroupByVariableKind` - -Following is the JSON for a default group by variable: - -```json - "variables": [ - { - "kind": "GroupByVariable", - "spec": { - "current": { - "text": [ - "" - ], - "value": [ - "" - ] - }, - "datasource": {}, - "hide": "dontHide", - "multi": false, - "name": "", - "options": [], - "skipUrlSync": false - } - } - ] -``` - -`GroupByVariableKind` consists of: - -- kind: "GroupByVariable" -- spec: [GroupByVariableSpec](#groupbyvariablespec) - -### `GroupByVariableSpec` - -The following table explains the usage of the group by variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable | -| datasource? | `DataSourceRef`. Refer to the [`DataSourceRef` definition](#datasourceref) under `QueryVariableKind`. | -| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | -| multi | bool. Default is `false`. | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string. | - -## `AdhocVariableKind` - -Following is the JSON for a default ad hoc variable: - -```json - "variables": [ - { - "kind": "AdhocVariable", - "spec": { - "baseFilters": [], - "defaultKeys": [], - "filters": [], - "hide": "dontHide", - "name": "", - "skipUrlSync": false - } - } - ] -``` - -`AdhocVariableKind` consists of: - -- kind: "AdhocVariable" -- spec: [AdhocVariableSpec](#adhocvariablespec) - -### `AdhocVariableSpec` - -The following table explains the usage of the ad hoc variable JSON fields: - -| Name | Usage | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| name | string. Name of the variable. | -| datasource? | `DataSourceRef`. Consists of:
        • type? - string. The plugin type-id.
        • uid? - string. The specific data source instance.
        | -| baseFilters | [AdHocFilterWithLabels](#adhocfilterswithlabels) | -| filters | [AdHocFilterWithLabels](#adhocfilterswithlabels) | -| defaultKeys | [MetricFindValue](#metricfindvalue) | -| label? | string | -| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. | -| skipUrlSync | bool. Default is `false`. | -| description? | string | - -#### `AdHocFiltersWithLabels` - -The following table explains the usage of the ad hoc variable with labels JSON fields: - -| Name | Type | -| ------------ | ------------- | -| key | string | -| operator | string | -| value | string | -| values? | `[...string]` | -| keyLabel | string | -| valueLabels? | `[...string]` | -| forceEdit? | bool | - -#### `MetricFindValue` - -The following table explains the usage of the metric find value JSON fields: - -| Name | Type | -| ----------- | ---------------- | -| text | string | -| value? | string or number | -| group? | string | -| expandable? | bool | diff --git a/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md b/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md index cf8f9be153a..5d9d4c04ce8 100644 --- a/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md +++ b/docs/sources/visualizations/dashboards/build-dashboards/view-dashboard-json-model/index.md @@ -292,4 +292,15 @@ tbd ## JSON Schema v2 -Go to swagger kids \ No newline at end of file +Go to swagger kids + +