# Upgrade
This article explains how to upgrade your existing Cognite Data Source for Grafana to version 2.1+, and then use a script to update your existing Grafana dashboards to use the new version.
In this article:
# Upgrade from 1.x.x to 2.1+
Follow the steps below to upgrade the Cognite Data Source for Grafana from version 1.x.x to 2.0.0 and update your existing Grafana dashboards to use the new version.
TIP
The new major version of the plugin includes new capabilities and improvements and significant changes to existing functionality. To ensure a smooth transition to the latest version, we highly recommend that you upgrade and test your existing dashboards in a staging environment before you upgrade them in your production environment.
First, make sure that you have:
A Grafana instance with Cognite Data Source for Grafana 1.0.x installed.
A Grafana API key (opens new window) with administrator access for your Grafana instance.
CDF API keys for the projects you use on the Grafana instance (the API keys need the
timeseriesAcl:READ
capability in CDF).Note: The script will prompt you for your CDF project names.
A computer with Node.js v10 installed. The script uses APIs and doesn't need to be executed from the Grafana instance.
To install Node.js, go here (opens new window) and download and run the distribution file for your platform (use
.pkg
for Mac).
Upgrade (opens new window) the Cognite Data Source for Grafana to v2.1+.
Open a terminal window and run this command:
npx @cognite/grafana-migration-script --grafanaUrl <grafana-url> --grafanaApiKey <grafana-api-key>
1where:
<grafana-url>
is the URL to your Grafana instance.<grafana-api-key>
is a token you generate from your Grafana instance. See the Grafana documentation (opens new window) for more information. The API key is attached to a specific organization, and to migrate multiple organizations you need to run thenpx @cognite/grafana-migration-script
script for each API key.
Optional flags:
--rollback
reverts the changes made by migration script.--dryRun
runs the migration script without writing back to the Grafana instance.
WARNING
This script is not compatible with the Cognite Grafana data source v2.0.0/v2.0.1. Consider upgrading to v2.1 or above.
- The script prompts you for the API key for your CDF project(s). Enter the API key for each project, or leave the field empty to skip a project.
When the script has run successfully, you'll see a message like this in your terminal window:
dashboard-name – status: SUCCESS
The script also logs the differences between the original and the new dashboard JSON configurations.
# Debugging
To help you identify issues with the upgrade, the script logs any error messages and JSON diffs to a debug-[[timestamp]].log
file every time you run it. If your dashboards are not migrated correctly:
For major issues, run this command to revert the dashboards to the previous state.
node dist/main.js --grafanaUrl <grafana-url> --grafanaApiKey <grafana-api-key> --rollback
Then inspect the script log file, correct any issues and rerun the migration script.
NOTE: Grafana has a limit for the amount of stored versions it keeps (default: 20).
For minor issues, consider correcting the issues directly in the upgraded dashboards in Grafana.
If you have any questions, contact our support team: support@cognite.com.
# Configuration changes between v1.x and v2
The tables below outlines the configuration changes between v1.x and v2 of the Cognite Data Source for Grafana.
# Time series
For time series reference, target: [timeseries_name]
has been replaced with the corresponding time series external id.
If the time series doesn't have an external id, the internal id will be used as a reference instead.
Custom queries now use the synthetic time series end-point.
Feature | 1.0.x | 2.0.0 |
---|---|---|
Root asset | Value from input field | Part of a custom query filter syntax. For example, ts{assetSubtreeIds=[{id=ASSET_ID}]} |
Time series reference | [ID] or [ID, AGGREGATE, GRANULARITY] | ts{id=TS_ID} or ts{id=TS_ID, aggregate='AGGREGATE', granularity="GRANULARITY"} |
Filter with aggregates | timeseries{}[AGGREGATE, GRANULARITY] | ts{aggregate='AGGREGATE', granularity='GRANULARITY'} |
Name filter | timeseries{name='TS_NAME'} | ts{externalId=TS_EXT_ID} or ts{id=TS_ID} |
Name RegExp filter | timeseries{name=~'.*regex.*'} | ts{name=~'.*regex.*'} |
Metadata filters | timeseries{metadata.type=~'.*well.*', metadata.tag='1'} | ts{metadata={type=~'.*well.*', tag='1'}} |
Math functions | sum , max , min , avg , pow , sin , cos , pi , sqrt , abs , exp , ln , round . E.g. sum(timeseries{}) or SUM(timeseries{}) | Lower-cased. For example, sum(ts{}) . In addition, power is converted to pow |
Unsupported functions | acos , asin , atan , ceil , cot , degrees , floor , log , log2 , log10 , radians , sign , tan , atan2 , mod , truncate , rand , crc32 , conv , div | Omitted by the script, not supported in API v1. |
Aggregation shortcuts | avg , int , step | Changed to full versions: average , interpolation , stepInterpolation . If these were used in variables, like [TS_ID, $aggregate] , the script tries to migrate them. |
Unsupported aggregations | continuousVariance (cv ), discreteVariance (dv ), totalVariation (tv ) | Not supported by API v1. The script tries to transpile them to the new query syntax. |
Non-quoted filters | timeseries{description=VAL} | ts{description="VAL"} |
# Template variables
The query
and filter
fields have been replaced with one query. Instead of using separate asset{}
and filter{}
, you can use assets{}
to achieve the same result.
Feature | 1.0.x | 2.0.0 |
---|---|---|
Asset sub-trees | asset{assetSubtrees=[ID1,ID2]} | assets{assetSubtreeIds=[{id=ID1}, {externalId='EXT_ID2'}]} |
Metadata query | asset{metadata={"key": "VAL1", "key2": "VAL2"}} | assets{metadata={key='VAL1', key2='VAL2'}} |
Timestamps query | Filters: minCreatedTime , maxCreatedTime , minLastUpdatedTime , maxLastUpdatedTime . E.g. asset{lastUpdatedTime=0} | Similar to API v1 assets{lastUpdatedTime={min=0, max=1}}} |
Filter | filter{name=~".*"} | Now is a part of the query: assets{name=~'.*'} |
Unsupported properties | sort , dir , offset , boostName | Not supported, the script will remove them from the query. |
# Annotations
The query
and filter
fields have been replaced with one query. Instead of using separate event{}
and filter{}
, you can use events{}
to achieve the same result.
The filtering syntax is changed the same way as for template variables. See the Template variables table for examples.
# Other JSON changes
The following properties have been removed: func
, assetQuery.templatedTarget
, assetQuery.func
, assetQuery.timeseries
.
target: 'Start typing tag id here'
has been replaced with an empty string.