Getting Started

Home

---

Argus is a highly scalable, time-series monitoring and alerting system. It stores metric data as time-series and event data in the form of annotations. You can apply its extensible query language and huge set of transforms to raw metric data. Currently, you can evaluate alerts that are configured with triggers and notifications.

Set Up Argus

Argus is built on top of OpenTSDB, RDMBS, Kafka, and an LDAP server. Argus authenticates each call for a user against the LDAP server and an optional Redis cache. Instructions on installing these components are provided at the following links.

• OpenTSDB—Stores metric time-series data and annotations
• Relational database management system (RDBMS)—Stores dashboard and alert metadata

NOTE: You can use any RDBMS of your choice. We’ve tried using PostgresSQL and Apache Derby.

• Kafka—Messaging system
• LDAP server—Authenticates users
• Redis—Cache

A web servlet container is required to run the web application archive (.war) file that is built as part of the build process. We use Tomcat. Instructions on getting Tomcat up and running are here.

After all these components are up and running, it’s time to download, build, configure, and deploy Argus in a local environment.

Download Source and Build

Note: Completing the build process requires running maven. Make sure that you have maven installed.

1. Download Argus from Github.
   
2. Go to the Argus directory and list all the files.
   

• ArgusClient— Command line distributed execution client used to perform asynchronous operations.
• ArgusCore—Core directory that contains all the business services.
• ArgusWeb— Argus stock UI embraces a complete service-oriented architecture. The UI contains static JS, CSS, and HTML5 that eventually call into the web service endpoints.
• ArgusWebServices - Contains RESTFul services that wrap the core services and expose them to users as web service endpoints.
• argus-build.properties—Properties that are used for configuring the build of Argus and specifying the runtime configuration for integration tests. The required properties start with build.*. Optionally, you can set any other Argus runtime configuration to wire up Argus to systems required to run the integration tests.

Example: Configuration file

/* 
The persistence unit definition. Here we’re using in memory derby. 
Whatever persistence unit you add here gets packaged with the artifact.  
You want to change it depending on whether you’re testing or running in production.
*/
build.property.persistence.unit=<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>\n    <exclude-unlisted-classes>false</exclude-unlisted-classes>\n    <properties>\n      <property name="javax.persistence.schema-generation.database.action" value="drop-and-create-tables"/>\n      <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>\n      <property name="javax.persistence.jdbc.url" value="jdbc:derby:memory:argus;create=true"/>\n      <property name="javax.persistence.jdbc.user" value="root"/>\n      <property name="javax.persistence.jdbc.password" value="root"/>\n      <property name="eclipselink.ddl-generation" value="drop-and-create-tables"/>\n      <property name="eclipselink.logging.level" value="SEVERE"/>\n      <property name="eclipselink.logging.parameters" value="true"/>\n      <property name="eclipselink.target-database" value="DERBY"/>\n      <property name="eclipselink.canonicalmodel.subpackage" value="unit"/>\n    </properties>

/*
Indicate in the web.xml whether secure cookies should be used.
*/
build.property.secure.cookies=true

/*
The following properties are regular Argus configuration, but are used to configure the integration tests. None of these configurations get packaged with the artifact. These are described in detail in [service-level](#service-level-properties) properties.
*/
system.property.log.level=ERROR
system.property.mail.enabled=false
service.property.mq.connection.count=2
service.property.mq.endpoint=vm\://localhost?broker.persistent\=false
service.property.auth.ldap.authtype=simple
service.property.auth.ldap.endpoint=ldaps://ldaps.yourcompany.com:636
service.property.auth.ldap.searchbase=OU=users,DC=yourcompany,DC=com:OU\=robots,DC\=yourcompany,DC\=com
service.property.auth.ldap.searchdn=CN=ldap_search_user,OU=users,DC=yourcompany,DC=com
service.property.auth.ldap.searchpwd=ldap_search_user_password
service.property.auth.ldap.usernamefield=sAMAccountName
service.property.tsdb.connection.count=2
service.property.tsdb.endpoint.read=http://tsdbreadendpoint:4466
service.property.tsdb.endpoint.timeout=10000
service.property.tsdb.endpoint.write=http://tsdbwriteendpoint:4477

