Skip to content

Commit 2be7755

Browse files
alhendricksonalhendrickson
authored
Create Quickstart Documentation (#2)
* Start documentation. Created Quickstart steps * Use quickstart script to run it in one line * Setup quickstart with script. Add Node exporter to quickstart
1 parent d791d40 commit 2be7755

File tree

10 files changed

+181
-8
lines changed

10 files changed

+181
-8
lines changed

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
# Custom ignores
2+
observability/examples/simple/observability-simple
3+
4+
5+
# Python ignores
16
# Byte-compiled / optimized / DLL files
27
__pycache__/
38
*.py[cod]

‎observability/docs/get-started/quickstart-manual.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
2+
## Manual Quickstart
3+
4+
The quickstart page uses a script to setup the folders for you.
5+
6+
This page instead details how to do it manually, to provide clarity.
7+
8+
## Step 1: Setup directory
9+
Create the necessary directory structure
10+
```
11+
mkdir -p observability-simple/prometheus/scrape-configs/probers
12+
mkdir -p observability-simple/prometheus/scrape-configs/exporters
13+
```
14+
15+
16+
Download these two files from github, and place in the right folder
17+
18+
- [docker-compose.yml](https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/docker-compose.yml) in observability-simple/
19+
- [prometheus/scrape-configs/probers/probe-simple.yml](https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/prometheus/scrape-configs/probers/probe-simple.yml)
20+
21+
### Step 2: Start the stack
22+
23+
In the folder containing the downloaded files, run:
24+
25+
```bash
26+
docker compose up -d
27+
```
28+
29+
### Step 3: Access the dashboards
30+
Open your web browser and go to:
31+
32+
`localhost/grafana`
33+
34+
You should see the Grafana dashboard displaying the availability of the sample web page.
35+
36+
There it is, you can now see the availability of the cogstack homepage, as well as the observability stack

‎observability/docs/get-started/quickstart.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
## QuickStart
2+
3+
This tutorial guides you through running the simplest setup of the observability stack using example configuration files and Docker Compose.
4+
5+
After completing these steps, you will have a full observability stack running locally, showing the availability of web pages you want to target
6+
7+
### Requirements
8+
9+
- Docker installed ([install Docker](https://docs.docker.com/get-docker/))
10+
- Docker Compose installed ([install Docker Compose](https://docs.docker.com/compose/install/))
11+
- A terminal with network access
12+
13+
### Step 1: Run the Quickstart script
14+
15+
Run this quickstart script to setup the project
16+
```bash
17+
curl https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/quickstart.sh | bash
18+
```
19+
Now go to "http://localhost/grafana" to see the dashboards
20+
21+
Thats everything. The stack is running and you can see the availability.
22+
23+
24+
### Optional Step: Probe your own web page
25+
Now you can look at getting monitoring of your own page
26+
27+
In your current folder, edit the file `prometheus/scrape-configs/probers/probe-simple.yml` that you downloaded from git.
28+
29+
Add the following yml to the bottom of the file:
30+
31+
```yaml
32+
- targets:
33+
- https://google.com
34+
labels:
35+
name: google
36+
job: probe-my-own-site
37+
```
38+
39+
40+
The change should get applied automatically, but if you dont want to wait then run
41+
```
42+
docker compose restart
43+
```
44+
45+
Now refresh the grafana dashboard, and you can see the availability of google.com, it's probably 100%!
46+
47+
48+
## Next steps
49+
This is the end of this quickstart tutorial, that enables probing availability of endpoints.
50+
51+
For the next steps we can:
52+
- Productionise our deployment to enable further features
53+
- Enable *Telemetry* like VM memory usage, and Elasticsearch index size, by running Exporters
54+
- Enable *Alerting* based on our availability and a defined Service Level Objective (SLO)
55+
- Look further into the available dashboards
56+
- Fully customize the stack with our own dashboards, recording rules and metrics
57+
58+
59+
60+
61+

‎observability/docs/get-started/setup-tutorial.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
2+
This page
3+
4+
5+
6+
## Run the Observability Stack using Docker Compose
7+
8+
See the /examples folder for a working example of running this
9+
10+
To setup the stack for your deployment:
11+
- Create prometheus configurations as listed below
12+
- Copy this docker-compose.yml file
13+
- Mount your site config files into `/etc/prometheus/cogstack/site`
14+
- Run with docker compose
15+
16+
To collect metrics from VMs to fill out the dashboards
17+
- Run the Exporters on each VM as detailed below

‎observability/docs/get-started/userguide-tutorial.md‎

Whitespace-only changes.

‎observability/docs/overview.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Cogstack Observability Stack
2+
3+
This project provides observability of a cogstack deployment.
4+
5+
It provides the following features:
6+
- Dashboards for availability
7+
- Telemetry of infrastructure such as host memory usage, and elasticsearch index size
8+
- Alerting based on a defined Service Level Objective (SLO) and burn rates
9+
- Blackbox Probing of services to find service level indicators of uptime and latency
10+
- A working inventory of what is running where
11+
12+
## Contents
13+
14+
See the [Quickstart](./get-started/quickstart.md) to see how to easily run this stack.
15+
16+
17+
18+

‎observability/examples/simple/docker-compose.yml‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ services:
66
image: cogstacksystems/cogstack-observability-prometheus:latest
77
restart: unless-stopped
88
volumes:
9-
- ./prometheus:/etc/prometheus/cogstack/site
9+
- ./prometheus:/etc/prometheus/cogstack/site/
1010
- prometheus-data:/prometheus
1111
networks:
1212
- observability
@@ -17,8 +17,6 @@ services:
1717
- grafana-data:/var/lib/grafana
1818
networks:
1919
- observability
20-
ports:
21-
- '3000:3000'
2220
environment:
2321
- GF_AUTH_ANONYMOUS_ENABLED=true # Allows use of grafana without sign in
2422
- GF_AUTH_ANONYMOUS_ORG_ROLE=Viewer
@@ -29,16 +27,23 @@ services:
2927
restart: unless-stopped
3028
ports:
3129
- "80:80"
32-
- "8080:8080"
3330
volumes:
3431
- /var/run/docker.sock:/var/run/docker.sock:ro # So that Traefik can listen to the Docker events
3532
blackbox-exporter:
3633
image: cogstacksystems/cogstack-observability-blackbox-exporter:latest
3734
restart: unless-stopped
38-
ports:
39-
- "9115:9115"
4035
networks:
41-
- observability-exporters
36+
- observability
37+
node-exporter:
38+
image: prom/node-exporter
39+
restart: unless-stopped
40+
networks:
41+
- observability
42+
labels:
43+
- "traefik.enable=true"
44+
- "traefik.http.routers.node-exporter.rule=PathPrefix(`/node-exporter`)"
45+
- "traefik.http.middlewares.node-exporter-stripprefix.stripprefix.prefixes=/node-exporter"
46+
- "traefik.http.routers.node-exporter.middlewares=node-exporter-stripprefix@docker"
4247
networks:
4348
observability:
4449
driver: bridge

‎observability/examples/simple/prometheus/scrape-configs/exporters/exporters-simple.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
- targets:
2+
- cogstack-observability-node-exporter-1:9100
3+
labels:
4+
job: node_exporter
5+
host: localhost

‎observability/examples/simple/prometheus/scrape-configs/probers/probe-simple.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33
- https://cogstack.org
44
labels:
55
name: cogstack-homepage
6-
job: "probe-simple-example"
6+
job: probe-services

‎observability/examples/simple/quickstart.sh‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#!/bin/bash
2+
set -e
3+
4+
mkdir -p observability-simple/prometheus/scrape-configs/probers
5+
mkdir -p observability-simple/prometheus/scrape-configs/exporters
6+
cd observability-simple
7+
8+
echo "Downloading docker-compose.yml..."
9+
curl -fsSL -o docker-compose.yml \
10+
https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/docker-compose.yml
11+
12+
echo "Downloading probe-simple.yml into prometheus/scrape-configs/probers/..."
13+
curl -fsSL -o prometheus/scrape-configs/probers/probe-simple.yml \
14+
https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/prometheus/scrape-configs/probers/probe-simple.yml
15+
16+
echo "Downloading exporters-simple.yml into prometheus/scrape-configs/exporters/..."
17+
curl -fsSL -o prometheus/scrape-configs/exporters/exporters-simple.yml \
18+
https://raw.githubusercontent.com/CogStack/cogstack-platform-toolkit/main/observability/examples/simple/prometheus/scrape-configs/exporters/exporters-simple.yaml
19+
20+
21+
echo "Setup complete in observability-simple/"
22+
23+
echo "Starting the observability stack"
24+
docker compose up -d
25+
26+
echo "Please open http://localhost/grafana in your browser"

0 commit comments

Comments
 (0)