Project: Grafana (Observability and Analysis / Observability)
File: breaking-changes-v10-0.md

description: Learn about breaking changes in Grafana v10.0 keywords: grafana breaking changes documentation '10.0' release notes labels: products: cloud enterprise oss title: Breaking changes in Grafana v10.0 weight: -1 Following are breaking changes that you should be aware of when upgrading to Grafana v10.0. For our purposes, a breaking change is any change that requires users or operators to do something. This includes: Changes in one part of the system that could cause other components to fail Deprecations or removal of a feature Changes to an API that could break automation Changes that affect some plugins or functions of Grafana Migrations that cant be rolled back For each change, the provided information: Helps you determine if youre affected Describes the change or relevant background information Guides you in how to mitigate for the change or migrate Provides more learning resources For release highlights and deprecations, refer to our . For the specific steps we recommend when you upgrade to v10.0, check out our . <!-- You must use relative references when linking to docs within the Grafana repo. Please do not use absolute URLs. For more information about relrefs, refer to .--> You create a new Grafana Cloud stack and intend to use any panel or data source plugins written using the Angular.js JavaScript framework. See the . AngularJS is an old frontend framework that stopped active development many years ago. Because of that, it's a security risk. AngularJS also requires unsafe-eval in the settings, which also reduces the security level of how javascript is executed in the browser. Angular plugin support in Grafana is deprecated, meaning it will be removed in a future release. There are still some community and private plugins built using Angular. Starting with v9.0, Grafana has a server configuration option, called , that controls whether Angular plugin support is available. Angular is disabled by default for all new Grafana Cloud stacks. Existing stacks in Grafana Cloud, Grafana Enterprise on-premise instances, and Grafana OSS instances will not be automatically impacted. If you're using Angular plugins in Grafana, try an alternative panel or data source that doesn't use Angular. This list of detected offers alternatives where they exist. If you're a developer maintaining a plugin that uses Angular, we recommend you refactor or rewrite its frontend using React.js instead. The team at Grafana is ready to help and provide tools and guidance; you can reach us in or on our . You use Grafana legacy alerting and have requested new features or changes to it. Grafana legacy alerting (dashboard alerts) has been deprecated since Grafana v9.0, in favor of the new, improved Grafana Alerting. In Grafana v10, the legacy alerting codebase&mdash;which depends on Angular&mdash;is still available, but we'll no longer contribute to it or accept external contributions for it. We'll continue to work on the migration path from legacy alerting to Grafana Alerting for our remaining users that need to migrate. The new Grafana Alerting was introduced in Grafana 8 and is a superset of legacy alerting. Learn how to migrate your alerts in the . You use Grafana API keys and haven't yet migrated to service accounts In Grafana

we introduced , which are a superset of API keys that support token rotation and role-based access control (RBAC). They were promoted to general availability (GA) in v9.1, with an option to manually migrate API keys to service accounts through the UI and API since then. When you upgrade to Grafana v10, Grafana will automatically migrate all API keys to service accounts and hide the API keys screen that was under the Admin section. This is a "breaking" change because if users are used to seeing and interacting with API keys, they won't see that page in navigation anymore and will need to navigate to the Service accounts page instead. However, your existing API tokens will remain fully functional and migrated to service accounts, so no automation will break. If you roll back to a previous version of Grafana, your API keys will remain intact. Grafana's remain functional, but we recommend you begin using the to generate and manage machine authentication instead. While upgrading to Grafana v10, you don't need to take any action; your API keys will be automatically migrated. To test or perform the migration from API keys to service accounts before upgrading to Grafana v10, follow our . You have the `dashboardPreviews` feature toggle switched on. We're removing the experimental dashboard previews feature due to user permission and performance issues that prevented us from continuing its development. Dashboard previews have been behind a feature toggle since Grafana v9.0. The entire feature has been removed from Grafana. For users who enabled the `dashboardPreviews` feature flag, Grafana will continue to work as-is but without dashboard previews. We recommend you remove the `dashboardPreviews` feature flag from your Grafana configuration. You have actively disabled RBAC in Grafana's configuration. Starting from Grafana 9, RBAC has been enabled by default. An option to disable RBAC was introduced as an emergency mechanism and has only been used in rare cases. With Grafana v10 we removed the configuration option to disable RBAC. This ensures that Grafana works consistently across different features and decreases the risk of having issues with Grafana's legacy access control. Additionally, access control for some of the Grafana v10 features only work with the RBAC, so disabling it is no longer an option. No action is needed&mdash;migration is automatic. Users' current roles, permissions, SSO mapping, and other authorization functionality will continue to work as before. You run Grafana with a Postgres or sqlite database, you import users from different SSO identity providers (like Google and Active Directory), and users who signed in from different providers were previously created twice because of case differences (for example "<Myra@Grafana.com>" vs "<myra@grafana.com>." When someone signs up for a Grafana account, they can do it using an email or a login. The fields were case sensitive, which could lead to two or more accounts being created for the same user. Additionally, Grafana allows users to set up an authentication provider, and that provider might return an individual's sign-up email with an uppercased domain name or some combination of uppercase and lowercase letters. Having several accounts leads to split user permissions, confusion among signup flows, and unused "zombie" accounts in your database. Plus, multiple accounts can introduce issues when switching between authentication