3. Go back to the parent Argus directory.

4. After you have correctly set the properties, run maven install and package from the Argus directory.

   $ mvn install -Dmaven.test.skip=true -DskipDockerBuild
   

   After the build is done, run the following:

   $ mvn javacc:javacc -DoutputDirectory=src/main/java
   

   NOTE: If you see an error referencing com.spotify:docker-maven-plugin:0.4.11:build for ArgusWeb, you may need to install Docker.

   At the end of these commands, you see something like the following example.

   Example:

   

   If everything went well, the build process created a target directory under each previously mentioned project (except for ArgusWeb). The following components are required.

   * `ArgusWebServices/target/argus-webservices-version-SNAPSHOT.war`
   * `ArgusClient/target/argus-client-version-SNAPSHOT-jar-with-dependencies.jar`
   

5. Before you deploy the .war file, configure Argus to use the different services previously mentioned.

Configure Argus

Argus uses several different services, and some services have more than one implementation. Configuring Argus is dynamic—switching from one implementation of a service to another does not require rebuilding the source.

1. On system startup, Argus loads configuration properties from files specified by the following two properties, passed as virtual machine arguments. Neither property is required, but if both of the properties are skipped, the default configuration is used:
   • argus.config.private.location
   • argus.config.public.location

NOTE: Properties from public location override the properties from private location.

2. Argus properties are broken into two parts.
   • Root level—Properties specifying the concrete implementations that Argus services are configured with and certain properties that are common to all services.
   • Service level—Properties that can be grouped in a single file for a particular service. The service file can then be referenced in the root properties. Alternatively, you can create one file for each service. We use the latter approach for clarity.

Root-level properties

Name	Description	Default Value
system.property.build	System build number	XXXX-XX
system.property.version	System version	X.X
system.property.log.level	Logging level for emitting logs in the system	INFO
system.property.admin.email	Admin email—all admin related emails are sent to this address	[email protected]
system.property.mail.enabled	Determines whether mail is sent out from the system	false
system.property.goc.enabled		false
system.property.client.threads	Number of client threads	2
system.property.client.connect.timeout	Number of second to elapse before client connection times out	10000
service.binding.cache	Concrete implementation to bind to the cache service	com.salesforce.dva.argus.service.cache.NoOperationCacheService
service.config.cache		cache.properties
service.binding.mq	Concrete implementation to bind to the internal messaging service	com.salesforce.dva.argus.service.mq.kafka.KafkaMessageService
service.config.mq		mq.properties
service.binding.alert	Concrete implementation to bind to the alert service	com.salesforce.dva.argus.service.alert.DefaultAlertService
service.config.alert		argus.properties
service.binding.scheduling	Concrete implementation to bind to the scheduling service	com.salesforce.dva.argus.service.schedule.DefaultSchedulingService
service.config.scheduling		argus.properties
service.binding.mail	Concrete implementation to bind to the mail service	com.salesforce.dva.argus.service.mail.DefaultMailService
service.config.mail		argus.properties
service.binding.auth	Concrete implementation to bind to the authentication service	com.salesforce.dva.argus.service.auth.LDAPAuthService
service.config.auth		argus.properties
service.binding.schema	Concrete implementation to bind to the schema service	com.salesforce.dva.argus.service.schema.HbaseSchemaService
*service.config.schema		argus.properties
service.binding.tsdb	Concrete implementation to bind to the TSDB service	com.salesforce.dva.argus.service.tsdb.DefaultTSDBService
service.config.tsdb		argus.properties

Deploy Argus Web Services

You can now deploy the argus-webservices--SNAPSHOT.war file. The file is generated in your Tomcat web apps directory (or any other server’s respective apps directory).

1. Start Tomcat (or your preferred web server).
2. Navigate to the following url.
   http://localhost:port_web_server_listens_on/name_of_your_war/help
   You see the following page.