diff --git a/README.md b/README.md index 8c19ffb..a375926 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,8 @@ ssh -p 2222 localhost If you want log like the [C implementation](https://github.com/skeeto/endlessh), you need to set both CLI arguments `-logtostderr` and `-v=1`, then the log will go to stderr. You can set different log destinations via CLI arguments. +Also check out [examples](./examples/examples.md). + ## Usage Usage of `./endlessh-go` @@ -74,7 +76,7 @@ Usage of `./endlessh-go` ## Metrics -This golang implementation exports the following Prometheus metrics. +Endlessh-go exports the following Prometheus metrics. | Metric | Type | Description | |--------------------------------------|-------|--------------| @@ -99,4 +101,6 @@ The dashboard requires Grafana 8.2. You can import the dashboard from Grafana.com using ID [15156](https://grafana.com/grafana/dashboards/15156) +The dashboard visualizes data for the selected time range. + The IP addresses are clickable and link you to the [ARIN](https://www.arin.net/) database. diff --git a/dashboard/endlessh.json b/dashboard/endlessh.json index a7b7bca..26e7db1 100755 --- a/dashboard/endlessh.json +++ b/dashboard/endlessh.json @@ -308,7 +308,7 @@ "type": "stat" }, { - "datasource": null, + "datasource": "${DS_PROMETHEUS}", "fieldConfig": { "defaults": { "color": { @@ -619,7 +619,7 @@ "type": "stat" }, { - "datasource": null, + "datasource": "${DS_PROMETHEUS}", "fieldConfig": { "defaults": { "color": { @@ -679,7 +679,7 @@ "expr": "(endlessh_client_open_count_total{instance=\"$host\",job=\"$job\"}) - (endlessh_client_closed_count_total{instance=\"$host\",job=\"$job\"} offset $__interval or endlessh_client_open_count_total{instance=\"$host\",job=\"$job\"} * 0)", "instant": false, "interval": "", - "legendFormat": "Current Open Connections", + "legendFormat": "Open Connections", "refId": "current_open" } ], @@ -1131,7 +1131,7 @@ "type": "geomap" }, { - "datasource": null, + "datasource": "${DS_PROMETHEUS}", "fieldConfig": { "defaults": { "color": { @@ -1427,5 +1427,5 @@ "timezone": "", "title": "Endlessh", "uid": "ATIxYkO7k", - "version": 292 + "version": 2 } \ No newline at end of file diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml index b0604bf..5ce80cb 100644 --- a/examples/docker-compose.yml +++ b/examples/docker-compose.yml @@ -50,12 +50,11 @@ services: - GF_SECURITY_ADMIN_PASSWORD=examples volumes: - grafana_var:/var/lib/grafana/ - - grafana_etc:/etc/grafana/ + - ./grafana-datasource.yml:/etc/grafana/provisioning/datasources/prometheus.yml networks: example_network: volumes: prometheus: - grafana_var: - grafana_etc: \ No newline at end of file + grafana_var: \ No newline at end of file diff --git a/examples/examples.md b/examples/examples.md index e69de29..6a98b8d 100644 --- a/examples/examples.md +++ b/examples/examples.md @@ -0,0 +1,24 @@ +# Examples + +## docker compose + +This is an example how to setup endlessh-go, Prometheus, and Grafana using [docker compose](https://docs.docker.com/compose/). The reference of the compose file can be find [here](https://docs.docker.com/compose/compose-file/). + +You also need `prometheus.yml` as a Prometheus configuration. [Here](https://prometheus.io/docs/prometheus/latest/configuration/configuration/) is more about Prometheus configuration. + +Although Grafana data source can be setup manually, to ease the setup, we provision a data source `grafana-datasource.yml` for Grafana. + +To start the stack, in the `examples` folder, run: + +``` +sudo docker-compose up -d +``` + +This example exposes the following ports. + +* **2222**: The SSH port. You may test endlessh-go by run `ssh -p 2222 localhost`. Your SSH client should hang. You can view the log of endlessh-go by run `sudo docker logs endlessh`. +* **2112**: The Prometheus metrics exported by endlessh-go. You can open the your web browser and go to [http://localhost:2112/metrics](http://localhost:2112/metrics) to view the metrics. +* **9090**: Prometheus web interface. Go to [http://localhost:9090](http://localhost:9090) in your web browser for Prometheus. You can check whether the target of endlessh-go is up (Click Status, then Targets). +* **3000**: Grafana. Go to [http://localhost:3000](http://localhost:3000) for Grafana. Use username `examples` and password `examples` to login. + +In this example, we do not [provision a dashboard](https://grafana.com/tutorials/provision-dashboards-and-data-sources/) for Grafana. You need to manually load the endlessh-go dashboard, by either importing it from the Grafana.com using ID [15156](https://grafana.com/grafana/dashboards/15156), or pasting the dashboard JSON text to the text area. See the [Grafana documentation](https://grafana.com/docs/grafana/latest/dashboards/export-import/). Then select *Prometheus* as the data source. diff --git a/examples/grafana-datasource.yml b/examples/grafana-datasource.yml new file mode 100644 index 0000000..8a20526 --- /dev/null +++ b/examples/grafana-datasource.yml @@ -0,0 +1,6 @@ +apiVersion: 1 + +datasources: + - name: Prometheus + type: prometheus + url: prometheus:9090 \ No newline at end of file