Python SDK Integration


The "Python SDK" module (hereafter: the PySDK) provides a lightweight, efficient, reliable input point to Alooma. The module provides a library of methods to record events and send them to Alooma from any Python application.

The module contains two main classes:

  • The PySDK: Enqueues events to be reported to the Alooma pipeline. Events are placed into a concurrent queue, from which they are later pulled by the Sender module to be sent to your dedicated Alooma server.

  • The Sender: Dequeues messages and sends them to your dedicated Alooma server. The Sender also runs as a daemon in the background.

When initialized, the PySDK instantiates a Sender. The Sender starts a separate thread on which a TCP connection is opened. Any disconnection, send error, or other event will not interfere with other code nor crash the service. The module handles errors automatically. Upon disconnection, the module attempts to renew the socket and connection.


To integrate the PySDK, follow these simple steps:

  1. Run pip install alooma_pysdk to install the SDK. Alternatively, the source can be downloaded directly from Alooma's GitHub repository.

  2. Import the module by adding the following line in your Python file:

    import alooma_pysdk

  3. Log in to your Alooma account and add an "Python App" input. You can do this by clicking Add new input from the Plumbing screen, and then selecting "Python App" and following the prompts.

  4. Give your input a label (name), and copy the generated token.

  5. Initialize a PySDK instance by adding the following line in your Python file:

    sdk = alooma_pysdk.PythonSDK(YOUR_TOKEN)

    • token - The unique identifier for this input you got at step 4.

    • There are many more useful parameters that can be supplied to this function. Here are some key ones (refer to the in-file method documentation for more):

      • servers - The server to send data to. Only needed if indicated by Alooma support.

      • port - The remote port to connect to. Only needed if indicated by Alooma support.

      • event_type - A string or callable which receives each event and returns a string. The event type for each event is placed in a _metadata.event_type field, which determines the type of the event in the Alooma Mapper screen.

      • callback_func - A callback function can be provided to be called whenever a log message is emitted from the PySDK.

      • blocking - Default is False, meaning that overflow events are discarded. If True, we try to resend overflow events. Set this to True if encountering "buffer is full" errors.

  6. To report an event to Alooma simply add this one-liner to your code:

    Alternatively, to report multiple events in one function call, use:

    sdk.report_many([event_dict, event_dict, ...])

    In both cases, each event must be a valid Python dictionary or a string. If not, it will be discarded and the callback function, if provided, will be called with an appropriate message.

  7. To ensure all internal SDK queues are flushed before closing your program, make sure to call alooma_pysdk.terminate().

That's it, you're ready to send events to Alooma! As always, contact us with any questions.

Example code

Some basic examples of how to use the Python SDK:

import alooma_pysdk
import datetime

sdk = alooma_pysdk.PythonSDK(<token from Alooma>)
for i in range(1, 100):
    event = {
        'id': i,

alooma_pysdk.terminate() # remember to terminate or risk losing events in queue

An example showing how to work with multiple tokens and how to batch import:

import alooma_pysdk
import datetime

sdk = alooma_pysdk.PythonSDK(<token from alooma>)
sdk2 = alooma_pysdk.PythonSDK(<another token from alooma>)
events = []
for i in range(1, 100):
    event = {
        'id': i,

# This basically does the same as .report, but in batch:

# This terminates both sdk's

Search results

    No results found