We refer to these inconsistencies in user uniqueness as a user identity conflict. Grafana will start matching users without regard for case. Conflicting users will not be able to sign in. We've built a which users can use to resolve any potential conflicts beforehand. This breaking change was communicated already with Grafana v9.3. You have configured Grafana to use multiple identity providers, and you have users with the same email address in multiple identity providers. You have configured Grafana to use Generic OAuth with an identity provider that does not support a unique ID field. Grafana used to validate identity provider accounts based on the email claim. On many identity providers, the email field is not unique, and this could open a possible account vector to perform an account takeover and authentication bypass in certain scenarios. This change also ensures that Grafana is protected against the vulnerability. Grafana will not allow the affected users to sign in. In order to address any errors, we have provided an escape hatch that allows you to activate email lookup. You can use the following configuration in your Grafana instance to return the previous behavior. ``` [auth] oauthallowinsecureemaillookup = true ``` We strongly recommend not doing this in case you are using Azure AD as an identity provider with a multi-tenant app. You're using the "Alias" field in the CloudWatch data source, instead of using dynamic labels. Alias patterns in the CloudWatch query editor were replaced by Label (dynamic labels) behind a feature toggle. Starting from Grafana v9, Label has been enabled by default. With Grafana v10 we removed the option to disable Label and remove the Alias field entirely. Open and save each dashboard that uses the Alias field. Alias is migrated to Label automatically when you load the dashboard. You've installed and are using the Athena data source plugin. Grafana v10.0.0 ships with the new React 18 upgrade. In turn, changes in the batching of state updates in React 18 cause a bug in the query editor in Athena plugin versions <=2.9.2. Update the plugin to version 2.9.3 or higher in your Grafana instance management console. This will ensure your plugin query editor works as intended. You've installed and are using the Redshift data source plugin. Grafana v10.0.0 ships with the new React 18 upgrade. In turn, changes in the batching of state updates in React 18 cause a bug in the query editor in Redshift plugin versions <=1.8.3. Update the plugin to version 1.8.3 or higher in your Grafana instance management console. This will ensure your plugin query editor works as intended. You've installed and are using the . In v10.0.0, Grafana no longer supports the use of the , which was moved to a "retired" state in the latter half of 2022, and for which the GitHub repository was archived in December 2022. For BigQuery data sources to continue functioning, you're required to migrate to the . For everyone using Grafana v8.5+, its possible to import queries created with the DoiT International BigQuery community plugin by simply changing the data source to Grafana BigQuery in the data source selector in the affected panel. Please note that as raw SQL queries.

You've developed a Grafana plugin that uses the React JS framework (this includes most app, panel, and data source plugins). Grafana has been upgraded to React 18 and now leverages the new React client rendering API. Plugin authors in particular should be aware, as there could be unintended side effects due to the changes around automatic batching of state updates and consistent `useEffect` timings. As a plugin developer: once a canary build has been released (post-9.5.0), test your plugin against one of the grafana-dev docker builds ( for example). Because of the extra optimisations made by React 18, some changes may be needed to maintain previous behavior. You're a plugin author and you use one of the following logs-related functions: The interface type LogsParser in grafana-data The following functions and classes related to logs in the grafana-ui package: `1LogLabels`, `LogMessageAnsi`, `LogRows`, `getLogRowStyles.`, `getLogLevel`, `getLogLevelFromKey`, `addLogLevelToSeries`, `LogsParsers`, `calculateFieldStats`, `calculateLogsLabelStats`, `calculateStats`, `getParser`, `sortInAscendingOrder`, `sortInDescendingOrder`, `sortLogsResult`, `sortLogRows`, `checkLogsError`, `escapeUnescapedString`. Certain rarely-used logs-related functions and variables have been moved from grafana-packages to the core grafana codebase. These items have been marked as deprecated previously, and a deprecation-notice was issued in the grafana changelog. Plugin authors who have relied on these functions and variables being available will have to adjust their codebase. If you've written a data source or panel plugin, make sure it doesn't use the functions and variables that have been deprecated and removed. <!--check on how the <T> are supposed to show up --> You're a plugin author and you've implemented your own version of Vector for data frames. Working with DataFrames was more complicated than it should have been because data was held in a Vector interface rather than a simple Array.In Grafana v10, the interface has been changed so developers can use simple arrays or Vectors. Any code using Vectors will continue to work without issue.If you've implemented your own version of Vector, it will need to be updated. The easiest approach is to refactor code so it extends MutableVector.This will work in both Grafana v9 and v10. You develop plugins using @grafana/toolkit CLI commands. We announced the deprecation of the grafana/toolkit in v9.3 (November 2022) and have a new tool called create-plugin now available as a replacement. We encourage you to migrate and use our updated tooling. All grafana/toolkit commands except `build` are removed in Grafana v10. Here are some of the benefits of create-plugin: More flexible: With @grafana/create-plugin, you have more control over your plugins and their dependencies, and can more easily customize the tooling to fit your specific needs. Faster development time: With its out-of-the-box development environment @grafana/create-plugin can significantly reduce development time compared to using @grafana/toolkit. Improved testing capabilities: Testing plugins with @grafana/create-plugin is much easier with GitHub workflows that automate unit and e2e test runs whenever changes are pushed to GitHub. Better documentation: The for @grafana/create-plugin is more comprehensive and easier to discover than that of @grafana/toolkit. You may already be using the new tooling. If you have an existing plugin previously created using the @grafana/toolkit, you can use the following command to migrate it to the new build tooling: ``` cd ./my-plugin npx @grafana/create-plugin@latest migrate ``` Changing the folder UID through the API is deprecated. This functionality will be removed in a future release.