Find file History
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Bumps versions and moves off deprecated apis Aug 31, 2018 Uses latest layout factory and fixes a little drift (#115) Dec 5, 2018
pom.xml [maven-release-plugin] prepare for next development iteration Jan 21, 2019



This is a Spring Boot AutoConfiguration module that can be added to a Zipkin Server deployment to collect Spans from Amazon SQS queues. Internally this module wraps the SQSCollector and exposes configuration options through environment variables.

Quick start

JRE 8 is required to run Zipkin server.

Fetch the latest released executable jar for Zipkin server and autoconfigure module jar for the sqs collector. Run Zipkin server with the SQS collector enabled.

For example:

$ curl -sSL | bash -s
$ curl -sSL | bash -s sqs.jar
      java \
      -Dloader.path='sqs.jar,sqs.jar!/lib' \ \
      -cp zipkin.jar \

After executing these steps, applications can send spans http://localhost:9411/api/v2/spans (or the legacy endpoint http://localhost:9411/api/v1/spans)

The Zipkin server can be further configured as described in the Zipkin server documentation.


Configuration can be applied either through environment variables or an external Zipkin configuration file. The module includes default configuration that can be used as a reference for users that prefer a file based approach.

Environment Variables
  • SQS_QUEUE_URL The AWS SQS queue URL as provided in the AWS Console.
  • SQS_PARALLELISM An integer that specifies how many collectors are used to poll SQS in parallel. Default is 1
  • SQS_WAIT_TIME_SECONDS How long to wait for messages from SQS before making a new API call. Default 20 seconds
  • SQS_MAX_NUMBER_OF_MESSAGES Max number of messages to accept for each SQS API call. Default 10
  • SQS_AWS_ACCESS_KEY_ID Optional AWS Access Key ID.
  • SQS_AWS_SECRET_ACCESS_KEY Optional AWS Secret Access Key.
  • SQS_AWS_STS_ROLE_ARN Optional IAM role ARN for cross account role delegation.
  • SQS_AWS_STS_REGION Optional AWS region ID when using STS. Default us-east-1


The auto configuration library uses the AWS SQS Java SDK and follows credential configuration resolution provided by the DefaultAWSCredentialsProviderChain. In the case of using IAM role delegation the STSAssumeRoleSessionCredentialsProvider is used.

The following IAM permissions are required by the SQSCollector

  • sqs:ReceiveMessage
  • sqs:DeleteMessageBatch


Once your collector is enabled, verify it is running:

curl -s localhost:9411/health|jq .zipkin.details.SQSCollector
  "status": "UP"

Now, you can send a test message like below:

# send a json list with a single json-encoded span
$ aws sqs send-message --queue-url $SQS_QUEUE_URL --message-body '[{
  "traceId": "86154a4ba6e91385",
  "parentId": "86154a4ba6e91385",
  "id": "4d1e00c0db9010db",
  "kind": "CLIENT",
  "name": "get",
  "timestamp": 1472470996199000,
  "duration": 207000,
  "localEndpoint": {
    "serviceName": "frontend",
    "ipv4": ""
  "tags": {
    "http.path": "/api"
# read it back using the zipkin v1 api
$ curl -s localhost:9411/api/v1/trace/86154a4ba6e91385|jq .[].traceId