README.md
1# Memcached plugin
2Provides native Zabbix solution for monitoring Memcached servers (distributed memory object caching system).
3It can monitor several Memcached instances simultaneously, remotes or locals to the Zabbix Agent.
4Both TCP and Unix-socket connections are supported. The plugin keeps connections in the opened state to reduce network
5congestion, latency, CPU and memory usage. Best for use in conjunction with the official
6[Memcached template.](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/app/memcached)
7You can extend it or create your template for your specific needs.
8
9## Requirements
10* Zabbix Agent 2
11* Go >= 1.13 (required only to build from source)
12
13## Supported versions
14* Memcached, version 1.4+
15
16## Installation
17The plugin is supplied as a part of Zabbix Agent 2, and it does not require any special installation steps. Once
18Zabbix Agent 2 installed, the plugin is ready to work. The only thing you need to do is to make sure a Memcached
19instance is available for connection.
20
21## Configuration
22The Zabbix Agent's configuration file is used to configure plugins.
23
24**Plugins.Memcached.KeepAlive** — Sets a time for waiting before unused connections will be closed.
25*Default value:* 300 sec.
26*Limits:* 60-900
27
28**Plugins.Memcached.Timeout** — The maximum time for waiting when a request has to be done.
29*Default value:* equals the global Timeout configuration parameter.
30*Limits:* 1-30
31
32### Configuring connection
33A connection can be configured using either keys' parameters or named sessions.
34
35*Notes*:
36* It is not possible to mix configuration using named sessions and keys' parameters simultaneously.
37* You can leave any connection parameter empty, a default hard-coded value will be used in the such case.
38* Embedded URI credentials (userinfo) are forbidden and will be ignored. So, you can't pass the credentials by this:
39
40 memcached.ping[tcp://user:password@127.0.0.1] — WRONG
41
42 The correct way is:
43
44 memcached.ping[tcp://127.0.0.1,user,password]
45
46* The only supported network schemas for a URI are "tcp" and "unix".
47Examples of valid URIs:
48 - tcp://127.0.0.1:11211
49 - tcp://localhost
50 - localhost
51 - unix:/var/run/memcached.sock
52 - /var/run/memcached.sock
53
54#### Using keys' parameters
55The common parameters for all keys are: [ConnString][,User][,Password]
56Where ConnString can be either a URI or a session name.
57ConnString will be treated as a URI if no session with the given name is found.
58If you use ConnString as a session name, just skip the rest of the connection parameters.
59
60#### Using named sessions
61Named sessions allow you to define specific parameters for each Memcached instance. Currently, there are only three supported
62parameters: Uri, User and Password. It's a bit more secure way to store credentials compared to item keys or macros.
63
64E.g: suppose you have two Memcached instances: "Prod" and "Test".
65You should add the following options to the agent configuration file:
66
67 Plugins.Memcached.Sessions.Prod.Uri=tcp://192.168.1.1:11211
68 Plugins.Memcached.Sessions.Prod.User=<UserForProd>
69 Plugins.Memcached.Sessions.Prod.Password=<PasswordForProd>
70
71 Plugins.Memcached.Sessions.Test.Uri=tcp://192.168.0.1:11211
72 Plugins.Memcached.Sessions.Test.User=<UserForTest>
73 Plugins.Memcached.Sessions.Test.Password=<PasswordForTest>
74
75Then you will be able to use these names as the 1st parameter (ConnString) in keys instead of URIs, e.g:
76
77 memcached.ping[Prod]
78 memcached.ping[Test]
79
80*Note*: sessions names are case-sensitive.
81
82## Supported keys
83**memcached.ping[\<commonParams\>]** — Tests if a connection is alive or not.
84*Returns:*
85- "1" if a connection is alive.
86- "0" if a connection is broken (if there is any error presented including AUTH and configuration issues).
87
88**memcached.stats[\<commonParams\>[,type]]** — Returns an output of the "stats" command
89serialized to JSON.
90*Params:*
91type — One of supported stat types: items, sizes, slabs and settings. Empty by default (returns general statistics).
92
93## Troubleshooting
94The plugin uses Zabbix agent's logs. You can increase debugging level of Zabbix Agent if you need more details about
95what is happening.
96