Humio Python SDK

Warnings

• breaking Version 0.2.0 introduced a breaking change with a complete update to the API interface. Code written for versions prior to 0.2.0 will likely not be compatible.
  Fix: Review the official documentation and examples for versions 0.2.0 and later to adapt your code to the new API interface.
• gotcha When performing static queries that return large amounts of data, the `streaming_query` method is preferred over `create_queryjob` and subsequent polling, as `streaming_query` opens a direct streaming socket connection, which is generally more efficient for bulk results.
  Fix: Use `client.streaming_query()` for large static query results to leverage streaming and avoid potential polling issues with `QueryJob`'s `poll` method.
• gotcha Live query jobs created via `create_queryjob` persist on the Humio instance for 1 hour after the last poll. It is recommended to explicitly delete them when they are no longer in use to free up resources.
  Fix: Ensure you call a method to delete the query job, or manage its lifecycle, if you create live query jobs that are not intended for long-term use.
• gotcha While the `HumioClient` can be used for ingesting data, the `HumioIngestClient` is specifically designed for data ingestion and is the recommended client for this purpose, potentially offering better performance or specialized methods.
  Fix: For dedicated data ingestion workflows, import and use `HumioIngestClient` (e.g., `from humiolib.HumioClient import HumioIngestClient`).
• gotcha An open issue (GitHub #26) indicates that `humiolib` might not sanitize URLs in some cases, which could potentially lead to unexpected behavior or security concerns if untrusted input is used in URL construction.
  Fix: Exercise caution when constructing URLs or passing user-provided strings to methods that interact with Humio endpoints. Monitor the GitHub repository for updates and fixes related to this issue.

Install

• pip install humiolib Install `humiolib`

Imports

• HumioClient

  from humiolib.HumioClient import HumioClient

• HumioIngestClient

  from humiolib.HumioClient import HumioIngestClient

  Both HumioClient and HumioIngestClient are found in the `humiolib.HumioClient` module.
• QueryJob

  from humiolib.QueryJob import QueryJob

  Provides functionality for asynchronous queries, with BaseQueryJob and PollResult classes within this module.

Quickstart

This quickstart demonstrates how to initialize the `HumioClient` using environment variables for credentials and then perform a streaming query to retrieve aggregated event counts. Replace `HUMIO_BASE_URL`, `HUMIO_REPOSITORY`, and `HUMIO_USER_TOKEN` with your Humio instance details.

import os
from humiolib.HumioClient import HumioClient

HUMIO_BASE_URL = os.environ.get("HUMIO_BASE_URL", "https://cloud.humio.com")
HUMIO_REPOSITORY = os.environ.get("HUMIO_REPOSITORY", "sandbox")
HUMIO_USER_TOKEN = os.environ.get("HUMIO_USER_TOKEN", "")

if not HUMIO_USER_TOKEN:
    print("Please set the HUMIO_USER_TOKEN environment variable.")
    exit(1)

try:
    client = HumioClient(
        base_url=HUMIO_BASE_URL,
        repository=HUMIO_REPOSITORY,
        user_token=HUMIO_USER_TOKEN
    )

    # Perform a streaming query for events in the last hour
    query_string = "timechart(span=1h) count()"
    print(f"Executing query: '{query_string}' in repository '{HUMIO_REPOSITORY}'")
    events_generator = client.streaming_query(
        query_string=query_string,
        start="1h@h", # Last hour, aligned to the hour
        end="now"
    )

    for event in events_generator:
        print(event)

except Exception as e:
    print(f"An error occurred: {e}")