Merge pull request #99 from Particular/john/claenup

Author: johnsimons

Package-README.md

@@ -2,8 +2,7 @@
 
 This showcase consists of 4 processes hosting MassTransit message producers and consumers that implement a simplified order processing logic from an e-commerce system.
 
-![System Overview](diagram.svg "width=680")
-
+![System Overview](docs/diagram.svg "width=680")
 
 ## Launching the Showcase in Docker
 
@@ -13,11 +12,12 @@ To help getting started we have created a few docker compose files that orchestr
 Run the docker command below from the `src` folder in a terminal.
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env up -d
 ```
 
-### To run against **Azure Service Bus**
+### (Alternative) Run in Docker against **Azure Service Bus**
 
+<details>
 The showcase can also be run using Azure Service Bus rather than RabbitMQ.  
 First configure the access to your Azure Service Bus namespace by editing the variables in `src/asb.env`.
 
@@ -28,25 +28,33 @@ CONNECTIONSTRING="Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccess
 Run docker command below from the `src` folder in a terminal.
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env up -d
 ```
 
-## Running from an IDE
+</details>
+
+### (Alternative) Run from an IDE
 
+<details>
 > [!WARNING]
 > When using Visual Studio, ensure you have the "Enable Multi-Project Launch profiles" setting on. Allow Visual Studio 2022 "multi-launch" so you can easily select the profile you want to run.
 >
 > It can be activated by accessing the Tools menu -> Manage preview features- Enable Multi-Project Launch profiles.
 
-To start the required infrastructure run the following docker command below from the `src` folder in a terminal.
+To start the required infrastructure for the showcase, run one of the docker command below from the `src` folder in a terminal.
 
 RabbitMQ
+
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env --profile infrastructure --profile frontend up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env --profile infrastructure --profile frontend up -d
 ```
+
 Azure Service Bus
+
+See [ASB setup](#alternative-run-from-azure-service-bus) above for setting the connection string to your Azure Service Bus namespace
+
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env --profile infrastructure --profile frontend up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env --profile infrastructure --profile frontend up -d
 ```
 
 After opening the solution (from Visual Studio or Rider), choose one of the run profiles that matches the transport configured previously:
@@ -56,6 +64,53 @@ After opening the solution (from Visual Studio or Rider), choose one of the run
 
 Run the solution to start the demo.
 
+</details>
+
 ## Opening the showcase UI
 
-Navigate to http://localhost:61335/ to see the UI.
+Navigate to http://localhost:61335/ to see the UI. Click `Run Scenario` to start the showcase scenario and generate some simulated message handling failures.
+
+## Handling failures with the Particular Platform
+
+### Inspecting failures
+
+Navigate to [http://localhost:9090](http://localhost:9090) in a new tab, or click the `View in ServicePulse` button, to see the details on failures ingested by the platform.
+
+![Service Pulse Dashboard](docs/service-pulse-dashboard-failed-messages.png "Message processing errors summary view")
+
+### Scheduling message reprocessing
+
+Click on the "Failed Messages" button at the top of the page to see all failed messages ingested by the platform, grouped by the exception type and stack trace.
+
+![Service Pulse Failed Messages](docs/service-pulse-dashboard-failed-messages-groups.png "Failed messages grouping")
+
+Drill into an existing group to see the list of individual processing failures. Clicking on any of the rows in the list shows detailed information of a given failed message in the headers and message body tabs.
+
+A failed message can be scheduled for reprocessing by clicking the `Retry message` button.
+
+> [!NOTE]
+> It may take several seconds after retrying a message for it to appear again in the consumer's input queue
+
+![Service Pulse Failed Message View](docs/service-pulse-failed-message-view.png "Failed message details view")
+
+### Editing messages before reprocessing
+
+Go to the details page for one of the failed messages and click the `Edit & retry` button. The pop-up window shows the headers collection and the message body in two separate tabs.
+
+Navigate to the `Message Body` tab and change some of the contents of the message, ensuring it's still valid JSON matching the message type, and click "Retry" to schedule the message for reprocessing.
+
+> [!WARNING]
+> Changing or deleting header values may change or cause issues with the subsequent re-processing. It is recommended that these values are not changed if you are unsure of their purpose.
+
+![Edit Message View](docs/service-pulse-edit-before-retry.png "Edit & Retry view showing the message body")
+
+### Viewing retries
+
+Return to the showcase UI to see that the retries have now been successfully handled.
+
+### Troubleshooting
+
+Having issues?
+
+- Check logs in docker. Ensure that there are no port clashes with existing containers or services on your machine.
+- Ask any questions on [our forum](https://discuss.particular.net/tag/masstransit)