opentracing

README

OpenTracing model for Flogo

DEPRECATED: OpenTracing listener for Flogo should be used instead.

This model adds OpenTracing instrumentation at Flogo engine level and tracers implementations (Zipkin over HTTP or Kafka, Jaeger) to send traces generated by flows and activities to corresponding collectors.

For an introduction of concepts, read the OpenTracing documentation.

Installation

Flogo Web

This model is not available with the Flogo Web UI.

Flogo CLI

Use patched version of Flogo CLI:

go get -u github.com/TIBCOSoftware/flogo-cli/...

cd $GOPATH/src/github.com/TIBCOSoftware/flogo-cli

git remote add debovema https://github.com/debovema/flogo-cli.git
git pull debovema ensure-development-mode

go get -u ./...

If you want to switch back to the official Flogo CLI, simply run:

rm -rf $GOPATH/src/github.com/TIBCOSoftware/flogo-cli

go get -u github.com/TIBCOSoftware/flogo-cli/...

Install the contribution

In the directory of a Flogo project (with a flogo.json file), run:

flogo install github.com/debovema/flogo-contrib-models/opentracing

IMPORTANT: This model requires some little updates in flogo-contrib and flogo-lib which are not yet merged into TIBCOSoftware repositories. Simply run following additionnal commands:

flogo install -u -v working-data-between-flow-and-activities -s github.com/debovema/flogo-contrib github.com/TIBCOSoftware/flogo-contrib
flogo install -u -v working-data-between-flow-and-activities -s github.com/debovema/flogo-lib github.com/TIBCOSoftware/flogo-lib
flogo install -u -o -v master github.com/apache/thrift

These additionnal commands will be removed after the merge.

Build and run

Finally, build the application:

flogo build -e

The binary is ready to be run in ./bin directory.

Usage

Flow-based configuration

For a basic usage with a Zipkin collector with HTTP transport, in the flogo.json generated by the flogo create command, replace

  "resources": [
    {
      "id": "flow:sample_flow",
      "data": {
        "name": "SampleFlow",
        "tasks": [
          {
            "id": "log_2",
            "name": "Log Message",
            "description": "Simple Log Activity",
            "activity": {
              "ref": "github.com/TIBCOSoftware/flogo-contrib/activity/log",
              "input": {
                "message": "Simple Log",
                "flowInfo": "false",
                "addToFlow": "false"
              }
            }
          }
        ]
      }
    }
  ]

by

  "resources": [
    {
      "id": "flow:sample_flow",
      "data": {
        "name": "SampleFlow",
        "model": "opentracing-model",
        "attributes": [
          {
            "name": "opentracing-config",
            "type": "any",
            "value": {
              "implementation": "zipkin",
              "transport": "http",
              "endpoints": [
                "http://127.0.0.1:9411/api/v1/spans"
              ]
            }
          }
        ],
        "tasks": [
          {
            "id": "log_2",
            "name": "Log Message",
            "description": "Simple Log Activity",
            "activity": {
              "ref": "github.com/TIBCOSoftware/flogo-contrib/activity/log",
              "input": {
                "message": "Simple Log",
                "flowInfo": "false",
                "addToFlow": "false"
              }
            }
          }
        ]
      }
    }
  ]

Replace 127.0.0.1 by the actual IP of the Zipkin collector.

Global configuration

If all flows of an application should have the same OpenTracing configuration, environment variables can be used instead.

1. activate the model in all flows of an application (flogo.json) with jq:

jq '.resources[].data  |= . + {"model": "opentracing-model"}' flogo.json > flogo.json.tmp && mv flogo.json.tmp flogo.json

1. declare following environment variables:

export FLOGO_OPENTRACING_IMPLEMENTATION=zipkin
export FLOGO_OPENTRACING_TRANSPORT=http
export FLOGO_OPENTRACING_ENDPOINTS=http://127.0.0.1:9411/api/v1/spans

Replace 127.0.0.1 by the actual IP of the Zipkin collector.

Configuration

This model is enabled by a model field, child of the data field of a flow, with a value of opentracing-model.

To enable this model in all flows of an application (flogo.json) with jq, run:

jq '.resources[].data  |= . + {"model": "opentracing-model"}' flogo.json > flogo.json.tmp && mv flogo.json.tmp flogo.json

It can then be configured by a JSON object in flogo.json (one object per flow) or globally with environment variables.

JSON-based configuration in flogo.json

This object is an attribute of type any with name opentracing-config.

The value is composed of three fields:

• implementation: possible values are zipkin or jaeger
• transport: possible values are http (for all implementations) or kafka (for zipkin implementation only)
• endpoints: an array with a single endpoint (for HTTP transport) or multiple endpoints (for Kafka transport)

