Skip to content

Commit a3540bc

Browse files
authored
Merge pull request #13 from signadot/update-readme
Update readme
2 parents 3ef1f9a + f2b996b commit a3540bc

File tree

3 files changed

+55
-81
lines changed

3 files changed

+55
-81
lines changed

README.md

Lines changed: 55 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@
33
</p>
44

55

6-
**[Online Boutique](https://microservices.honeydemo.io)** is a cloud-native microservices demo application. Online
7-
Boutique consists of a 10-tier microservices application, writen in 5 different languages: Go, Java, .NET, Node, and
8-
Python. The application is a web-based e-commerce platform where users can browse items, add them to a cart, and
9-
purchase them.
10-
11-
**[Honeycomb](https://honeycomb.io)** uses this application to demonstrate use of technologies like Kubernetes, gRPC,
12-
and OpenTelemetry. This application works on any Kubernetes cluster. It’s **easy to deploy with little to no
6+
**[Online Boutique](https://microservices.honeydemo.io)** is a cloud-native
7+
microservices demo application. Online Boutique consists of a 10-tier
8+
microservices application, written in 5 different languages: Go, Java, .NET,
9+
Node, and Python. The application is a web-based e-commerce platform where users
10+
can browse items, add them to a cart, and purchase them.
11+
12+
**[Signadot](https://signadot.com)** uses this application to demonstrate the
13+
use of technologies like Kubernetes, gRPC, and OpenTelemetry. This application
14+
works on any Kubernetes cluster. It’s **easy to deploy with little to no
1315
configuration**.
1416

1517
## Screenshots
@@ -20,24 +22,29 @@ configuration**.
2022

2123
## OpenTelemetry
2224

23-
Online Boutique is instrumented using the [OpenTelemetry](https://opentelemetry.io) framework. There are simple and
24-
advanced instrumentation techniques offered by OpenTelemetry that are leveraged in the application. Each service in
25-
the [src](./src) folder explains how OpenTelemetry was used with specific code examples.
25+
Online Boutique is instrumented using the
26+
[OpenTelemetry](https://opentelemetry.io) framework. There are simple and
27+
advanced instrumentation techniques offered by OpenTelemetry that are leveraged
28+
in the application. Each service in the [src](./src) folder explains how
29+
OpenTelemetry was used with specific code examples.
2630

2731
## Development
2832

2933
### Prerequisites
3034

3135
- [Docker for Desktop](https://www.docker.com/products/docker-desktop)
32-
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl), a CLI to interact with Kubernetes
33-
- [skaffold]( https://skaffold.dev/docs/install/), a tool that builds and deploys Docker images in bulk
36+
- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl), a CLI to interact
37+
with Kubernetes
38+
- [skaffold]( https://skaffold.dev/docs/install/), a tool that builds and
39+
deploys Docker images in bulk
3440
- [Helm](https://helm.sh), a package manager for Kubernetes
3541

3642
### Install
3743

3844
1. Launch a local Kubernetes cluster with one of the following options:
3945

40-
- To launch **Minikube** (tested with Ubuntu Linux). Please, ensure that the local Kubernetes cluster has at least:
46+
- To launch **Minikube** (tested with Ubuntu Linux). Please, ensure that the
47+
local Kubernetes cluster has at least:
4148
- 4 CPUs
4249
- 4.0 GiB memory
4350
- 32 GB disk space
@@ -50,41 +57,38 @@ minikube start --cpus=4 --memory 4096 --disk-size 32g
5057
- set CPUs to at least 3, and Memory to at least 6.0 GiB
5158
- on the "Disk" tab, set at least 32 GB disk space
5259

53-
2. Run `kubectl get nodes` to verify you're connected to the respective control plane.
54-
55-
3. Install the [OpenTelemetry Collector Helm chart](https://github.com/honeycombio/helm-charts/tree/main/charts/opentelemetry-collector) from Honeycomb.
56-
Specify your Honeycomb API key when installing the Helm chart.
57-
```shell
58-
helm repo add honeycomb https://honeycombio.github.io/helm-charts
59-
helm install opentelemetry-collector honeycomb/opentelemetry-collector \
60-
--set honeycomb.apiKey=YOUR_API_KEY \
61-
--values ./kubernetes-manifests/additional_resources/opentelemetry-collector-values.yaml
62-
```
60+
2. Run `kubectl get nodes` to verify you're connected to the respective control
61+
plane.
6362

64-
4. Run `skaffold run` (first time will be slow, it can take ~20 minutes). This will build and deploy the application.
65-
If you need to rebuild the images automatically as you refactor the code, run `skaffold dev` command.
63+
3. Run `skaffold run` (first time will be slow, it can take ~20 minutes). This
64+
will build and deploy the application. If you need to rebuild the images
65+
automatically as you refactor the code, run `skaffold dev` command.
6666

67-
5. Run `kubectl get pods` to verify the Pods are ready and running.
67+
4. Run `kubectl get pods` to verify the Pods are ready and running.
6868

69-
6. Access the web frontend through your browser
69+
5. Access the web frontend through your browser
7070

7171
- **Minikube** requires you to run a command to access the frontend service:
7272
```shell
7373
minikube service frontend-external
7474
```
7575

76-
- **Docker For Desktop** should automatically provide the frontend at http://localhost:80
76+
- **Docker For Desktop** should automatically provide the frontend at
77+
http://localhost:80
7778

7879

7980
### Cleanup
8081

81-
If you've deployed the application with `skaffold run` command, you can run `skaffold delete` to clean up the deployed resources.
82+
If you've deployed the application with `skaffold run` command, you can run
83+
`skaffold delete` to clean up the deployed resources.
8284

8385
## Architecture
8486

85-
**Online Boutique** is composed of 10 microservices (plus a load generator) written in 5 different languages that communicate with each other over gRPC.
87+
**Online Boutique** is composed of 10 microservices (plus a load generator)
88+
written in 5 different languages that communicate with each other over gRPC.
8689

87-
[![Architecture of microservices](./docs/img/architecture-diagram.png)](./docs/img/architecture-diagram.png)
90+
[![Architecture of
91+
microservices](./docs/img/architecture-diagram.png)](./docs/img/architecture-diagram.png)
8892

8993
Find **Protocol Buffers Descriptions** at the [`./pb` directory](./pb).
9094

@@ -104,45 +108,34 @@ Find **Protocol Buffers Descriptions** at the [`./pb` directory](./pb).
104108

105109
## Features
106110

107-
- **[Kubernetes](https://kubernetes.io):**
108-
The app is designed to run on Kubernetes
109-
- **[gRPC](https://grpc.io):** Microservices use a high volume of gRPC calls to communicate to each other.
110-
- **[OpenTelemetry](https://opentelemetry.io/) Tracing:** Most services are instrumented using OpenTelemetry trace
111-
providers for gRPC/HTTP.
112-
- **[Skaffold](https://skaffold.dev):** Application is deployed to Kubernetes with a single command using Skaffold.
113-
- **Synthetic Load Generation:** The application demo comes with a background job that creates realistic usage patterns
114-
on the website using
111+
- **[Kubernetes](https://kubernetes.io):** The app is designed to run on
112+
Kubernetes
113+
- **[gRPC](https://grpc.io):** Microservices use a high volume of gRPC calls to
114+
communicate to each other.
115+
- **[OpenTelemetry](https://opentelemetry.io/) Tracing:** Most services are
116+
instrumented using OpenTelemetry trace providers for gRPC/HTTP.
117+
- **[Skaffold](https://skaffold.dev):** Application is deployed to Kubernetes
118+
with a single command using Skaffold.
119+
- **Synthetic Load Generation:** The application demo comes with a background
120+
job that creates realistic usage patterns on the website using
115121
[Locust](https://locust.io/) load generator.
116122

117123
## History
118124

119-
This project originated from the excellent Google Cloud
120-
Platform [Microservices Demo](https://github.com/GoogleCloudPlatform/microservices-demo). It was forked in 2021, before
121-
significant changes were performed. All application telemetry which was previously done with OpenCensus and Stackdriver,
122-
was moved to use [OpenTelemetry](https://opentelemetry.io) for application telemetry, with tracing export intended for
123-
an OpenTelemetry Collector. Additional instrumentation is leveraged throughout the application to show some basic and
124-
advanced capabilities of OpenTelemetry. This application is used as a demo platform for the Honeycomb team, and many
125-
changes were made to the application code so it will break in ways that make for a more compelling demonstration of the
126-
Honeycomb platform.
125+
This project originated from Honeycomb's [Microservices
126+
Demo](https://github.com/honeycombio/microservices-demo/), which itself was
127+
derived from the excellent Google Cloud Platform [Microservices
128+
Demo](https://github.com/GoogleCloudPlatform/microservices-demo). It was forked
129+
in 2022.
127130

128131
## Application demo
129132

130-
This application will exhibit a problem meant to be discovered with ease using the [Honeycomb](https://honeycomb.io)
131-
platform.
132-
133-
The checkout service has a memory leak, cause by an internal cache store. This service has tight Kubernetes
134-
pod/container memory limits, so the leak will cause out of memory crashes, resulting in a pod restart after
135-
approximately 4 hours. Code in the checkout service will introduce additional delays in the form of SQL calls
136-
under `getDiscounts`. The number of SQL calls made will increase as the cache size increases, creating exponentially
137-
increasing latency. There is additional code in the frontend service, which will introduce a specific userid (20109)
138-
after the cache limit from checkout has reached a specific threshold. This results in a pattern where a single user from
139-
a pool of thousands, receiving a bad experience that continues to get worse.
140-
141-
When using Honeycomb BubbleUp, and combined with the Honeycomb SLO feature, understanding the single user from the high
142-
cardinality pool of thousands of user ids is easy to do. Honeycomb allows the user to ask novel questions from the data,
143-
to quickly understand the memory leak and cache problem in code.
133+
This application will exhibit usage of Sandbox environments using the
134+
[Signadot](https://signadot.com) platform. See [feature testing
135+
guide](https://github.com/signadot/microservices-demo/blob/main/docs/feature-testing.md)
136+
for more details.
144137

145138

146139
---
147140

148-
This is not an official Honeycomb or Google project.
141+
This is not an official Signadot or Google project.

src/checkoutservice/README.md

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -93,14 +93,3 @@ Setting orderid into Baggage
9393
bags, _ = bags.SetMember(orderIDMember)
9494
ctx = baggage.ContextWithBaggage(ctx, bags)
9595
```
96-
97-
## Demo Story code
98-
99-
In order to produce an effective demo story, this service includes additional functionality.
100-
This service will grow an internal cache with each request.
101-
Eventually, the cache size will grow large enough to cause an out of memory (OOM) error and crash the service.
102-
The cache size is exposed via an internal call, so the frontend can properly assign a problematic userid when a cache size threshold is reached.
103-
When an order is placed, an additional delay through `getDiscounts` may be introduced.
104-
In this function, if a random chance exists to call the `loadDiscountFromDatabase` function, which will introduce a synthetic delay based on cache size.
105-
The synthetic delay is manifested as a series of spans making mock database calls.
106-
User "20109", whom should only show up when cache size is high, will have a higher likelihood to exhibit the delay.

src/frontend/README.md

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -110,11 +110,3 @@ The userid and requestid will be available to all downstream spans.
110110
```
111111

112112
Baggage is propagated to downstream services, but by default it is not exported to your telemetry backend.
113-
A Span Processor that explicitly exports Baggage is required to export this data to a telemetry backend like Honeycomb.
114-
115-
## Demo Story code
116-
117-
In order to produce an effective demo story, this service includes additional functionality.
118-
The `ensureSessionID` function in `middleware.go` assigns user ids in a random fashion, which may be affected under other random condition, when the cache size from the checkout service exceeds a threshold.
119-
The application will enter a degraded state of performance when cache size climbs.
120-
The checkout service has code to continuously grow a cache, until memory is exhausted and the service crashes with an out of memory (OOM) error.

0 commit comments

Comments
 (0)