Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
README.md
pom.xml

README.md

autoconfigure-collector-kinesis

ZipkinKinesisCollectorAutoConfiguration

This is a Spring Boot AutoConfiguration module that can be added to a Zipkin Server deployment to collect Spans from Amazon Kinesis streams. Internally this module wraps the KinesisCollector 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 kinesis collector. Run Zipkin server with the Kinesis collector enabled.

For example:

$ curl -sSL https://zipkin.io/quickstart.sh | bash -s
$ curl -sSL https://zipkin.io/quickstart.sh | bash -s io.zipkin.aws:zipkin-autoconfigure-collector-kinesis:LATEST:module kinesis.jar
$ KINESIS_STREAM_NAME=zipkin \
    java \
    -Dloader.path='kinesis.jar,kinesis.jar!/lib' \
    -Dspring.profiles.active=kinesis \
    -cp zipkin.jar \
    org.springframework.boot.loader.PropertiesLauncher

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

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
  • KINESIS_STREAM_NAME The name of the Kinesis stream to read from
  • KINESIS_APP_NAME The name for this app to use for sharing a stream Defaults to zipkin
  • KINESIS_AWS_ACCESS_KEY_ID Optional AWS Access Key ID.
  • KINESIS_AWS_SECRET_ACCESS_KEY Optional AWS Secret Access Key.
  • KINESIS_AWS_STS_ROLE_ARN Optional IAM role ARN for cross account role delegation.
  • KINESIS_AWS_STS_REGION Optional AWS region ID when using STS.
  • KINESIS_AWS_REGION Optional AWS region ID for the associated Kinesis Collector.
  • AWS_REGION Optional AWS region ID, implicitly sets both KINESIS_AWS_STS_REGION and KINESIS_AWS_REGION.Default us-east-1

Security

The auto configuration library uses the AWS Kinesis 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 KinesisCollector

  • kinesis:DescribeStream
  • kinesis:GetRecords
  • kinesis:GetShardIterator
  • dynamodb:CreateTable
  • dynamodb:DescribeTable
  • dynamodb:GetItem
  • dynamodb:PutItem
  • dynamodb:Scan
  • dynamodb:UpdateItem
  • dynamodb:DeleteItem
  • cloudwatch:PutMetricData

Testing

Once your collector is enabled, verify it is running:

$ curl -s localhost:9411/health|jq .zipkin.details.KinesisCollector
{
  "status": "UP"
}

Now, you can send a test message like below:

# send a json list with a single json-encoded span
$ aws kinesis put-record --stream-name $KINESIS_STREAM_NAME --partition-key $(hostname) --data '[{
  "traceId": "86154a4ba6e91385",
  "parentId": "86154a4ba6e91385",
  "id": "4d1e00c0db9010db",
  "kind": "CLIENT",
  "name": "get",
  "timestamp": 1472470996199000,
  "duration": 207000,
  "localEndpoint": {
    "serviceName": "frontend",
    "ipv4": "127.0.0.1"
  },
  "tags": {
    "http.path": "/api"
  }
}]'
# read it back using the zipkin v1 api
$ curl -s localhost:9411/api/v1/trace/86154a4ba6e91385|jq .[].traceId
"86154a4ba6e91385"