For instance:

          {
            "name": "opentracing-config",
            "type": "any",
            "value": {
              "implementation": "zipkin",
              "transport": "http",
              "endpoints": [
                "http://127.0.0.1:9411/api/v1/spans"
              ]
            }
          }

Environment variables configuration

Environment variable	Possible values	Description
FLOGO_OPENTRACING_IMPLEMENTATION	zipkin, jaeger	Choose which implementation of OpenTracing tracer to use. Zipkin and Jaeger are available
FLOGO_OPENTRACING_TRANSPORT	http, kafka(for zipkin only)	http is supported by both Zipkin and Jaeger kafka is only supported by Zipkin
FLOGO_OPENTRACING_ENDPOINTS	http://127.0.0.1:9411/api/v1/spans (zipkin over HTTP) 10.1.0.1:29092,10.1.0.2:29092,10.1.0.3:29092 (zipkin over Kafka)	A comma-separated list of endpoints
FLOGO_OPENTRACING_SINGLE_TRACER	false, true	Optional, whether to use a single shared tracer (service name will be 'flogo') or a flow-based tracer (service name will be the name of the flow)

Collectors

This model can send traces to the following collectors:

• Zipkin over HTTP transport
• Zipkin over Kafka transport
• Jaeger over HTTP transport

For test purposes, here are quick methods to get collectors up and running locally, using Docker.

Zipkin

HTTP transport

To start a single-node instance of a Zipkin server with HTTP transport, run:

docker run --name zipkin -d -p 9411:9411 openzipkin/zipkin

Use following configuration for the model:

          {
            "name": "opentracing-config",
            "type": "any",
            "value": {
              "implementation": "zipkin",
              "transport": "http",
              "endpoints": [
                "http://127.0.0.1:9411/api/v1/spans"
              ]
            }
          }

If using Docker Machine, replace 127.0.0.1 by the IP of the active Docker Machine (usually 192.168.99.100, echo $(docker-machine ip $(docker-machine active)) to display the IP).

Kafka transport

For Kafka transport, start a single-node instance of a Kafka server with its Zookeeper:

mkdir -p /tmp/kafka
cd /tmp/kafka
curl -fsSL https://raw.githubusercontent.com/confluentinc/cp-docker-images/5.0.0-post/examples/kafka-single-node/docker-compose.yml -o docker-compose.yml
# uncomment if using Docker Machine
# sed -i "s|localhost:|$(docker-machine ip $(docker-machine active)):|" docker-compose.yml
docker-compose up -d

Then start a single-node instance of a Zipkin server with Kafka transport by running:

docker run --name zipkin -d -p 9411:9411 -e KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:29092 openzipkin/zipkin

If using Docker Machine, run instead:

docker run --name zipkin -d -p 9411:9411 -e KAFKA_BOOTSTRAP_SERVERS=$(docker-machine ip $(docker-machine active)):29092 openzipkin/zipkin

Use following configuration for the model:

          {
            "name": "opentracing-config",
            "type": "any",
            "value": {
              "implementation": "zipkin",
              "transport": "kafka",
              "endpoints": [
                "127.0.0.1:29092"
              ]
            }
          }

If using Docker Machine, replace 127.0.0.1 by the IP of the active Docker Machine (usually 192.168.99.100, echo $(docker-machine ip $(docker-machine active)) to display the IP).

Jaeger

HTTP transport

To start a single-node instance of a Jaeger server with HTTP transport, run:

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
  -p 5775:5775/udp \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 9411:9411 \
  jaegertracing/all-in-one

Use following configuration for the model:

          {
            "name": "opentracing-config",
            "type": "any",
            "value": {
              "implementation": "jaeger",
              "transport": "http",
              "endpoints": [
                "http://127.0.0.1:14268/api/traces"
              ]
            }
          }

If using Docker Machine, replace 127.0.0.1 by the IP of the active Docker Machine (usually 192.168.99.100, echo $(docker-machine ip $(docker-machine active)) to display the IP).

Documentation

Index

• Constants
• func New() *model.FlowModel

Constants

const (
	MODEL_NAME = "opentracing-model"

	ENV_VARS_PREFIX        = "FLOGO_OPENTRACING_"
	ENV_VAR_IMPLEMENTATION = ENV_VARS_PREFIX + "IMPLEMENTATION"
	ENV_VAR_TRANSPORT      = ENV_VARS_PREFIX + "TRANSPORT"
	ENV_VAR_ENDPOINTS      = ENV_VARS_PREFIX + "ENDPOINTS"
	ENV_VAR_SINGLE_TRACER  = ENV_VARS_PREFIX + "SINGLE_TRACER"
)

Functions

func New

func New() *model.FlowModel