Install & Compatibility
Where this runs
tested against v0.2.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.628s · 37.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.2s · import 0.558s · 39MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingVersion 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.fixReview the official documentation and examples for versions 0.2.0 and later to adapt your code to the new API interface.
affects: <0.2.0
gotchaWhen 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.fixUse `client.streaming_query()` for large static query results to leverage streaming and avoid potential polling issues with `QueryJob`'s `poll` method.
affects: All
gotchaLive 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.fixEnsure 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.
affects: All
gotchaWhile 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.fixFor dedicated data ingestion workflows, import and use `HumioIngestClient` (e.g., `from humiolib.HumioClient import HumioIngestClient`).
affects: All
gotchaAn 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.fixExercise 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.
affects: All known versions up to 0.2.6
Errors
Common errors & fixes
humiolib.HumioExceptions.HumioHTTPException: (401 Client Error: Unauthorized for url: ...)
The provided Humio user token is invalid, expired, or lacks the necessary permissions for the requested action or repository, or the base URL is incorrect.
fixVerify that your `base_url`, `repository`, and `user_token` are correct and that the `user_token` has the required read/write permissions within Humio.
AttributeError: 'HumioClient' object has no attribute 'ingest_messages'
You are attempting to use data ingestion methods like `ingest_messages` or `ingest_json_data` on a `HumioClient` instance, which is primarily for queries and repository management. Ingestion methods are exclusive to the `HumioIngestClient`.
fixInstantiate `humiolib.HumioClient.HumioIngestClient` for all data ingestion tasks, passing the `ingest_token` instead of `user_token`.
humiolib.HumioExceptions.HumioQueryJobExpiredException
A Humio query job has expired on the server, typically because it was not polled for results frequently enough, or the server-side timeout for the query job was reached.
fixEnsure that query results are consumed promptly by polling the `QueryJob` instance more frequently. For long-running queries, consider adjusting the query's `is_live` or `end` parameters, or increasing the server-side query job timeout if applicable.
AttributeError: 'HumioClient' object has no attribute 'query'
You are attempting to call a non-existent `query` method on the `HumioClient` instance. The `humiolib` client provides specific methods for different types of queries.
fixUse the correct query methods: `client.streaming_query()` for a real-time stream of results or `client.create_queryjob()` for an asynchronous query job.
Upgrade
Version history
0.2.6latest on PyPI · released Oct 5, 2023
Audit
Dependencies
requestsrequiredUsed internally for making HTTP requests to the Humio API, though not explicitly listed in PyPI's install_requires.