[](https://github.com/infrasonar/python-libprobe/actions)
[](https://github.com/infrasonar/python-libprobe/releases)
# Python library for building InfraSonar Probes
This library is created for building [InfraSonar](https://infrasonar.com) probes.
## Environment variable
Variable | Default | Description
------------------- | ------------------------------ | ------------
`AGENTCORE_HOST` | `127.0.0.1` | Hostname or Ip address of the AgentCore.
`AGENTCORE_PORT` | `8750` | AgentCore port to connect to.
`ENCRYPTION_KEY` | _default_ | Use your own encryption key for encrypting secrets in the YAML file.
`INFRASONAR_CONF` | `/data/config/infrasonar.yaml` | File with probe and asset configuration like credentials.
`MAX_PACKAGE_SIZE` | `500` | Maximum package size in kilobytes _(1..2000)_.
`MAX_CHECK_TIMEOUT` | `300` | Check time-out is 80% of the interval time with `MAX_CHECK_TIMEOUT` in seconds as absolute maximum.
`DRY_RUN` | _none_ | Do not run demonized, just return checks and assets specified in the given yaml _(see the [Dry run section](#dry-run) below)_.
`LOG_LEVEL` | `warning` | Log level (`debug`, `info`, `warning`, `error` or `critical`).
`LOG_COLORIZED` | `0` | Log using colors (`0`=disabled, `1`=enabled).
`LOG_FTM` | `%y%m%d %H:%M:%S` | Log format prefix.
`OUTPUT_TYPE` | `JSON` | Set the output type to `JSON` or `PPRINT` (Only for a dry run).
## Usage
Building an InfraSonar.get_state
```python
import logging
from libprobe.asset import Asset
from libprobe.probe import Probe
from libprobe.severity import Severity
from libprobe.exceptions import (
CheckException,
IgnoreResultException,
IgnoreCheckException,
IncompleteResultException,
NoCountException,
)
__version__ = "0.1.0"
async def my_first_check(asset: Asset, asset_config: dict, check_config: dict):
"""My first check.
Arguments:
asset: Asset contains an id, name and check which should be used
for logging;
asset_config: local configuration for this asset, for example credentials;
check_config: configuration for this check; contains for example the
interval at which the check is running and an address of
the asset to probe;
"""
if "ignore_this_check_iteration":
# nothing will be send to InfraSonar for this check iteration;
raise IgnoreResultException()
if "no_longer_try_this_check":
# nothing will be send to InfraSonar for this check iteration and the
# check will not start again until the probe restarts or configuration
# has been changed;
raise IgnoreCheckException()
if "something_has_happened":
# send a check error to InfraSonar because something has happened which
# prevents us from building a check result; The default severity for a
# CheckException is MEDIUM but this can be overwritten;
raise CheckException("something went wrong", severity=Severity.LOW)
if "something_unexpected_has_happened":
# other exceptions will be converted to CheckException, MEDIUM severity
raise Exception("something went wrong")
# A check result may have multiple types, items, and/or metrics
result = {"myType": [{"name": "my item"}]}
if "result_is_incomplete":
# optionally, IncompleteResultException can be given another severity;
# the default severity is LOW.
raise IncompleteResultException('missing type x', result)
if "not_count_as_check_result":
# optionally, NoCountException can be raised in which case the check
# result is not counted by InfraSonar; Thus, the last seen services
# will not "see" this check result.
# A severity can be given if we also want a check error; (similar to
# the IncompleteResultException exception)
raise NoCountException('do not count this check result', result)
# Use the asset in logging; this will include asset info and the check key
logging.info(f"log something; {asset}")
# Return the check result
return result
if __name__ == "__main__":
checks = {
"myFirstCheck": my_first_check,
}
# Initialize the probe with a name, version and checks
probe = Probe("myProbe", __version__, checks)
# Start the probe
probe.start()
```
## ASCII item names
InfraSonar requires each item to have a unique _name_ property. The value for _name_ must be a _string_ with ASCII compatible character.
When your _name_ is not guaranteed to be ASCII compatible, the following code replaces the incompatible characters with question marks (`?`):
```python
name = name.encode('ascii', errors='replace').decode()
```
## Config
When using a `password` or `secret` within a _config_ section, the library
will encrypt the value so it will be unreadable by users. This must not be
regarded as true encryption as the encryption key is publicly available.
Example yaml configuration:
```yaml
exampleProbe:
config:
username: alice
password: secret_password
assets:
- id: 123
config:
username: bob
password: "my secret"
- id: [456, 789]
config:
username: charlie
password: "my other secret"
otherProbe:
use: exampleProbe # use the exampleProbe config for this probe
```
## Dry run
Create a yaml file, for example _(test.yaml)_:
```yaml
asset:
name: "foo.local"
check: "system"
config:
address: "192.168.1.2"
```
Run the probe with the `DRY_RUN` environment variable set the the yaml file above.
```
DRY_RUN=test.yaml python main.py
```
> Note: Optionally an asset _id_ might be given which can by used to find asset configuration in the local asset configuration file. Asset _config_ is also optional.
### Dump to JSON
A dry run writes all log to _stderr_ and only the JSON dump is written to _stdout_. Therefore, writing the output to JSON is easy:
```
DRY_RUN=test.yaml python main.py > dump.json
```
Raw data
{
"_id": null,
"home_page": "https://github.com/infrasonar/python-libprobe",
"name": "libprobe",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "monitoring,infrasonar,probe",
"author": "Cesbit",
"author_email": "info@cesbit.com",
"download_url": "https://files.pythonhosted.org/packages/e1/6d/2253772c3cdd666351e16e67f5e641600923fcb5b8eb7002f2c018b268a9/libprobe-0.2.36.tar.gz",
"platform": null,
"description": "[](https://github.com/infrasonar/python-libprobe/actions)\n[](https://github.com/infrasonar/python-libprobe/releases)\n\n# Python library for building InfraSonar Probes\n\nThis library is created for building [InfraSonar](https://infrasonar.com) probes.\n\n## Environment variable\n\nVariable | Default | Description\n------------------- | ------------------------------ | ------------\n`AGENTCORE_HOST` | `127.0.0.1` | Hostname or Ip address of the AgentCore.\n`AGENTCORE_PORT` | `8750` | AgentCore port to connect to.\n`ENCRYPTION_KEY` | _default_ | Use your own encryption key for encrypting secrets in the YAML file.\n`INFRASONAR_CONF` | `/data/config/infrasonar.yaml` | File with probe and asset configuration like credentials.\n`MAX_PACKAGE_SIZE` | `500` | Maximum package size in kilobytes _(1..2000)_.\n`MAX_CHECK_TIMEOUT` | `300` | Check time-out is 80% of the interval time with `MAX_CHECK_TIMEOUT` in seconds as absolute maximum.\n`DRY_RUN` | _none_ | Do not run demonized, just return checks and assets specified in the given yaml _(see the [Dry run section](#dry-run) below)_.\n`LOG_LEVEL` | `warning` | Log level (`debug`, `info`, `warning`, `error` or `critical`).\n`LOG_COLORIZED` | `0` | Log using colors (`0`=disabled, `1`=enabled).\n`LOG_FTM` | `%y%m%d %H:%M:%S` | Log format prefix.\n`OUTPUT_TYPE` | `JSON` | Set the output type to `JSON` or `PPRINT` (Only for a dry run).\n\n## Usage\n\nBuilding an InfraSonar.get_state\n\n```python\nimport logging\nfrom libprobe.asset import Asset\nfrom libprobe.probe import Probe\nfrom libprobe.severity import Severity\nfrom libprobe.exceptions import (\n CheckException,\n IgnoreResultException,\n IgnoreCheckException,\n IncompleteResultException,\n NoCountException,\n)\n\n__version__ = \"0.1.0\"\n\n\nasync def my_first_check(asset: Asset, asset_config: dict, check_config: dict):\n \"\"\"My first check.\n Arguments:\n asset: Asset contains an id, name and check which should be used\n for logging;\n asset_config: local configuration for this asset, for example credentials;\n check_config: configuration for this check; contains for example the\n interval at which the check is running and an address of\n the asset to probe;\n \"\"\"\n if \"ignore_this_check_iteration\":\n # nothing will be send to InfraSonar for this check iteration;\n raise IgnoreResultException()\n\n if \"no_longer_try_this_check\":\n # nothing will be send to InfraSonar for this check iteration and the\n # check will not start again until the probe restarts or configuration\n # has been changed;\n raise IgnoreCheckException()\n\n if \"something_has_happened\":\n # send a check error to InfraSonar because something has happened which\n # prevents us from building a check result; The default severity for a\n # CheckException is MEDIUM but this can be overwritten;\n raise CheckException(\"something went wrong\", severity=Severity.LOW)\n\n if \"something_unexpected_has_happened\":\n # other exceptions will be converted to CheckException, MEDIUM severity\n raise Exception(\"something went wrong\")\n\n # A check result may have multiple types, items, and/or metrics\n result = {\"myType\": [{\"name\": \"my item\"}]}\n\n if \"result_is_incomplete\":\n # optionally, IncompleteResultException can be given another severity;\n # the default severity is LOW.\n raise IncompleteResultException('missing type x', result)\n\n if \"not_count_as_check_result\":\n # optionally, NoCountException can be raised in which case the check\n # result is not counted by InfraSonar; Thus, the last seen services\n # will not \"see\" this check result.\n # A severity can be given if we also want a check error; (similar to\n # the IncompleteResultException exception)\n raise NoCountException('do not count this check result', result)\n\n # Use the asset in logging; this will include asset info and the check key\n logging.info(f\"log something; {asset}\")\n\n # Return the check result\n return result\n\n\nif __name__ == \"__main__\":\n checks = {\n \"myFirstCheck\": my_first_check,\n }\n\n # Initialize the probe with a name, version and checks\n probe = Probe(\"myProbe\", __version__, checks)\n\n # Start the probe\n probe.start()\n```\n\n## ASCII item names\n\nInfraSonar requires each item to have a unique _name_ property. The value for _name_ must be a _string_ with ASCII compatible character.\nWhen your _name_ is not guaranteed to be ASCII compatible, the following code replaces the incompatible characters with question marks (`?`):\n\n```python\nname = name.encode('ascii', errors='replace').decode()\n```\n\n## Config\n\nWhen using a `password` or `secret` within a _config_ section, the library\nwill encrypt the value so it will be unreadable by users. This must not be\nregarded as true encryption as the encryption key is publicly available.\n\nExample yaml configuration:\n\n```yaml\nexampleProbe:\n config:\n username: alice\n password: secret_password\n assets:\n - id: 123\n config:\n username: bob\n password: \"my secret\"\n - id: [456, 789]\n config:\n username: charlie\n password: \"my other secret\"\notherProbe:\n use: exampleProbe # use the exampleProbe config for this probe\n```\n\n## Dry run\n\nCreate a yaml file, for example _(test.yaml)_:\n\n```yaml\nasset:\n name: \"foo.local\"\n check: \"system\"\n config:\n address: \"192.168.1.2\"\n```\n\nRun the probe with the `DRY_RUN` environment variable set the the yaml file above.\n\n```\nDRY_RUN=test.yaml python main.py\n```\n\n> Note: Optionally an asset _id_ might be given which can by used to find asset configuration in the local asset configuration file. Asset _config_ is also optional.\n\n### Dump to JSON\nA dry run writes all log to _stderr_ and only the JSON dump is written to _stdout_. Therefore, writing the output to JSON is easy:\n```\nDRY_RUN=test.yaml python main.py > dump.json\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Library for building InfraSonar probes",
"version": "0.2.36",
"project_urls": {
"Download": "https://github.com/infrasonar/python-libprobe/tarball/v0.2.36",
"Homepage": "https://github.com/infrasonar/python-libprobe"
},
"split_keywords": [
"monitoring",
"infrasonar",
"probe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e16d2253772c3cdd666351e16e67f5e641600923fcb5b8eb7002f2c018b268a9",
"md5": "607d56b675444204cb5a0f9ececbfd53",
"sha256": "fea4c3f5c315eff9d36e90586b1d95734009c551a200151cfb0844444d0f206d"
},
"downloads": -1,
"filename": "libprobe-0.2.36.tar.gz",
"has_sig": false,
"md5_digest": "607d56b675444204cb5a0f9ececbfd53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30678,
"upload_time": "2023-10-25T08:54:05",
"upload_time_iso_8601": "2023-10-25T08:54:05.256134Z",
"url": "https://files.pythonhosted.org/packages/e1/6d/2253772c3cdd666351e16e67f5e641600923fcb5b8eb7002f2c018b268a9/libprobe-0.2.36.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-25 08:54:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "infrasonar",
"github_project": "python-libprobe",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "libprobe"
}
JSON
