{"id":6376,"library":"humiolib","title":"Humio Python SDK","description":"The `humiolib` library is an official Python SDK for interacting with Humio's web API, enabling easy integration for log ingestion and query execution directly from Python. It aims to provide an opinionated and user-friendly wrapper over the raw API. The current version is 0.2.6, and the project is actively maintained by Humio ApS employees, with releases occurring irregularly but consistently since 2020.","status":"active","version":"0.2.6","language":"en","source_language":"en","source_url":"https://github.com/humio/python-humio","tags":["humio","logging","sdk","api","observability"],"install":[{"cmd":"pip install humiolib","lang":"bash","label":"Install `humiolib`"}],"dependencies":[{"reason":"Used internally for making HTTP requests to the Humio API, though not explicitly listed in PyPI's install_requires.","package":"requests"}],"imports":[{"symbol":"HumioClient","correct":"from humiolib.HumioClient import HumioClient"},{"note":"Both HumioClient and HumioIngestClient are found in the `humiolib.HumioClient` module.","symbol":"HumioIngestClient","correct":"from humiolib.HumioClient import HumioIngestClient"},{"note":"Provides functionality for asynchronous queries, with BaseQueryJob and PollResult classes within this module.","symbol":"QueryJob","correct":"from humiolib.QueryJob import QueryJob"}],"quickstart":{"code":"import os\nfrom humiolib.HumioClient import HumioClient\n\nHUMIO_BASE_URL = os.environ.get(\"HUMIO_BASE_URL\", \"https://cloud.humio.com\")\nHUMIO_REPOSITORY = os.environ.get(\"HUMIO_REPOSITORY\", \"sandbox\")\nHUMIO_USER_TOKEN = os.environ.get(\"HUMIO_USER_TOKEN\", \"\")\n\nif not HUMIO_USER_TOKEN:\n    print(\"Please set the HUMIO_USER_TOKEN environment variable.\")\n    exit(1)\n\ntry:\n    client = HumioClient(\n        base_url=HUMIO_BASE_URL,\n        repository=HUMIO_REPOSITORY,\n        user_token=HUMIO_USER_TOKEN\n    )\n\n    # Perform a streaming query for events in the last hour\n    query_string = \"timechart(span=1h) count()\"\n    print(f\"Executing query: '{query_string}' in repository '{HUMIO_REPOSITORY}'\")\n    events_generator = client.streaming_query(\n        query_string=query_string,\n        start=\"1h@h\", # Last hour, aligned to the hour\n        end=\"now\"\n    )\n\n    for event in events_generator:\n        print(event)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Review the official documentation and examples for versions 0.2.0 and later to adapt your code to the new API interface.","message":"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.","severity":"breaking","affected_versions":"<0.2.0"},{"fix":"Use `client.streaming_query()` for large static query results to leverage streaming and avoid potential polling issues with `QueryJob`'s `poll` method.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"For dedicated data ingestion workflows, import and use `HumioIngestClient` (e.g., `from humiolib.HumioClient import HumioIngestClient`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All known versions up to 0.2.6"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}