openzipkin/zipkin-aws repository overview

⁠zipkin-aws

Shared libraries that provide Zipkin integration with AWS Kinesis, SQS, and X-Ray. Requires JRE 8 or later.

⁠Usage

These components provide Zipkin Reporters⁠ and Senders⁠, which build off interfaces provided by the zipkin-reporters-java⁠, and and Collectors⁠, which are used in a Zipkin⁠ server.

⁠Reporters and Senders

The component in a traced application that sends timing data (spans) out of process is called a Reporter. It is responsible for handling the queueing and encoding of outbound spans.

Reporters that are sending Zipkin data to Zipkin typically make use of a Sender, which implements the wire protocol to a particular technology used to send the encoded spans. Typically Senders are called on interval by an async reporter⁠.

NOTE: Applications can be written in any language. While we currently only have Reporters and Senders in Java, senders in other languages are welcome.

⁠Collectors

The component in a zipkin server that receives trace data is called a collector. This decodes spans reported by applications and persists them to a configured storage component.

⁠Server integration

In order to integrate with zipkin-server, you need to use properties launcher to load your collector (or sender) alongside the zipkin-server process.

To integrate a module with a Zipkin server, you need to:

• add a module jar to the loader.path
• enable the profile associated with that module
• launch Zipkin with PropertiesLauncher

Each module will also have different minimum variables that need to be set.

Ex.

$ java -Dloader.path=sqs.jar -Dspring.profiles.active=sqs -cp zipkin.jar org.springframework.boot.loader.PropertiesLauncher

⁠Example integrating the SQS Collector

If you cannot use our Docker image⁠, you can still integrate yourself by downloading a couple jars. Here's an example of integrating the SQS Collector.

⁠Step 1: Download zipkin-server jar

Download the latest released server⁠ as zipkin.jar:

cd /tmp
curl -sSL https://zipkin.io/quickstart.sh | bash -s

⁠Step 2: Download the latest sqs-module jar

Download the latest released SQS module⁠ as sqs.jar:

cd /tmp
curl -sSL https://zipkin.io/quickstart.sh | bash -s io.zipkin.aws:zipkin-module-collector-sqs:LATEST:module sqs.jar

⁠Step 3: Run the server with the "sqs" profile active

When you enable the "sqs" profile, you can configure sqs with short environment variables similar to other Zipkin integrations⁠.

cd /tmp
SQS_QUEUE_URL=<from aws sqs list-queues> \
    java \
    -Dloader.path='sqs.jar,sqs.jar!/lib' \
    -Dspring.profiles.active=sqs \
    -cp zipkin.jar \
    org.springframework.boot.loader.PropertiesLauncher

** NOTE: Make sure the parameters are defined in the same line or use environment variables **

⁠Artifacts

All artifacts publish to the group ID "io.zipkin.aws". We use a common release version for all components.

⁠Library Releases

Releases are uploaded to Bintray⁠ and synchronized to Maven Central⁠

⁠Library Snapshots

Snapshots are uploaded to JFrog⁠ after commits to master.