Leela project¶

Leela UDP/Collectd¶

They simply parse the packet and forward to the timeline using the leela internal protocol.

Leela HTTP¶

This exposes the rest API which allows you to retrieve historical data. It reads data from cassandra directly but in the future all reading and writing to the storage will be go through the leela-storage service.

The HTTP provides a read/write interface. Writing are simply forward to the timeline, as the previous components do.

Timeline¶

This is the only component that effectively knows about metrics. You may think of it as a function that takes a metric and produces one or more events [an event is just a gauge type].

The process exposes the following unix sockets:

The databus socket is the one metrics should arrive. Each frontend [udp, collectd, http] writes one or more metrics into it. Then, if any given metric generates any event then the timeline writes them into the connected peers. This is done using the multicast unix socket.

Interested processes should continuously register themselves using the multicast socket in order to receive the events that the timeline generates.

The reason this must be a continuous operation is that the timeline purges dead nodes, i.e., nodes that are not sending register messages in a timely manner.

DMPROC¶

This is the engine that allows users to monitor metrics as soon as they are received. Once started, it register itself in timeline in order to receive events into the databus socket, and exposes its service through the proc socket.

The proc socket is the only one that is stream oriented. The protocol is fairly simple though. It prefixes all packets with its size, using a unsigned short [2 bytes] big endian encoded.

0                       2
|           |           |
------------+-----------+
|         size          |
+-----------------------+
|                       |
|        payload        |
|        (0-65k)        |
|                       |
+-----------------------+

Leela XMPP¶

Exposes its services as an user of a XMPP service using a language that resembles SQL. This module allows one to monitor metrics in real time via XMPP.

The redis is used as a directory service. When a request is made by a user an new entry is written into the redis. Periodically, leela xmpp service reads from redis in order to know which users are requesting information. When a new entry is found, it establishes a connection with dmproc and any output is forwarded via XMPP to the users requesting the information. Similarly, whenever an entry is removed from redis the associated connection with dmproc is closed.

The load on a redis server is very low, but it is extremely important to make sure it is always available. If the redis service become unavailable, so does the leela-xmpp.

Requirements¶

• python2
• virtualenv
• ghc7
• cabal

On arch linux, the above can be fulfilled using pacman:

$ pacman -S python2-virtualenv cabal-install

Now, download the latest release from github and build it:

$ wget -Oleela-v2x.tar.gz https://github.com/locaweb/leela/archive/v2.x.tar.gz
$ tar -xf leela-v2x.tar.gz
$ cd leela-2.x
$ make bootstrap
$ make dist-build

And install it:

$ root=/opt/leela
$ make dist-install root=$root

You should check the configuration file [= $root/etc/leela.conf] and make sure everything checks out. After that, start the service.

$ $root/etc/init.d/leela start

Function syntax¶

Each function contains a name, usually as ascii encoded string, followed by zero or more arguments. For instance, the maximum function, which computes the maximum value of a set of events, takes no arguments. Operators are the sole exception to this rule, as they are enclosed by parenthesis or brackets. Currently all functions (as well as operators) depends only on the input. They will only produce a result when it receives one or more events. In other words, they are pure functions.

You may compose functions using the | (pipe) operator which resembles greatly the unix pipe operator. So you may think of each function as a combinator and using the pipe operator allow you to grow bigger pipelines. For instance, suppose you have a event that ranges from 0 to 1, the following function should compute the mean of the current set of events and then multiply this value by 100 (left to right application), only returning those greater than 50:

mean | (* 100) | [> 50]

Operators are always enclosed by parenthesis or brackets. Parenthesis are used for arithmetic operators whereas brackets are used for comparison operators. The syntax allow the operator to be placed either on the left or right side. For instance, (/ 100) will divide by 100 whereas (100 /) will divide 100 by the value of the event. The same applies for comparison operators.

There are four arithmetic operators defined: *, +, - and /, which respectively computes the multiplication, addition, subtraction and division.

And there are six comparison operators defined: > [greater than], < [less than], >= [greater than or equal to], <= [less than or equal to], = [equal to] and /= [not equal to].

