Skip to content

Commit 6c23140

Browse files
tmiddlet2666tmiddlet2666
committed
Add documnetation
1 parent 33d7b15 commit 6c23140

File tree

6 files changed

+239
-11
lines changed

6 files changed

+239
-11
lines changed

‎docs/reference/members.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
=== Overview
1616
There are various cluster commands that allow you to work with and manage cluster members.
1717
18-
* <<get-members, `cohctl get members`>> - displays the members for a cluster
18+
* <<get-members, `cohctl get members`>> - initializes local monitoring for Coherence
1919
* <<get-network-stats, `cohctl get network-stats`>> - displays all member network statistics for a cluster
2020
* <<get-p2p-stats, `cohctl get p2p-stats`>> - displays point-to-point network statistics for a specific member
2121
* <<describe-member, `cohctl describe member`>> - shows information related to a specific member

‎docs/reference/monitoring.adoc‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2025 Oracle and/or its affiliates.
4+
Licensed under the Universal Permissive License v 1.0 as shown at
5+
https://oss.oracle.com/licenses/upl.
6+
7+
///////////////////////////////////////////////////////////////////////////////
8+
9+
= Local Monitoring
10+
:description: Coherence CLI - Local Monitoring
11+
:keywords: oracle coherence, coherence-cli, documentation, management, cli, monitoring, grafana, prometheus, metrics
12+
13+
== Local Monitoring
14+
15+
=== Overview
16+
There are various commands that allow you to initialize, start and stop a local monitoring stack using Grafana and Prometheus. This
17+
allows you gain insight into your local development clusters using the pre-built dashboards.
18+
19+
After using `cohctl monitoring init`, the directory `/Users/timbo/.cohctl/monitoring` contains a complete `docker compose` project.
20+
You can manually start/ stop using `docker compose` from that directory, or use the <<start-monitoring,`start monitoring`>> or <<stop-monitoring,`stop monitoring`>> convenience commands. Prometheus scrapes local metrics ports from 9612 -> 9169 for any Coherence clusters with metrics enabled.
21+
22+
After you start the monitoring you can start a local cluster using `cohctl start cluster my-cluster -t 9612` to enable metrics.
23+
24+
See the Coherence documentation to {commercial-docs-base-url}/manage/using-coherence-metrics.html[setup up Coherence metrics] on your own cluster.
25+
26+
NOTE: You must have a `docker` version installed and running on your machine that includes the updated `docker compose` command.
27+
28+
* <<init-monitoring, `cohctl init monitoring`>> - initialize local monitoring for Coherence
29+
* <<start-monitoring, `cohctl start monitoring`>> - starts the local monitoring stack
30+
* <<stop-monitoring, `cohctl stop monitoring`>> - stops the local monitoring stack
31+
* <<get-monitoring, `cohctl get monitoring`>> - gets the current monitoring stack status
32+
33+
34+
[#init-monitoring]
35+
==== Initialize Monitoring Stack
36+
37+
include::../../build/_output/docs-gen/init_monitoring.adoc[tag=text]
38+
39+
[source,bash]
40+
----
41+
cohctl init monitoring
42+
----
43+
44+
Output:
45+
[source,bash]
46+
----
47+
This command will:
48+
1. Create a directory /Users/timbo/.cohctl/monitoring
49+
2. Download Grafana dashboards
50+
2. Download docker compose files
51+
3. Pull Grafana and Prometheus images
52+
53+
Are you sure you want to initialize monitoring? (y/n) y
54+
55+
Ensuring directories...
56+
Downloading Grafana dashboards...
57+
- cache-details-dashboard.json
58+
- cache-store-details-dashboard.json
59+
- caches-summary-dashboard.json
60+
- coherence-dashboard-main.json
61+
- elastic-data-summary-dashboard.json
62+
- executor-details.json
63+
- executors-summary.json
64+
- federation-details-dashboard.json
65+
- federation-summary-dashboard.json
66+
- grpc-proxy-details-dashboard.json
67+
- grpc-proxy-summary-dashboard.json
68+
- http-servers-summary-dashboard.json
69+
- machines-summary-dashboard.json
70+
- member-details-dashboard.json
71+
- members-summary-dashboard.json
72+
- persistence-summary-dashboard.json
73+
- proxy-server-detail-dashboard.json
74+
- proxy-servers-summary-dashboard.json
75+
- service-details-dashboard.json
76+
- services-summary-dashboard.json
77+
- topic-details-dashboard.json
78+
- topic-subscriber-details.json
79+
- topic-subscriber-group-details.json
80+
- topics-summary-dashboard.json
81+
Downloading docker compose files...
82+
- grafana.ini
83+
- dashboards.yaml
84+
- datasources.yaml
85+
- docker-compose.yaml
86+
- prometheus.yaml
87+
Pulling docker images...
88+
Issuing docker pull prom/prometheus:v2.53.4
89+
v2.53.4: Pulling from prom/prometheus
90+
Digest: sha256:502ad90314c7485892ce696cb14a99fceab9fc27af29f4b427f41bd39701a199
91+
Status: Image is up to date for prom/prometheus:v2.53.4
92+
docker.io/prom/prometheus:v2.53.4
93+
Issuing docker pull grafana/grafana:11.6.2
94+
11.6.2: Pulling from grafana/grafana
95+
Digest: sha256:a3464c5dadc2e16aaeb813aead8c852e81cc7bbfa851c66d96f016d5257b9848
96+
Status: Image is up to date for grafana/grafana:11.6.2
97+
docker.io/grafana/grafana:11.6.2
98+
operation completed
99+
100+
Note: You can change the grafana and prometheus image versions by editing:
101+
/Users/timbo/.cohctl/monitoring/docker-compose.yaml
102+
----
103+
104+
NOTE: The directory `/Users/timbo/.cohctl/monitoring` contains a complete `docker compose` project.
105+
You can manually start/ stop using `docker compose` from that directory, or use the `start monitoring` or `stop monitoring` convenience commands.
106+
You can also update the Grafana and Prometheus image versions in the `docker-compse.yaml` file in this directory.
107+
108+
109+
[#start-monitoring]
110+
==== Start Monitoring Stack
111+
112+
include::../../build/_output/docs-gen/start_monitoring.adoc[tag=text]
113+
114+
[source,bash]
115+
----
116+
cohctl start monitoring
117+
----
118+
119+
Output:
120+
[source,bash]
121+
----
122+
Issuing docker compose -f /Users/timbo/.cohctl/monitoring/docker-compose.yaml up -d
123+
Network monitoring_coherence Creating
124+
Network monitoring_coherence Created
125+
Container monitoring-prometheus-1 Creating
126+
Container monitoring-grafana-1 Creating
127+
Container monitoring-grafana-1 Created
128+
Container monitoring-prometheus-1 Created
129+
Container monitoring-grafana-1 Starting
130+
Container monitoring-prometheus-1 Starting
131+
Container monitoring-prometheus-1 Started
132+
Container monitoring-grafana-1 Started
133+
134+
Open the Grafana dashboard at http://localhost:3000/d/coh-main/coherence-dashboard-main, using admin/admin
135+
136+
Issuing docker ps
137+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
138+
03d14608f5e2 prom/prometheus:v2.53.4 "/bin/prometheus --c…" Less than a second ago Up Less than a second 0.0.0.0:9090->9090/tcp monitoring-prometheus-1
139+
5dc519fd544b grafana/grafana:11.6.2 "/run.sh" Less than a second ago Up Less than a second 0.0.0.0:3000->3000/tcp monitoring-grafana-1
140+
----
141+
142+
Wait for around 30 seconds, before accessing the Grafana dashboard at http://localhost:3000/d/coh-main/coherence-dashboard-main using the username/password mentioned above.
143+
144+
NOTE: This is local only setup for monitoring your development clusters, is not meant for production use.
145+
146+
[#stop-monitoring]
147+
==== Stop Monitoring Stack
148+
149+
include::../../build/_output/docs-gen/stop_monitoring.adoc[tag=text]
150+
151+
[source,bash]
152+
----
153+
cohctl stop monitoring
154+
----
155+
156+
Output:
157+
[source,bash]
158+
----
159+
Are you sure you want to stop monitoring? (y/n) y
160+
Issuing docker compose -f /Users/timbo/.cohctl/monitoring/docker-compose.yaml down
161+
Container monitoring-grafana-1 Stopping
162+
Container monitoring-prometheus-1 Stopping
163+
Container monitoring-prometheus-1 Stopped
164+
Container monitoring-prometheus-1 Removing
165+
Container monitoring-prometheus-1 Removed
166+
Container monitoring-grafana-1 Stopped
167+
Container monitoring-grafana-1 Removing
168+
Container monitoring-grafana-1 Removed
169+
Network monitoring_coherence Removing
170+
Network monitoring_coherence Removed
171+
Issuing docker ps
172+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
173+
----
174+
175+
[#get-monitoring]
176+
==== Get Monitoring Stack Status
177+
178+
include::../../build/_output/docs-gen/get_monitoring.adoc[tag=text]
179+
180+
[source,bash]
181+
----
182+
cohctl get monitoring
183+
----
184+
185+
Output:
186+
[source,bash]
187+
----
188+
Monitoring status
189+
Grafana: http://localhost:3000/d/coh-main/coherence-dashboard-main
190+
Image: grafana/grafana:11.6.2
191+
Status: ok, version=11.6.2
192+
Prometheus: http://localhost:9090/
193+
Image: prom/prometheus:v2.53.4
194+
Status: Prometheus Server is Healthy.
195+
196+
Compose: /Users/timbo/.cohctl/monitoring/docker-compose.yaml
197+
Docker
198+
Issuing docker ps
199+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
200+
ac74f5b13702 prom/prometheus:v2.53.4 "/bin/prometheus --c…" About a minute ago Up About a minute 0.0.0.0:9090->9090/tcp monitoring-prometheus-1
201+
6c550a1f58d1 grafana/grafana:11.6.2 "/run.sh" About a minute ago Up About a minute 0.0.0.0:3000->3000/tcp monitoring-grafana-1
202+
----
203+
204+
=== See Also
205+
206+
* {commercial-docs-base-url}/manage/using-coherence-metrics.html[Setting up Coherence Metrics]
207+
* xref:create_clusters.adoc[Creating Development Clusters]
208+
209+
210+

‎docs/reference/overview.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,5 +206,16 @@ Experimental command to monitor clusters with text UI.
206206
--
207207
Experimental command to create example starter Maven project integrating Coherence and various frameworks.
208208
--
209+
====
210+
211+
[PILLARS]
212+
====
213+
214+
[CARD]
215+
.Local Monitoring
216+
[link=monitoring.adoc]
217+
--
218+
Initialize and run a local monitoring stack using Grafana, Prometheus and Docker.
219+
--
209220
210221
====

‎docs/sitegen.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@ backend:
110110
- "create_clusters.adoc"
111111
- "monitor_clusters.adoc"
112112
- "create_starter.adoc"
113+
- "monitoring.adoc"
113114
- type: "PAGE"
114115
title: "Security"
115116
source: "docs/security/overview.adoc"

pkg/cmd/observability.go renamed to pkg/cmd/monitoring.go

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ const (
2525
monitoringDirectory = "monitoring"
2626
dashboardsDirectory = "dashboards"
2727
dashboardBaseURL = "https://raw.githubusercontent.com/oracle/coherence-operator/refs/heads/main/dashboards/grafana"
28-
configBaseURL = "https://raw.githubusercontent.com/oracle/coherence-cli/refs/heads/observability/monitoring"
29-
//configBaseURL = "https://raw.githubusercontent.com/oracle/coherence-cli/refs/heads/main/monitoring"
28+
//configBaseURL = "https://raw.githubusercontent.com/oracle/coherence-cli/refs/heads/observability/monitoring"
29+
configBaseURL = "https://raw.githubusercontent.com/oracle/coherence-cli/refs/heads/main/monitoring"
3030
grafanaPort = 3000
3131
prometheusPort = 9090
3232
dockerComposeYAML = "docker-compose.yaml"
@@ -72,10 +72,10 @@ var (
7272
// initMonitoringCmd represents the init monitoring command.
7373
var initMonitoringCmd = &cobra.Command{
7474
Use: "monitoring",
75-
Short: "initializes local monitoring for Coherence",
75+
Short: "initialize local monitoring for Coherence",
7676
Long: `The 'init monitoring' initializes local monitoring for Coherence.
7777
This involves downloading Grafana and Prometheus docker images and downloading
78-
docker compose files and related dashboards to ~/.cohctl/monitoring directory.
78+
docker compose files and related dashboards to the ''~/.cohctl/monitoring' directory.
7979
Use the 'start monitoring' command to start local Grafana and Prometheus to
8080
monitor local Coherence clusters.`,
8181
Args: cobra.ExactArgs(0),
@@ -141,7 +141,7 @@ type grafanaStatus struct {
141141
// getMonitoringCmd represents the get monitoring command.
142142
var getMonitoringCmd = &cobra.Command{
143143
Use: "monitoring",
144-
Short: "returns monitoring status",
144+
Short: "return monitoring status",
145145
Long: `The 'get monitoring' gets the monitoring status and ensures
146146
the environment is setup correctly.`,
147147
Args: cobra.ExactArgs(0),
@@ -155,7 +155,7 @@ the environment is setup correctly.`,
155155
promURL = fmt.Sprintf("http://localhost:%v/", prometheusPort)
156156
promHealthURL = fmt.Sprintf("%s-/healthy", promURL)
157157
grafanaURL = fmt.Sprintf("http://localhost:%v/d/coh-main/coherence-dashboard-main", grafanaPort)
158-
grafanaHealthURL = fmt.Sprintf("%sapi/health", grafanaURL)
158+
grafanaHealthURL = fmt.Sprintf("http://localhost:%d/api/health", grafanaPort)
159159
)
160160

161161
if err != nil {
@@ -198,8 +198,8 @@ the environment is setup correctly.`,
198198
// startMonitoringCmd represents the start monitoring command.
199199
var startMonitoringCmd = &cobra.Command{
200200
Use: "monitoring",
201-
Short: "starts the monitoring stack",
202-
Long: `The 'start monitoring' starts the monitoring stack, Grafana and
201+
Short: "start the local monitoring stack",
202+
Long: `The 'start monitoring' starts the local monitoring stack, Grafana and
203203
Prometheus using docker compose.`,
204204
Args: cobra.ExactArgs(0),
205205
RunE: func(cmd *cobra.Command, _ []string) error {
@@ -227,8 +227,8 @@ Prometheus using docker compose.`,
227227
// stopMonitoringCmd represents the stop command.
228228
var stopMonitoringCmd = &cobra.Command{
229229
Use: "monitoring",
230-
Short: "stops the monitoring stack",
231-
Long: `The 'stop monitoring' stops the monitoring stack, Grafana and Prometheus
230+
Short: "stop the local monitoring stack",
231+
Long: `The 'stop monitoring' stops the local monitoring stack, Grafana and Prometheus
232232
using docker compose.`,
233233
Args: cobra.ExactArgs(0),
234234
RunE: func(cmd *cobra.Command, _ []string) error {

‎scripts/generate-doc-snippets.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,12 @@ create_doc $DOCS_DIR/get_service_description "${COHCTL} get service-description
121121
create_doc $DOCS_DIR/get_management "${COHCTL} get management --help"
122122
create_doc $DOCS_DIR/set_management "${COHCTL} set management --help"
123123

124+
# Monitoring
125+
create_doc $DOCS_DIR/init_monitoring "${COHCTL} init monitoring --help"
126+
create_doc $DOCS_DIR/start_monitoring "${COHCTL} start monitoring --help"
127+
create_doc $DOCS_DIR/stop_monitoring "${COHCTL} stop monitoring --help"
128+
create_doc $DOCS_DIR/get_monitoring "${COHCTL} get monitoring --help"
129+
124130
# Caches
125131
create_doc $DOCS_DIR/get_caches "${COHCTL} get caches --help"
126132
create_doc $DOCS_DIR/get_cache_stores "${COHCTL} get cache-stores --help"

0 commit comments

Comments
 (0)