Getting Started

In this section we will demonstrate the basic functionality of Kadabra by publishing some metrics using the DebugPublisher, which just outputs the metrics to a logger.

Make sure you have installed Kadabra following the directions in the Installation section.

Install and Run Redis Server

First, we need to have an instance of Redis server running locally. Redis is very easy to setup and run. If you haven’t used it before, follow the docs here to get your Redis server up and running. We will assume the Redis server is running locally on port 6379 (the default port).

Run the Agent

Next, we will run the agent, which will watch for metrics and publish them (in this case, to a logger setup to write to stdout). Put the following code into a file called run_agent.py:

import logging, sys, kadabra

handler = logging.StreamHandler(sys.stdout)

agent_logger = logging.getLogger("kadabra.agent")
agent_logger.setLevel("INFO")
agent_logger.addHandler(handler)

publisher_logger = logging.getLogger("kadabra.publisher")
publisher_logger.setLevel("INFO")
publisher_logger.addHandler(handler)

agent = kadabra.Agent()
agent.start()

This code sets up the agent’s logger (so we can see what it’s doing) and the publisher’s logger (so we can see the metrics get printed).

Now we can run the agent:

python run_agent.py

You should see some output indicating that the agent has started running, meaning it is listening to Redis for metrics. If you see some output about connection errors, ensure that the Redis server is actually running and that you can connect to it.

Publish Some Metrics

Now, in a separate terminal, open up a Python interpreter. We’ll record some metrics and publish them. First, let’s initialize the Kadabra client:

>>> import kadabra
>>> client = kadabra.Kadabra()

Now let’s get a MetricsCollector object from our client. This is the API we use to record metrics in our application. It is thread-safe and can be shared throughout our application:

>>> metrics = client.metrics()

In a real application, the metrics code would be located in places where we care about recording important information, such as customer sales, user signups, or application failures. But since we are just demonstrating basic functionality, let’s record a few counters and a timer:

>>> import datetime
>>> metrics.add_count("myCount", 1.0)
>>> metrics.add_count("myOtherCount", 1.0)
>>> metrics.add_count("myOtherCount", 1.0)
>>> metrics.set_timer("myTimer", datetime.timedelta(seconds=30), kadabra.Units.MILLISECONDS)

Note

Timers record a datetime.timedelta, but you can report the actual value in any of the units from kadabra.Units.

Now we’re ready to send our metrics for publishing:

>>> client.send(metrics.close())

Go over to the terminal where your agent is running. You should see the metrics output as serialized JSON. Lastly, hit CTRL+C to gracefully shut down the agent.

Configuration

You can configure the client API and the Agent using a dictionary when you instantiate them to control various aspects of their functionality. For more information see the Configuration section.

Publishing to Storage

The DebugPublisher just serializes the metrics into JSON and outputs them to a logger. You could pipe this output into another program which writes the metrics into more permanant storage. But it would be best to publish the metrics directly into a database that is designed for metrics. Time-series databases are ideal for storing metrics data.

One such database engine is InfluxDB, which is capable of storing metrics with indexed tags and provides mechanisms for querying those metrics in useful ways. Kadabra ships with an InfluxDBPublisher that can publish metrics straight to an InfluxDB server - you just provide the host, port, and database name.

For a guide on how to set up Kadabra to publish metrics using InfluxDB, see Using with InfluxDB.

Learning More

You now have everything you need to use Kadabra in your application. You can find out more about Collecting Metrics, Sending Metrics, and Publishing Metrics in the corresponding sections. For a complete look at the API, see API.