mirror of
https://github.com/postmannen/ctrl.git
synced 2025-01-07 04:49:17 +00:00
update doc
This commit is contained in:
postmannen
parent
9dda8ac68d
commit
2cdf406ec3
9 changed files with 223 additions and 4 deletions
|
|
@ -111,6 +111,7 @@ ctrl supports both the use of flags with env variables. An .env file can also be
|
|||
|-----|-------|------------|
|
||||
|toNode | `string` | A single node to send a message to|
|
||||
|toNodes | `string array` | A comma separated list of nodes to send a message to|
|
||||
|jetstreamToNode| `string array` | JetstreamToNode, the topic used to prefix the stream name with the format NODES.\<JetstreamToNode> |
|
||||
|method | `string` | The request method to use |
|
||||
|methodArgs | `string array` | The arguments to use for the method |
|
||||
|replyMethod | `string` | The method to use for the reply message |
|
||||
|
|
|
|||
BIN
README.pdf
BIN
README.pdf
Binary file not shown.
4
doc/core-messaging.svg
Normal file
4
doc/core-messaging.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 101 KiB |
91
doc/ctrl-drawings.drawio
Normal file
91
doc/ctrl-drawings.drawio
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.7.17 Chrome/128.0.6613.36 Electron/32.0.1 Safari/537.36" version="24.7.17">
|
||||
<diagram name="Page-1" id="nlSWXV44TWduW5NrCRzE">
|
||||
<mxGraphModel dx="812" dy="603" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
|
||||
<root>
|
||||
<mxCell id="0" />
|
||||
<mxCell id="1" parent="0" />
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-1" value="central" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="570" y="50" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-3" value="operator" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="230" y="50" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-4" value="linux1" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="175" y="410" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-5" value="linux1" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="410" y="410" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-6" value="linux1" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="660" y="410" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-9" value="NATS Server" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
|
||||
<mxGeometry x="410" y="220" width="120" height="60" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-10" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="295" y="120" as="sourcePoint" />
|
||||
<mxPoint x="400" y="220" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-12" value="command<br>Upgrade all servers,<br>and restart" style="html=1;verticalLabelPosition=bottom;align=center;labelBackgroundColor=#7EA6E0;verticalAlign=top;strokeWidth=2;strokeColor=#0080F0;shadow=0;dashed=0;shape=mxgraph.ios7.icons.envelope_(message);" vertex="1" parent="1">
|
||||
<mxGeometry x="305" y="120" width="30" height="30" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-13" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="410" y="290" as="sourcePoint" />
|
||||
<mxPoint x="250" y="400" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-14" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="490" y="290" as="sourcePoint" />
|
||||
<mxPoint x="490" y="400" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-15" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="530" y="290" as="sourcePoint" />
|
||||
<mxPoint x="730" y="400" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-17" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="360" y="80" as="sourcePoint" />
|
||||
<mxPoint x="560" y="80" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-18" value="to audit log" style="html=1;verticalLabelPosition=bottom;align=center;labelBackgroundColor=#7EA6E0;verticalAlign=top;strokeWidth=2;strokeColor=#0080F0;shadow=0;dashed=0;shape=mxgraph.ios7.icons.envelope_(message);" vertex="1" parent="1">
|
||||
<mxGeometry x="440" y="40" width="30" height="30" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-19" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="210" y="380" as="sourcePoint" />
|
||||
<mxPoint x="390" y="260" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-20" value="result" style="html=1;verticalLabelPosition=bottom;align=center;labelBackgroundColor=#7EA6E0;verticalAlign=top;strokeWidth=2;strokeColor=#0080F0;shadow=0;dashed=0;shape=mxgraph.ios7.icons.envelope_(message);" vertex="1" parent="1">
|
||||
<mxGeometry x="280" y="280" width="25" height="30" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-21" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="469" y="400" as="sourcePoint" />
|
||||
<mxPoint x="469" y="290" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-23" value="" style="endArrow=classic;html=1;rounded=0;" edge="1" parent="1">
|
||||
<mxGeometry width="50" height="50" relative="1" as="geometry">
|
||||
<mxPoint x="760" y="380" as="sourcePoint" />
|
||||
<mxPoint x="550" y="260" as="targetPoint" />
|
||||
</mxGeometry>
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-28" value="result" style="html=1;verticalLabelPosition=bottom;align=center;labelBackgroundColor=#7EA6E0;verticalAlign=top;strokeWidth=2;strokeColor=#0080F0;shadow=0;dashed=0;shape=mxgraph.ios7.icons.envelope_(message);" vertex="1" parent="1">
|
||||
<mxGeometry x="457.5" y="320" width="25" height="30" as="geometry" />
|
||||
</mxCell>
|
||||
<mxCell id="JB4UHpmZ01gNuVjmXd_b-29" value="result" style="html=1;verticalLabelPosition=bottom;align=center;labelBackgroundColor=#7EA6E0;verticalAlign=top;strokeWidth=2;strokeColor=#0080F0;shadow=0;dashed=0;shape=mxgraph.ios7.icons.envelope_(message);" vertex="1" parent="1">
|
||||
<mxGeometry x="640" y="270" width="25" height="30" as="geometry" />
|
||||
</mxCell>
|
||||
</root>
|
||||
</mxGraphModel>
|
||||
</diagram>
|
||||
</mxfile>
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
|
||||
# Core ctrl
|
||||
|
||||
- [Core overview](./core_overview.md)
|
||||
- [Messaging](./core_messaging_overview.md)
|
||||
- [Message fields](./core_messaging_message_fields.md)
|
||||
- [Message jetstream/broadcast](./core_messaging_jetstream.md)
|
||||
|
|
@ -37,4 +38,5 @@
|
|||
|
||||
# Using ctrl
|
||||
|
||||
- [ctrl as github action runner](usecase-ctrl-as-github-action-runner)
|
||||
- [ctrl as github action runner](usecase-ctrl-as-github-action-runner.md)
|
||||
- [ctrl as prometheus collector](usecase-ctrl-as-prometheus-collector.md)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,28 @@
|
|||
# Message fields
|
||||
|
||||
## Schema for the message structure to use with ctrl
|
||||
|
||||
|Field Name | Value Type | Description|
|
||||
|-----|-------|------------|
|
||||
|toNode | `string` | A single node to send a message to|
|
||||
|toNodes | `string array` | A comma separated list of nodes to send a message to|
|
||||
|jetstreamToNode| `string array` | JetstreamToNode, the topic used to prefix the stream name with the format NODES.\<JetstreamToNode> |
|
||||
|method | `string` | The request method to use |
|
||||
|methodArgs | `string array` | The arguments to use for the method |
|
||||
|replyMethod | `string` | The method to use for the reply message |
|
||||
|replyMethodArgs | `string array` | The arguments to use for the reply method |
|
||||
|ACKTimeout | `int` | The time to wait for a received acknowledge (ACK). 0 for no acknowledge|
|
||||
|retries | `int` | The number of times to retry if no ACK was received |
|
||||
|replyACKTimeout | `int` | The timeout to wait for an ACK message before we retry |
|
||||
|replyRetries | `int` | The number of times to retry if no ACK was received for repply messages |
|
||||
|methodTimeout | `int` | The timeout in seconds for how long we wait for a method to complete |
|
||||
|replyMethodTimeout | `int` | The timeout in seconds for how long we wait for a method to complete for repply messages |
|
||||
|directory | `string` | The directory for where to store the data of the repply message |
|
||||
|fileName | `string` | The name of the file for where we store the data of the reply message |
|
||||
|schedule | [int type value for interval in seconds, int type value for total run time in seconds] | Schedule a message to re run at interval |
|
||||
|
||||
## More detailed description of the fields
|
||||
|
||||
```yaml
|
||||
toNode : "some-node"
|
||||
```
|
||||
|
|
@ -22,9 +45,7 @@ The actual data in the message. This is the field where we put the returned data
|
|||
method : cliCommand
|
||||
```
|
||||
|
||||
What request method type to use, like cliCommand, httpGet..
|
||||
|
||||
All [methods](./core_request_methods.md).
|
||||
What request method type to use, like cliCommand, httpGet, [all methods](./core_request_methods.md).
|
||||
|
||||
```yaml
|
||||
methodArgs :
|
||||
|
|
|
|||
11
doc/src/core_overview.md
Normal file
11
doc/src/core_overview.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
# Core overview
|
||||
|
||||
<style>
|
||||
img {
|
||||
background-color: #FFFFFF;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<p align="center"><img src="https://github.com/postmannen/ctrl/blob/main/doc/core-messaging.svg?raw=true" /></p>
|
||||
</body>
|
||||
89
doc/src/usecase-ctrl-as-prometheus-collector.md
Normal file
89
doc/src/usecase-ctrl-as-prometheus-collector.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# ctrl as prometheus collector
|
||||
|
||||
ctrl can be used to collect collect metrics from various systems. It can for example scrape/read some defined metrics with one node, and deliver the result to another node where you can expose the metrics directly using ctrl's builtin http server, or you could for example inject the metrics data to some database if that is desired. It is totally up to you.
|
||||
|
||||
The example that follows will scrape prometheus metrics with two ctrl nodes, deliver them to a third node called **metrics**, and expose them with the builtin http server. Prometheus can then be used to read all the metrics from the various nodes on the **metrics** node.
|
||||
|
||||
Before you start, make sure to read the **User Guides** section for how to start up a NATS broker, and for general information about setting up ctrl.
|
||||
|
||||
## Node Setup
|
||||
|
||||
### central node
|
||||
|
||||
Start up a ctrl node named **central** that will serve as central for audit logs and other system logs happening with the ctrl nodes. Example of .env file to use.
|
||||
|
||||
```env
|
||||
NODE_NAME=central
|
||||
BROKER_ADDRESS=localhost:4222
|
||||
LOG_LEVEL=info
|
||||
START_PUB_HELLO=60
|
||||
IS_CENTRAL_ERROR_LOGGER=true
|
||||
```
|
||||
|
||||
### collected metrics node
|
||||
|
||||
Start up a node named **metrics** that will serve as the central place where we deliver all the metrics. On this node we expose ctrl's data folder over http. Example .env file below.
|
||||
|
||||
```env
|
||||
NODE_NAME=metrics
|
||||
BROKER_ADDRESS=localhost:4222
|
||||
LOG_LEVEL=info
|
||||
START_PUB_HELLO=60
|
||||
EXPOSE_DATA_FOLDER=localhost:6060
|
||||
```
|
||||
|
||||
### metrics collector nodes
|
||||
|
||||
#### prometheus node exporter
|
||||
|
||||
If don't yet have any metrics to collect, you can start up [prometheus node_exporter](https://github.com/prometheus/node_exporter) to get some local system metrics.
|
||||
|
||||
#### collector node setup
|
||||
|
||||
The following configuration file can be used on all nodes, but for each node started replace with a unique **NODE_NAME**, eg. **node1** and **node2**.
|
||||
|
||||
```env
|
||||
NODE_NAME=node1 #give each node a unique node name
|
||||
BROKER_ADDRESS=localhost:4222
|
||||
LOG_LEVEL=info
|
||||
START_PUB_HELLO=60
|
||||
```
|
||||
|
||||
##### Startup folder
|
||||
|
||||
Each ctrl instance started will have a **startup** folder in it's running directory. Messages in the startup folder will be read at startup, and handled by ctrl.
|
||||
|
||||
We can use the **schedule** field in the message to make ctrl rerun the method of the message at a scheduled interval.
|
||||
|
||||
Put the following message in the **startup** folder on all the nodes that will collect metrics.
|
||||
|
||||
```yaml
|
||||
---
|
||||
- toNodes:
|
||||
# Deliver the message locally
|
||||
- local
|
||||
# Set the node where we send the reply with the result
|
||||
fromNode: central
|
||||
method: httpGet
|
||||
methodArgs:
|
||||
- http://localhost:9100/metrics
|
||||
# Write the result to a file on the fromNode
|
||||
replyMethod: file
|
||||
# The directory which we want to write the result in
|
||||
directory: nodeexporters
|
||||
# The filename we want to write the result to
|
||||
fileName: metrics.html
|
||||
# Schedule rerun of the method every 30 second, for 999999999 seconds.
|
||||
schedule: [30,999999999]
|
||||
```
|
||||
|
||||
## Check the collected metrics
|
||||
|
||||
When all nodes are started, they should start to send metrics to the **metrics** node. We can see the result by using curl on the node named **metrics**.
|
||||
|
||||
```bash
|
||||
http://localhost:6060/nodeexporters/node1/metrics.html
|
||||
http://localhost:6060/nodeexporters/node2/metrics.html
|
||||
```
|
||||
|
||||
If you want to do something further with this example you can install prometheus on the **metrics** node, and direct it to collect read the metrics from the various folders via the url's above.
|
||||
Loading…
Reference in a new issue