mtop 0.2.0

mtop: top for Memcached
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# mtop

![build status](https://github.com/56quarters/mtop/actions/workflows/rust.yml/badge.svg)
[![docs.rs](https://docs.rs/mtop/badge.svg)](https://docs.rs/mtop/)
[![crates.io](https://img.shields.io/crates/v/mtop.svg)](https://crates.io/crates/mtop/)

mtop: `top` for Memcached.

![mtop](/images/mtop.png)

## Features

* Display real-time statistics about your `memcached` servers such as
  * Memory usage/limit
  * Current/max connections
  * Hit ratio
  * Gets/Sets/Evictions
  * Bytes transmitted and received
  * Server CPU usage
* Support for monitoring multiple servers: `mtop example1:11211 example2:11211 example3:11211`

## Install

There are multiple ways to install `mtop` listed below.

### Binaries

TBD

### Cargo

`mtop` along with its dependencies can be downloaded and built from source using the
Rust `cargo` tool. Note that this requires you have a Rust toolchain installed.

To install:

```
cargo install mtop
```

To install as a completely static binary (Linux only):

```
cargo install --target=x86_64-unknown-linux-musl mtop 
```

To uninstall:

```
cargo uninstall mtop
```

### Source

`mtop` along with its dependencies can be built from the latest sources on Github using
the Rust `cargo` tool. Note that this requires you have Git and a Rust toolchain installed.

Get the sources:

```
git clone https://github.com/56quarters/mtop.git && cd mtop
```

Build a binary:

```
cargo build --release
./target/release/mtop --help
```

Build a completely static binary (Linux only):

```
cargo build --target=x86_64-unknown-linux-musl --release
./target/x86_64-unknown-linux-musl/release/mtop --help
```

These binaries should then be copied on to your `$PATH`.

## Usage

`mtop` takes one or more Memcached `host:port` combinations as arguments. Statistics from
each of these  servers will be collected approximately once a second. A maximum of ten
measurements from each server will be kept in memory to use for computations.

If `mtop` is not able to connect to the servers when starting, it will exit after printing
an error message. If `mtop` is not able to connect to servers or fetch statistics from
them _after_ starting, the errors will be logged to a file. The location of this file is
`/tmp/mtop/mtop.log` on Unix-like systems. This log file is truncated every time `mtop`
starts.

Some examples of invoking `mtop` are given below.

### Connecting to a local server
```
mtop localhost:11211
```

### Connecting to multiple servers

```
mtop cache01.example.com:11211 cache02.example.com:11211 cache03.example.com:11211
```

### Connecting to a port-forwarded Kubernetes pod

```
kubectl port-forward --namespace=example memcached-0 11211:11211
mtop localhost:11211
```

## Limitations

### No TLS connections

`mtop` currently only supports plain-text (unencrypted) connections to servers. TLS support
*may* be added in a future version.

### No historical data

`mtop` displays instantaneous statistics or an average over the last 10 seconds (depending on
the particular statistic). It does not persist statistics anywhere for historical analysis. If
this is something you need, use the [memcached_exporter](https://github.com/prometheus/memcached_exporter)
for Prometheus.

## License

mtop is available under the terms of the [GPL, version 3](LICENSE).

### Contribution

Any contribution intentionally submitted  for inclusion in the work by you
shall be licensed as above, without any additional terms or conditions.