Python library for building InfraSonar Probes

This library is created for building InfraSonar 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 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

importloggingfromlibprobeimportloggerfromlibprobe.assetimportAssetfromlibprobe.probeimportProbefromlibprobe.checkimportCheckfromlibprobe.severityimportSeverityfromlibprobe.exceptionsimport (
CheckException,
IgnoreResultException,
IgnoreCheckException,
IncompleteResultException,
NoCountException,
)
__version__="0.1.0"classMyFirstCheck(Check):
key='myFirstCheck'unchanged_eol=0# Can be for example 14400, to prevent sending the same# check result for the next 4 hours (0=disabled)@staticmethodasyncdefrun(asset: Asset, local_config: dict, config: dict) ->dict:
"""My first check. Arguments: asset: Asset contains an id, name and check which should be used for logging; local_config: local configuration for this asset, for example credentials; 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;raiseIgnoreResultException()
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;raiseIgnoreCheckException()
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;raiseCheckException("something went wrong", severity=Severity.LOW)
if"something_unexpected_has_happened":
# exceptions will be converted to CheckException, MEDIUM severityraiseException("something went wrong")
# A check result may have multiple types, items, and/or metricsresult= {"myType": [{"name": "my item"}]}
if"result_is_incomplete":
# optionally, IncompleteResultException with severity;# the default severity is LOW.raiseIncompleteResultException('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)raiseNoCountException('do not count this check result', result)
# Use the asset in logging; includes asset info and the check keylogging.info(f"log something; {asset}")
# In alpha versions and debug logging enabled, unknown exception will# be logged when debug logging is enabled.# You may use logger.exception() yourself if you want exception# logging for debug logging only.try:
42/0# ZeroDivision error for exampleexceptException:
logger.exception() # log the exception only when DEBUG logging# Return the check resultreturnresultif__name__=="__main__":
checks= (
MyFirstCheck
)
# Initialize the probe with a name, version and checksprobe=Probe("myProbe", __version__, checks)
# Start the probeprobe.start()

On CLose

Using the set_on_close() method, it is possible to configure a method which will be called before the probe is stopped. This can be useful in case you want to nicely close some connections.

asyncdefcustom_on_close():
...
probe=Probe("myProbe", '3.0.0', {})
probe.set_on_close(custom_on_close)

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 (?):

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:

exampleProbe:
config:
username: alicepassword: secret_passwordassets:
- id: 123config:
username: bobpassword: "my secret"
- id: [456, 789]config:
username: charliepassword: "my other secret"otherProbe:
use: exampleProbe # use the exampleProbe config for this probe

Dry run

Create a yaml file, for example (test.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