======================
Humiolib
======================
The `humiolib` library is a wrapper for Humio's web API, supporting easy interaction with Humio directly from Python.
Full documentation for this repository can be found at https://python-humio.readthedocs.io/en/latest/readme.html.
Vision
======
The vision for `humiolib` is to create an opinionated wrapper around the Humio web API, supporting log ingestion and log queries.
The project does not simply expose web endpoints as Python methods, but attempts to improve upon the usability experience of the API.
In addition the project seeks to add non-intrusive quality of life features, so that users can focus on their primary goals during development.
Governance
==========
This project is maintained by employees at Humio ApS.
As a general rule, only employees at Humio can become maintainers and have commit privileges to this repository.
Therefore, if you want to contribute to the project, which we very much encourage, you must first fork the repository.
Maintainers will have the final say on accepting or rejecting pull requests.
As a rule of thumb, pull requests will be accepted if:
* The contribution fits with the project's vision
* All automated tests have passed
* The contribution is of a quality comparable to the rest of the project
The maintainers will attempt to react to issues and pull requests quickly, but their ability to do so can vary.
If you haven't heard back from a maintainer within 7 days of creating an issue or making a pull request, please feel free to ping them on the relevant post.
The active maintainers involved with this project include:
* `Alexander Brandborg <https://github.com/AlexanderBrandborg>`_
Installation
============
The `humiolib` library has been published on PyPI, so you can use `pip` to install it:
::
pip install humiolib
Usage
========
The examples below seek to get you going with `humiolib`.
For further documentation have a look at the code itself.
HumioClient
***********
The HumioClient class is used for general interaction with Humio.
It is mainly used for performing queries, as well as managing different aspects of your Humio instance.
.. code-block:: python
from humiolib.HumioClient import HumioClient
# Creating the client
client = HumioClient(
base_url= "https://cloud.humio.com",
repository= "sandbox",
user_token="*****")
# Using a streaming query
webStream = client.streaming_query("Login Attempt Failed", is_live=True)
for event in webStream:
print(event)
# Using a queryjob
queryjob = client.create_queryjob("Login Attempt Failed", is_live=True)
poll_result = queryjob.poll()
for event in poll_result.events:
print(event)
# With a static queryjob you can poll it iterativly until it has been exhausted
queryjob = client.create_queryjob("Login Attempt Failed", is_live=False)
for poll_result in queryjob.poll_until_done():
print(poll_result.metadata)
for event in poll_result.events:
print(event)
HumioIngestClient
*****************
The HumioIngestClient class is used for ingesting data into Humio.
While the HumioClient can also be used for ingesting data, this is mainly meant for debugging.
.. code-block:: python
from humiolib.HumioClient import HumioIngestClient
# Creating the client
client = HumioIngestClient(
base_url= "https://cloud.humio.com",
ingest_token="*****")
# Ingesting Unstructured Data
messages = [
"192.168.1.21 - user1 [02/Nov/2017:13:48:26 +0000] \"POST /humio/api/v1/ingest/elastic-bulk HTTP/1.1\" 200 0 \"-\" \"useragent\" 0.015 664 0.015",
"192.168.1..21 - user2 [02/Nov/2017:13:49:09 +0000] \"POST /humio/api/v1/ingest/elastic-bulk HTTP/1.1\" 200 0 \"-\" \"useragent\" 0.013 565 0.013"
]
client.ingest_messages(messages)
# Ingesting Structured Data
structured_data = [
{
"tags": {"host": "server1" },
"events": [
{
"timestamp": "2020-03-23T00:00:00+00:00",
"attributes": {"key1": "value1", "key2": "value2"}
}
]
}
]
client.ingest_json_data(structured_data)
Changelog
=========
0.2.0 (2020-03-30)
******************
Initial real release to PyPI
Added:
* Tests, mocking out API calls with vcr.py
* Custom error handling to completly wrap url library used
* QueryJob class
Changed:
* Whole API interface has been updated
* Updated Sphinx documentation
Removed:
* A few configuration files left over from earlier versions
0.2.2 (2020-05-19)
******************
Bugfixing to ensure that static queryjobs can be polled for all their results
Added:
* Static queryjobs can now be queried for more than one segment
Changed:
* Upon polling from a QueryJob it will now stall until it can poll data from Humio, ensuring that an empty result is not returned prematurely.
Removed:
* The poll_until_done method has been removed from live query jobs, as this does not make conceptual sense to do, in the same manner as a static query job.
0.2.3 (2021-08-13)
******************
Smaller bugfixes
Changed:
* Fix urls in docstrings in HumioClient.py
* Propagate kwargs to poll functions in QueryJob.py
0.2.4 (2022-08-15)
******************
Smaller file related bugfixes
Changed:
* upload_file function no longer attempts a cast to json
* list_files function now works on newer versions of humio
0.2.5 (2023-04-17)
******************
Expand file functionality
Changed:
* Added additional endpoints for manipulating files via GraphQL
0.2.6 (2023-10-05)
******************
Add 'Saved Query' Support
Changed:
* Added additional endpoints for managing saved queries
Raw data
{
"_id": null,
"home_page": "https://github.com/humio/python-humio",
"name": "humiolib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "humio,log management",
"author": "Humio ApS",
"author_email": "integrations@humio.com",
"download_url": "https://files.pythonhosted.org/packages/06/71/84d9cb441a8f9734b2fcf3ce5097bd1c98a305c3dc8613291bf844ebae3c/humiolib-0.2.6.tar.gz",
"platform": null,
"description": "======================\nHumiolib\n======================\n \n\n \nThe `humiolib` library is a wrapper for Humio's web API, supporting easy interaction with Humio directly from Python.\nFull documentation for this repository can be found at https://python-humio.readthedocs.io/en/latest/readme.html.\n \nVision\n======\nThe vision for `humiolib` is to create an opinionated wrapper around the Humio web API, supporting log ingestion and log queries.\nThe project does not simply expose web endpoints as Python methods, but attempts to improve upon the usability experience of the API.\nIn addition the project seeks to add non-intrusive quality of life features, so that users can focus on their primary goals during development.\n \nGovernance\n==========\nThis project is maintained by employees at Humio ApS.\nAs a general rule, only employees at Humio can become maintainers and have commit privileges to this repository.\nTherefore, if you want to contribute to the project, which we very much encourage, you must first fork the repository.\nMaintainers will have the final say on accepting or rejecting pull requests.\nAs a rule of thumb, pull requests will be accepted if:\n \n * The contribution fits with the project's vision\n * All automated tests have passed\n * The contribution is of a quality comparable to the rest of the project\n \nThe maintainers will attempt to react to issues and pull requests quickly, but their ability to do so can vary.\nIf you haven't heard back from a maintainer within 7 days of creating an issue or making a pull request, please feel free to ping them on the relevant post.\n \nThe active maintainers involved with this project include:\n \n * `Alexander Brandborg <https://github.com/AlexanderBrandborg>`_\n \nInstallation\n============\nThe `humiolib` library has been published on PyPI, so you can use `pip` to install it:\n::\n \n pip install humiolib\n \n \nUsage\n========\nThe examples below seek to get you going with `humiolib`.\nFor further documentation have a look at the code itself.\n \nHumioClient\n***********\nThe HumioClient class is used for general interaction with Humio.\nIt is mainly used for performing queries, as well as managing different aspects of your Humio instance.\n \n.. code-block:: python\n \n from humiolib.HumioClient import HumioClient\n \n # Creating the client\n client = HumioClient(\n base_url= \"https://cloud.humio.com\",\n repository= \"sandbox\",\n user_token=\"*****\")\n \n # Using a streaming query \n webStream = client.streaming_query(\"Login Attempt Failed\", is_live=True)\n for event in webStream:\n print(event)\n \n # Using a queryjob \n queryjob = client.create_queryjob(\"Login Attempt Failed\", is_live=True)\n poll_result = queryjob.poll()\n for event in poll_result.events:\n print(event)\n\n # With a static queryjob you can poll it iterativly until it has been exhausted\n queryjob = client.create_queryjob(\"Login Attempt Failed\", is_live=False)\n for poll_result in queryjob.poll_until_done():\n print(poll_result.metadata)\n for event in poll_result.events:\n print(event)\n \nHumioIngestClient\n*****************\nThe HumioIngestClient class is used for ingesting data into Humio.\nWhile the HumioClient can also be used for ingesting data, this is mainly meant for debugging.\n \n.. code-block:: python\n\n from humiolib.HumioClient import HumioIngestClient\n \n # Creating the client\n client = HumioIngestClient(\n base_url= \"https://cloud.humio.com\",\n ingest_token=\"*****\")\n \n # Ingesting Unstructured Data\n messages = [\n \"192.168.1.21 - user1 [02/Nov/2017:13:48:26 +0000] \\\"POST /humio/api/v1/ingest/elastic-bulk HTTP/1.1\\\" 200 0 \\\"-\\\" \\\"useragent\\\" 0.015 664 0.015\",\n \"192.168.1..21 - user2 [02/Nov/2017:13:49:09 +0000] \\\"POST /humio/api/v1/ingest/elastic-bulk HTTP/1.1\\\" 200 0 \\\"-\\\" \\\"useragent\\\" 0.013 565 0.013\"\n ]\n \n client.ingest_messages(messages) \n \n # Ingesting Structured Data\n structured_data = [\n {\n \"tags\": {\"host\": \"server1\" },\n \"events\": [\n {\n \"timestamp\": \"2020-03-23T00:00:00+00:00\",\n \"attributes\": {\"key1\": \"value1\", \"key2\": \"value2\"} \n }\n ]\n }\n ]\n \n client.ingest_json_data(structured_data)\n \n\n\nChangelog\n=========\n\n0.2.0 (2020-03-30)\n******************\nInitial real release to PyPI\n\nAdded:\n\n * Tests, mocking out API calls with vcr.py \n * Custom error handling to completly wrap url library used\n * QueryJob class\n\nChanged:\n\n * Whole API interface has been updated\n * Updated Sphinx documentation\n\nRemoved:\n\n * A few configuration files left over from earlier versions\n\n\n0.2.2 (2020-05-19)\n******************\nBugfixing to ensure that static queryjobs can be polled for all their results\n\nAdded:\n\n * Static queryjobs can now be queried for more than one segment\n \n\nChanged:\n\n * Upon polling from a QueryJob it will now stall until it can poll data from Humio, ensuring that an empty result is not returned prematurely.\n\nRemoved:\n\n * The poll_until_done method has been removed from live query jobs, as this does not make conceptual sense to do, in the same manner as a static query job.\n\n0.2.3 (2021-08-13)\n******************\nSmaller bugfixes\nChanged:\n\n * Fix urls in docstrings in HumioClient.py\n * Propagate kwargs to poll functions in QueryJob.py\n\n0.2.4 (2022-08-15)\n******************\nSmaller file related bugfixes\nChanged:\n\n * upload_file function no longer attempts a cast to json \n * list_files function now works on newer versions of humio\n\n0.2.5 (2023-04-17)\n******************\nExpand file functionality\nChanged:\n\n * Added additional endpoints for manipulating files via GraphQL\n\n\n0.2.6 (2023-10-05)\n******************\nAdd 'Saved Query' Support\nChanged:\n\n * Added additional endpoints for managing saved queries\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python SDK for connecting to Humio",
"version": "0.2.6",
"project_urls": {
"Changelog": "https://python-humio.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://python-humio.readthedocs.io/",
"Homepage": "https://github.com/humio/python-humio",
"Issue Tracker": "https://github.com/humio/python-humio/issues"
},
"split_keywords": [
"humio",
"log management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9ffe1b175c36042cdfe67c1a0d49fb29df4b96cb48c9850e4e9e95663c6d2426",
"md5": "a8ae4464e51c00e0cfb9cbfba4a50030",
"sha256": "49b353689ee6ceef64fb82f1b182cc73a9df4d17d9bf54e812e0fe67acfb08a5"
},
"downloads": -1,
"filename": "humiolib-0.2.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8ae4464e51c00e0cfb9cbfba4a50030",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.5",
"size": 20268,
"upload_time": "2023-10-05T09:47:40",
"upload_time_iso_8601": "2023-10-05T09:47:40.329485Z",
"url": "https://files.pythonhosted.org/packages/9f/fe/1b175c36042cdfe67c1a0d49fb29df4b96cb48c9850e4e9e95663c6d2426/humiolib-0.2.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "067184d9cb441a8f9734b2fcf3ce5097bd1c98a305c3dc8613291bf844ebae3c",
"md5": "0f7fd72fd2283b2582864d2619c62d1c",
"sha256": "c4e024983ab70c7d5395b03d24b140e7a23c13d432b0ad79301d1b14cae44de0"
},
"downloads": -1,
"filename": "humiolib-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "0f7fd72fd2283b2582864d2619c62d1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 41318,
"upload_time": "2023-10-05T09:47:43",
"upload_time_iso_8601": "2023-10-05T09:47:43.133630Z",
"url": "https://files.pythonhosted.org/packages/06/71/84d9cb441a8f9734b2fcf3ce5097bd1c98a305c3dc8613291bf844ebae3c/humiolib-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-05 09:47:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "humio",
"github_project": "python-humio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "humiolib"
}
JSON
