Skip to content

Commit f922ce9

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #272443 from Saglodha/Saglodha-EmulatorDocs
Saglodha emulator docs
2 parents cf8d75e + 72db07a commit f922ce9

File tree

4 files changed

+257
-1
lines changed

4 files changed

+257
-1
lines changed

‎articles/event-hubs/TOC.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,9 @@
110110
- name: Log compaction
111111
href: log-compaction.md
112112
- name: Application groups
113-
href: resource-governance-overview.md
113+
href: resource-governance-overview.md
114+
- name: Local emulator
115+
href: overview-emulator.md
114116
- name: Tiers
115117
items:
116118
- name: Premium tier
@@ -210,6 +212,8 @@
210212
href: ../service-bus-messaging/deprecate-service-bus-management.md?toc=/azure/event-hubs/toc.json
211213
- name: Exchange events between applications using different protocols
212214
href: event-hubs-exchange-events-different-protocols.md
215+
- name: Test locally with Event Hubs emulator
216+
href: test-locally-with-event-hub-emulator.md
213217
- name: Programming language samples
214218
items:
215219
- name: .NET samples in GitHub

‎articles/event-hubs/media/test-locally-with-event-hub-emulator/test-locally-with-event-hub-emulator.png

82.6 KB
Loading

‎articles/event-hubs/overview-emulator.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Overview of Event Hubs emulator
3+
description: This article provides an overview of Azure Event Hubs emulator.
4+
ms.topic: article
5+
ms.author: Saglodha
6+
ms.date: 05/06/2024
7+
---
8+
9+
10+
# Overview of Event Hubs emulator
11+
12+
Azure Event Hubs emulator is designed to offer a local development experience for Azure Event Hubs, enabling you to develop and test code against our services in isolation, free from cloud interference.
13+
14+
### Benefits of emulator
15+
16+
The primary advantages of using the emulator are:
17+
18+
- Local Development: The Emulator provides a local development experience, enabling developers to work offline and avoid network latency.
19+
- Cost-Efficiency: With the Emulator, developers can test their applications without incurring any cloud usage costs.
20+
- Isolated Testing Environment: You can test your code in isolation, ensuring that the tests aren't impacted by other activities in the cloud.
21+
- Optimized Inner Development loop: Developers can use the Emulator to quickly prototype and test their applications before deploying them to the cloud.
22+
23+
>[!NOTE]
24+
> Event Hubs emulator is licensed under End user License Agreement. For more details, refer [here.](https://github.com/Azure/azure-event-hubs-emulator-installer/blob/main/EMULATOR_EULA.md)
25+
26+
### Features of Emulator
27+
28+
This section highlights different features provided with Emulator:
29+
30+
- Containerized Deployment: The Emulator runs as a Docker container (Linux-based).
31+
- Cross-Platform Compatibility: It can be used on any platform, including Windows, macOS, and Linux.
32+
- Managing Entity Configuration: Users can manage number of event hubs, partition count etc. using JSON supplied Configuration.
33+
- Streaming Support: The Emulator supports streaming messages using AMQP (Advanced Message Queuing Protocol).
34+
- Observability: It provides observability features, including console and file logging.
35+
36+
### Known Limitations
37+
38+
Current version of emulator has the following limitations:
39+
40+
- It can't stream messages using Kafka protocol.
41+
- It doesn't support on fly management operations using Client side SDK.
42+
43+
> [!NOTE]
44+
> In case of container restart,data and entities are not persisted in emulator.
45+
46+
### Difference between emulator and Event hubs cloud service?
47+
48+
Since Emulator is only meant for development and test purpose, there are functional differences between emulator and cloud service. Here are the high-level features that aren't supported in the Event Hubs emulator:
49+
50+
- Azure Goodness – VNet Integration/ Microsoft Entra ID integration/ Activity Logs/ UI Portal etc.
51+
- Event Hubs Capture
52+
- Resource Governance features like Application Groups
53+
- Auto scale capabilities
54+
- Geo DR capabilities
55+
- Schema Registry Integration.
56+
- Visual Metrics/ Alerts
57+
58+
>[!CAUTION]
59+
>The emulator is intended solely for development and testing scenarios.Any kind of Production use is strictly discouraged. There is no official support provided for emulator.
60+
> Any issues/suggestions should be reported via GitHub issues on emulator Installer [repository.](https://github.com/Azure/azure-event-hubs-emulator-installer/issues).
61+
62+
### Managing Quotas and Configuration
63+
64+
Like our cloud service, Azure Event Hubs emulator provides below quotas for usage:
65+
66+
| Property| Value| User Configurable within limits
67+
| ----|----|----|
68+
Number of supported namespaces| 1 |No|
69+
Maximum number of Event Hubs within namespace| 10| Yes|
70+
Maximum number of consumer groups within event hub| 20 |Yes|
71+
Maximum number of partitions in event hub |32 |Yes
72+
Maximum size of event being published to event hub (batch/nonbatch) |1 MB |No
73+
Minimum event retention time | 1 hr | No
74+
75+
76+
### Making configuration changes
77+
78+
You could use config.json to configure quotas associated with Event Hubs. By default, emulator would run with following [configuration](https://github.com/Azure/azure-event-hubs-emulator-installer/blob/main/EventHub-Emulator/Config/Config.json). Under the configuration file, you could make following edits as per needs:
79+
80+
- **Entities**: You could add more entities (event hubs), with customized partition count and consumer groups count as per supported quotas.
81+
- **Logging**: Emulator supports Logging in file or console or both. You could set as per your personal preference.
82+
83+
>[!IMPORTANT]
84+
> Any changes in JSON configuration must be supplied before running emulator and isn't honoured on fly. For subsequent changes to take effect, container restart is required.
85+
>You cannot rename the preset namespace ("name") in configuration file.
86+
87+
### Drill through available logs
88+
During testing phase, logs help in debugging unexpected failures. For this reason, Emulator supports logging in forms of Console and File. Follow below steps to review the logs:
89+
- **Console Logs**: On docker desktop UI, click on the container name to open Console Logs.
90+
- **File Logs**: These would be present at /home/app/EmulatorLogs within the container.
91+
92+
### Next Steps
93+
94+
For instructions on how to develop locally with Event Hubs emulator, see [test locally with event hubs emulator](test-locally-with-event-hub-emulator.md).
95+

‎articles/event-hubs/test-locally-with-event-hub-emulator.md

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: Test locally with Azure Event Hubs emulator
3+
description: This article describes how to develop and test locally with Event Hubs emulator.
4+
ms.topic: how-to
5+
ms.author: Saglodha
6+
ms.date: 05/05/2024
7+
---
8+
9+
# Test locally with Event Hubs emulator
10+
11+
This article summarizes the steps to develop and test locally with Event hubs emulator. To read more about Event hubs, read [here.](event-hubs-about.md)
12+
13+
## Prerequisites
14+
15+
- Docker desktop
16+
- [Docker desktop](https://docs.docker.com/desktop/install/windows-install/#:~:text=Install%20Docker%20Desktop%20on%20Windows%201%20Download%20the,on%20your%20choice%20of%20backend.%20...%20More%20items)
17+
- Minimum hardware requirements:
18+
- 2 GB RAM
19+
- 5 GB of Disk space
20+
- WSL enablement (only for Windows):
21+
- [Install Windows Subsystem for Linux (WSL) | Microsoft Learn](/windows/wsl/install)
22+
- [Configure Docker to use WSL](https://docs.docker.com/desktop/wsl/#:~:text=Turn%20on%20Docker%20Desktop%20WSL%202%201%20Download,engine%20..%20...%206%20Select%20Apply%20%26%20Restart.)
23+
24+
>[!NOTE]
25+
>Before you continue with the subsequent steps, make sure Docker Desktop is operational in the background.
26+
27+
## Running the emulator
28+
29+
This section highlights different steps to run Event Hubs emulator. Details are as follows:
30+
31+
### [Automated Script](#tab/automated-script)
32+
33+
Before running automated script, clone the Event Hubs emulator GitHub Installer [repository](https://github.com/Azure/azure-event-hubs-emulator-installer) locally.
34+
35+
### Windows
36+
After completing the prerequisites, you can proceed with the following steps to run the Event Hubs emulator locally.
37+
1. Before executing the setup script, we need to allow execution of unsigned scripts. Run the below command in the PowerShell window:
38+
39+
`$>Start-Process powershell -Verb RunAs -ArgumentList 'Set-ExecutionPolicy Bypass –Scope CurrentUser’`
40+
41+
2. Execute setup script `LaunchEmulator.ps1`. Running the script would bring up two containers – Event Hubs emulator & Azurite (dependency for Emulator).
42+
43+
### Linux & macOS
44+
After completing the prerequisites, you can proceed with the following steps to run the Event Hubs emulator locally.
45+
46+
1. Execute the setup script `LaunchEmulator.sh` . Running the script would bring up two containers – Event Hubs emulator & Azurite (dependency for Emulator).
47+
48+
### [Docker (Linux Container)](#tab/docker-linux-container)
49+
1. To start the emulator, you should supply configuration for the entities you want to use. Save the following JSON file locally as config.json
50+
51+
```JSON
52+
{
53+
"UserConfig": {
54+
"NamespaceConfig": [
55+
{
56+
"Type": "EventHub",
57+
"Name": "emulatorNs1",
58+
"Entities": [
59+
{
60+
"Name": "eh1",
61+
"PartitionCount": "2",
62+
"ConsumerGroups": [
63+
{
64+
"Name": "cg1"
65+
}
66+
]
67+
}
68+
]
69+
}
70+
],
71+
"LoggingConfig": {
72+
"Type": "File"
73+
}
74+
}
75+
}
76+
77+
```
78+
79+
2. Save following yaml file as docker-compose.yaml to spin up containers for Event Hubs emulator.
80+
```
81+
name: microsoft-azure-eventhubs
82+
services:
83+
emulator:
84+
container_name: "eventhubs-emulator"
85+
image: "mcr.microsoft.com/azure-messaging/eventhubs-emulator:latest"
86+
volumes:
87+
- "${CONFIG_PATH}:/Eventhubs_Emulator/ConfigFiles/Config.json"
88+
ports:
89+
- "5672:5672"
90+
environment:
91+
BLOB_SERVER: azurite
92+
METADATA_SERVER: azurite
93+
ACCEPT_EULA: ${ACCEPT_EULA}
94+
depends_on:
95+
- azurite
96+
networks:
97+
eh-emulator:
98+
aliases:
99+
- "eventhubs-emulator"
100+
azurite:
101+
container_name: "azurite"
102+
image: "mcr.microsoft.com/azure-storage/azurite:latest"
103+
ports:
104+
- "10000:10000"
105+
- "10001:10001"
106+
- "10002:10002"
107+
networks:
108+
eh-emulator:
109+
aliases:
110+
- "azurite"
111+
networks:
112+
eh-emulator:
113+
```
114+
3. Create .env file to declare the environment variables for event hubs emulator.
115+
116+
```
117+
# Centralized environment variables store for docker-compose
118+
119+
# 1. CONFIG_PATH: Path to config.json file
120+
CONFIG_PATH="<Replace with path to config.json file>"
121+
122+
# 2. ACCEPT_EULA: Pass 'Y' to accept license terms.
123+
ACCEPT_EULA="N"
124+
125+
```
126+
127+
>[!IMPORTANT]
128+
>Argument 'ACCEPT_EULA' is to confirm on the license terms, read more about the license [here](https://github.com/Azure/azure-event-hubs-emulator-installer/blob/main/EMULATOR_EULA.md)
129+
>. Ensure to place .env file in same directory to docker-compose.yaml file.
130+
>. When specifying file paths in Windows, use double backslashes (`\\`) instead of single backslashes (`\`) to avoid issues with escape characters.
131+
132+
4. **Run following command to run emulator**
133+
134+
```
135+
docker compose -f <PathToDockerComposeFile> up -d
136+
```
137+
---
138+
139+
Once the steps are successful, you could find containers running in Docker:
140+
141+
:::image type="content" source="./media/test-locally-with-event-hub-emulator/test-locally-with-event-hub-emulator.png" alt-text="Screenshot showing the event hubs emulator running in container.":::
142+
143+
144+
## Interacting with Emulator
145+
146+
1. You can use the following connection string to connect to Azure Event Hubs emulator.
147+
```
148+
"Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"
149+
```
150+
2. With the latest client SDK releases, you can interact with the emulator in various programming language. For details, refer
151+
[here](./sdks.md)
152+
153+
To get started, refer to our GitHub [samples.](https://github.com/Azure/azure-event-hubs-emulator-installer/tree/main/Sample-Code-Snippets/.NET/EventHubs-Emulator-Demo)
154+
155+
## Next Steps
156+
157+
Read more about Azure event hubs emulator [here](overview-emulator.md)

0 commit comments

Comments
 (0)