Merge pull request #229749 from maud-lv/ml-g-dashboardext

JamesJBarnett · web-flow · commit 05791a1481af · 2023-03-15T10:21:56.000-07:00
Create doc: how to share dashboard
diff --git a/articles/managed-grafana/how-to-create-dashboard.md b/articles/managed-grafana/how-to-create-dashboard.md
@@ -4,8 +4,8 @@ description: Learn how to create and configure Azure Managed Grafana dashboards.
 author: maud-lv
 ms.author: malev
 ms.service: managed-grafana
-ms.topic: how-to 
-ms.date: 01/02/2023
+ms.topic: how-to
+ms.date: 03/07/2023
 ---
 
 # Create a dashboard in Azure Managed Grafana
@@ -15,7 +15,7 @@ In this guide, learn how to create a dashboard in Azure Managed Grafana to visua
 A Grafana dashboard contains panels and rows. You can import a Grafana dashboard and adapt it to your own scenario, create a new Grafana dashboard, or duplicate an existing dashboard.
 
 > [!NOTE]
-> The Grafana UI may change periodically. This article shows the Grafana interface and user flow at a given point. Your experience may slightly differ from the examples below at the time of reading this document. If this is the case, refer to the [Grafana Labs documentation.](https://grafana.com/docs/grafana/latest/dashboards/)
+> The Grafana UI may change periodically. This article shows the Grafana interface and user flow at a given point. Your experience may slightly differ from the examples below at the time of reading this document. If this is the case, refer to the [Grafana Labs documentation](https://grafana.com/docs/grafana/latest/dashboards/).
 
 ## Prerequisites
 
@@ -25,39 +25,64 @@ A Grafana dashboard contains panels and rows. You can import a Grafana dashboard
 
 ## Import a Grafana dashboard
 
-To quickly create a dashboard, import a dashboard template from the Grafana Labs website and add it to your Managed Grafana workspace.
+To quickly create a dashboard, import an existing dashboard and add it to your Managed Grafana instance. You can do so by importing a dashboard template from Grafana Labs, uploading a JSON file or pasting JSON code. 
+
+### Import a dashboard from Grafana Labs 
+
+Import a dashboard template from the Grafana Labs website.
 
 1. From the Grafana Labs website, browse through [Grafana dashboards templates](https://grafana.com/grafana/dashboards/?category=azure) and select a dashboard to import.
 1. Select **Copy ID to clipboard**.
 1. For the next steps, use the Azure portal or the Azure CLI.
 
     ### [Portal](#tab/azure-portal)
 
-    1. In the Azure portal, open your Azure Managed Grafana workspace and select the **Endpoint** URL.
-    1. In the Grafana portal, go to **Dashboards > Import**.
-    1. On the **Import** page, under **Import via grafana.com**, paste the Grafana dashboard ID copied earlier, and select **Load**.
+   1. In the Azure portal, open your Azure Managed Grafana workspace and select the **Endpoint** URL.
+   1. In the Grafana portal, go to **Dashboards > Import**.
+   1. Under **Import via grafana.com**, paste the Grafana dashboard ID copied earlier, and select **Load**.
 
-       :::image type="content" source="media/create-dashboard/import-load.png" alt-text="Screenshot of the Grafana instance. Load dashboard to import.":::
+      :::image type="content" source="media/create-dashboard/import-load.png" alt-text="Screenshot of the Grafana instance. Load dashboard to import.":::
 
-    1. Optionally update the dashboard name, folder and UID.
-    1. Select a datasource and select **Import**.
-    1. A new dashboard is displayed.
-    1. Review the visualizations displayed and edit the dashboard if necessary.
+   1. Optionally update the dashboard name, folder, unique identifier (UID), and other parameters.
+   1. Select a datasource and select **Import**.
+   1. A new dashboard is displayed. Review and edit it if necessary.
 
     ### [Azure CLI](#tab/azure-cli)
+    
+    Run the [az grafana dashboard import](/cli/azure/grafana/dashboard#az-grafana-update) command and replace the placeholders `<AMG-name>`, `<AMG-resource-group>`, and `<dashboard-id>` with the name of the Azure Managed Grafana instance, its resource group, and the dashboard ID you copied earlier.
 
-    1. Open a CLI and run the `az login` command.
-    1. Run the [az grafana dashboard import](/cli/azure/grafana/dashboard#az-grafana-update)command and replace the placeholders `<AMG-name>`, `<AMG-resource-group>`, and `<dashboard-id>` with the name of the Azure Managed Grafana instance, its resource group, and the dashboard ID you copied earlier.
-
-       ```azurecli
-       az grafana dashboard import --name <AMG-name> --resource-group <AMG-resource-group> --definition <dashboard-id>
-       ```
+   ```azurecli
+   az grafana dashboard import --name <AMG-name> --resource-group <AMG-resource-group> --definition <dashboard-id>
+   ```
 
     ---
 
+### Import a JSON dashboard
+
+Follow these steps to import a JSON dashboard to Grafana:
+
+### [Portal](#tab/azure-portal)
+
+1. In the Azure portal, open your Azure Managed Grafana workspace and select the **Endpoint** URL.
+1. Go to **Dashboard > Import** use a preferred import option:
+   - Select **Upload JSON file** and then **Load** to import from a JSON file.
+   - Paste JSON text in the **Import via panel json** box and select **Load** to use text from your clipboard.
+1. Optionally update the dashboard name, folder, unique identifier (UID) and other parameters.
+1. Select **Import**.
+
+### [Azure CLI](#tab/azure-cli)
+
+Run the [az grafana dashboard import](/cli/azure/grafana/dashboard#az-grafana-update) command and replace the placeholders `<AMG-name>`, `<AMG-resource-group>`, and `<local-path-to-file>` with the name of the Azure Managed Grafana instance, its resource group, and the path to the JSON File on your local machine, ending with `.json`.
+
+   ```azurecli
+   az grafana dashboard import --name <AMG-name> --resource-group <AMG-resource-group> --definition @<local-path-to-file>
+   ```
+
+---
+
 ## Create a new Grafana dashboard
 
-If none of the pre-configured dashboards listed on the Grafana Labs website fit your needs, create a new dashboard.
+To create your own new dashboard, follow these steps. 
 
 ### [Portal](#tab/azure-portal)
 
@@ -104,10 +129,10 @@ Duplicate a Grafana dashboard using your preferred method.
 
 To copy a Grafana dashboard:
 
-1. Open an existing dashboard in your Grafana instance
-1. Select **Dashboard settings**
-1. Select **Save as**
-1. Enter a new name and/or a new folder and select **Save**
+1. Open an existing dashboard in your Grafana instance.
+1. Select **Dashboard settings**.
+1. Select **Save as**.
+1. Enter a new name and/or a new folder and select **Save**.
 
    :::image type="content" source="media\create-dashboard\copy-dashboard.png" alt-text="Screenshot of the Grafana instance. Duplicate a dashboard.":::
 
@@ -168,8 +193,8 @@ To update a Grafana panel, follow the steps below.
 
 1. At the top of the page:
    1. Toggle **Table view** to display data as a table.
-   1. Switch between **Fill** and **Actual** to edit panel size
-   1. Select the time icon to update the time range
+   1. Switch between **Fill** and **Actual** to edit panel size.
+   1. Select the time icon to update the time range.
    1. Select the visualization drop-down menu to choose a visualization type that best supports your use case. Go to [visualization](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/) for more information.
 
     :::image type="content" source="media/create-dashboard/panel-time-visualization-options.png" alt-text="Screenshot of the Grafana instance. Time, visualization and more options.":::
@@ -188,7 +213,7 @@ az grafana dashboard update --name <AMG-name> --resource-group <AMG-resource-gro
 
 ## Next steps
 
-In this how-to guide, you learned how to create a Grafana dashboard. To learn how to manage your data sources, go to:
+In this how-to guide, you learned how to create a Grafana dashboard. To learn share this dashboard with internal and external stakeholders, go to:
 
 > [!div class="nextstepaction"]
-> [Configure data sources](how-to-data-source-plugins-managed-identity.md)
+> [Share a dashboard or panel](how-to-share-dashboard.md)
diff --git a/articles/managed-grafana/how-to-share-dashboard.md b/articles/managed-grafana/how-to-share-dashboard.md
@@ -0,0 +1,102 @@
+---
+title: Share an Azure Managed Grafana dashboard or panel
+description: Learn how to share a Grafana dashboard with internal and external stakeholders, such as customers or partners.
+author: maud-lv
+ms.author: malev
+ms.service: managed-grafana
+ms.topic: how-to 
+ms.date: 03/01/2023
+---
+
+# Share a Grafana dashboard or panel
+
+In this guide for Azure Managed Grafana, learn how to share a Grafana dashboard or a Grafana panel with internal and external stakeholders, whether they're registered in your Azure Active Directory tenant or not. You can choose to share a dashboard or panel with restricted access, or share it with public access to facilitate collaboration with partners or customers.
+
+You can share Grafana visualizations by generating:
+
+- a direct link
+- a snapshot
+- an embedded link (for panels only)
+- a library panel (for panels only)
+- an export link (for dashboards only)
+
+> [!NOTE]
+> The Grafana UI may change periodically. This article shows the Grafana interface and user flow at a given point. Your experience may slightly differ from the examples below at the time of reading this document. If this is the case, refer to the [Grafana Labs documentation.](https://grafana.com/docs/grafana/latest/dashboards/)
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free).
+- An Azure Managed Grafana instance. If you don't have one yet, [create an Azure Managed Grafana instance](./quickstart-managed-grafana-portal.md).
+- A Grafana dashboard. If you don't have one, [create a Grafana dashboard](./quickstart-managed-grafana-portal.md).
+
+## Open sharing options
+
+Access Grafana dashboard and panel sharing options with the following steps:
+
+1. In the Azure portal, open your Azure Managed Grafana workspace and select the **Endpoint** URL.
+1. In the Grafana portal, go to **Dashboards > Browse**, and open a dashboard of your choice.
+1. Open the sharing options:
+   - To share a whole dashboard, select the **Share dashboard or panel** icon at the top of the page.
+   - To share a single dashboard panel, hover on top of a panel title, expand the panel menu and select **Share**.
+
+   :::image type="content" source="media/share-dashboard/find-share-option.png" alt-text="Screenshot of the Grafana instance. Create a new dashboard.":::
+
+A new window opens, offering various sharing options.
+
+> [!TIP] 
+> If you update a dashboard or a panel, make sure to save your changes before sharing it so that it contains your latest changes.
+
+### Share a link
+
+The **Link** tab lets you create a direct link to a Grafana dashboard or panel.
+
+Create a sharable link in one step, by selecting **Copy**, at the bottom of the tab. Optionally customize sharing with the options below:
+
+- **Lock time range**: sets the time range of the shared panel or dashboard to the time range currently displayed in your shared panel or dashboard.
+- **Theme**: keep the current theme or choose a dark or a light theme.
+- **Shorten URL**: shortens the sharable link.
+
+> [!NOTE] 
+> Users must have a Grafana Viewer permission to view shared links.
+
+### Share a snapshot
+
+The **Snapshot** tab lets you share an interactive dashboard or panel publicly. Sensitive data like queries (metric, template, and annotation) and panel links are removed from the snapshot, leaving only the visible metric data and series names embedded in your dashboard.
+
+1. Optionally update the snapshot name, select an expiry date and change the value of the timeout.
+1. Choose to publish the Grafana snapshot:
+   - to snapshots.raintank.io to make it accessible publicly to anyone with the link.
+   - as a local snapshot, to restrict access to users who are registered in your Azure AD tenant.
+1. **Copy** the snapshot URL generated by Grafana. Select **Delete snapshot** if you no longer need it.
+
+> [!NOTE] 
+> - Snapshots published on snapshots.raintank.io can be viewed by anyone who has the link.
+> - Users must have a Grafana Viewer permission to view snapshots shared locally.
+
+### Share a panel using an embedded link
+
+The **Embed** tab generates HTML code embedding an iframe with a panel, so that you can include it in another web page. The HTML code is automatically generated. Get it in a single step by selecting **Copy to clipboard** at the bottom of the tab. Optionally customize sharing with the options below:
+
+- **Current time range**: transforms the relative time range of the shared panel to an absolute time range, as currently displayed in your shared panel.
+- **Theme**: keep the current theme or choose a dark or a light theme.
+- **Shorten URL**: shortens the sharable link.
+
+> [!NOTE] 
+> Users must have a Grafana Viewer permission to view embedded links.
+
+### Create a library panel
+
+The **Library panel** tab lets you create a library panel that can be reused in other Grafana dashboards. Do this in a single step by selecting The **Create library panel** at the bottom of the tab. Optionally update the panel library name and select another folder to save it in.
+
+Once you've created a library panel, reuse it in other dashboards of the same Grafana instance by going to **Dashboards > New dashboard > Add panel from panel library**.
+
+### Export a dashboard
+
+The **Export** tab lets you export a dashboard in JSON format. Do this by selecting **Save to file** to download the JSON file, or select **View JSON > Copy to Clipboard**.
+
+**Export for sharing externally** is disabled by default. Optionally enable this option to generate JSON code for external stakeholders. The exported dashboard can then be [imported to Grafana](how-to-create-dashboard.md#import-a-json-dashboard).
+
+In this how-to guide, you learned how to create a Grafana dashboard. To learn about the latest updates to Azure Managed Grafana, go to:
+
+> [!div class="nextstepaction"]
+> [What's new](concept-whats-new.md)
diff --git a/articles/managed-grafana/index.yml b/articles/managed-grafana/index.yml
@@ -43,6 +43,8 @@ landingContent:
             url: how-to-authentication-permissions.md
           - text: Create a dashboard
             url: how-to-create-dashboard.md
+          - text: Share a dashboard
+            url: how-to-share-dashboard.md
           - text: Configure SMTP settings
             url: how-to-smtp-settings.md
   - title: Manage Azure Managed Grafana
diff --git a/articles/managed-grafana/media/share-dashboard/find-share-option.png b/articles/managed-grafana/media/share-dashboard/find-share-option.png
diff --git a/articles/managed-grafana/toc.yml b/articles/managed-grafana/toc.yml
@@ -37,6 +37,8 @@ items:
     href: how-to-permissions.md
   - name: Create a dashboard
     href: how-to-create-dashboard.md
+  - name: Share a dashboard
+    href: how-to-share-dashboard.md
   - name: Share an Azure Managed Grafana instance
     href: how-to-share-grafana-workspace.md
   - name: Configure SMTP settings
