Getting Started

Getting started with Cereebro, Spring Cloud Netflix and the Eureka Server

Cereebro is at its best when coupled to Spring Cloud and Netflix OSS.

It takes two steps to have your component graph drawn for you by Cereebro :

1. Add the Cereebro Snitch Spring Boot Starter to each application in your system
2. Create a Cereebro Server that will resolve a graph for you

Cereebro leverages Eureka on both sides :

• The Cereebro Snitch on each application provides information to Eureka as metadata (Snitch Endpoint URI and SystemFragment JSON data)
• The Cereebro Server can access that metadata and use the Eureka server as a SnitchRegistry

The Cereebro server does not even have to access each application's Snitch endpoint, as the information is published on Eureka.

1) Add the Cereebro Snitch to each application

Add the following Spring Boot starter in each application's pom.xml :

<dependency>
    <groupId>io.cereebro</groupId>
    <artifactId>cereebro-snitch-spring-boot-starter</artifactId>
    <version>1.1.0</version>
</dependency>

<!-- Your usual Spring Cloud Feign and Eureka Client dependencies -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-feign</artifactId>
</dependency>

This starter will add the following behavior to your applications :

• detect automatically :
  • SQL databases dependencies
  • Apache Cassandra database dependencies
  • Redis dependencies
  • MongoDB dependencies
  • Elasticsearch dependencies
  • Neo4j dependencies
  • RabbitMQ dependencies
• detect beans annotated with Cereebro annotations : @DependencyHint, @ConsumerHint or @RelationshipHints
• detect relationships declared in application properties
• provide an actuator Snitch endpoint that will reveal your applications relationships
• detect @FeignClient annotated beans as dependencies
• populate the Eureka instance metadata with the Snitch endpoint URI and JSON SystemFragment

Don't forget to give your application a name, by order of preference we use the following properties :

• spring.application.name : this name also used as a serviceId by Eureka and Feign
• cereebro.application.component.name : will override the spring name if set (you should probably not)
• a random UUID by default (please don't -- it's only here to prevent your app from crashing at startup)

2) Create a Cereebro Server

The Eureka Server provides a centralized registry of all HTTP applications in the system.
This is a gift for anyone trying to draw a component graph.

Two options for the Cereebro server using Eureka :

• Create a separate Spring Cloud application that will consume the Eureka server's metadata
• Use the Cereebro add-on for the Eureka server

In both cases, you should add the @EnableCereebroServer annotation on some configuration class, for example your @SpringBootApplication class.

Separate Cereebro Server

Create a new Spring Cloud application with the following dependencies :

<dependency>
    <groupId>io.cereebro</groupId>
    <artifactId>cereebro-server-spring-boot-starter</artifactId>
    <version>1.1.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>

Add the @EnableCereebroServer annotation on a configuration class, for example :

@SpringBootApplication
@EnableCereebroServer
public class CereebroServerEurekaClientApplication {

    public static void main(String[] args) {
        SpringApplication.run(CereebroServerEurekaClientApplication.class, args);
    }

}

Configure the application to target your Eureka Server with traditional Eureka client properties :

# No need to declare the Cereebro server as a service instance
eureka.client.register-with-eureka=false

# Fetch the Eureka server registry to discover service instances
eureka.client.fetch-registry=true

# URL of your Eureka server (ending with /eureka)
eureka.client.service-url.defaultZone=

Under the hood, the Cereebro server will use Spring Cloud's DiscoveryClient interface to consume the Eureka server's HTTP API and read each registered application's metadata.

To visualize your system's component graph, open the /cereebro/system page on your Cereebro server application.

See the sample source code.

Cereebro Server as a Eureka server add-on

Add the following dependencies to your Eureka server application :

<dependency>
    <groupId>io.cereebro</groupId>
    <artifactId>cereebro-server-spring-boot-starter</artifactId>
    <version>1.1.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka-server</artifactId>
</dependency>

Add the @EnableCereebroServer annotation on some configuration class, for example :

@SpringBootApplication
@EnableCereebroServer
@EnableEurekaServer
public class CereebroEurekaServerSampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(CereebroEurekaServerSampleApplication.class, args);
    }

}

Cereebro will use the Eureka server's internal registry to read each registered application's metadata.

Voilà ! Hit /cereebro/system on your Eureka server to see what your system looks like.

See the sample source code.

Learn more

See our samples.

Read the rest of our documentation to learn more about Cereebro.