Cognite documentation

Upgrade

This article explains how to upgrade your existing Cognite Data Source for Grafana to version 2.0.0, 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.0.0

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.

  1. First, make sure that you have:

    • A Grafana instance with Cognite Data Source for Grafana 1.0.x installed.

    • A Grafana API key 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 and download and run the distribution file for your platform (use .pkg for Mac).

  2. Upgrade the Cognite Data Source for Grafana 2.0.0+.

  3. Open a terminal window and run this command:

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

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

  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
1

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

The tables below outlines the configuration changes between v1.x and v2.0.0 of the Cognite Data Source for Grafana.

Time series

For time series reference, target: [timeseries_name] has been replaced with the corresponding time series ID.

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.

Last Updated: 6/29/2020, 3:55:18 PM