- Notifications
You must be signed in to change notification settings - Fork0
A Rust Opsview API Client Library with batteries included.
License
johanthoren/opsview-rs
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Theopsview crate is a Rust library designed to interact with theOpsviewmonitoring software. Itprovides a comprehensive coverage of the Opsview REST API and allows you tohandle Opsview objects such as hosts, service checks, host groups, and more. Theinitial focus is on theclient andconfig modules which enables the user toperform all kinds of object configuration management using this Rust library.
This project is currently in development and is subject to change at any time.It is not yet complete.
- Comprehensive coverage of Opsview objects: Hosts, Service Checks, Host Groups,etc. All objects in the configuration API are available as native Rustobjects.
- Builder pattern objects for creating and configuring Opsview objects.
- Asynchronous API interactions with built-in error handling.
- Custom serialization and deserialization for Opsview API compatibility.
This library aims to provide client side validation of as many fields aspossible. That means that you can add solid error handling of any incompatiblefield values before even making an API call to the Opsview server and insteadcatch and handle the error returned by the API.
For example, let's say that your program parses a name from some file anddecides to create aHashtag with the nameMy New Hashtag. You don't have tocover all name checks on your side, you can simply try to build aHashtagusing either of the associatedbuilder orminimal functions and then matchtheResult. No need to even connect to the Opsview API.
Example:
use opsview::config::Hashtag;use opsview::prelude::*;#[tokio::main]asyncfnmain(){let my_new_hashtag =Hashtag::minimal("My New Hashtag");match my_new_hashtag{Err(OpsviewConfigError::DoesNotMatchRegex(_, _)) =>{todo!("Do something")},// <-- This is the matching branchErr(_) =>{todo!("Do something else")}Ok(_) =>(),// Do nothing.}}
This allows you to write robust solutions with fewer errors.
Adding these checks is a priority but still a work in progress. All fieldsmissing validation are marked with a TODO in the source code. If you find onethat doesn't, please let me know.
This library makes frequent use of the Builder pattern to create and configureOpsview objects.
All configuration related objects such asHashtag,Host,ServiceCheck andso on are represented as native Rust structs with the traitConfigObject.These all have theBuilder trait which defines thebuilder() function whichwill initiate a new builder object.
The standard pattern for creating a new object is to use the associatedbuilder() function of the type ofConfigObject that you want to create tocreate a new builder, then chain the builder's methods to configure the object,and finally callbuild() to create the object. Using thebuild() method willgive you some assurances that theConfigObject that you are trying to createis valid.
Note that there are noonline checks when building the object, you will stillhave to check for existing names, etc, at some point. But it will force you topopulate all required fields with valid data.
It is generally discouraged to createConfigObject structs directly, as thismay result in invalid objects that cannot be used with the Opsview API. Theseobjects are primarily used for deserialization from the Opsview API.
Here's a quick example to get you started with this library:
use opsview::{client::OpsviewClient, prelude::*, config::Hashtag};asyncfnnew_hashtag(client:&OpsviewClient,name:&str) ->Result<(),OpsviewError>{let new_hashtag =Hashtag::builder().name(name).description("This Hashtag was created using Rust").enabled(true).all_hosts(true).build()?; new_hashtag.create(client).await?;Ok(())}#[tokio::main]asyncfnmain(){let client =OpsviewClient::builder().url("https://opsview.example.com").username("admin").password("password").build().await.unwrap();let result =new_hashtag(&client,"foo").await;match result{Ok(_) =>{println!("Success")},Err(_) =>{println!("Failure")},} client.apply_changes().await.expect("Failed to apply changes"); client.logout().await.expect("Failed to log out");}
A more complex example:
use opsview::client::OpsviewClient;use opsview::config::{Host,Hashtag,HostGroup,HostTemplate};use opsview::prelude::*;#[tokio::main]asyncfnmain(){let client =OpsviewClient::builder().url("https://opsview.example.com").username("admin").password("password").build().await.unwrap();let master_monitoring_server = client.get_monitoringcluster_config("Master Monitoring Server",None).await.expect("Couldn't fetch 'Master Monitoring Server' from the API");let root_hostgroup = client.get_hostgroup_config("Opsview",None).await.expect("Couldn't fetch HostGroup with the name 'Opsview' from the API");let opsview_rs_hostgroup =HostGroup::builder().name("OpsviewRS").parent(root_hostgroup).build().expect("Failed to build hostgroup 'opsview_rs_hostgroup'");// Create the HostGroup before adding is to the Host, since doing so will// consume the HostGroup and require a clone if the call to create is done// later. opsview_rs_hostgroup.create(&client).await.expect("Failed to create hostgroup 'opsview_rs_hostgroup'");let network_base_template = client.get_hosttemplate_config("Network - Base",None).await.expect("Couldn't fetch 'Network - Base' from the API");letmut templates =ConfigObjectMap::<HostTemplate>::new(); templates.add(network_base_template);let templates = templates;// Optional shadowing to avoid mutable objects.let opsview_rs_hashtag =Hashtag::builder().name("OpsviewRS").description("This Hashtag represents objects created by opsview-rs").build().expect("Failed to build hashtag 'OpsviewRS'");// Create the Hashtag before adding it to the ConfigObjectMap<Hashtag>// since adding it will consume the Hashtag and require a clone if the// call to create is done later. opsview_rs_hashtag.create(&client).await.expect("Failed to create hashtag 'opsview_rs_hashtag'");letmut hashtags =ConfigObjectMap::<Hashtag>::new(); hashtags.add(opsview_rs_hashtag);let hashtags = hashtags;// Optional shadowing to avoid mutable objects.let new_host =Host::builder().name("MyNewHost").alias("This host was created using opsview-rs").ip("127.0.0.1").monitored_by(master_monitoring_server).hostgroup(opsview_rs_hostgroup).hosttemplates(&templates).hashtags(&hashtags).build().expect("Failed to build host 'MyNewHost'"); new_host.create(&client).await.expect("Failed to create host 'new_host'"); client.apply_changes().await.expect("Failed to apply changes"); client.logout().await.expect("Failed to log out");}
For detailed documentation on all available modules, structs, and functions,please refer to the generated docs using:
cargo doc --open
This project is not affiliated withITRS Group.
Please direct any questions or bug reports tothe GitHub page of theproject and not to ITRS GroupSupport.
For testing with a live Opsview server, make sure to populate the followingenvironment variables:
OV_URLOV_USERNAMEOV_PASSWORD
When running theignored tests, make sure to use--test-threads=1 and thatthere are no unsaved changes on the Opsview server in question.
Copyright © 2024 Johan Thorénjohan@thoren.xyz
This project is released under the ISC license. See the LICENSE file for moredetails.
About
A Rust Opsview API Client Library with batteries included.
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Uh oh!
There was an error while loading.Please reload this page.