diff --git a/src/content/docs/infrastructure/prometheus-integrations/view-query-data/grafana-to-nr-dashboard-translation-rest-api.mdx b/src/content/docs/infrastructure/prometheus-integrations/view-query-data/grafana-to-nr-dashboard-translation-rest-api.mdx new file mode 100644 index 00000000000..c66ec349311 --- /dev/null +++ b/src/content/docs/infrastructure/prometheus-integrations/view-query-data/grafana-to-nr-dashboard-translation-rest-api.mdx @@ -0,0 +1,204 @@ +--- +title: Translate Grafana dashboards to New Relic dashboards +tags: + - Integrations + - Prometheus integrations + - View and query data +translate: + - jp + - kr +metaDescription: Read about how to translate Grafana dashboards into New Relic ones. +freshnessValidatedDate: never +--- + +You can use the Grafana to New Relic Dashboard Translation REST API to convert your existing Grafana dashboards into New Relic native dashboards. This API can aid in the migration from Grafana to New Relic for customers who are currently using the Grafana plugin to visualize their New Relic data. Whether you're looking to consolidate your observability tools, migrate your entire monitoring setup to New Relic, or simply test out New Relic dashboards alongside your existing Grafana setup, this API makes it easier to get started. + +This API uses New Relic's PromQL translation logic to translate your queries. To see a list of supported PromQL features and functions, see [PromQL features support](/docs/infrastructure/prometheus-integrations/view-query-data/supported-promql-features). + +## Prerequisites [#prerequisites] + +Before using this API, you'll need: + + * A [New Relic user API key](/docs/apis/get-started/intro-apis/types-new-relic-api-keys#user-api-key) + * Your Grafana dashboard exported as JSON (in Grafana: Settings → JSON Model → Copy to Clipboard) + * Your New Relic account ID (if you want to override the default account) + +## Make a request to the API endpoints [#api-endpoints] +To translate a Grafana dashboard to a New Relic dashboard, send a `POST` request to the appropriate endpoint for your region with the dashboard you want to translate in the body of the request. + +* For the US, `https://prometheus-api.newrelic.com/api/v1/translate/dashboard/grafana` +* For EU, `https://prometheus-api.eu.newrelic.com/api/v1/translate/dashboard/grafana` + +### Authentication [#authentication] +All API calls require a [user API key](/docs/apis/get-started/intro-apis/types-new-relic-api-keys#user-api-key). Include this key in the `x-api-key` header of your request. + +### Request body [#request-body] +The request body should be a JSON object with the following format: +``` +{ + "accountId": int [optional], + "dashboard": object [required] +} +``` + +Where `dashboard` is the JSON object of the Grafana dashboard you want to translate, and `accountId` is the account you want your translated dashboard to query data from. If `accountId` is not included, the translated dashboard will query data from the account of the user making the request. + +### Response format [#response-format] +The API returns a JSON object containing the translated New Relic dashboard: +```json +{ + "dashboard": { + "name": "Translated Dashboard", + "permissions": "PUBLIC_READ_WRITE", + "pages": [...] + } +} +``` + +## Troubleshoot translation errors [#troubleshooting] + +When the translator encounters issues that prevent complete translation of a widget or query, it creates "Action Items" - special Markdown widgets that explain what went wrong and suggest fixes. +Action Item Example + +## Examples [#examples] + + + ```bash + export NR_USER_KEY="your_user_key" + export JSON_FILE="my_grafana_dashboard.json" + export TRANSLATOR_ENDPOINT="" # (see API endpoints section above) + + curl -s ${TRANSLATOR_ENDPOINT} \ + -H "Content-Type: application/json" \ + -H "x-api-key:${NR_USER_KEY}" \ + -d "$(jq -c -n --slurpfile dashboard "${JSON_FILE}" '{dashboard: $dashboard[0]}')" \ + | jq '.dashboard' + ``` + + + + If you want to override the account of which your dashboard will query data from, you can include `accountId: int` in the payload of the request. This will make all queries in the dashboard query data from the specified account. + + ```bash + export NR_USER_KEY="your_user_key" + export ACCOUNT_ID="your_staging_account_id" + export JSON_FILE="my_grafana_dashboard.json" + export TRANSLATOR_ENDPOINT="" # (see API endpoints section above) + + curl -s ${TRANSLATOR_ENDPOINT} \ + -H "Content-Type: application/json" \ + -H "x-api-key:${NR_USER_KEY}" \ + -d "$(jq -c -n --arg accountId "$ACCOUNT_ID" --slurpfile dashboard "$JSON_FILE" '{accountId: $accountId, dashboard: $dashboard[0]}')" \ + | jq '.dashboard' + ``` + + + + + + For more information on how to use NerdGraph and to find your regional endpoint, see [Introduction to New Relic NerdGraph](/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph). + + + ```bash + export NR_USER_KEY="your_user_key" + export ACCOUNT_ID="your_staging_account_id" + export JSON_FILE="my_grafana_dashboard.json" + export TRANSLATOR_ENDPOINT="" # (see API endpoints section above) + export NERDGRAPH_ENDPOINT="US/EU Regional Nerdgraph endpoint" + + NR_DASHBOARD=$(curl -s ${TRANSLATOR_ENDPOINT} \ + -H "Content-Type: application/json" \ + -H "x-api-key:${NR_USER_KEY}" \ + -d "$(jq -c -n --arg accountId "$ACCOUNT_ID" --slurpfile dashboard "$JSON_FILE" '{accountId: $accountId, dashboard: $dashboard[0]}')" \ + | jq '.dashboard') + + + curl -X POST ${NERDGRAPH_ENDPOINT} \ + -H "Content-Type: application/json" \ + -H "API-Key: ${NR_USER_KEY}" \ + -d '{ + "query": "mutation($accountId: Int!, $dashboard: DashboardInput!) { dashboardCreate(accountId: $accountId, dashboard: $dashboard) { entityResult { guid name } errors { description } } }", + "variables": { + "accountId": '${ACCOUNT_ID}', + "dashboard": '${NR_DASHBOARD}' + } + }' + ``` + + + +## Grafana and New Relic widget types + +The following is a list of Grafana widget types that we support and their corresponding New Relic widget types. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Grafana widget typeNew Relic widget type
singlestatBILLBOARD
statBILLBOARD
bargaugeBILLBOARD
gaugeBULLET
tableTABLE
graph (line chart)LINE
graph (area chart)AREA
textMARKDOWN
piechartPIE
heatmapHEATMAP
bar-chartBAR
barchartBAR
diff --git a/src/content/docs/infrastructure/prometheus-integrations/view-query-data/supported-promql-features.mdx b/src/content/docs/infrastructure/prometheus-integrations/view-query-data/supported-promql-features.mdx index bd61e12d782..2ab0acddb33 100644 --- a/src/content/docs/infrastructure/prometheus-integrations/view-query-data/supported-promql-features.mdx +++ b/src/content/docs/infrastructure/prometheus-integrations/view-query-data/supported-promql-features.mdx @@ -1,5 +1,5 @@ --- -title: Supported PromQL Features +title: Supported PromQL features tags: - Integrations - Prometheus integrations @@ -7,7 +7,7 @@ tags: translate: - jp - kr -metaDescription: Read about how support Promethus and PromQL features. +metaDescription: Read about how we support Prometheus and PromQL features. redirects: - /docs/integrations/prometheus-integrations/view-query-data/supported-promql-features - /docs/supported-promql-features @@ -15,9 +15,9 @@ redirects: freshnessValidatedDate: never --- -New Relic supports PromQL-style queries, and our query builder offers a PromQL-style query mode that translates PromQL syntax queries into the closest NRQL approximation. Although the method of approximation means that a handful of edge cases are not fully supported, it provides coverage for an overwhelming majority of queries, supporting over 99.5% of queries across the 7.8 million top Grafana dashboard downloads. +New Relic supports PromQL-style queries, and our query builder offers a PromQL-style query mode that translates PromQL syntax queries into the closest NRQL approximation. Although the method of approximation means that a handful of edge cases aren't fully supported, it provides coverage for an overwhelming majority of queries, supporting over 99.5% of queries across the 7.8 million top Grafana dashboard downloads. -Read on to learn about how we work with PromQL queries, as well as differences between standard PromQL and our PromQL-like query language we want you to be aware of. +Learn how we work with PromQL queries, as well as differences between standard PromQL and our PromQL-like query language. For general information about Prometheus queries and operators, see the [Prometheus.io](https://prometheus.io/docs/prometheus/latest/querying/operators/) documentation. @@ -40,7 +40,7 @@ We support the following aggregation, arithmetic, mathematical, and rate-like fu * [`max()`](http://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) * [`quantile()`](https://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) * [`stddev()`](http://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) - * `stdvar()` + * [`stdvar()`](http://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) * [`sum()`](http://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) * [`topk()`](http://prometheus.io/docs/prometheus/latest/querying/operators/#aggregation-operators) @@ -51,6 +51,7 @@ We support the following aggregation, arithmetic, mathematical, and rate-like fu * [`avg_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) * [`count_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) + * [`last_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) * [`min_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) * [`max_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) * [`quantile_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#aggregation_over_time) @@ -74,6 +75,7 @@ We support the following aggregation, arithmetic, mathematical, and rate-like fu * [`and`](https://prometheus.io/docs/prometheus/latest/querying/operators/#logical-set-binary-operators) * [`or`](https://prometheus.io/docs/prometheus/latest/querying/operators/#logical-set-binary-operators) + * [`unless`](https://prometheus.io/docs/prometheus/latest/querying/operators/#logical-set-binary-operators) + + + * [`sort`](https://prometheus.io/docs/prometheus/latest/querying/functions/#sort) + * [`sort_desc`](https://prometheus.io/docs/prometheus/latest/querying/functions/#sort_desc) + + + + * [`label_join()`](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join) + ## PromQL troubleshooting [#troubleshooting] @@ -148,13 +159,13 @@ This section describes differences in behavior between PromQL and our PromQL-sty Prometheus recommendations note that you should only use some functions, like delta(), on gauges, and only use others like rate() and increase() on counters, but queries in Prometheus still work most of the time even if they don’t follow those instructions. -However, because NRDB converts PromQL-style accumulating counters to `delta` counters, our implementation is unforgiving when using these functions on the wrong data type and will produce different or incorrect answers. +However, because NRDB converts PromQL-style accumulating counters to `delta` counters, our implementation doesn't handle these functions on the wrong data type and will produce different or incorrect answers. For this reason, it's best to follow all Prometheus recommendations when working with our PromQL-style queries, even if you don't follow these recommendations in Prometheus. ### Limits -* In order to ensure the stability and performance of our system for all users, we place some limits on what queries can be run. In all cases, we enforce a limit of 366 steps in range queries. We also default to only returning 100 time series from queries by default. +* To ensure the stability and performance of our system for all users, we place some limits on what queries can run. In all cases, we enforce a limit of 366 steps in range queries. We also return only 100 time series from queries by default. * If you want to see more (or fewer), you need to explicitly add a `topk()` to your query. (Note that the `topk()` implementation in our PromQL-style query is different from that of Prometheus.) * We limit the total memory a query can use. This means that requests for large numbers of time steps or large numbers of time series may be rejected, particularly if they are combined with an aggregation like unique `count` or `quantile` which require significantly more memory to compute than simple arithmetic aggregations. diff --git a/static/images/grafana_dashboard_translator_action_items.webp b/static/images/grafana_dashboard_translator_action_items.webp new file mode 100644 index 00000000000..5cbdc6bb965 Binary files /dev/null and b/static/images/grafana_dashboard_translator_action_items.webp differ