Skip to content

Commit 3c3c1a9

Browse files
DocGailZhouDocGailZhou
authored
Merge pull request #18 from microsoft/gh-updates-1208
docs: Updates in Deployment Guide, Demonstrate Guide and README file
2 parents 72029bd + ac3a170 commit 3c3c1a9

5 files changed

Lines changed: 649 additions & 301 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ If you'd like to customize the solution accelerator, here are some common areas
4747

4848
[Microsoft Fabric Blog](https://blog.fabric.microsoft.com/en-us/blog)
4949

50-
[What Is Real-Time Intelligence in Microsoft Fabric? ](https://learn.microsoft.com/en-us/fabric/real-time-intelligence/overview)
50+
[What Is Real-Time Intelligence in Microsoft Fabric?](https://learn.microsoft.com/en-us/fabric/real-time-intelligence/overview)
5151

5252
[Fabric data agent creation](https://learn.microsoft.com/en-us/fabric/data-science/concept-data-agent)
5353

@@ -67,7 +67,7 @@ If you'd like to customize the solution accelerator, here are some common areas
6767

6868
- **Anomaly Detection and Alerts through Fabric Activator** <br/>Microsoft Activator is configured with anomaly detection rules that trigger Outlook email notifications when an anomaly occurs. For more details, please refer to [Activator Guide](./docs/ActivatorGuide.md).
6969

70-
- **Useful Data Analysis and Performance Metrics KQL Code** <br/>Reusable KQL code is provided to get you started quickly. For details, please refer to [Data Analysis KQL Guide](./src/kql/data_analysis/data_analysis_guide.md) and [Performance Metrics KQL Queryset Guide](./src/kql/kql_queryset/kql_queryset_guide.md).
70+
- **Useful Data Analysis and Performance Metrics KQL Code** <br/>Reusable KQL code is provided to get you started quickly. For details, please refer to [Data Analysis KQL Guide](./src/kql/data_analysis/data_analysis_guide.md) and [Performance Metrics KQL Queryset Guide](./src/kql/kql_queryset/kql_queryset_guide.md).
7171

7272
- **Demonstrator's Guide** <br/> After successful deployment of the solution accelerator, you or your colleague who has required access can demonstrate this solution by following the steps outlined in the [Demonstrator's Guide](./docs/DemonstratorGuide.md).
7373

@@ -86,7 +86,7 @@ Follow these steps to deploy the solution to your own Azure subscription:
8686
| [![GitHub Codespaces](https://img.shields.io/badge/GitHub_Codespaces-Open-grey?style=flat&labelColor=grey&message=Open&color=blue&logo=github)](https://codespaces.new/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Visual Studio Code Dev Containers](https://img.shields.io/badge/Visual_Studio_Code_Dev_Container-Open-gray?style=flat&labelColor=grey&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Visual Studio Code Web](https://img.shields.io/badge/Visual_Studio_Code_Web-Open-gray?style=flat&labelColor=grey&message=Open&color=blue)](https://vscode.dev/github/microsoft/real-time-intelligence-operations-solution-accelerator) | [![Azure Cloud Shell](https://img.shields.io/badge/Azure_Cloud_Shell-Open-grey?style=flat&labelColor=grey&message=Open&color=blue)](https://portal.azure.com/#cloudshell/) |
8787
|---|---|---|---|
8888

89-
**One-command deployment** - Deploy everything with [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) and [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (check [prerquisites](./docs/DeploymentGuide.md#prerequisites)):
89+
**One-command deployment** - Deploy everything with [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) and [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (check [prerequisites](./docs/DeploymentGuide.md#step-1-prerequisites--setup)):
9090

9191
```bash
9292
# Clone and navigate to repository
@@ -114,23 +114,13 @@ azd env set FABRIC_ACTIVATOR_NAME "my_custom_activator"
114114
# Deploy everything
115115
azd up
116116
```
117-
<br/>
118117

119-
Check more deployment aspects in our [deployment guide](./docs/DeploymentGuide.md):
118+
<br/>
120119

121-
| Topic | Description |
122-
|---|---|
123-
| [**Prerequisites**](./docs/DeploymentGuide.md#prerequisites) | Required Azure permissions, API access, and software installations (Python, Azure CLI, azd) |
124-
| [**Event Simulation**](./docs/DeploymentGuide.md#start-event-simulation) | Once deployed, generate real-time telemetry data and test anomaly detection with the event simulator tool |
125-
| [**Deployment validation**](./docs/DeploymentGuide.md#deployment-results) | Once deployed, verify Azure infrastructure, Fabric workspace components, and real-time data flow |
126-
| [**Deployment overview**](./docs/DeploymentGuide.md#deployment-overview) | Two-phase deployment process: Azure infrastructure provisioning and Fabric workspace setup |
127-
| [**Advanced configuration**](./docs/DeploymentGuide.md#advanced-configuration-options) | Customize workspace names, component names, email alerts, and capacity deployment options |
128-
| [**Alternative deployment options**](./docs/DeploymentGuide.md#deployment-options) | Deploy locally, Azure Cloud Shell, GitHub Codespaces, VS Code Dev Container or GitHub Actions|
129-
| [**Limitations**](./docs/DeploymentGuide.md#known-limitations) | See identified limitations of the solution |
130-
| [**Cleanup**](./docs/DeploymentGuide.md#environment-cleanup) | Remove all deployed resources and clean up your environment with `azd down` |
120+
For additional deployment configuration and detailed setup instructions, see the [deployment guide](./docs/DeploymentGuide.md).
131121

132122
### Prerequisites and costs
133-
Microsoft Fabric Capacity is enabled for your organization. Please refer to [Enable Microsoft Fabric for your organization](https://learn.microsoft.com/en-us/fabric/admin/fabric-switch) for more information.
123+
Microsoft Fabric Capacity is enabled for your organization. Please refer to [Enable Microsoft Fabric for your organization](https://learn.microsoft.com/en-us/fabric/admin/fabric-switch) for more information.
134124

135125
To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control role on the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](./docs/AzureAccountSetUp.md).
136126

‎docs/DemonstratorAccessRequirement.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Demonstrator's Access Requirements
2+
3+
To effectively demonstrate the Real-Time Intelligence Operations solution using a pre-configured environment, you must have the following permissions and access levels.
4+
5+
## 1. Fabric Workspace Contributor Role
6+
7+
You must have at least **contributor** level access to the Fabric workspace to modify resources, including:
8+
9+
- [Real-Time Intelligence Operations Dashboard](./RealTimeIntelligenceDashboardGuide.md)
10+
- [Activator](./ActivatorGuide.md)
11+
12+
> **Note:** Viewer-level access is insufficient for demonstration purposes.
13+
14+
## 2. Configure Activator Rules
15+
16+
Update the Activator rules with your Outlook email address to receive alert notifications.
17+
18+
### Steps to Update Activator Rule Email Address
19+
20+
1. Open the [Activator](./ActivatorGuide.md) in your Fabric workspace
21+
2. Navigate to the rule you wish to modify
22+
3. Locate the email notification settings on the right panel **Definitions**
23+
4. Replace the existing email address with your Outlook email address
24+
5. Click **Save** to apply the changes
25+
6. Verify you have access to the updated email account to receive alerts
26+
27+
## 3. Azure Event Hubs Data Sender Role
28+
29+
To send simulated events to the Azure Event Hub, you must have the **Azure Event Hubs Data Sender** role assigned to your account. Contact either the Event Hub owner, or your Azure Administrator to request this role assignment.
30+
31+
The diagram below illustrates the role assignment process:
32+
33+
![Event Hubs Data Sender Role](../docs/images/deployment/eventhubs-data-sender-role.png)

‎docs/DemonstratorGuide.md‎

Lines changed: 82 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,110 @@
1-
# Demonstrator's Guide
1+
# Demonstrator's Guide
22

3-
This page provides guidance on how to set up a demonstration environment for the solution and how to start the data generation simulators. It also describes the security setup for the person to demonstrate the solution.
3+
This guide provides instructions for demonstrating the Real-Time Intelligence Operations solution. Follow the steps in order to effectively showcase the system's capabilities.
44

5-
Please review the Access Requirements Section to ensure you have proper access first.
5+
## Access Prerequisites
66

7-
## Access Requirements
7+
Before beginning the demonstration, verify your access permissions:
88

9-
If you deployed the solution accelerator via AZD following the [Deployment Guide](./DeploymentGuide.md), you have already established the required access to the solution, and **you can skip this Access Requirements section**, and start at [Step 1. Refresh Historical Data](#step-1-refresh-historical-data).
9+
- **If deployed using AZD:** You have the required access and may proceed directly to the demonstration steps.
10+
- **If using a pre-configured environment:** Review the [Demonstrator Access Requirements](./DemonstratorAccessRequirement.md) guide to verify your access level.
1011

11-
If you are using a demonstration environment already set up by someone else, you will need below accesses:
12+
---
1213

13-
1. You will need to be added as a contributor of the Fabric workspace. If you are a viewer, you will not be able to update any resources such as [Real-Time Intelligence Operations Dashboard](./RealTimeIntelligenceDashboardGuide.md) or [Activator](./ActivatorGuide.md). Recommend role: **contributor**.
14-
2. You will need to be able to send simulated events to the Azure Event Hub deployed with the solution. The owner of the Event Hub or your Azure Admin can add you to the role of **Azure Event Hubs Data Sender**. Below diagram illustrates the key steps.
14+
## Step 1. Demonstrate the Fabric Data Agent
1515

16-
![Event Hubs Data Sender Role](../docs/images/deployment/eventhubs-data-sender-role.png)
16+
The Fabric Data Agent is an AI-powered assistant that provides natural language responses to business questions about your data.
1717

18-
## Step 1. Refresh Historical Data
18+
**Instructions:**
1919

20-
When the solution accelerator was deployed, it automatically creates 90 days of telemetry data and stores the data in the EventHouse database. By the time you demonstrate this solution, the data needs to be refreshed. You will need to follow instructions in [Fabric Data Ingestion Guide](./FabricDataIngestion.md) and use the options `--refresh-dates` and `--overwrite` to get a fresh and up to date dataset.
20+
1. Refer to the [Fabric Data Agent Guide](./FabricDataAgentGuide.md) for detailed setup instructions
21+
2. After deployment (or if already deployed), locate the Data Agent in your Fabric workspace
22+
3. Submit questions about the data using the [provided sample questions](./fabric_data_agent/user_sample_test_questions.md) or your own queries
23+
4. Observe how the agent delivers instant responses in natural language
2124

22-
## Step 2. Start Real Time Event Simulator
25+
**What you'll see:**
2326

24-
You will need to start the Real-Time Event Simulator by following the instructions in [Event Simulator Guide](./EventSimulatorGuide.md) to start the simulator. We recommend you start with normal mode and then switch to anomaly mode to illustrate how anomaly events can be observed and how the anomaly events can trigger alerts.
27+
![Fabric Data Agent UI](../docs/images/deployment/fabric_data_agent_ui.png)
2528

26-
## Step 3. Demonstrate the Real-Time Intelligence Operations Dashboard
29+
## Step 2. Refresh Historical Data
2730

28-
Please follow the [Real-Time Intelligence Operations Dashboard Guide](./RealTimeIntelligenceDashboardGuide.md) to understand the concepts and business metrics. You will want to highlight the anomaly spikes as shown in below diagram. Suggest you select time range filter as last 2 days or last 24 hours depending on when you started the anomaly event simulation.
31+
The system contains 90 days of sample data. To ensure the demonstration reflects current information, you must refresh the dataset.
32+
33+
**Instructions:**
34+
35+
1. Follow the [Fabric Data Ingestion Guide](./FabricDataIngestion.md) for detailed procedures
36+
2. Use the `--refresh-dates` and `--overwrite` options to update the data
37+
38+
This process takes approximately a few minutes and ensures the demonstration displays current data.
39+
40+
---
41+
42+
## Step 3. Initialize the Event Simulator
43+
44+
The Event Simulator generates realistic business events to demonstrate the system's real-time anomaly detection capabilities.
45+
46+
**Instructions:**
47+
48+
1. Refer to the [Event Simulator Guide](./EventSimulatorGuide.md) for detailed setup procedures
49+
2. Start the simulator in **Normal Mode** to demonstrate standard operational conditions
50+
3. Switch to **Anomaly Mode** to illustrate system detection and alert capabilities
51+
52+
You may switch operating modes or restart the simulator at any time during the demonstration without interrupting the session.
53+
54+
---
55+
56+
## Step 4. Present the Real-Time Intelligence Dashboard
57+
58+
The Real-Time Intelligence Operations Dashboard displays critical business metrics and provides real-time visibility into operational anomalies.
59+
60+
**Instructions:**
61+
62+
1. Refer to the [Dashboard Guide](./RealTimeIntelligenceDashboardGuide.md) for detailed information
63+
2. On Fabric workspace Real-Time Dashboard, identify **anomaly spikes** in the data visualization. These represent potential operational issues
64+
3. Configure the time filter to display "Last 24 Hours" or "Last 2 Days" corresponding to the simulator start time
65+
4. Highlight the dashboard's real-time update capability as events are processed
66+
67+
**Example of anomaly spikes on the dashboard:**
2968

3069
![RTI Dashboard Anomaly Spikes](../docs/images/deployment/rti-dashboard-anomaly-spikes.png)
3170

32-
## Step 4. Demonstrate the Activator Anomaly Alerts
71+
---
72+
73+
## Step 5. Demonstrate Alert Mechanisms with Activator
74+
75+
The Activator component monitors real-time data streams and automatically triggers alerts when anomalies exceed defined thresholds, enabling proactive incident response.
3376

34-
Please follow the [Activator Guide](./ActivatorGuide.md) to understand how the anomaly detection rules are set. You may need to reconfigure the rules to send alerts to an email account that you have access to. You can also reconfigure the rules to send anomaly alerts to a Microsoft Teams channel instead of an email account.
77+
When anomalies are detected, the system automatically generates alerts, enabling teams to respond promptly to operational issues.
3578

36-
If the simulator is in normal mode, you will rarely receive anomaly events as things should be running much smoother during normal mode. If the simulator is switched to 'anomaly' mode, you will get many alerts. The frequency of the simulated events can be adjusted with the simulator's command line options. This is well documented in the [Event Simulator Guide](./EventSimulatorGuide.md). You can stop and restart this event simulator at any time, or switch the operating mode while it is running.
79+
**Instructions:**
80+
81+
1. Review the [Activator Guide](./ActivatorGuide.md) to understand alert configuration and functionality
82+
2. Open Activator from the workspace
83+
3. Ensure alerts are configured to send to an accessible email address (configuration updates may be required)
84+
4. Optionally configure alerts to be sent to a Microsoft Teams channel for team visibility
85+
86+
**Alert Behavior:**
87+
88+
- **Normal Mode:** Minimal anomalies result in infrequent alerts
89+
- **Anomaly Mode:** Frequent anomalies trigger regular alert notifications
90+
91+
Example email notification:
3792

3893
![Anomaly Alert](../docs/images/deployment/anomaly-email-alerts.png)
3994

40-
When you open one of the emails, you will see something similar to below:
95+
When you open the email, it shows details like this:
4196

4297
![Activator Email Alert](../docs/images/deployment/activator-email-alert.png)
4398

99+
---
44100

101+
## Summary
45102

46-
## Step 5. Demonstrate the Fabric Data Agent
47-
48-
Please follow the [Fabric Data Agent Guide](./FabricDataAgentGuide.md) to understand how the Fabric Data Agent is created and set up. If it is not already set up, you can follow the instructions to create and configure a new Fabric Data Agent in minutes. After that, you can ask any questions you'd like the agent to answer. For starters, you can use the [sample test questions](./fabric_data_agent/user_sample_test_questions.md).
103+
You have successfully demonstrated the following capabilities:
49104

50-
In the Fabric workspace, find the Fabric Data Agent that is already set up. You will be able to chat with the agent right away. Below is the user interface you can expect:
105+
1. **Intelligent Data Assistant:** Natural language query interface for business intelligence
106+
2. **Real-Time Dashboard:** Comprehensive visualization of key operational metrics
107+
3. **Automated Alerting:** Proactive notification system for anomaly detection
108+
4. **Operational Response:** Integrated system enabling rapid response to critical events
51109

52-
![Fabric Data Agent UI](../docs/images/deployment/fabric_data_agent_ui.png)
110+
These components work in concert to provide organizations with real-time operational visibility and accelerated incident response capabilities.

0 commit comments

Comments
 (0)