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+
• Debugging
• Configuration changes between v1.x and v2
  • Time series
  • Template variables
  • Annotations
  • Other JSON changes

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.

1. 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).

2. Upgrade (opens new window) the Cognite Data Source for Grafana to v2.1+.

3. Open a terminal window and run this command:

   npx @cognite/grafana-migration-script --grafanaUrl <grafana-url> --grafanaApiKey <grafana-api-key>
   

   where:

   • <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 the npx @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.

4. 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.