Document how to make a custom standalone collector

This involves some spring magic and isn’t particularly obvious on how to do it. I did it earlier today, but I’ll have to look at it tomorrow to remember what exactly is needed. Here’s what I remember so far:

POM modifications:

• Lots of copy/paste from zipkin-server POM
  • Need to add the correct zipkin autoconfigure dependencies to your POM (so for example, if you’re writing to cassandra, add zipkin-autoconfigure-storage-cassandra… or just add all of them)
  • Add spring boot configuration parser to POM
  • Add sprint boot starter to POM

Creating the collector:

• Lots of copy/paste from the kafka collector
  • Two pieces: configuration and stream collector, it’s fairly straightforward copy/pasting
  • Need to add a spring autoconfigure thing to your resources

Creating a main function to run:

• Create a main class, see the main zipkin-server class
  • This class should have the sampler @Bean in it
• If you want to use environment variables to configure the app like everything else in zipkin, then you need to copy/paste a bunch of stuff from zipkin-server.yml, and add that to your own app’s resources

Finally, make sure that you don’t mess up the annotation compilation, otherwise you’ll get really weird errors and it won’t work.

At some point, it might be useful to make a sample project with all of these.

Execution is however one would normally execute a spring boot application.

[codefromthecrypt]

copied from #1488

Update: figured out how to get modularity working. It is a little constrained, but it works now.

Here’s how.

Step 1: Add spring boot plugin to your autoconfig module, adding a “module” jar

The classifier name “module” is arbitrary, but I think it works. Take extreme care to not duplicate jars already in zipkin-server’s exec jar. Here’s an example configuration for the SQS collector:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <!-- Import dependency management from Spring Boot -->
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>${spring-boot.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>repackage</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <layout>MODULE</layout>
          <classifier>module</classifier>
          <!-- https://github.com/spring-projects/spring-boot/issues/3426 transitive exclude doesn't work -->
          <excludeGroupIds>io.zipkin.java,org.springframework.boot,org.springframework,commons-codec,com.fasterxml.jackson.core,com.fasterxml.jackson.dataformat,org.apache.httpcomponents,commons-logging,joda-time,software.amazon.ion</excludeGroupIds>
          <!-- already packaged in zipkin-server -->
          <excludeArtifactIds>aws-java-sdk-core,aws-java-sdk-sts,jmespath-java</excludeArtifactIds>
        </configuration>
      </plugin>
    </plugins>
  </build>

This will make a file like… autoconfigure/collector-sqs/target/zipkin-autoconfigure-collector-sqs-0.0.4-SNAPSHOT-module.jar

Step 2: Extract this module jar when composing a server layer

I cannot get the PropertiesLauncher configuration to accept the module-jar directly. However, the following does work.

1. extract your module jar somewhere (Ex to an extensions folder)
2. explicitly start zipkin using PropertiesLauncher with loader.path set to include that directory

Example:

$ java  -Dloader.path=/tmp/extensions -cp zipkin.jar org.springframework.boot.loader.PropertiesLauncher --zipkin.collector.sqs.queue-url=http://foobar

Note: the module jar is self-contained… when doing your devopsian things, feel free to just curl it from jcenter, like we do for the server jar.

[codefromthecrypt]

this works fine now. both in aws and azure. we just need to polish instructions