sFlow.org Peter Phaal http://www.sFlow.org/ InMon Corp. info@sflow.org Dave Mangot Tagged Inc. December 2011 sFlow Memcache Structures Copyright Notice Copyright (C) sFlow.org (2010,2011). All Rights Reserved. Abstract This memo describes sFlow version 5 structures for exporting memcache related data. Table of Contents 1. Overview ...................................................... 1 2. Discussion .................................................... 1 3. sFlow Datagram Extensions ..................................... 2 4. References .................................................... 5 5. Author's Addresses ............................................ 5 1. Overview This document describes additional structures that allow an sFlow agent to export information from a server accessed using the memcache protocol, defined by the Memcached project [1]. sFlow version 5 is an extensible protocol that allows the addition of new data structures without impacting existing collectors. This document does not change the sFlow version 5 protocol [2], it simply defines additional, optional, data structures that a memcache entity can use to report performance. 2. Discussion A memcache server provides a networked service for storing and retrieving data using a key. Defining standard sFlow structures simplifies management of memcache server clusters by linking memcache FINAL sFlow.org [Page 1] FINAL sFlow Memcache Structures December 2011 performance to the performance of the underlying network and system resources required to deliver the memcache service, providing the complete set of metrics needed to manage performance. The sFlow Host Structures [3] specification defines a framework for implementing sFlow in application services such as memcache. This document builds on that framework by defining structures specific to the memcache service. 3. sFlow Datagram Extensions The memcache_counters structure is used to export the standard set of counters already maintained by memcache servers. Currently memcache counters are retrieved using the memcache protocol. Exporting the counters using sFlow reduces the overhead associated with memcache polling and simplifies performance management by reducing the number of protocols that a management application needs to support in order to retrieve performance metrics. The memcache_operation structure is used to export attributes of randomly sampled memcache operations performed by the server. Each memcache flow_sample includes a memcache_operation structure as well as an extended_socket_ip4 or extended_socket_ipv6 structure [3]. The flow_sample input and output interface fields [2] are used to indicate service direction. If the sFlow agent is running on a memcache server then the input interface must be set to the ifIndex corresponding to the interface the request was received on (0 if unknown) and the output interface must be set to 0x3FFFFFFF, indicating that the target of the operation is the local memcache server. If the sFlow agent is running as part of the memcache client, then the input interface must be set to 0x3FFFFFFF and the output interface set to the ifIndex corresponding to the interface the request was sent on (0 if unknown). An sFlow sub-agent embedded within the memcache entity is responsible for reporting on the memcache logical entity data source. The sub_agent_id and the data source index must be unique within the host. To ensure uniqueness and provide persistence, an embedded sub- agent should use the lowest port number that is being used to receive memcache requests as the sub_agent_id and data source index. For example, if a memcache server is listening for memcache requests on TCP port 11211 then sub_agent_id = 11211 and the data source type = 3 (entLogicalEntry) and index = 11211. /* The memcache_protocol enumeration may be expanded over time. Applications receiving sFlow must be prepared to receive memcache_operation structures with unknown memcache_protocol FINAL sFlow.org [Page 2] FINAL sFlow Memcache Structures December 2011 values */ enum memcache_protocol { OTHER = 0; ASCII = 1; BINARY = 2; } /* The memcache_cmd enumeration may be expanded over time. Applications receiving sFlow must be prepared to receive memcache_operation structures with unknown memcache_cmd values */ enum memcache_cmd { OTHER = 0; SET = 1; ADD = 2; REPLACE = 3; APPEND = 4; PREPEND = 5; CAS = 6; GET = 7; GETS = 8; INCR = 9; DECR = 10; DELETE = 11; STATS = 12; FLUSH = 13; VERSION = 14; QUIT = 15; TOUCH = 16; } /* The memcache_status enumeration may be expanded over time. Applications receiving sFlow must be prepared to receive memcache_operation structures with unknown memcache_status values */ enum memcache_status { UNKNOWN = 0; OK = 1; ERROR = 2; CLIENT_ERROR = 3; SERVER_ERROR = 4; STORED = 5; NOT_STORED = 6; EXISTS = 7; NOT_FOUND = 8; FINAL sFlow.org [Page 3] FINAL sFlow Memcache Structures December 2011 DELETED = 9; } /* Memcache operation */ /* opaque = flow_data; enterprise = 0; format = 2200 */ struct memcache_operation { memcache_protocol protocol; /* protocol */ memcache_cmd cmd; /* command */ string<255> key; /* key used to store/retrieve data */ unsigned int nkeys; /* number of keys (including sampled key) */ unsigned int value_bytes; /* size of the value (in bytes) */ unsigned int uS; /* duration of the operation (in microseconds) */ memcache_status status; /* status of command */ } /* Memcache counters */ /* See Memcached protocol.txt */ /* opaque = counter_data; enterprise = 0; format = 2204 */ struct memcache_counters { unsigned int cmd_set; unsigned int cmd_touch; unsigned int cmd_flush; unsigned int get_hits; unsigned int get_misses; unsigned int delete_hits; unsigned int delete_misses; unsigned int incr_hits; unsigned int incr_misses; unsigned int decr_hits; unsigned int decr_misses; unsigned int cas_hits; unsigned int cas_misses; unsigned int cas_badval; unsigned int auth_cmds; unsigned int auth_errors; unsigned int threads; unsigned int conn_yields; unsigned int listen_disabled_num; unsigned int curr_connections; unsigned int rejected_connections; unsigned int total_connections; unsigned int connection_structures; unsigned int evictions; unsigned int reclaimed; unsigned int curr_items; unsigned int total_items; FINAL sFlow.org [Page 4] FINAL sFlow Memcache Structures December 2011 unsigned hyper bytes_read; unsigned hyper bytes_written; unsigned hyper bytes; unsigned hyper limit_maxbytes; } 4. References [1] "Memcached", http://memcached.org [2] Phaal, P. and Lavine, M., "sFlow Version 5", http://www.sflow.org/sflow_version_5.txt, July 2006 [3] Phaal, P. and Jordan, R., "sFlow Host Structures", http://www.sflow.org/sflow_host.txt July 2010 5. Author's Address Peter Phaal InMon Corp. 580 California Street, 5th Floor San Francisco, CA 94104 Phone: (415) 283-3263 EMail: peter.phaal@inmon.com Dave Mangot Tagged Inc. 110 Pacific Ave Mail Box #117 San Francisco, CA 94111 Phone: (415) 283-3263 EMail: dmangot@tagged.com FINAL sFlow.org [Page 5]