Quick Start - nuclearfurnace/oscilloscope GitHub Wiki

Getting Oscilloscope configured

Oscilloscope uses two separate forms for configuration: the default Dropwizard configuration, and Archaius for the more dynamic bits. In almost all cases, the Dropwizard configuration can stay as is. The only configuration we need for sure is the Archaius one, so we'll be generating a config.properties file to use. This is a simple name.of.my.key = value_here format, so no sweat!

(If you can't have Oscilloscope running HTTP on port 8080, then you can tweak its oscilloscope.yaml configuration. Dropwizard has a great configuration reference that goes over all the possible values)

Prep work: create a configuration file

Go ahead and create a file called config.properties somewhere. We'll be referencing its path directly when running Oscilloscope, so location is not important right now.

Choose your own adventure: discovery providers

Discovery providers are Oscilloscope's way of finding Hystrix-enabled clusters. These can be statically configured lists, or more dynamic, using services like Consul or directly querying ELBs in EC2. Below is a list of the supported discovery providers and all the necessary configuration -- for Oscilloscope and any prerequisites -- for each of them. You can use multiple providers at the same time.

Static

This mode takes a statically defined list of cluster names, and a statically defined list of hosts for each of those cluster names.

You'll need to add the static provider to your list of providers so it gets loaded: oscilloscope.discovery.providers.

Next, you'll have to set the list of clusters you want to expose and the list of hosts in each of those clusters: oscilloscope.discovery.providers.static.

If your service cluster is serving over HTTP, with the Hystrix endpoint at /hystrix.stream, then you're good. If it serves HTTPS, or has the Hystrix endpoint at a different path, you'll need to tweak the URI template used: oscilloscope.discovery.providers.static.uri_template.

Since this provider is defined statically, there's nothing else you need here.

Example configuration:

oscilloscope.discovery.providers = static
oscilloscope.discovery.providers.static = svc-prod
oscilloscope.discovery.providers.static.uri_template = https://{HOSTNAME}:{PORT}/hystrix.stream
oscilloscope.discovery.providers.static.svc-prod = 10.0.0.1:8080,10.0.0.2:8080,10.0.0.3:8080

Consul

This mode uses Consul to find services which are Hystrix-enabled. It expects that a Consul agent will be running locally on port 8500. It does not currently have support for targeting a specific datacenter.

You'll need to add the consul provider to your list of providers so it gets loaded: oscilloscope.discovery.providers.

The only remaining step is that, for each service in Consul which should be Hystrix-enabled, you will need to add a tag to that service called hystrix. This is how Oscilloscope differentiates Hystrix-enabled services from non-Hystrix-enabled services.

Example configuration:

oscilloscope.discovery.providers = consul
oscilloscope.discovery.providers.consul.uri_template = https://{HOSTNAME}:{PORT}/hystrix.stream

ELB

This mode queries ELBs in EC2 directly to find Hystrix-enabled services. As we use the AWS Java SDK, it expects to find the access/secret key in environment variables or to be able to get them from whatever IAM profile is applied to the instance. There is currently no support for passing keys in to Oscilloscope manually.

You'll need to add the elb provider to your list of providers so it gets loaded: oscilloscope.discovery.providers.

For tricky setups involving talking between EC2-Classic and VPCs, there is an option to configure whether Oscilloscope uses the public address or private address of an instance when connecting to the Hystrix endpoint: oscilloscope.discovery.providers.elb.use_private_address. By default, Oscilloscope uses the private address.

The only remaining step is that, for each ELB which should be Hystrix-enabled, you will need to add a tag to the ELB with the name features and a value of hystrix. This is how Oscilloscope differentiates Hystrix-enabled ELBs from non-Hystrix-enabled ELBs. You have some wiggle room, though, in that the tag name Oscilloscope looks for can be changed if you want: oscilloscope.discovery.providers.elb.tag_name. The value of the tag must contain hystrix, however, although it can be on its own or a substring of the value.

Example configuration:

oscilloscope.discovery.providers = elb
oscilloscope.discovery.providers.elb.tag_name = svc_features
oscilloscope.discovery.providers.elb.uri_template = https://{HOSTNAME}:{PORT}/hystrix.stream

Building Oscilloscope

There's some simple prerequisites to build/run Oscilloscope:

Node.js
Maven
Java 1.8

From the root of the checkout, run the following:

npm install
npm run webpack
mvn clean
mvn package

If all goes well, you should now have a fat JAR built and available under target/oscilloscope-*-SNAPSHOT.jar.

Running Oscilloscope

To run Oscilloscope, we simply need to specify the JAR to use and also set the path to our config.properties. From the root of the checkout, run the following:

java -jar target/oscilloscope-{VERSION}-SNAPSHOT.jar -Darchaius.configurationSource.additionalUrls=file://{PATH TO CONFIG} server oscilloscope.yaml

Replace {VERSION} with the version of Oscilloscope, and {PATH TO CONFIG} with the full path to your config.properties file. It's important to note that Archaius expects to see the file:// portion of the path, otherwise it won't load your configuration.

If all went well, Oscilloscope should now be running. If you didn't change oscilloscope.yaml, you can now navigate to http://localhost:8080.