Skip to content

Latest commit

 

History

History
112 lines (89 loc) · 4.96 KB

README.md

File metadata and controls

112 lines (89 loc) · 4.96 KB
Raw

Gitter chat Build Status Maven Central

zipkin-aws

Shared libraries that provide Zipkin integration with AWS Kinesis, SQS, and X-Ray. Requires JRE 6 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.

Reporter Description
X-Ray UDP Reports spans to X-Ray, AWS's alternative to Zipkin.
Sender Description
SQS Sends tracing data to Zipkin using SQS, a message queue service.
Kinesis Sends tracing data to Zipkin using Kinesis, an alternative similar to Kafka.

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.

Collector Description
SQS An alternative to Kafka.
Kinesis An alternative to Kafka.

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.