You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+33-66
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,36 @@
1
1
# Horus
2
2
3
-
A test project for learning microservices observability through: **centralized logging** and **distributed tracing**.
3
+
A project for learning about microservices observability.
4
4
5
-
## Requirements
5
+
* Centralized Logging
6
+
* Distributed Tracing
7
+
8
+
## Development Requirements
6
9
7
10
- Docker Compose v1.23.2
8
-
- OSX or GNU/Linux operating system
11
+
- OSX or GNU/Linux
9
12
10
13
## Development Setup
11
14
12
15
1. Clone this repo and open the root folder in an IDE like *Visual Studio Code*.
13
16
14
17
2. For each microservice, rename `example.env` to `.env` and supply the needed secrets.
15
-
> TODO: Is there a way to eliminate this friction?
18
+
> TODO: Eliminate this friction.
16
19
17
20
3. Start all microservices in *development mode*.
18
21
19
22
docker-compose -f docker-compose.dev.yml \
20
23
up -d --build
21
24
22
-
> Development mode is important for 2 reasons.
23
-
> - Changes to a service's source files will automatically restart/rebuild the docker service to show the changes.
24
-
> - You can attach a remote debugger from your IDE to the docker process for seemless debugging like placing breakpoints and watching variables.
25
-
> - NOTE: When you edit a service's source files, the docker process will restart, severing your remote debugger connection. So, you'd need to reattach the debugger again.
26
-
27
-
4. Attach the IDE's debugger to the desired service. Follow these steps in Visual Studio Code: *shift+cmd+D > Select a debug configuration > F5*.
28
-
> All Visual Studio Code debug configurations are stored in *.vscode/launch.json*. You can modify configs as you see fit.
25
+
> In Development Mode
26
+
>
27
+
> - You can attach a remote debugger to a running service Docker for seemless debugging like placing breakpoints and watching variables.
28
+
> - Changes to source files will automatically restart the corresponding docker service.
29
29
30
-
5. To view tracing information, access the Jaeger UI on http://localhost:16686
30
+
4. Optionally, attach the IDE's debugger to a service as follows in Visual Studio Code: *shift+cmd+D > Select a debug configuration > F5*.
31
+
> All vscode debug configurations are stored in *.vscode/launch.json*. You can modify configs as you see fit.
31
32
32
-
> In development, the tracing backend is a single service (*tracing-backend*) for simplicity, and traces are stored in-memory. However, in production, the tracing backend will setup as multiple services (running on multiple containers), and traces will be persisted in an external store like Elasticsearch.
33
+
5. Visit http://localhost:16686 to view traces.
33
34
34
35
### Useful dev commands
35
36
@@ -39,87 +40,53 @@ A test project for learning microservices observability through: **centralized l
39
40
# stop all services
40
41
docker-compose -f docker-compose.dev.yml down
41
42
42
-
# restart only all [or specific] service
43
+
# restart all [or specific] service
43
44
docker-compose -f docker-compose.dev.yml \
44
45
up -d --no-deps --build [service-name]
45
46
46
47
# tail logs from all [or specific] service
47
48
docker-compose -f docker-compose.dev.yml \
48
49
logs -f [service-name]
50
+
51
+
# see how an image was built
52
+
docker history <image-name>
49
53
50
-
## Production Setup
51
-
52
-
TODO
53
-
54
-
- Signup with an ELK SaaS provider like [Logz.io](logz.io) to obtain an authentication token. Then for each microservice, rename `example.env` to `.env` and supply the needed secrets.
55
-
- Then log into your ELK SaaS and view your microservices logs.
56
-
57
-
## Project Documentation
54
+
## Project Architecture
58
55
59
-
### System Architecture
56
+
### Logging Infrastructure
60
57
61
58
62
59
63
-
I wrote an accompanying [article](https://hackernoon.com/monitoring-containerized-microservices-with-a-centralized-logging-architecture-ba6771c1971a)explaining this architecture.
60
+
Read this [article](https://hackernoon.com/monitoring-containerized-microservices-with-a-centralized-logging-architecture-ba6771c1971a)for more details.
64
61
65
-
##Notes
62
+
### Tracing Infrastructure
66
63
67
-
- You can update a single service/container while the entire suite is running using the following command
> `--build` recreates the container from its image/dockerfile and `--no-deps` ensures dependent services aren't affected.
70
+
### TODO (Improvement Considerations)
76
71
77
-
-Some docker images on dockerhub don't list the dockerfile, so to figure out some information like which ports are exposed by default, you can run `docker history <image>`.
72
+
-Research **jaeger-operator**
78
73
79
-
-TODO: research **jaeger-operator**
74
+
-Name Duplication: The value of the `API_SERVER_ADDRESS` variable in *user-simulator/.env* depends on the service name `api-server` specified in *docker-compose.yml*. If we rename the service, we must also change the variable. Is there a way to make this DRY?
80
75
81
-
### Docker Networking
76
+
- In the log-shipper container, I had to install a logz.io-specific plugin. Can't this step be eliminated since fluentd is capable of connecting to https endpoints without plugins?
82
77
83
-
By default each containerized process runs in an isolated network namespace. For inter-container communication, place them in the same network namespace...as seen in *docker-compose.yml*.
78
+
- Use sub-second precision for fluentd timestamps (probably best to use nanoseconds.)
84
79
85
80
### Best practices
86
81
87
82
1. You can pass secrets for a microservice using the `env_file` attribute in *docker-compose.yml*.
88
83
2. Microservices can communicate using their service names if they are in the same docker network.
89
84
90
-
### How do you debug an app running in a container (i.e breakpoints and watch variables etc.)?
91
-
?
92
-
- You can tail the logs from all services using `docker-compose [-f <file>] logs -f`.
93
-
94
-
### Improvement Considerations
95
-
96
-
1.**Name Duplication:** The value of the `API_SERVER_ADDRESS` variable in *user-simulator/.env* depends on the service name `api-server` specified in *docker-compose.yml*. If we rename the service, we must also change the variable. Is there a way to make this DRY?
97
-
98
-
2. In the log-shipper container, I had to install a logz.io-specific plugin. Can't this step be eliminated since fluentd is capable of connecting to https endpoints without plugins?
99
-
100
-
3. Use sub-second precision for fluentd timestamps (probably best to use nanoseconds.)
101
-
102
-
### Environment variables used by Jaeger components
By default each containerized process runs in an isolated network namespace. For inter-container communication, place them in the same network namespace.
0 commit comments