Functions reference¶

n * (L (mod m)) + minimum n (L (mod m))

sma 30 | sample 1/5

window 30 (mean | (* 100))

Operators reference¶

Common Response Codes¶

Error Responses¶

They will always come using the following format:

{"status": int, "reason": string}

Resources¶

%Y%m%dT%H%M

$ curl {endpoint}/v1/foobar?start=20120101T1430&finish=20120101T1500
{ "status": 200,
  "results": ...
}

$ curl -X POST -d '{"type": "gauge", "value": 0.2}' {endpoint}/v1/foobar
{"status": 201,
 "results": [{"name": "foobar", "timestamp": 1366549812, "type": "gauge", "value": 0.2}]
}

$ curl -X POST -d '{"value": :VALUE, "timestamp": 1352483918}' {endpoint}/v1/data/foobar
{ "status": 201,
  "results": [{"name": "foobar", "timestamp": 1352483918, "value": :VALUE}]
}

PING¶

The UDP protocol is also capable of receiving a PING message that can use used to test connectivity. The syntax is as follows:

ping\n

Examples¶

Assuming you have netcat, and the server up and running, the following shell commands should work:

# the ping message
$ echo ping                                      | nc -u localhost 6968
pong

$ echo -n "gauge 10|example.e0 0.75 1350332001;" | nc -u localhost 6968
$ echo -n "derive 10|example.e0 0.76;"           | nc -u localhost 6968

Legacy udp protocol¶

This protocol is deprecated. It will be removed in future releases:

<name>: <value>[ timestamp]\n

SELECT * FROM leela.xmpp;¶

Returns the current registered functions. Example:

SELECT * FROM leela.xmpp;
{ "status": 200,
  "results": [ { "cmd": "SELECT id FROM hm6177.cpu.cpu.idle;",
                 "key": "b0acdfe11875c074c760bfa8e34da49c1dfe73bd998bf720efc349c6bfd31d756d9b88f23894dbfe3555bddd2d9d7a890ac09831fe3ad6ea469ca3f52bf3fd0a"
               }
             ]
}

The results entry contains an object with the following keys:

SELECT :proc FROM :regex;¶

Registers a new function to monitor real time events. Example:

SELECT id FROM ^.*.cpu.cpu.idle$;
{ "status": 200,
  "results": { "key": "baa7163f7b51c3e96d7ee54e08a147840c1c2a682c89cbae2edd288506954dd568980394a827c1d4fb339e2a928e55ff36c277b73cac9be417a1c80c2086ea6f"
             }
}

The regex is a posix regular expression and proc is a function to apply over the events that matches the regex. The complete reference may be found at dmproc.

This command returns an structure with the following keys:

Then for each event that is generated by the registered function the following message is created:

{ "status": 200, "results": { "event", { "name": "...",
                                         "timestamp": 1350334144.0,
                                         "value": 0.8553317028766958
                                       }
                            }
}

DELETE FROM leela.xmpp;¶

Unregister all functions registered for this account. Example:

DELETE FROM leela.xmpp;
{ "status": 200,
  "results": [ { "key": "baa7163f7b51c3e96d7ee54e08a147840c1c2a682c89cbae2edd288506954dd568980394a827c1d4fb339e2a928e55ff36c277b73cac9be417a1c80c2086ea6f"
               }
             ]
}

DELETE FROM leela.xmpp WHERE key=284692849396a112668bbaa3dbc30e9d5c097c31998ec0569938d8cb0aaee9a282852fa56cdfaaf3aa953e76cf40315e399f851c3613a1f560f77a1553bd899e;
{ "status": 200,
  "results": { "key": "284692849396a112668bbaa3dbc30e9d5c097c31998ec0569938d8cb0aaee9a282852fa56cdfaaf3aa953e76cf40315e399f851c3613a1f560f77a1553bd899e"
             }
}

Response structure¶

All messages follows this structure:

{"status":INTEGER, "debug":OBJECT, "reason":STRING, "results":OBJECT}