Version 1.5.1.RELEASE

© 2012-2017 Pivotal Software, Inc.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Preface

1. About the documentation

The documentation for this release is available in HTML.

The latest copy of the Spring Cloud Data Flow reference guide can be found here.

Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

2. Getting help

Having trouble with Spring Cloud Data Flow, We would like to help!

All of Spring Cloud Data Flow is open source, including the documentation! If you find problems with the docs or if you just want to improve them, please get involved.

Getting started

If you are getting started with Spring Cloud Data Flow, this section is for you. In this section, we answer the basic “what?”, “how?” and “why?” questions. You can find a gentle introduction to Spring Cloud Data Flow along with installation instructions. We then build an introductory Spring Cloud Data Flow application, discussing some core principles as we go.

3. System Requirements

You need Java 8 to run and to build you need to have Maven.

You need to have an RDBMS for storing stream definition and deployment properites and task/batch job states. By default, the Data Flow server uses embedded H2 database for this purpose but you can easily configure the server to use another external database.

You also need to have Redis running if you are running any streams that involve analytics applications. Redis may also be required to run the unit/integration tests.

For the deployed streams applications communicate, either RabbitMQ or Kafka needs to be installed.

If you would like to have the feature of upgrading and rolling back applications in Streams at runtime, you should install the Spring Cloud Skipper server.

4. Getting Started with Docker Compose

As of Spring Cloud Data Flow 1.4, a Docker Compose file is provided to quickly bring up Spring Cloud Data Flow and its dependencies without having to obtain them manually. When running, a composed system includes the latest GA release of Spring Cloud Data Flow Local Server using the Kafka binder for communication. Docker Compose is required and it’s recommended to use the latest version.

  1. Download the Spring Cloud Data Flow Local Server Docker Compose file:

    wget https://raw.githubusercontent.com/spring-cloud/spring-cloud-dataflow/v1.5.1.RELEASE/spring-cloud-dataflow-server-local/docker-compose.yml
  2. Start Docker Compose

    In the directory where you downloaded docker-compose.yml, start the system, as follows:

    $ DATAFLOW_VERSION=1.5.1.RELEASE docker-compose up
    By default Docker Compose will use locally available images. If for example when using the latest tag, execute docker-compose pull prior to docker-compose up to ensure the latest image is downloaded.
  3. Launch the Spring Cloud Data Flow Dashboard

    Spring Cloud Data Flow will be ready for use once the docker-compose command stops emitting log messages. At this time, in your browser navigate to the Spring Cloud Data Flow Dashboard. By default the latest GA releases of Stream and Task applications will be imported automatically.

  4. Create a Stream

    To create a stream, first navigate to the "Streams" menu link then click the "Create Stream" link. Enter time | log into the "Create Stream" textarea then click the "CREATE STREAM" button. Enter "ticktock" for the stream name and click the "Deploy Stream(s) checkbox as show in the following image:

    Creating a Stream
    Figure 1. Creating a Stream

    Then click "OK" which will return back to the Definitions page. The stream will be in "deploying" status and move to "deployed" when finished. You may need to refresh your browser to see the updated status.

  5. View Stream Logs

    To view the stream logs, navigate to the "Runtime" menu link and click the "ticktock.log" link. Copy the path in the "stdout" text box on the dashboard and in another console type:

    $ docker exec -it dataflow-server tail -f /path/from/stdout/textbox/in/dashboard

    You should now see the output of the log sink, printing a timestamp once per second. Press CTRL+c to end the tail.

  6. Delete a Stream

    To delete the stream, first navigate to the "Streams" menu link in the dashboard then click the checkbox on the "ticktock" row. Click the "DESTROY ALL 1 SELECTED STREAMS" button and then "YES" to destroy the stream.

  7. Destroy the Quick Start environment

    To destroy the Quick Start environment, in another console from where the docker-compose.yml is located, type as follows:

    $ docker-compose down

4.1. Docker Compose Customization

Out of the box Spring Cloud Data Flow will use the H2 embedded database for storing state, Kafka for communication and no analytics. Customizations can be made to these components by editing the docker-compose.yml file as described below.

  1. To use MySQL rather than the H2 embedded database, add the following configuration under the services section:

      mysql:
        image: mariadb:10.2
        environment:
          MYSQL_DATABASE: dataflow
          MYSQL_USER: root
          MYSQL_ROOT_PASSWORD: rootpw
        expose:
          - 3306

    The following entries need to be added to the environment block of the dataflow-server service definition:

          - spring_datasource_url=jdbc:mysql://mysql:3306/dataflow
          - spring_datasource_username=root
          - spring_datasource_password=rootpw
          - spring_datasource_driver-class-name=org.mariadb.jdbc.Driver

    Update the depends_on attribute of the dataflow-server service definition to include:

          - mysql
  2. To use RabbitMQ instead of Kafka for communication, replace the following configuration under the services section:

      kafka:
        image: wurstmeister/kafka:0.10.1.0
        expose:
          - "9092"
        environment:
          - KAFKA_ADVERTISED_PORT=9092
          - KAFKA_ZOOKEEPER_CONNECT=zookeeper:2181
        depends_on:
          - zookeeper
      zookeeper:
        image: wurstmeister/zookeeper
        expose:
          - "2181"
        environment:
          - KAFKA_ADVERTISED_HOST_NAME=zookeeper

    With:

      rabbitmq:
        image: rabbitmq:3.7
        expose:
          - "5672"

    In the dataflow-server services configuration block, add the following environment entry:

          - spring.cloud.dataflow.applicationProperties.stream.spring.rabbitmq.host=rabbitmq

    Then replace:

        depends_on:
          - kafka

    With:

        depends_on:
          - rabbitmq

    And finally, modify the app-import service definition command attribute to replace bit.ly/Celsius-SR2-stream-applications-kafka-10-maven with bit.ly/Celsius-SR2-stream-applications-rabbit-maven.

  3. To enable analytics using redis as a backend, add the following configuration under the services section:

      redis:
        image: redis:2.8
        expose:
          - "6379"

    Update the depends_on attribute of the dataflow-server service definition to include:

          - redis

    Then add the following entries to the environment block of the dataflow-server service definition:

          - spring.cloud.dataflow.applicationProperties.stream.spring.redis.host=redis
          - spring_redis_host=redis

5. Getting Started with Manual Installation

  1. Download the Spring Cloud Data Flow Server and Shell apps:

    wget https://repo.spring.io/release/org/springframework/cloud/spring-cloud-dataflow-server-local/1.5.1.RELEASE/spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar
    
    wget https://repo.spring.io/release/org/springframework/cloud/spring-cloud-dataflow-shell/1.5.1.RELEASE/spring-cloud-dataflow-shell-1.5.1.RELEASE.jar

    Starting 1.3.x, the Data Flow Server can run in either the skipper or classic mode. The classic mode is how the Data Flow Server worked in the 1.2.x releases. The mode is specified when starting the Data Flow server using the property spring.cloud.dataflow.features.skipper-enabled. By default, the classic mode is enabled.

  2. Download Skipper if you would like the added features of upgrading and rolling back applications inside Streams, since Data Flow delegates to Skipper for those features.

    wget https://repo.spring.io/release/org/springframework/cloud/spring-cloud-skipper-server/1.0.5.RELEASE/spring-cloud-skipper-server-1.0.5.RELEASE.jar
    
    wget https://repo.spring.io/release/org/springframework/cloud/spring-cloud-skipper-shell/1.0.5.RELEASE/spring-cloud-skipper-shell-1.0.5.RELEASE.jar
  3. Launch Skipper (Required only if you want to run Spring Cloud Data Flow server in skipper mode)

    In the directory where you downloaded Skipper, run the server using java -jar, as follows:

    $ java -jar spring-cloud-skipper-server-1.0.5.RELEASE.jar
  4. Launch the Data Flow Server

    In the directory where you downloaded Data Flow, run the server using java -jar, as follows:

    To run the Data Flow server in classic mode:

    $ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar

    To run the Data Flow server in skipper mode:

    $ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --spring.cloud.dataflow.features.skipper-enabled=true

    If Skipper and the Data Flow server are not running on the same host, set the configuration property spring.cloud.skipper.client.serverUri to the location of Skipper, e.g.

    $ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --spring.cloud.skipper.client.serverUri=http://192.51.100.1:7577/api
  5. Launch the Data Flow Shell, as follows:

    Launching the Data Flow shell requires the appropriate data flow server mode to be specified. To start the Data Flow Shell for the Data Flow server running in classic mode:

    $ java -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar

    To start the Data Flow Shell for the Data Flow server running in skipper mode:

    $ java -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar --dataflow.mode=skipper
    Both the Data Flow Server and the Shell must be on the same mode.

    If the Data Flow Server and shell are not running on the same host, you can also point the shell to the Data Flow server URL using the dataflow config server command when in the shell’s interactive mode.

    If the Data Flow Server and shell are not running on the same host, point the shell to the Data Flow server URL, as follows:

    server-unknown:>dataflow config server http://198.51.100.0
    Successfully targeted http://198.51.100.0
    dataflow:>

    Alternatively, pass in the command line option --dataflow.uri. The shell’s command line option --help shows what is available.

6. Deploying Streams

  1. Register Stream Apps

    By default, the application registry is empty. As an example, register two applications, http and log, that communicate by using RabbitMQ.

    dataflow:>app register --name http --type source --uri maven://org.springframework.cloud.stream.app:http-source-rabbit:1.2.0.RELEASE
    Successfully registered application 'source:http'
    
    dataflow:>app register --name log --type sink --uri maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.1.0.RELEASE
    Successfully registered application 'sink:log'

    For more details, such as how to register applications that are based on docker containers or use Kafka as the messaging middleware, review the section on how to register applications.

    Depending on your environment, you may need to configure the Data Flow Server to point to a custom Maven repository location or configure proxy settings. See Maven for more information.

    In this getting started section, we only show deploying a stream, so the commands are the same in skipper as well as classic mode of the server.

  2. Create a stream

    Use the stream create command to create a stream with a http source and a log sink and deploy it:

    dataflow:> stream create --name httptest --definition "http --server.port=9000 | log" --deploy
    You need to wait a little while, until the apps are actually deployed successfully, before posting data. Look in the log file of the Data Flow server for the location of the log files for the http and log applications. Use the tail command on the log file for each application to verify that the application has started.

    Now post some data, as shown in the following example:

    dataflow:> http post --target http://localhost:9000 --data "hello world"

    Check to see if hello world ended up in log files for the log application. The location of the log file for the log application will be shown in the Data Flow server’s log.

You can read more about the general features of using Skipper to deploy streams in the section Stream Lifecycle with Skipper and how to upgrade and rollback streams in Streams with Skipper.

When deploying locally, each app (and each app instance, in case of count > 1) gets a dynamically assigned server.port, unless you explicitly assign one with --server.port=x. In both cases, this setting is propagated as a configuration property that overrides any lower-level setting that you may have used (for example, in application.yml files).

7. Deploying Tasks

In this getting started section, we show how to register a task, create a task definition and then launch it. We will then also review information about the task executions.

Launching Spring Cloud Task applications are not delegated to Skipper since they are short lived applications. Tasks are alwasy deployed directly via the Data Flow Server.
  1. Register a Task App

    By default, the application registry is empty. As an example, we will register one task application, timestamp which simply prints the current time to the log.

    dataflow:>app register --name timestamp --type task --uri maven://org.springframework.cloud.task.app:timestamp-task:1.3.0.RELEASE
    Successfully registered application 'task:timestamp'
    Depending on your environment, you may need to configure the Data Flow Server to point to a custom Maven repository location or configure proxy settings. See Maven for more information.
  2. Create a Task Definition

    Use the task create command to create a task definition using the previously registered timestamp application. In this example, no additional properties are used to configure the timestamp application.

    dataflow:> task create --name printTimeStamp --definition "timestamp"
  3. Launch a Task

    The launching of task definitions is done through the shell’s task launch command.

    dataflow:> task launch printTimeStamp

    Check to see if the a timestamp ended up in log file for the timestamp task. The location of the log file for the task application will be shown in the Data Flow server’s log. You should see a log entry similar to

    TimestampTaskConfiguration$TimestampTask : 2018-02-28 16:42:21.051
  4. Review task execution

    Information about the task execution can be obtained using the command task execution list.

    dataflow:>task execution list
    ╔══════════════╤══╤════════════════════════════╤════════════════════════════╤═════════╗
    ║  Task Name   │ID│         Start Time         │          End Time          │Exit Code║
    ╠══════════════╪══╪════════════════════════════╪════════════════════════════╪═════════╣
    ║printTimeStamp│1 │Wed Feb 28 16:42:21 EST 2018│Wed Feb 28 16:42:21 EST 2018│0        ║
    ╚══════════════╧══╧════════════════════════════╧════════════════════════════╧═════════╝

    Additional information can be obtained using the command task execution status.

    dataflow:>task execution status --id 1
    ╔══════════════════════╤═══════════════════════════════════════════════════╗
    ║         Key          │                       Value                       ║
    ╠══════════════════════╪═══════════════════════════════════════════════════╣
    ║Id                    │1                                                  ║
    ║Name                  │printTimeStamp                                     ║
    ║Arguments             │[--spring.cloud.task.executionid=1]                ║
    ║Job Execution Ids     │[]                                                 ║
    ║Start Time            │Wed Feb 28 16:42:21 EST 2018                       ║
    ║End Time              │Wed Feb 28 16:42:21 EST 2018                       ║
    ║Exit Code             │0                                                  ║
    ║Exit Message          │                                                   ║
    ║Error Message         │                                                   ║
    ║External Execution Id │printTimeStamp-ab86b2cc-0508-4c1e-b33d-b3896d17fed7║
    ╚══════════════════════╧═══════════════════════════════════════════════════╝

    The Tasks section has more information on the lifecycle of Tasks and also how to use Composed Tasks which let you create a directed graph where each node of the graph is a task application.

Applications

A selection of pre-built stream and task/batch starter apps for various data integration and processing scenarios to facilitate learning and experimentation. The table below includes the pre-built applications at a glance. For more details, review how to register supported applications.

8. Available Applications

Architecture

9. Introduction

Spring Cloud Data Flow simplifies the development and deployment of applications focused on data processing use cases. The major concepts of the architecture are Applications, the Data Flow Server, and the target runtime.

Applications come in two flavors:

  • Long-lived Stream applications where an unbounded amount of data is consumed or produced through messaging middleware.

  • Short-lived Task applications that process a finite set of data and then terminate.

Depending on the runtime, applications can be packaged in two ways:

  • Spring Boot uber-jar that is hosted in a maven repository, file, or HTTP(S).

  • Docker image.

The runtime is the place where applications execute. The target runtimes for applications are platforms that you may already be using for other application deployments.

The supported platforms are:

  • Cloud Foundry

  • Apache YARN

  • Kubernetes

  • Apache Mesos

  • Local Server for development

There is a deployer Service Provider Interface (SPI) that lets you extend Data Flow to deploy onto other runtimes. There are community implementations of Hashicorp’s Nomad and RedHat Openshift. We look forward to working with the community for further contributions!

There are two mutually exclusive options that determine how applications are deployed to the platform.

  1. Select a Spring Cloud Data Flow Server executable jar that targets a single platform.

  2. Enable the Spring Cloud Data Flow Server to delegate the deployment and runtime status of applications to the Spring Cloud Skipper Server, which has the capability to deploy to multiple platforms.

Selecting the Spring Cloud Skipper option also enables the ability to update and rollback applications in a Stream at runtime.

The Data Flow server is also responsible for:

  • Interpreting and executing a stream DSL that describes the logical flow of data through multiple long-lived applications.

  • Launching a long-lived task application.

  • Interpreting and executing a composed task DSL that describes the logical flow of data through multiple short-lived applications.

  • Applying a deployment manifest that describes the mapping of applications onto the runtime - for example, to set the initial number of instances, memory requirements, and data partitioning.

  • Providing the runtime status of deployed applications.

As an example, the stream DSL to describe the flow of data from an HTTP source to an Apache Cassandra sink would be written using a Unix pipes and filter syntax " http | cassandra ". Each name in the DSL is mapped to an application that can that Maven or Docker repositories. You can also register an application to an http location. Many source, processor, and sink applications for common use cases (such as JDBC, HDFS, HTTP, and router) are provided by the Spring Cloud Data Flow team. The pipe symbol represents the communication between the two applications through messaging middleware. The two messaging middleware brokers that are supported are:

  • Apache Kafka

  • RabbitMQ

In the case of Kafka, when deploying the stream, the Data Flow server is responsible for creating the topics that correspond to each pipe symbol and configure each application to produce or consume from the topics so the desired flow of data is achieved. Similarly for RabbitMQ, exchanges and queues are created as needed to achieve the desired flow.

The interaction of the main components is shown in the following image:

The Spring Cloud Data Flow High Level Architecture
Figure 2. The Spring Cloud Data High Level Architecure

In the preceding diagram, a DSL description of a stream is POSTed to the Data Flow Server. Based on the mapping of DSL application names to Maven and Docker artifacts, the http-source and cassandra-sink applications are deployed on the target runtime. Data that is posted to the HTTP application will then be stored in Cassandra. The Samples Repository shows this use case in full detail.

10. Microservice Architectural Style

The Data Flow Server deploys applications onto the target runtime that conform to the microservice architectural style. For example, a stream represents a high-level application that consists of multiple small microservice applications each running in their own process. Each microservice application can be scaled up or down independently of the other and each has its own versioning lifecycle. Using Data Flow with Skipper enables you to independently upgrade or rollback each application at runtime.

Both Streaming and Task-based microservice applications build upon Spring Boot as the foundational library. This gives all microservice applications functionality such as health checks, security, configurable logging, monitoring, and management functionality, as well as executable JAR packaging.

It is important to emphasize that these microservice applications are 'just apps' that you can run by yourself by using java -jar and passing in appropriate configuration properties. We provide many common microservice applications for common operations so you need not start from scratch when addressing common use cases that build upon the rich ecosystem of Spring Projects, such as Spring Integration, Spring Data, and Spring Batch. Creating your own microservice application is similar to creating other Spring Boot applications. You can start by using the Spring Initializr web site to create the basic scaffolding of either a Stream or Task-based microservice.

In addition to passing the appropriate application properties to each applications, the Data Flow server is responsible for preparing the target platform’s infrastructure so that the applications can be deployed. For example, in Cloud Foundry, it would bind specified services to the applications and execute the cf push command for each application. For Kubernetes, it would create the replication controller, service, and load balancer.

The Data Flow Server helps simplify the deployment of multiple, relatated, applications onto a target runtime, setting up necessary input and output topics, partitions, and metrics functionality. However, one could also opt to deploy each of the microservice applications manually and not use Data Flow at all. This approach might be more appropriate to start out with for small scale deployments, gradually adopting the convenience and consistency of Data Flow as you develop more applications. Manual deployment of Stream- and Task-based microservices is also a useful educational exercise that can help you better understand some of the automatic application configuration and platform targeting steps that the Data Flow Server provides.

10.1. Comparison to Other Platform Architectures

Spring Cloud Data Flow’s architectural style is different than other Stream and Batch processing platforms. For example in Apache Spark, Apache Flink, and Google Cloud Dataflow, applications run on a dedicated compute engine cluster. The nature of the compute engine gives these platforms a richer environment for performing complex calculations on the data as compared to Spring Cloud Data Flow, but it introduces the complexity of another execution environment that is often not needed when creating data-centric applications. That does not mean you cannot do real-time data computations when using Spring Cloud Data Flow. Refer to the section Analytics, which describes the integration of Redis to handle common counting-based use cases. Spring Cloud Stream also supports using Reactive APIs such as Project Reactor and RxJava which can be useful for creating functional style applications that contain time-sliding-window and moving-average functionality. Similarly, Spring Cloud Stream also supports the development of applications in that use the Kafka Streams API.

Apache Storm, Hortonworks DataFlow, and Spring Cloud Data Flow’s predecessor, Spring XD, use a dedicated application execution cluster, unique to each product, that determines where your code should run on the cluster and performs health checks to ensure that long-lived applications are restarted if they fail. Often, framework-specific interfaces are required in order to correctly “plug in” to the cluster’s execution framework.

As we discovered during the evolution of Spring XD, the rise of multiple container frameworks in 2015 made creating our own runtime a duplication of effort. There is no reason to build your own resource management mechanics when there are multiple runtime platforms that offer this functionality already. Taking these considerations into account is what made us shift to the current architecture, where we delegate the execution to popular runtimes, which you may already be using for other purposes. This is an advantage in that it reduces the cognitive distance for creating and managing data-centric applications as many of the same skills used for deploying other end-user/web applications are applicable.

11. Data Flow Server

The Data Flow Server provides the following functionality:

11.1. Endpoints

The Data Flow Server uses an embedded servlet container and exposes REST endpoints for creating, deploying, undeploying, and destroying streams and tasks, querying runtime state, analytics, and the like. The Data Flow Server is implemented by using Spring’s MVC framework and the Spring HATEOAS library to create REST representations that follow the HATEOAS principle, as shown in the following image:

The Spring Cloud Data Flow Server Architecture
Figure 3. The Spring Cloud Data Flow Server

11.2. Security

The Data Flow Server executable jars support basic HTTP, LDAP(S), File-based, and OAuth 2.0 authentication to access its endpoints. Refer to the security section for more information.

12. Streams

12.1. Topologies

The Stream DSL describes linear sequences of data flowing through the system. For example, in the stream definition http | transformer | cassandra, each pipe symbol connects the application on the left to the one on the right. Named channels can be used for routing and to fan in/fan out data to multiple messaging destinations.

The concept of a tap can be used to ‘listen’ to the data that is flowing across any of the pipe symbols. "Taps" are just other streams that use an input any one of the "pipes" in a target stream and have an independent life cycle from the target stream.

12.2. Concurrency

For an application that consumes events, Spring Cloud Stream exposes a concurrency setting that controls the size of a thread pool used for dispatching incoming messages. See the Consumer properties documentation for more information.

12.3. Partitioning

A common pattern in stream processing is to partition the data as it moves from one application to the next. Partitioning is a critical concept in stateful processing, for either performance or consistency reasons, to ensure that all related data is processed together. For example, in a time-windowed average calculation example, it is important that all measurements from any given sensor are processed by the same application instance. Alternatively, you may want to cache some data related to the incoming events so that it can be enriched without making a remote procedure call to retrieve the related data.

Spring Cloud Data Flow supports partitioning by configuring Spring Cloud Stream’s output and input bindings. Spring Cloud Stream provides a common abstraction for implementing partitioned processing use cases in a uniform fashion across different types of middleware. Partitioning can thus be used whether the broker itself is naturally partitioned (for example, Kafka topics) or not (RabbitMQ). The following image shows how data could be partitioned into two buckets, such that each instance of the average processor application consumes a unique set of data.

Stream Partitioning Architecture
Figure 4. Spring Cloud Stream Partitioning

To use a simple partitioning strategy in Spring Cloud Data Flow, you need only set the instance count for each application in the stream and a partitionKeyExpression producer property when deploying the stream. The partitionKeyExpression identifies what part of the message is used as the key to partition data in the underlying middleware. An ingest stream can be defined as http | averageprocessor | cassandra. (Note that the Cassandra sink is not shown in the diagram above.) Suppose the payload being sent to the HTTP source was in JSON format and had a field called sensorId. For example, consider the case of deploying the stream with the shell command stream deploy ingest --propertiesFile ingestStream.properties where the contents of the ingestStream.properties file are as follows:

deployer.http.count=3
deployer.averageprocessor.count=2
app.http.producer.partitionKeyExpression=payload.sensorId

The result is to deploy the stream such that all the input and output destinations are configured for data to flow through the applications but also ensure that a unique set of data is always delivered to each averageprocessor instance. In this case, the default algorithm is to evaluate payload.sensorId % partitionCount where the partitionCount is the application count in the case of RabbitMQ and the partition count of the topic in the case of Kafka.

Please refer to Passing Stream Partition Properties for additional strategies to partition streams during deployment and how they map onto the underlying Spring Cloud Stream Partitioning properties.

Also note that you cannot currently scale partitioned streams. Read Scaling at Runtime for more information.

12.4. Message Delivery Guarantees

Streams are composed of applications that use the Spring Cloud Stream library as the basis for communicating with the underlying messaging middleware product. Spring Cloud Stream also provides an opinionated configuration of middleware from several vendors, in particular providing persistent publish-subscribe semantics.

The Binder abstraction in Spring Cloud Stream is what connects the application to the middleware. There are several configuration properties of the binder that are portable across all binder implementations and some that are specific to the middleware.

For consumer applications, there is a retry policy for exceptions generated during message handling. The retry policy is configured by using the common consumer properties maxAttempts, backOffInitialInterval, backOffMaxInterval, and backOffMultiplier. The default values of these properties retry the callback method invocation 3 times and wait one second for the first retry. A backoff multiplier of 2 is used for the second and third attempts.

When the number of retry attempts has exceeded the maxAttempts value, the exception and the failed message become the payload of a message and are sent to the application’s error channel. By default, the default message handler for this error channel logs the message. You can change the default behavior in your application by creating your own message handler that subscribes to the error channel.

Spring Cloud Stream also supports a configuration option for both Kafka and RabbitMQ binder implementations that sends the failed message and stack trace to a dead letter queue. The dead letter queue is a destination and its nature depends on the messaging middleware (for example, in the case of Kafka, it is a dedicated topic). To enable this for RabbitMQ set the republishtoDlq and autoBindDlq consumer properties and the autoBindDlq producer property to true when deploying the stream. To always apply these producer and consumer properties when deploying streams, configure them as common application properties when starting the Data Flow server.

Additional messaging delivery guarantees are those provided by the underlying messaging middleware that is chosen for the application for both producing and consuming applications. Refer to the Kafka Consumer and Producer and Rabbit Consumer and Producer documentation for more details. You can find extensive declarative support for all the native QOS options.

13. Stream Programming Models

While Spring Boot provides the foundation for creating DevOps-friendly microservice applications, other libraries in the Spring ecosystem help create Stream-based microservice applications. The most important of these is Spring Cloud Stream.

The essence of the Spring Cloud Stream programming model is to provide an easy way to describe multiple inputs and outputs of an application that communicate over messaging middleware. These input and outputs map onto Kafka topics or Rabbit exchanges and queues. Common application configuration for a Source that generates data, a Processor that consumes and produces data, and a Sink that consumes data is provided as part of the library.

13.1. Imperative Programming Model

Spring Cloud Stream is most closely integrated with Spring Integration’s imperative "one event at a time" programming model. This means you write code that handles a single event callback, as shown in the following example,

@EnableBinding(Sink.class)
public class LoggingSink {

    @StreamListener(Sink.INPUT)
    public void log(String message) {
        System.out.println(message);
    }
}

In this case, the String payload of a message coming on the input channel is handed to the log method. The @EnableBinding annotation is used to tie the input channel to the external middleware.

13.2. Functional Programming Model

However, Spring Cloud Stream can support other programming styles, such as reactive APIs, where incoming and outgoing data is handled as continuous data flows and how each individual message should be handled is defined. With many reactive AOIs, you can also use operators that describe functional transformations from inbound to outbound data flows. Here is an example:

@EnableBinding(Processor.class)
public static class UppercaseTransformer {

  @StreamListener
  @Output(Processor.OUTPUT)
  public Flux<String> receive(@Input(Processor.INPUT) Flux<String> input) {
    return input.map(s -> s.toUpperCase());
  }
}

14. Application Versioning

Application versioning within a Stream is now supported when using Data Flow together with Skipper. You can update application and deployment properties as well as the version of the application. Rolling back to a previous application version is also supported.

15. Task Programming Model

The Spring Cloud Task programming model provides:

  • Persistence of the Task’s lifecycle events and exit code status.

  • Lifecycle hooks to execute code before or after a task execution.

  • The ability to emit task events to a stream (as a source) during the task lifecycle.

  • Integration with Spring Batch Jobs.

See the Tasks section for more information.

16. Analytics

Spring Cloud Data Flow is aware of certain Sink applications that write counter data to Redis and provides a REST endpoint to read counter data. The types of counters supported are as follows:

  • Counter: Counts the number of messages it receives, optionally storing counts in a separate store such as Redis.

  • Field Value Counter: Counts occurrences of unique values for a named field in a message payload.

  • Aggregate Counter: Stores total counts but also retains the total count values for each minute, hour, day, and month.

Note that the timestamp used in the aggregate counter can come from a field in the message itself so that out-of-order messages are properly accounted.

17. Runtime

The Data Flow Server relies on the target platform for the following runtime functionality:

17.1. Fault Tolerance

The target runtimes supported by Data Flow all have the ability to restart a long-lived application. Spring Cloud Data Flow sets up health probes are required by the runtime environment when deploying the application. You also have the ability to customize the health probes.

The collective state of all applications that make up the stream is used to determine the state of the stream. If an application fails, the state of the stream changes from ‘deployed’ to ‘partial’.

17.2. Resource Management

Each target runtime lets you control the amount of memory, disk, and CPU allocated to each application. These are passed as properties in the deployment manifest by using key names that are unique to each runtime. Refer to each platform’s server documentation for more information.

17.3. Scaling at Runtime

When deploying a stream, you can set the instance count for each individual application that makes up the stream. Once the stream is deployed, each target runtime lets you control the target number of instances for each individual application. Using the APIs, UIs, or command line tools for each runtime, you can scale up or down the number of instances as required.

Currently, scaling at runtime is not supported with the Kafka binder, as well as with partitioned streams, for which the suggested workaround is redeploying the stream with an updated number of instances. Both cases require a static consumer to be set up, based on information about the total instance count and current instance index.

Configuration

This section covers how to configure Spring Cloud Data Flow Server’s features, such as which relational database to use and security. It also covers how to configure Spring Cloud Data Flow’s shell features.

18. Feature Toggles

Sprig Cloud Data Flow Server offers specific set of features that can be enabled/disabled when launching. These features include all the lifecycle operations and REST endpoints (server and client implementations, including the shell and the UI) for:

  • Streams

  • Tasks

  • Analytics

  • Skipper

One can enable and disable these features by setting the following boolean properties when launching the Data Flow server:

  • spring.cloud.dataflow.features.streams-enabled

  • spring.cloud.dataflow.features.tasks-enabled

  • spring.cloud.dataflow.features.analytics-enabled

  • spring.cloud.dataflow.features.skipper-enabled

By default, stream, tasks, and analytics are enabled and Skipper is disabled by default.

Since the analytics feature is enabled by default, the Data Flow Server expects to have a valid Redis store available to server as the analytic repository, because Spring Cloud Data Flow provides a default implementation of analytics based on Redis. This also means that the Data Flow Server’s health depends on the redis store availability as well. If you do not want Data Flow’s endpoints to read analytics data written to Redis, then disable the analytics feature by setting the property mentioned above.

The REST /about endpoint provides information on the features that have been enabled and disabled.

19. Database

A relational database is used to store stream and task definitions as well as the state of executed tasks. Spring Cloud Data Flow provides schemas for H2, HSQLDB, MySQL, Oracle, Postgresql, DB2, and SqlServer. The schema is automatically created when the server starts.

By default, Spring Cloud Data Flow offers an embedded instance of the H2 database. The H2 database is good for development purposes but is not recommended for production use.

The JDBC drivers for MySQL (through the MariaDB driver), HSQLDB, PostgreSQL, and embedded H2 are available without additional configuration. If you are using any other database, then you need to put the corresponding JDBC driver jar on the classpath of the server.

The database properties can be passed as environment variables or command-line arguments to the Data Flow Server.

The following example shows how to define a database connection with environment variables:

export spring_datasource_url=jdbc:postgresql://localhost:5432/mydb
export spring_datasource_username=myuser
export spring_datasource_password=mypass
export spring_datasource_driver_class_name="org.postgresql.Driver"

The following example shows how to define a MySQL database connection with command Line arguments

java -jar spring-cloud-dataflow-server-local/target/spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar \
    --spring.datasource.url=jdbc:mysql:<db-info> \
    --spring.datasource.username=<user> \
    --spring.datasource.password=<password> \
    --spring.datasource.driver-class-name=org.mariadb.jdbc.Driver &

The following example shows how to define a PostgreSQL database connection with command line arguments:

java -jar spring-cloud-dataflow-server-local/target/spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar \
    --spring.datasource.url=jdbc:postgresql:<db-info> \
    --spring.datasource.username=<user> \
    --spring.datasource.password=<password> \
    --spring.datasource.driver-class-name=org.postgresql.Driver &

The following example shows how to define a HSQLDB database connection with command line arguments:

java -jar spring-cloud-dataflow-server-local/target/spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar \
    --spring.datasource.url=jdbc:hsqldb:<db-info> \
    --spring.datasource.username=SA \
    --spring.datasource.driver-class-name=org.hsqldb.jdbc.JDBCDriver &
If you wish to use an external H2 database instance instead of the one embedded with Spring Cloud Data Flow, set the spring.dataflow.embedded.database.enabled property to false. If spring.dataflow.embedded.database.enabled is set to false or a database other than h2 is specified as the datasource, the embedded database does not start.

19.1. Disabling database schema creation and migration strategies

You can control whether or not Data Flow bootstraps your database on startup. On most production environments chances are you will not have enough privileges to do so. If that’s the case you can disable it by setting the property spring.cloud.dataflow.rdbms.initialize.enable to false. The scripts that the server uses to bootstrap the database can be found under spring-cloud-dataflow-core/src/main/resources/ folder.

For new installations run the corresponding database script located under /schemas and /migrations.1.x.x, for upgrades from version 1.2.0 you only need to run the /migrations.1.x.x scripts.

19.2. Adding a Custom JDBC Driver

To add a custom driver for the database (for example, Oracle), you should rebuild the Data Flow Server and add the dependency to the Maven pom.xml file. Since there is a Spring Cloud Data Flow Server for each target platform, you need to modify the appropriate maven pom.xml for each platform. There are tags in each GitHub repository for each server version.

To add a custom JDBC driver dependency for the local server implementation:

  1. Select the tag that corresponds to the version of the server you want to rebuild and clone the github repository.

  2. Edit the spring-cloud-dataflow-server-local/pom.xml and, in the dependencies section, add the dependency for the database driver required. In the following example , an Oracle driver has been chosen:

<dependencies>
...
  <dependency>
    <groupId>com.oracle.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <version>12.2.0.1</version>
  </dependency>
...
</dependencies>
  1. Build the application as described in Building Spring Cloud Data Flow

You can also provide default values when rebuilding the server by adding the necessary properties to the dataflow-server.yml file, as shown in the following example for PostgreSQL:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: myuser
    password: mypass
    driver-class-name:org.postgresql.Driver

20. Local Deployer

You can use the following configuration properties of the Data Flow Local server’s deployer to customize how applications are deployed:

spring.cloud.deployer.local.workingDirectoriesRoot=java.io.tmpdir # Directory in which all created processes will run and create log files.

spring.cloud.deployer.local.deleteFilesOnExit=true # Whether to delete created files and directories on JVM exit.

spring.cloud.deployer.local.envVarsToInherit=TMP,LANG,LANGUAGE,"LC_.*. # Array of regular expression patterns for environment variables that are passed to launched applications.

spring.cloud.deployer.local.javaCmd=java # Command to run java.

spring.cloud.deployer.local.shutdownTimeout=30 # Max number of seconds to wait for app shutdown.

spring.cloud.deployer.local.javaOpts= # The Java options to pass to the JVM

spring.cloud.deployer.local.freeDiskSpacePercentage=5 # The target percentage of free disk space to always aim for when cleaning downloaded resources (typically via the local maven repository). Specify as an integer greater than zero and less than 100. Default is 5.

Data Flow Local server itself overrides spring.cloud.deployer.local.freeDiskSpacePercentage to 0 from its default value.

When deploying the application, you can also set deployer properties prefixed with deployer.<name of application>. For example, to set Java options for the time application in the ticktock stream, use the following stream deployment properties.

dataflow:> stream create --name ticktock --definition "time --server.port=9000 | log"
dataflow:> stream deploy --name ticktock --properties "deployer.time.local.javaOpts=-Xmx2048m -Dtest=foo"

As a convenience, you can set the deployer.memory property to set the Java option -Xmx, as shown in the following example:

dataflow:> stream deploy --name ticktock --properties "deployer.time.memory=2048m"

At deployment time, if you specify an -Xmx option in the deployer.<app>.local.javaOpts property in addition to a value of the deployer.<app>.local.memory option, the value in the javaOpts property has precedence. Also, the javaOpts property set when deploying the application has precedence over the Data Flow Server’s spring.cloud.deployer.local.javaOpts property.

21. Maven

If you want to override specific maven configuration properties (remote repositories, proxies, and others) or run the Data Flow Server behind a proxy, you need to specify those properties as command line arguments when starting the Data Flow Server, as shown in the following example:

$ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --maven.localRepository=mylocal
--maven.remote-repositories.repo1.url=https://repo1
--maven.remote-repositories.repo1.auth.username=user1
--maven.remote-repositories.repo1.auth.password=pass1
--maven.remote-repositories.repo1.snapshot-policy.update-policy=daily
--maven.remote-repositories.repo1.snapshot-policy.checksum-policy=warn
--maven.remote-repositories.repo1.release-policy.update-policy=never
--maven.remote-repositories.repo1.release-policy.checksum-policy=fail
--maven.remote-repositories.repo2.url=https://repo2
--maven.remote-repositories.repo2.policy.update-policy=always
--maven.remote-repositories.repo2.policy.checksum-policy=fail
--maven.proxy.host=proxy1
--maven.proxy.port=9010 --maven.proxy.auth.username=proxyuser1
--maven.proxy.auth.password=proxypass1

By default, the protocol is set to http. You can omit the auth properties if the proxy does not need a username and password. Also, the maven localRepository is set to ${user.home}/.m2/repository/ by default. As shown in the preceding example, the remote repositories can be specified along with their authentication (if needed). If the remote repositories are behind a proxy, then the proxy properties can be specified as shown in the preceding example.

The repository policies can be specified for each remote repository configuration as shown in the preceding example. The key policy is applicable to both snapshot and the release repository policies.

You can refer to Repository Policies for the list of supported repository policies.

As these are Spring Boot @ConfigurationProperties, you can also specify them as environment variables, such as MAVEN_REMOTE_REPOSITORIES_REPO1_URL. Another common option is to set the properties by setting the SPRING_APPLICATION_JSON environment variable. The following example shows how the JSON is structured:

$ SPRING_APPLICATION_JSON='{ "maven": { "local-repository": null,
"remote-repositories": { "repo1": { "url": "https://repo1", "auth": { "username": "repo1user", "password": "repo1pass" } }, "repo2": { "url": "https://repo2" } },
"proxy": { "host": "proxyhost", "port": 9018, "auth": { "username": "proxyuser", "password": "proxypass" } } } }' java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar

22. Skipper

To use features such as Stream update and rollback, the Data Flow Server delegates to the Skipper server to manage the Stream’s lifecycle. Set the configuration property spring.cloud.skipper.client.serverUri to the location of Skipper, e.g.

+

$ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --spring.cloud.skipper.client.serverUri=http://192.51.100.1:7577/api --spring.cloud.dataflow.features.skipper-enabled=true

23. Security

By default, the Data Flow server is unsecured and runs on an unencrypted HTTP connection. You can secure your REST endpoints as well as the Data Flow Dashboard by enabling HTTPS and requiring clients to authenticate using either:

  • OAuth 2.0

  • Traditional Authentication (including Basic Authentication)

The following image shows the authentication options for Spring Cloud Data Flow Server:

Authentication Options
Figure 5. Authentication Options

When choosing traditional authentication, the Spring Cloud Data Flow server is the main authentication point, using Spring Security under the covers. When selecting this option, users then need to further define their preferred authentication mechanism by selecting the desired authentication backing store, which can be one of the following options:

When choosing between traditional authentication or OAuth2, keep in mind that both options are mutually exclusive. Please refer to the sections below for a more detailed discussion.

By default, the REST endpoints (administration, management, and health) as well as the Dashboard UI do not require authenticated access.

23.1. Enabling HTTPS

By default, the dashboard, management, and health endpoints use HTTP as a transport. You can switch to HTTPS by adding a certificate to your configuration in application.yml, as shown in the following example:

server:
  port: 8443                                         (1)
  ssl:
    key-alias: yourKeyAlias                          (2)
    key-store: path/to/keystore                      (3)
    key-store-password: yourKeyStorePassword         (4)
    key-password: yourKeyPassword                    (5)
    trust-store: path/to/trust-store                 (6)
    trust-store-password: yourTrustStorePassword     (7)
1 As the default port is 9393, you may choose to change the port to a more common HTTPs-typical port.
2 The alias (or name) under which the key is stored in the keystore.
3 The path to the keystore file. Classpath resources may also be specified, by using the classpath prefix - for example: classpath:path/to/keystore.
4 The password of the keystore.
5 The password of the key.
6 The path to the truststore file. Classpath resources may also be specified, by using the classpath prefix - for example: classpath:path/to/trust-store
7 The password of the trust store.
If HTTPS is enabled, it completely replaces HTTP as the protocol over which the REST endpoints and the Data Flow Dashboard interact. Plain HTTP requests will fail. Therefore, make sure that you configure your Shell accordingly.

23.1.1. Using Self-Signed Certificates

For testing purposes or during development, it might be convenient to create self-signed certificates. To get started, execute the following command to create a certificate:

$ keytool -genkey -alias dataflow -keyalg RSA -keystore dataflow.keystore \
          -validity 3650 -storetype JKS \
          -dname "CN=localhost, OU=Spring, O=Pivotal, L=Kailua-Kona, ST=HI, C=US"  (1)
          -keypass dataflow -storepass dataflow
1 CN is the important parameter here. It should match the domain you are trying to access - for example, localhost.

Then add the following lines to your application.yml file:

server:
  port: 8443
  ssl:
    enabled: true
    key-alias: dataflow
    key-store: "/your/path/to/dataflow.keystore"
    key-store-type: jks
    key-store-password: dataflow
    key-password: dataflow

This is all that is needed for the Data Flow Server. Once you start the server, you should be able to access it at localhost:8443/. As this is a self-signed certificate, you should hit a warning in your browser, which you need to ignore.

23.1.2. Self-Signed Certificates and the Shell

By default, self-signed certificates are an issue for the shell, and additional steps are necessary to make the shell work with self-signed certificates. Two options are available:

  • Add the self-signed certificate to the JVM truststore.

  • Skip certificate validation.

Adding the Self-signed Certificate to the JVM Truststore

In order to use the JVM truststore option, we need to export the previously created certificate from the keystore, as follows:

$ keytool -export -alias dataflow -keystore dataflow.keystore -file dataflow_cert -storepass dataflow

Next, we need to create a truststore which the shell can use, as follows:

$ keytool -importcert -keystore dataflow.truststore -alias dataflow -storepass dataflow -file dataflow_cert -noprompt

Now, you are ready to launch the Data Flow Shell by using the following JVM arguments:

$ java -Djavax.net.ssl.trustStorePassword=dataflow \
       -Djavax.net.ssl.trustStore=/path/to/dataflow.truststore \
       -Djavax.net.ssl.trustStoreType=jks \
       -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar

In case you run into trouble establishing a connection over SSL, you can enable additional logging by using and setting the javax.net.debug JVM argument to ssl.

Do not forget to target the Data Flow Server with the following:

dataflow:> dataflow config server https://localhost:8443/
Skipping Certificate Validation

Alternatively, you can also bypass the certification validation by providing the optional command-line parameter --dataflow.skip-ssl-validation=true.

If you set this command-line parameter, the shell accepts any (self-signed) SSL certificate.

If possible, you should avoid using this option. Disabling the trust manager defeats the purpose of SSL and makes you vulnerable to man-in-the-middle attacks.

23.2. Traditional Authentication

When using traditional authentication, Spring Cloud Data Flow is the sole authentication provider. In that case, Data Flow REST API users would use Basic Authentication to access the endpoints.

When using that option, users have a choice of three backing stores for authentication details:

  • Single User Authentication by setting Spring Boot properties

  • File-based Authentication for multiple users by using a Yaml file

  • Ldap Authentication

23.2.1. Single User Authentication

This is the simplest option and mimics the behavior of the default Spring Boot user experience. It can be enabled by setting environment variables or by adding the following to application.yml:

security:
  basic:
    enabled: true                                                     (1)
    realm: Spring Cloud Data Flow                                     (2)
1 Enables basic authentication. Must be set to true for security to be enabled.
2 (Optional) The realm for Basic authentication. Defaults to Spring if not explicitly set.
Current versions of Chrome do not display the realm. Please see the following Chromium issue ticket for more information.

In this use case, the underlying Spring Boot auto-creates a user called user with an auto-generated password which is printed out to the console upon startup.

With this setup, the generated user has all main roles assigned, as follows:

  • VIEW

  • CREATE

  • MANAGE

The following image shows the default Spring Boot user credentials as they appear in the console.

Default Spring Boot user credentials
Figure 6. Default Spring Boot user credentials

You can customize the user by setting the following properties:

security.user.name=user # Default user name.
security.user.password= # Password for the default user name. A random password is logged on startup by default.
security.user.role=VIEW,CREATE,MANAGE # Granted roles for the default user name.
Please be aware of inherent issues of Basic Authentication and logging out: The credentials are cached by the browser and simply browsing back to application pages logs you back in.

Of course, you can also pass in credentials by setting system properties, environment variables, or command-line arguments, as this is standard Spring Boot behavior. For instance, in the following example, command-line arguments are used to specify the user credentials:

$ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar\
    --security.basic.enabled=true \
    --security.user.name=test \
    --security.user.password=pass \
    --security.user.role=VIEW

If you need to define more than one file-based user account, please take a look at File-based authentication.

23.2.2. File-based Authentication

By default, Spring Boot lets you specify only one single user. Spring Cloud Data Flow also supports the listing of more than one user in a configuration file. Each user must be assigned a password and one or more roles. The following example shows the creation of additional users:

security:
  basic:
    enabled: true
    realm: Spring Cloud Data Flow
spring:
  cloud:
    dataflow:
      security:
        authentication:
          file:
            enabled: true                                                 (1)
            users:                                                        (2)
              bob: bobspassword, ROLE_MANAGE                              (3)
              alice: alicepwd, ROLE_VIEW, ROLE_CREATE
1 Enables file based authentication.
2 This is a yaml map of username to password.
3 Each map value is made of a corresponding password and role(s), comma separated.

23.2.3. LDAP Authentication

Spring Cloud Data Flow also supports authentication against an LDAP (Lightweight Directory Access Protocol) server, providing support for the following modes:

  • Direct bind

  • Search and bind

When the LDAP authentication option is activated, the default single user mode is turned off.

In direct bind mode, a pattern is defined for the user’s distinguished name (DN), using a placeholder for the username. The authentication process derives the distinguished name of the user by replacing the placeholder and using it to authenticate a user against the LDAP server, along with the supplied password. You can set up LDAP direct bind as follows:

security:
  basic:
    enabled: true
    realm: Spring Cloud Data Flow
spring:
  cloud:
    dataflow:
      security:
        authentication:
          ldap:
            enabled: true                                                 (1)
            url: ldap://ldap.example.com:3309                             (2)
            userDnPattern: uid={0},ou=people,dc=example,dc=com            (3)
1 Enables LDAP authentication
2 The URL for the LDAP server
3 The distinguished name (DN) pattern for authenticating against the server

The search and bind mode involves connecting to an LDAP server, either anonymously or with a fixed account, searching for the distinguished name of the authenticating user based on its username, and then using the resulting value and the supplied password for binding to the LDAP server. This option is configured as follows:

security:
  basic:
    enabled: true
    realm: Spring Cloud Data Flow
spring:
  cloud:
    dataflow:
      security:
        authentication:
          ldap:
            enabled: true                                                 (1)
            url: ldap://localhost:10389                                   (2)
            managerDn: uid=admin,ou=system                                (3)
            managerPassword: secret                                       (4)
            userSearchBase: ou=otherpeople,dc=example,dc=com              (5)
            userSearchFilter: uid={0}                                     (6)
1 Enables LDAP integration
2 The URL of the LDAP server
3 A DN to authenticate to the LDAP server, if anonymous searches are not supported (optional, required together with next option)
4 A password to authenticate to the LDAP server, if anonymous searches are not supported (optional, required together with previous option)
5 The base for searching the DN of the authenticating user (serves to restrict the scope of the search)
6 The search filter for the DN of the authenticating user
For more information, please also see the LDAP Authentication chapter of the Spring Security reference guide.
LDAP Role Mapping

By default, the role name retrieved from Ldap needs to match the name of the role in Spring Cloud Data Flow. However, it is also possible to explicitly provide a mapping between LDAP roles and Spring Cloud Data Flow roles.

security:
  basic:
    enabled: true
    realm: Spring Cloud Data Flow
spring:
  cloud:
    dataflow:
      security:
        authentication:
          ldap:
            enabled: true
            url: ldap://localhost:10389
            managerDn: uid=admin,ou=system
            managerPassword: secret
            userSearchBase: ou=otherpeople,dc=example,dc=com
            userSearchFilter: uid={0}
            roleMappings:                                                 (1)
              ROLE_MANAGE: foo-manage                                     (2)
              ROLE_VIEW: bar-view
              ROLE_CREATE: foo-manage
1 Enables explicit role mapping support
2 When role mapping support is enabled, you must provide a mapping for all 3 Spring Cloud Data Flow roles ROLE_MANAGE, ROLE_VIEW, ROLE_CREATE.
LDAP Transport Security

When connecting to an LDAP server, you typically (in the LDAP world) have two options to establish a connection to an LDAP server securely:

  • LDAP over SSL (LDAPs)

  • Start Transport Layer Security (Start TLS is defined in RFC2830)

As of Spring Cloud Data Flow 1.1.0, only LDAPs is supported out-of-the-box. When using official certificates, no special configuration is necessary to connect to an LDAP Server over LDAPs. You need only change the url format to ldaps - for example: ldaps://localhost:636.

In the case of self-signed certificates, the setup for your Spring Cloud Data Flow server becomes slightly more complex. The setup is very similar to Using Self-Signed Certificates (please read first), and Spring Cloud Data Flow needs to reference a trustStore in order to work with your self-signed certificates.

While useful during development and testing, never use self-signed certificates in production!

Ultimately, you have to provide a set of system properties to reference the trustStore and its credentials when starting the server, as follows:

$ java -Djavax.net.ssl.trustStorePassword=dataflow \
       -Djavax.net.ssl.trustStore=/path/to/dataflow.truststore \
       -Djavax.net.ssl.trustStoreType=jks \
       -jar spring-cloud-starter-dataflow-server-local-1.5.1.RELEASE.jar

As mentioned earlier, another option to connect to an LDAP server securely is over Start TLS. In the LDAP world, LDAPs is technically even considered deprecated in favor of Start TLS. However, this option is currently not supported out-of-the-box by Spring Cloud Data Flow.

Please follow the following issue tracker ticket to track its implementation. You may also want to look at the Spring LDAP reference documentation chapter on Custom DirContext Authentication Processing for further details.

23.2.4. Shell Authentication

When using traditional authentication with the Data Flow Shell, you typically provide a username and password by using command-line arguments, as shown in the following example:

$ java -jar target/spring-cloud-dataflow-shell-1.5.1.RELEASE.jar  \
  --dataflow.username=myuser                                          \   (1)
  --dataflow.password=mysecret                                            (2)
1 If authentication is enabled, the username must be provided.
2 If the password is not provided, the shell prompts for it.

Alternatively, you can target a Data Flow Server also from within the shell, as follows:

server-unknown:>dataflow config server
  --uri  http://localhost:9393                                        \   (1)
  --username myuser                                                   \   (2)
  --password mysecret                                                 \   (3)
  --skip-ssl-validation  true                                         \   (4)
1 Optional, defaults to localhost:9393.
2 Mandatory if security is enabled.
3 If security is enabled, and the password is not provided, the user is prompted for it.
4 Optional, ignores certificate errors (when using self-signed certificates). Use cautiously!

The following image shows a typical shell command to connect to and authenticate a Data Flow Server:

Target and Authenticate with the Data Flow Server from within the Shell
Figure 7. Target and Authenticate with the Data Flow Server from within the Shell

23.2.5. Customizing Authorization

The preceding content deals with authentication - that is, how to assess the identity of the user. Irrespective of the option chosen, you can also customize authorization - that is, who can do what.

The default scheme uses three roles to protect the REST endpoints that Spring Cloud Data Flow exposes:

  • ROLE_VIEW for anything that relates to retrieving state

  • ROLE_CREATE for anything that involves creating, deleting, or mutating the state of the system

  • ROLE_MANAGE for boot management endpoints

All of those defaults are specified in dataflow-server-defaults.yml, which is part of the Spring Cloud Data Flow Core Module. Nonetheless, you can override those, if desired - for example, in application.yml. The configuration takes the form of a YAML list (as some rules may have precedence over others). Consequently, you need to copy and paste the whole list and tailor it to your needs (as there is no way to merge lists).

Always refer to your version of application.yml, as the following snippet may be outdated.

The default rules are as follows:

spring:
  cloud:
    dataflow:
      security:
        authorization:
          enabled: true
          rules:
            # Metrics

            - GET    /metrics/streams                => hasRole('ROLE_VIEW')

            # About

            - GET    /about                          => hasRole('ROLE_VIEW')

            # Metrics

            - GET    /metrics/**                     => hasRole('ROLE_VIEW')
            - DELETE /metrics/**                     => hasRole('ROLE_CREATE')

            # Boot Endpoints

            - GET    /management/**                  => hasRole('ROLE_MANAGE')

            # Apps

            - GET    /apps                           => hasRole('ROLE_VIEW')
            - GET    /apps/**                        => hasRole('ROLE_VIEW')
            - DELETE /apps/**                        => hasRole('ROLE_CREATE')
            - POST   /apps                           => hasRole('ROLE_CREATE')
            - POST   /apps/**                        => hasRole('ROLE_CREATE')

            # Completions

            - GET /completions/**                    => hasRole('ROLE_CREATE')

            # Job Executions & Batch Job Execution Steps && Job Step Execution Progress

            - GET    /jobs/executions                => hasRole('ROLE_VIEW')
            - PUT    /jobs/executions/**             => hasRole('ROLE_CREATE')
            - GET    /jobs/executions/**             => hasRole('ROLE_VIEW')

            # Batch Job Instances

            - GET    /jobs/instances                 => hasRole('ROLE_VIEW')
            - GET    /jobs/instances/*               => hasRole('ROLE_VIEW')

            # Running Applications

            - GET    /runtime/apps                   => hasRole('ROLE_VIEW')
            - GET    /runtime/apps/**                => hasRole('ROLE_VIEW')

            # Stream Definitions

            - GET    /streams/definitions            => hasRole('ROLE_VIEW')
            - GET    /streams/definitions/*          => hasRole('ROLE_VIEW')
            - GET    /streams/definitions/*/related  => hasRole('ROLE_VIEW')
            - POST   /streams/definitions            => hasRole('ROLE_CREATE')
            - DELETE /streams/definitions/*          => hasRole('ROLE_CREATE')
            - DELETE /streams/definitions            => hasRole('ROLE_CREATE')

            # Stream Deployments

            - DELETE /streams/deployments/*          => hasRole('ROLE_CREATE')
            - DELETE /streams/deployments            => hasRole('ROLE_CREATE')
            - POST   /streams/deployments/*          => hasRole('ROLE_CREATE')

            # Task Definitions

            - POST   /tasks/definitions              => hasRole('ROLE_CREATE')
            - DELETE /tasks/definitions/*            => hasRole('ROLE_CREATE')
            - GET    /tasks/definitions              => hasRole('ROLE_VIEW')
            - GET    /tasks/definitions/*            => hasRole('ROLE_VIEW')

            # Task Executions

            - GET    /tasks/executions               => hasRole('ROLE_VIEW')
            - GET    /tasks/executions/*             => hasRole('ROLE_VIEW')
            - POST   /tasks/executions               => hasRole('ROLE_CREATE')
            - DELETE /tasks/executions/*             => hasRole('ROLE_CREATE')

The format of each line is the following:

HTTP_METHOD URL_PATTERN '=>' SECURITY_ATTRIBUTE

where

  • HTTP_METHOD is one http method, capital case

  • URL_PATTERN is an Ant style URL pattern

  • SECURITY_ATTRIBUTE is a SpEL expression. See Expression-Based Access Control.

  • Each of those separated by one or several blank characters (spaces, tabs, and so on)

Be mindful that the above is indeed a YAML list, not a map (thus the use of '-' dashes at the start of each line) that lives under the spring.cloud.dataflow.security.authorization.rules key.

In case you are solely interested in authentication but not authorization (for instance every user shall have have access to all endpoints), then you can also set spring.cloud.dataflow.security.authorization.enabled=false.

If you use basic security configuration by setting security properties, then it is important to set the roles for the users, as shown in the following example:

java -jar spring-cloud-dataflow-server-local/target/spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar \
    --security.basic.enabled=true \
    --security.user.name=test \
    --security.user.password=pass \
    --security.user.role=VIEW

23.2.6. Authorization - Shell and Dashboard Behavior

When authorization is enabled, the dashboard and the shell are role-aware, meaning that, depending on the assigned roles, not all functionality may be visible.

For instance, shell commands for which the user does not have the necessary roles are marked as unavailable.

Currently, the shell’s help command lists commands that are unavailable. Please track the following issue: github.com/spring-projects/spring-shell/issues/115

Similarly, for the dashboard, the UI does not show pages or page elements for which the user is not authorized.

23.2.7. Authorization with LDAP

When configuring LDAP for authentication, you can also specify the group-role-attribute in conjunction with group-search-base and group-search-filter.

The group role attribute contains the name of the role. If not specified, the ROLE_MANAGE role is populated by default.

For further information, please refer to Configuring an LDAP Server in the Spring Security reference guide.

23.3. OAuth 2.0

OAuth 2.0 lets you integrate Spring Cloud Data Flow into Single Sign On (SSO) environments. The following OAuth2 Grant Types are used:

  • Authorization Code: Used for the GUI (browser) integration. Visitors are redirected to your OAuth Service for authentication

  • Password: Used by the shell (and the REST integration), so visitors can log in with username and password

  • Client Credentials: Retrieve an access token directly from your OAuth provider and pass it to the Data Flow server by using the Authorization HTTP header

The REST endpoints can be accessed in two ways:

  • Basic authentication, which uses the Password Grant Type under the covers to authenticate with your OAuth2 service

  • Access token, which uses the Client Credentials Grant Type under the covers

When authentication is set up, it is strongly recommended to enable HTTPS as well, especially in production environments.

You can turn on OAuth2 authentication by adding the following to application.yml or by setting environment variables:

security:
  oauth2:
    client:
      client-id: myclient                                             (1)
      client-secret: mysecret
      access-token-uri: http://127.0.0.1:9999/oauth/token
      user-authorization-uri: http://127.0.0.1:9999/oauth/authorize
    resource:
      user-info-uri: http://127.0.0.1:9999/me
1 Providing the Client ID in the OAuth Configuration Section activates OAuth2 security

You can verify that basic authentication is working properly by using curl, as follows:

$ curl -u myusername:mypassword http://localhost:9393/ -H 'Accept: application/json'

As a result, you should see a list of available REST endpoints.

Please be aware that when accessing the Root URL with a web browser and enabled security, you are redirected to the Dashboard UI. In order to see the list of REST endpoints, specify the application/json. Also be sure to add the Accept header using tools such as Postman (Chrome) or RESTClient (Firefox).

Besides Basic Authentication, you can also provide an Access Token in order to access the REST Api. In order to make that happen, you would retrieve an OAuth2 Access Token from your OAuth2 provider first and then pass that Access Token to the REST Api using the Authorization Http header:

$ curl -H "Authorization: Bearer <ACCESS_TOKEN>" http://localhost:9393/ -H 'Accept: application/json'

23.3.1. OAuth REST Endpoint Authorization

The OAuth2 authentication option uses the same authorization rules as used by the Traditional Authentication option.

The authorization rules are defined in dataflow-server-defaults.yml (part of the Spring Cloud Data Flow Core module). Please see the chapter on customizing authorization for more details.

Because the determination of security roles is environment-specific, Spring Cloud Data Flow, by default, assigns all roles to authenticated OAuth2 users by using the DefaultDataflowAuthoritiesExtractor class.

You can customize that behavior by providing your own Spring bean definition that extends Spring Security OAuth’s AuthoritiesExtractor interface. In that case, the custom bean definition takes precedence over the default one provided by Spring Cloud Data Flow.

23.3.2. OAuth Authentication using the Spring Cloud Data Flow Shell

When using the Shell, the credentials can either be provided via username and password or by specifying a credentials-provider command.

If your OAuth2 provider supports the Password Grant Type you can start the Data Flow Shell with:

$ java -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar \
  --dataflow.uri=http://localhost:9393 \
  --dataflow.username=my_username --dataflow.password=my_password
Keep in mind that when authentication for Spring Cloud Data Flow is enabled, the underlying OAuth2 provider must support the Password OAuth2 Grant Type if you want to use the Shell via username/password authentication.

From within the Data Flow Shell you can also provide credentials by using the following command:

dataflow config server --uri http://localhost:9393 --username my_username --password my_password

Once successfully targeted, you should see the following output:

dataflow:>dataflow config info
dataflow config info

╔═══════════╤═══════════════════════════════════════╗
║Credentials│[username='my_username, password=****']║
╠═══════════╪═══════════════════════════════════════╣
║Result     │                                       ║
║Target     │http://localhost:9393                  ║
╚═══════════╧═══════════════════════════════════════╝

Alternatively, you can specify the credentials-provider command in order to pass-in a bearer token directly, instead of providing a username and password. This works from within the shell or by providing the --dataflow.credentials-provider-command command-line argument when starting the Shell.

When using the credentials-provider command, please be aware that your specified command must return a Bearer token (Access Token prefixed with Bearer). For instance, in Unix environments the following simplistic command can be used:

$ java -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar \
  --dataflow.uri=http://localhost:9393 \
  --dataflow.credentials-provider-command="echo Bearer 123456789"

23.3.3. OAuth2 Authentication Examples

This section offers the following authentication examples:

Local OAuth2 Server

With Spring Security OAuth, you can easily create your own OAuth2 Server with the following simple annotations:

  • @EnableResourceServer

  • @EnableAuthorizationServer

A working example application can be found at:

Clone the project and configure Spring Cloud Data Flow with the respective Client ID and Client Secret. Then build and start the project.

Authentication with GitHub

If you like to use an existing OAuth2 provider, here is an example for GitHub. First, you need to register a new application under your GitHub account at:

When running a default version of Spring Cloud Data Flow locally, your GitHub configuration should look like the following image:

Register an OAuth Application for GitHub
Figure 8. Register an OAuth Application for GitHub
For the authorization callback URL, enter Spring Cloud Data Flow’s Login URL - for example, localhost:9393/login.

Configure Spring Cloud Data Flow with the GitHub relevant Client ID and Secret, as follows:

security:
  oauth2:
    client:
      client-id: your-github-client-id
      client-secret: your-github-client-secret
      access-token-uri: https://github.com/login/oauth/access_token
      user-authorization-uri: https://github.com/login/oauth/authorize
    resource:
      user-info-uri: https://api.github.com/user
GitHub does not support the OAuth2 password grant type. As a result, you cannot use the Spring Cloud Data Flow Shell in conjunction with GitHub.

23.4. Securing the Spring Boot Management Endpoints

When enabling security, please also make sure that the Spring Boot HTTP Management Endpoints are secured as well. You can enable security for the management endpoints by adding the following to application.yml:

management:
  contextPath: /management
  security:
    enabled: true
If you do not explicitly enable security for the management endpoints, you may end up having unsecured REST endpoints, despite security.basic.enabled being set to true.

24. Monitoring and Management

The Spring Cloud Data Flow server is a Spring Boot 1.5 application that includes the Actuator library, which adds several production ready features to help you monitor and manage your application.

The Actuator library adds HTTP endpoints under the context path /management which is a discovery page for available managerment endpoints. For example, there is a health endpoint that shows application health information and an env that lists properties from Spring’s ConfigurableEnvironment. By default, only the health and application info endpoints are accessible. The other endpoints are considered to be sensitive and need to be enabled explicitly via configuration. If you enable sensitive endpoints, you should also secure the Data Flow server’s endpoints so that information is not inadvertently exposed to unauthenticated users. The local Data Flow server has security disabled by default, so all actuator endpoints are available.

The Data Flow server requires a relational database, and, if the feature toggle for analytics is enabled, a Redis server is also required. The Data Flow server autoconfigures the DataSourceHealthIndicator and RedisHealthIndicator if needed. The health of these two services is incorporated to the overall health status of the server through the health endpoint.

24.1. Monitoring Deployed Stream Applications

The stream applications deployed by Spring Cloud Data Flow can be based on Spring Boot 1.5 or Spring Boot 2.0. Both versions contains several features for monitoring your application in production. However, Spring Boot 1.x and 2.x as well as Spring Cloud Stream 1.x and 2.x differ in how monitoring is implemented. Since Spring Cloud Data Flow supports deploying 1.x and 2.x applications, we will cover both cases individually.

What is common across 1.x and 2.x applications is that Spring Cloud Stream apps can be configured to publish metrics to a messaging middleware destination. The Spring Cloud Data Flow Metrics Collector subscribes to this destination and aggregates metrics into a stream based view. The Metrics Collector 2.0 server supports collecting metrics from streams that contain only Boot 1.x or 2.x apps as well as streams that contain a mixture of Boot versions. The Data Flow UI queries the Metrics collector over HTTP to display messages rates next to each deployed application.

The following image shows the architecture when using Spring Cloud Stream’s metrics publisher, the Metrics Collector, and the Data Flow server:

Spring Cloud Data Flow Metrics Architecture
Figure 9. Spring Cloud Data Flow Metrics Architecture

24.1.1. Using the Metrics Collector

There are two versions of the Metrics Collector, a 1.0 version based on Spring Boot 1.0 that understands how to aggregate metrics from Spring Boot 1.x applications and a 2.0 version based on Spring Boot 2.0 that understands how to aggregate metrics from Spring Boot 1.x and 2.x. There is a Metrics Collector server for Rabbit and Kafka. You can find more information on downloading and running the Metrics Collector on its project page.

The Data Flow server property: spring.cloud.dataflow.metrics.collector.uri references the URI the Metrics Collector. For example, if you run the Metrics Collector locally on port 8080, this is how you start local Data Flow server to reference the Metrics Collector.

$ java -jar spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --spring.cloud.dataflow.metrics.collector.uri=http://localhost:8080

The Metrics Collector can be secured with 'basic' authentication that requires a username and password. To set the username and password, use the properties spring.cloud.dataflow.metrics.collector.username and spring.cloud.dataflow.metrics.collector.password when starting the Data Flow server.

The metrics for each application are published when the property spring.cloud.stream.bindings.applicationMetrics.destination is set. Using a destination name of metrics is a good choice as the Metrics Collector subscribes to that name by default.

Since it is quite common to want all stream applications deployed by Data Flow to emit metrics, setting the property:

spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.bindings.applicationMetrics.destination=metrics

on the Data Flow server will let you configure support for metrics publication in one central location.

Using a destination name of metrics is a good choice as the Metrics Collector subscribes to that name by default, which of course, can be overridden to be different than the default as needed.

The next most common way to configure the metrics destination is to use deployment properties. The following example shows the ticktock stream that uses the App Starters time and log applications:

app register --name time --type source --uri maven://org.springframework.cloud.stream.app:time-source-rabbit:1.2.0.RELEASE

app register --name log --type sink --uri maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.2.0.RELEASE

stream create --name foostream --definition "time | log"

stream deploy --name foostream --properties "app.*.spring.cloud.stream.bindings.applicationMetrics.destination=metrics"

The Metrics Collector exposes aggregated metrics under the HTTP endpoint /collector/metrics in JSON format. The Data Flow server accesses this endpoint in two distinct ways. The first is by exposing a /metrics/streams HTTP endpoint that acts as a proxy to the Metrics Collector endpoint. This is accessed by the UI when overlaying message rates on SCDF’s Flo and it’s visual representation of streaming pipelines. It is also accessed to enrich the Data Flow /runtime/apps endpoint that is exposed in the UI in the Runtime tab and in the shell through the runtime apps command with message rates.

The following image shows the message rates as they appear in the Streams tab of the UI:

Stream Message Rates
Figure 10. Stream Message Rates

When deploying applications, Data Flow sets the spring.cloud.stream.metrics.properties property, as shown in the following example:

spring.cloud.stream.metrics.properties=spring.application.name,spring.application.index,spring.cloud.application.*,spring.cloud.dataflow.*

The values of these keys are used as the tags to perform aggregation. In the case of 2.x applications, these key-values map directly onto tags in the Micrometer library. The property spring.cloud.application.guid can be used to track back to the specific application instance that generated the metric. The guid value is platform-dependent.

Data Flow also sets the application property that controls which metric values are exported. For 1.x applications, the property is spring.metrics.export.triggers.application.includes and the default value is is shown below:

spring.metrics.export.triggers.application.includes=integration**

For 2.x applications, the property is spring.cloud.stream.metrics.meter-filter and it does not have a default value, so all metrics are exported.

Note that the Data Flow UI only displays instantaneous input and output channel message rates. Data Flow does not provide its own implementation to store and visualize historical metrics data, instead we integrate with existing monitoring systems. For Boot 1.x, there is support for sending metrics to the application log and Datadog. For Boot 2.x, metrics is backed by the Micrometer library that provides a wide range of monitoring systems.

24.1.2. Spring Boot 2.x

We have developed a sample application that show how to modify the time and log applications and export metrics to InfluxDB using the micrometer library. A Grafana front end is also provided. This is a WIP, so check the Spring Cloud Data Flow Samples Repository for the latest status.

24.1.3. Spring Boot 1.x

Each deployed application contains web endpoints for monitoring and interacting with Stream and Task applications.

In particular, the /metrics endpoint contains counters and gauges for HTTP requests, System Metrics such as JVM stats, DataSource Metrics, and Message Channel Metrics. Spring Boot lets you add your own metrics to the /metrics endpoint either by registering an implementation of the PublicMetrics interface or through its integration with Dropwizard.

The Spring Boot interfaces, MetricWriter and Exporter, are used to send the metrics data to a place where they can be displayed and analyzed. There are implementations in Spring Boot to export metrics to Redis, Open TSDB, Statsd, and JMX.

A few additional Spring projects provide support for sending metrics data to external systems:

To make use of this functionality, you need to build the Stream application with the additional pom dependency of the MetricWriter implementation you want to use. To customize the “out of the box” Stream applications, use the Spring Cloud Stream Initializr to generate a project and then modify the pom. The documentation on the Data Flow Metrics project pages provides the additional information you need to get started.

25. About Configuration

The Spring Cloud Data Flow About Restful API result contains a display name, version, and, if specified, a URL for each of the major dependencies that comprise Spring Cloud Data Flow. The result (if enabled) also contains the sha1 and or sha256 checksum values for the shell dependency. The information that is returned for each of the dependencies is configurable by setting the following properties:

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-core.name: the name to be used for the core.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-core.version: the version to be used for the core.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-dashboard.name: the name to be used for the dashboard.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-dashboard.version: the version to be used for the dashboard.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-implementation.name: the name to be used for the implementation.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-implementation.version: the version to be used for the implementation.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.name: the name to be used for the shell.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.version: the version to be used for the shell.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.url: the URL to be used for downloading the shell dependency.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha1: the sha1 checksum value that is returned with the shell dependency info.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha256: the sha256 checksum value that is returned with the shell dependency info.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha1-url: if the spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha1 is not specified, SCDF uses the contents of the file specified at this URL for the checksum.

  • spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha256-url: if the spring.cloud.dataflow.version-info.spring-cloud-dataflow-shell.checksum-sha256 is not specified, SCDF uses the contents of the file specified at this URL for the checksum.

25.1. Enabling Shell Checksum values

By default, checksum values are not displayed for the shell dependency. If you need this feature enabled, set the spring.cloud.dataflow.version-info.dependency-fetch.enabled property to true.

25.2. Reserved Values for URLs

There are reserved values (surrounded by curly braces) that you can insert into the URL that will make sure that the links are up to date:

  • repository: if using a build-snapshot, milestone, or release candidate of Data Flow, the repository refers to the repo-spring-io repository. Otherwise, it refers to Maven Central.

  • version: Inserts the version of the jar/pom.

Shell

This section covers the options for starting the shell and more advanced functionality relating to how the shell handles white spaces, quotes, and interpretation of SpEL expressions. The introductory chapters to the Stream DSL and Composed Task DSL are good places to start for the most common usage of shell commands.

26. Shell Options

The shell is built upon the Spring Shell project. There are command line options generic to Spring Shell and some specific to Data Flow. The shell takes the following command line options

unix:>java -jar spring-cloud-dataflow-shell-1.5.1.RELEASE.jar --help
Data Flow Options:
  --dataflow.uri=                              Address of the Data Flow Server [default: http://localhost:9393].
  --dataflow.username=                        Username of the Data Flow Server [no default].
  --dataflow.password=                    Password of the Data Flow Server [no default].
  --dataflow.credentials-provider-command= Executes an external command which must return an
                                                    OAuth Bearer Token (Access Token prefixed with 'Bearer '),
                                                    e.g. 'Bearer 12345'), [no default].
  --dataflow.skip-ssl-validation=       Accept any SSL certificate (even self-signed) [default: no].
  --dataflow.proxy.uri=                  Address of an optional proxy server to use [no default].
  --dataflow.proxy.username=        Username of the proxy server (if required by proxy server) [no default].
  --dataflow.proxy.password=        Password of the proxy server (if required by proxy server) [no default].
  --spring.shell.historySize=                 Default size of the shell log file [default: 3000].
  --spring.shell.commandFile=                 Data Flow Shell executes commands read from the file(s) and then exits.
  --help                                            This message.

The spring.shell.commandFile option can be used to point to an existing file that contains all the shell commands to deploy one or many related streams and tasks. This is useful when creating some scripts to help automate deployment.

Also, the following shell command helps to modularize a complex script into multiple independent files:

dataflow:>script --file <YOUR_AWESOME_SCRIPT>

27. Listing Available Commands

Typing help at the command prompt gives a listing of all available commands. Most of the commands are for Data Flow functionality, but a few are general purpose.

! - Allows execution of operating system (OS) commands
clear - Clears the console
cls - Clears the console
date - Displays the local date and time
exit - Exits the shell
http get - Make GET request to http endpoint
http post - POST data to http endpoint
quit - Exits the shell
system properties - Shows the shell's properties
version - Displays shell version

Adding the name of the command to help shows additional information on how to invoke the command.

dataflow:>help stream create
Keyword:                   stream create
Description:               Create a new stream definition
 Keyword:                  ** default **
 Keyword:                  name
   Help:                   the name to give to the stream
   Mandatory:              true
   Default if specified:   '__NULL__'
   Default if unspecified: '__NULL__'

 Keyword:                  definition
   Help:                   a stream definition, using the DSL (e.g. "http --port=9000 | hdfs")
   Mandatory:              true
   Default if specified:   '__NULL__'
   Default if unspecified: '__NULL__'

 Keyword:                  deploy
   Help:                   whether to deploy the stream immediately
   Mandatory:              false
   Default if specified:   'true'
   Default if unspecified: 'false'

28. Tab Completion

The shell command options can be completed in the shell by pressing the TAB key after the leading --. For example, pressing TAB after stream create -- results in

dataflow:>stream create --
stream create --definition    stream create --name

If you type --de and then hit tab, --definition will be expanded.

Tab completion is also available inside the stream or composed task DSL expression for application or task properties. You can also use TAB to get hints in a stream DSL expression for what available sources, processors, or sinks can be used.

29. White Space and Quoting Rules

It is only necessary to quote parameter values if they contain spaces or the | character. The following example passes a SpEL expression (which is applied to any data it encounters) to a transform processor:

transform --expression='new StringBuilder(payload).reverse()'

If the parameter value needs to embed a single quote, use two single quotes, as follows:

scan --query='Select * from /Customers where name=''Smith'''

29.1. Quotes and Escaping

There is a Spring Shell-based client that talks to the Data Flow Server and is responsible for parsing the DSL. In turn, applications may have applications properties that rely on embedded languages, such as the Spring Expression Language.

The shell, Data Flow DSL parser, and SpEL have rules about how they handle quotes and how syntax escaping works. When combined together, confusion may arise. This section explains the rules that apply and provides examples of the most complicated situations you may encounter when all three components are involved.

It’s not always that complicated

If you do not use the Data Flow shell (for example, you use the REST API directly) or if application properties are not SpEL expressions, then the escaping rules are simpler.

29.1.1. Shell rules

Arguably, the most complex component when it comes to quotes is the shell. The rules can be laid out quite simply, though:

  • A shell command is made of keys (--something) and corresponding values. There is a special, keyless mapping, though, which is described later.

  • A value cannot normally contain spaces, as space is the default delimiter for commands.

  • Spaces can be added though, by surrounding the value with quotes (either single (') or double (") quotes).

  • Values passed inside deployment properties (e.g. deployment <stream-name> --properties " …​") should not be quoted again.

  • If surrounded with quotes, a value can embed a literal quote of the same kind by prefixing it with a backslash (\).

  • Other escapes are available, such as \t, \n, \r, \f and unicode escapes of the form \uxxxx.

  • The keyless mapping is handled in a special way such that it does not need quoting to contain spaces.

For example, the shell supports the ! command to execute native shell commands. The ! accepts a single keyless argument. This is why the following works:

dataflow:>! rm something

The argument here is the whole rm something string, which is passed as is to the underlying shell.

As another example, the following commands are strictly equivalent, and the argument value is something (without the quotes):

dataflow:>stream destroy something
dataflow:>stream destroy --name something
dataflow:>stream destroy "something"
dataflow:>stream destroy --name "something"

29.1.2. Property files rules

Rules are relaxed when loading the properties from files. * The special characters used in property files (both Java and YAML) needs to be escaped. For example \ should be replaced by \\, '\t` by \\t and so forth. * For Java property files (--propertiesFile <FILE_PATH>.properties) the property values should not be surrounded by quotes! It is not needed even if they contain spaces.

filter.expression=payload > 5
  • For YAML property files (--propertiesFile <FILE_PATH>.yaml), though, the values need to be surrounded by double quotes.

app:
    filter:
        filter:
            expression: "payload > 5"

29.1.3. DSL Parsing Rules

At the parser level (that is, inside the body of a stream or task definition) the rules are as follows:

  • Option values are normally parsed until the first space character.

  • They can be made of literal strings, though, surrounded by single or double quotes.

  • To embed such a quote, use two consecutive quotes of the desired kind.

As such, the values of the --expression option to the filter application are semantically equivalent in the following examples:

filter --expression=payload>5
filter --expression="payload>5"
filter --expression='payload>5'
filter --expression='payload > 5'

Arguably, the last one is more readable. It is made possible thanks to the surrounding quotes. The actual expression is payload > 5 (without quotes).

Now, imagine that we want to test against string messages. If we want to compare the payload to the SpEL literal string, "something", we could use the following:

filter --expression=payload=='something'           (1)
filter --expression='payload == ''something'''     (2)
filter --expression='payload == "something"'       (3)
1 This works because there are no spaces. It is not very legible, though.
2 This uses single quotes to protect the whole argument. Hence, the actual single quotes need to be doubled.
3 SpEL recognizes String literals with either single or double quotes, so this last method is arguably the most readable.

Please note that the preceding examples are to be considered outside of the shell (for example, when calling the REST API directly). When entered inside the shell, chances are that the whole stream definition is itself inside double quotes, which would need to be escaped. The whole example then becomes the following:

dataflow:>stream create something --definition "http | filter --expression=payload='something' | log"

dataflow:>stream create something --definition "http | filter --expression='payload == ''something''' | log"

dataflow:>stream create something --definition "http | filter --expression='payload == \"something\"' | log"

29.1.4. SpEL Syntax and SpEL Literals

The last piece of the puzzle is about SpEL expressions. Many applications accept options that are to be interpreted as SpEL expressions, and, as seen above, String literals are handled in a special way there, too. The rules are as follows:

  • Literals can be enclosed in either single or double quotes.

  • Quotes need to be doubled to embed a literal quote. Single quotes inside double quotes need no special treatment, and the reverse is also true.

As a last example, assume you want to use the transform processor. This processor accepts an expression option which is a SpEL expression. It is to be evaluated against the incoming message, with a default of payload (which forwards the message payload untouched).

It is important to understand that the following statements are equivalent:

transform --expression=payload
transform --expression='payload'

However, they are different from the following (and variations upon them):

transform --expression="'payload'"
transform --expression='''payload'''

The first series evaluates to the message payload, while the latter examples evaluate to the literal string, payload, (again, without quotes).

29.1.5. Putting It All Together

As a last, complete example, consider how one could force the transformation of all messages to the string literal, hello world, by creating a stream in the context of the Data Flow shell:

dataflow:>stream create something --definition "http | transform --expression='''hello world''' | log" (1)

dataflow:>stream create something --definition "http | transform --expression='\"hello world\"' | log" (2)

dataflow:>stream create something --definition "http | transform --expression=\"'hello world'\" | log" (2)
1 In the first line, there are single quotes around the string (at the Data Flow parser level), but they need to be doubled because they are inside a string literal (started by the first single quote after the equals sign).
2 The second and third lines, use single and double quotes respectively to encompass the whole string at the Data Flow parser level. Consequently, the other kind of quote can be used inside the string. The whole thing is inside the --definition argument to the shell, though, which uses double quotes. Consequently, double quotes are escaped (at the shell level)

Streams

This section goes into more detail about how you can create Streams, which are collections of Spring Cloud Stream applications. It covers topics such as creating and deploying Streams.

If you are just starting out with Spring Cloud Data Flow, you should probably read the Getting Started guide before diving into this section.

30. Introduction

A Stream is are a collection of long-lived Spring Cloud Stream applications that communicate with each other over messaging middleware. A text-based DSL defines the configuration and data flow between the applications. While many applications are provided for you to implement common use-cases, you typically create a custom Spring Cloud Stream application to implement custom business logic.

The general lifecycle of a Stream is:

  1. Register applications.

  2. Create a Stream Definition.

  3. Deploy the Stream.

  4. Undeploy or Destroy the Stream.

  5. Upgrade or Rollack applications in the Stream.

If you use Skipper, you can upgrade or rollback applications in the Stream.

There are two options for deploying streams:

  • Use a Data Flow Server implementation that deploys to a single platform.

  • Configure the Data Flow Server to delegate the deployment to a new server in the Spring Cloud ecosystem named Skipper.

When using the first option, you can use the Local Data Flow Server to deploy streams to your local machine, the Data Flow Server for Cloud Foundry to deploy streams to a single org and space on Cloud Foundry. Similarly, you can use Data Flow Server for Kuberenetes to deploy a stream to a single namespace on a Kubernetes cluster. See the Spring Cloud Data Flow project page for a list of Data Flow server implementations.

When using the second option, you can configure Skipper to deploy applications to one or more Cloud Foundry orgs and spaces, one or more namespaces on a Kubernetes cluster, or to the local machine. When deploying a stream in Data Flow using Skipper, you can specify which platform to use at deployment time. Skipper also provides Data Flow with the ability to perform updates to deployed streams. There are many ways the applications in a stream can be updated, but one of the most common examples is to upgrade a processor application with new custom business logic while leaving the existing source and sink applications alone.

30.1. Stream Pipeline DSL

A stream is defined by using a unix-inspired Pipeline syntax. The syntax uses vertical bars, also known as “pipes” to connect multiple commands. The command ls -l | grep key | less in Unix takes the output of the ls -l process and pipes it to the input of the grep key process. The output of grep in turn is sent to the input of the less process. Each | symbol connects the standard output of the command on the left to the standard input of the command on the right. Data flows through the pipeline from left to right.

In Data Flow, the Unix command is replaced by a Spring Cloud Stream application and each pipe symbol represents connecting the input and output of applications over messaging middleware, such as RabbitMQ or Apache Kafka.

Each Spring Cloud Stream application is registered under a simple name. The registration process specifies where the application can be obtained (for example, in a Maven Repository or a Docker registry). You can find out more information on how to register Spring Cloud Stream applications in this section. In Data Flow, we classify the Spring Cloud Stream applications as Sources, Processors, or Sinks.

As a simple example, consider the collection of data from an HTTP Source writing to a File Sink. Using the DSL, the stream description is:

http | file

A stream that involves some processing would be expressed as:

http | filter | transform | file

Stream definitions can be created by using the shell’s stream create command, as shown in the following example:

dataflow:> stream create --name httpIngest --definition "http | file"

The Stream DSL is passed in to the --definition command option.

The deployment of stream definitions is done through the shell’s stream deploy command.

dataflow:> stream deploy --name ticktock

The Getting Started section shows you how to start the server and how to start and use the Spring Cloud Data Flow shell.

Note that the shell calls the Data Flow Servers' REST API. For more information on making HTTP requests directly to the server, consult the REST API Guide.

30.2. Application properties

Each application takes properties to customize its behavior. As an example, the http source module exposes a port setting that allows the data ingestion port to be changed from the default value.

dataflow:> stream create --definition "http --port=8090 | log" --name myhttpstream

This port property is actually the same as the standard Spring Boot server.port property. Data Flow adds the ability to use the shorthand form port instead of server.port. One may also specify the longhand version as well, as shown in the following example:

dataflow:> stream create --definition "http --server.port=8000 | log" --name myhttpstream

This shorthand behavior is discussed more in the section on Whitelisting application properties. If you have registered application property metadata you can use tab completion in the shell after typing -- to get a list of candidate property names.

The shell provides tab completion for application properties. The shell command app info <appType>:<appName> provides additional documentation for all the supported properties.

Supported Stream <appType> possibilities are: source, processor, and sink.

31. Stream Lifecycle

The lifecycle of a stream, in "classic" mode, goes through the following stages:

31.1. Register a Stream App

You can register a Stream App with the App Registry by using the Spring Cloud Data Flow Shell app register command. You must provide a unique name, an application type, and a URI that can be resolved to the app artifact. For the type, specify source, processor, or sink. Here are a few examples:

dataflow:>app register --name mysource --type source --uri maven://com.example:mysource:0.0.1-SNAPSHOT

dataflow:>app register --name myprocessor --type processor --uri file:///Users/example/myprocessor-1.2.3.jar

dataflow:>app register --name mysink --type sink --uri http://example.com/mysink-2.0.1.jar

When providing a URI with the maven scheme, the format should conform to the following:

maven://<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>

For example, if you would like to register the snapshot versions of the http and log applications built with the RabbitMQ binder, you could do the following:

dataflow:>app register --name http --type source --uri maven://org.springframework.cloud.stream.app:http-source-rabbit:1.2.1.BUILD-SNAPSHOT
dataflow:>app register --name log --type sink --uri maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.2.1.BUILD-SNAPSHOT

If you would like to register multiple apps at one time, you can store them in a properties file where the keys are formatted as <type>.<name> and the values are the URIs.

For example, if you would like to register the snapshot versions of the http and log applications built with the RabbitMQ binder, you could have the following in a properties file (for example, stream-apps.properties):

source.http=maven://org.springframework.cloud.stream.app:http-source-rabbit:1.2.1.BUILD-SNAPSHOT
sink.log=maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.2.1.BUILD-SNAPSHOT

Then to import the apps in bulk, use the app import command and provide the location of the properties file with the --uri switch, as follows:

dataflow:>app import --uri file:///<YOUR_FILE_LOCATION>/stream-apps.properties

31.1.1. Register Supported Applications and Tasks

For convenience, we have the static files with application-URIs (for both maven and docker) available for all the out-of-the-box stream and task/batch app-starters. You can point to this file and import all the application-URIs in bulk. Otherwise, as explained previously, you can register them individually or have your own custom property file with only the required application-URIs in it. It is recommended, however, to have a “focused” list of desired application-URIs in a custom property file.

The following table lists the bit.ly links to the available Stream Application Starters:

Artifact Type Stable Release SNAPSHOT Release

RabbitMQ + Maven

bit.ly/Celsius-SR2-stream-applications-rabbit-maven

bit.ly/Celsius-BUILD-SNAPSHOT-stream-applications-rabbit-maven

RabbitMQ + Docker

bit.ly/Celsius-SR2-stream-applications-rabbit-docker

bit.ly/Celsius-BUILD-SNAPSHOT-stream-applications-rabbit-docker

Kafka 0.10 + Maven

bit.ly/Celsius-SR2-stream-applications-kafka-10-maven

bit.ly/Celsius-BUILD-SNAPSHOT-stream-applications-kafka-10-maven

Kafka 0.10 + Docker

bit.ly/Celsius-SR2-stream-applications-kafka-10-docker

bit.ly/Celsius-BUILD-SNAPSHOT-stream-applications-kafka-10-docker

The following table lists the available Task Application Starters:

Artifact Type Stable Release SNAPSHOT Release

Maven

bit.ly/Clark-GA-task-applications-maven

bit.ly/Clark-BUILD-SNAPSHOT-task-applications-maven

Docker

bit.ly/Clark-GA-task-applications-docker

bit.ly/Clark-BUILD-SNAPSHOT-task-applications-docker

You can find more information about the available task starters in the Task App Starters Project Page and related reference documentation. For more information about the available stream starters, look at the Stream App Starters Project Page and related reference documentation.

As an example, if you would like to register all out-of-the-box stream applications built with the Kafka binder in bulk, you can use the following command:

$ dataflow:>app import --uri http://bit.ly/Celsius-SR2-stream-applications-kafka-10-maven

Alternatively you can register all the stream applications with the Rabbit binder, as follows:

$ dataflow:>app import --uri http://bit.ly/Celsius-SR2-stream-applications-rabbit-maven

You can also pass the --local option (which is true by default) to indicate whether the properties file location should be resolved within the shell process itself. If the location should be resolved from the Data Flow Server process, specify --local false.

When using either app register or app import, if an app is already registered with the provided name and type, it is not overridden by default. If you would like to override the pre-existing app coordinates, then include the --force option.

Note, however, that, once downloaded, applications may be cached locally on the Data Flow server, based on the resource location. If the resource location does not change (even though the actual resource bytes may be different), then it is not re-downloaded. When using maven:// resources on the other hand, using a constant location may still circumvent caching (if using -SNAPSHOT versions).

Moreover, if a stream is already deployed and using some version of a registered app, then (forcibly) re-registering a different app has no effect until the stream is deployed again.

In some cases, the Resource is resolved on the server side. In others, the URI is passed to a runtime container instance where it is resolved. Consult the specific documentation of each Data Flow Server for more detail.

31.1.2. Whitelisting application properties

Stream and Task applications are Spring Boot applications that are aware of many Common Application Properties, such as server.port but also families of properties such as those with the prefix spring.jmx and logging. When creating your own application, you should whitelist properties so that the shell and the UI can display them first as primary properties when presenting options through TAB completion or in drop-down boxes.

To whitelist application properties, create a file named spring-configuration-metadata-whitelist.properties in the META-INF resource directory. There are two property keys that can be used inside this file. The first key is named configuration-properties.classes. The value is a comma separated list of fully qualified @ConfigurationProperty class names. The second key is configuration-properties.names, whose value is a comma-separated list of property names. This can contain the full name of the property, such as server.port, or a partial name to whitelist a category of property names, such as spring.jmx.

The Spring Cloud Stream application starters are a good place to look for examples of usage. The following example comes from the file sink’s spring-configuration-metadata-whitelist.properties file:

configuration-properties.classes=org.springframework.cloud.stream.app.file.sink.FileSinkProperties

If we also want to add server.port to be white listed, it would become the following line:

configuration-properties.classes=org.springframework.cloud.stream.app.file.sink.FileSinkProperties
configuration-properties.names=server.port

Make sure to add 'spring-boot-configuration-processor' as an optional dependency to generate configuration metadata file for the properties.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

31.1.3. Creating and Using a Dedicated Metadata Artifact

You can go a step further in the process of describing the main properties that your stream or task app supports by creating a metadata companion artifact. This jar file contains only the Spring boot JSON file about configuration properties metadata and the whitelisting file described in the previous section.

The following example shows the contents of such an artifact, for the canonical log sink:

$ jar tvf log-sink-rabbit-1.2.1.BUILD-SNAPSHOT-metadata.jar
373848 META-INF/spring-configuration-metadata.json
   174 META-INF/spring-configuration-metadata-whitelist.properties

Note that the spring-configuration-metadata.json file is quite large. This is because it contains the concatenation of all the properties that are available at runtime to the log sink (some of them come from spring-boot-actuator.jar, some of them come from spring-boot-autoconfigure.jar, some more from spring-cloud-starter-stream-sink-log.jar, and so on). Data Flow always relies on all those properties, even when a companion artifact is not available, but here all have been merged into a single file.

To help with that (you do not want to try to craft this giant JSON file by hand), you can use the following plugin in your build:

<plugin>
 	<groupId>org.springframework.cloud</groupId>
 	<artifactId>spring-cloud-app-starter-metadata-maven-plugin</artifactId>
 	<executions>
 		<execution>
 			<id>aggregate-metadata</id>
 			<phase>compile</phase>
 			<goals>
 				<goal>aggregate-metadata</goal>
 			</goals>
 		</execution>
 	</executions>
 </plugin>
This plugin comes in addition to the spring-boot-configuration-processor that creates the individual JSON files. Be sure to configure both.

The benefits of a companion artifact include:

  • Being much lighter. (The companion artifact is usually a few kilobytes, as opposed to megabytes for the actual app.) Consequently, they are quicker to download, allowing quicker feedback when using, for example, app info or the Dashboard UI.

  • As a consequence of being lighter, they can be used in resource constrained environments (such as PaaS) when metadata is the only piece of information needed.

  • For environments that do not deal with Spring Boot uber jars directly (for example, Docker-based runtimes such as Kubernetes or Mesos), this is the only way to provide metadata about the properties supported by the app.

Remember, though, that this is entirely optional when dealing with uber jars. The uber jar itself also includes the metadata in it already.

31.1.4. Using the Companion Artifact

Once you have a companion artifact at hand, you need to make the system aware of it so that it can be used.

When registering a single app with app register, you can use the optional --metadata-uri option in the shell, as follows:

dataflow:>app register --name log --type sink
    --uri maven://org.springframework.cloud.stream.app:log-sink-kafka-10:1.2.1.BUILD-SNAPSHOT
    --metadata-uri=maven://org.springframework.cloud.stream.app:log-sink-kafka-10:jar:metadata:1.2.1.BUILD-SNAPSHOT

When registering several files by using the app import command, the file should contain a <type>.<name>.metadata line in addition to each <type>.<name> line. Strictly speaking, doing so is optional (if some apps have it but some others do not, it works), but it is best practice.

The following example shows a Dockerized app, where the metadata artifact is being hosted in a Maven repository (retrieving it through http:// or file:// would be equally possible).

...
source.http=docker:springcloudstream/http-source-rabbit:latest
source.http.metadata=maven://org.springframework.cloud.stream.app:http-source-rabbit:jar:metadata:1.2.1.BUILD-SNAPSHOT
...

31.1.5. Creating Custom Applications

While there are out-of-the-box source, processor, sink applications available, you can extend these applications or write a custom Spring Cloud Stream application.

The process of creating Spring Cloud Stream applications with Spring Initializr is detailed in the Spring Cloud Stream documentation. It is possible to include multiple binders to an application. If doing so, see the instructions in Passing Spring Cloud Stream properties for how to configure them.

For supporting property whitelisting, Spring Cloud Stream applications running in Spring Cloud Data Flow may include the Spring Boot configuration-processor as an optional dependency, as shown in the following example:

<dependencies>
  <!-- other dependencies -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
  </dependency>
</dependencies>

Make sure that the spring-boot-maven-plugin is included in the POM. The plugin is necessary for creating the executable jar that is registered with Spring Cloud Data Flow. Spring Initialzr includes the plugin in the generated POM.

Once a custom application has been created, it can be registered as described in Register a Stream App.

31.2. Creating a Stream

The Spring Cloud Data Flow Server exposes a full RESTful API for managing the lifecycle of stream definitions, but the easiest way to use is it is through the Spring Cloud Data Flow shell. Start the shell as described in the Getting Started section.

New streams are created with the help of stream definitions. The definitions are built from a simple DSL. For example, consider what happens if we execute the following shell command:

dataflow:> stream create --definition "time | log" --name ticktock

This defines a stream named ticktock that is based off the DSL expression time | log. The DSL uses the "pipe" symbol (|), to connect a source to a sink.

31.2.1. Application Properties

Application properties are the properties associated with each application in the stream. When the application is deployed, the application properties are applied to the application through command line arguments or environment variables, depending on the underlying deployment implementation.

The following stream can have application properties defined at the time of stream creation:

dataflow:> stream create --definition "time | log" --name ticktock

The shell command app info <appType>:<appName> displays the white-listed application properties for the application. For more info on the property white listing, refer to Whitelisting application properties

The following listing shows the white_listed properties for the time app:

dataflow:> app info source:time
╔══════════════════════════════╤══════════════════════════════╤══════════════════════════════╤══════════════════════════════╗
║         Option Name          │         Description          │           Default            │             Type             ║
╠══════════════════════════════╪══════════════════════════════╪══════════════════════════════╪══════════════════════════════╣
║trigger.time-unit             │The TimeUnit to apply to delay│<none>                        │java.util.concurrent.TimeUnit ║
║                              │values.                       │                              │                              ║
║trigger.fixed-delay           │Fixed delay for periodic      │1                             │java.lang.Integer             ║
║                              │triggers.                     │                              │                              ║
║trigger.cron                  │Cron expression value for the │<none>                        │java.lang.String              ║
║                              │Cron Trigger.                 │                              │                              ║
║trigger.initial-delay         │Initial delay for periodic    │0                             │java.lang.Integer             ║
║                              │triggers.                     │                              │                              ║
║trigger.max-messages          │Maximum messages per poll, -1 │1                             │java.lang.Long                ║
║                              │means infinity.               │                              │                              ║
║trigger.date-format           │Format for the date value.    │<none>                        │java.lang.String              ║
╚══════════════════════════════╧══════════════════════════════╧══════════════════════════════╧══════════════════════════════╝

The following listing shows the white-listed properties for the log app:

dataflow:> app info sink:log
╔══════════════════════════════╤══════════════════════════════╤══════════════════════════════╤══════════════════════════════╗
║         Option Name          │         Description          │           Default            │             Type             ║
╠══════════════════════════════╪══════════════════════════════╪══════════════════════════════╪══════════════════════════════╣
║log.name                      │The name of the logger to use.│<none>                        │java.lang.String              ║
║log.level                     │The level at which to log     │<none>                        │org.springframework.integratio║
║                              │messages.                     │                              │n.handler.LoggingHandler$Level║
║log.expression                │A SpEL expression (against the│payload                       │java.lang.String              ║
║                              │incoming message) to evaluate │                              │                              ║
║                              │as the logged message.        │                              │                              ║
╚══════════════════════════════╧══════════════════════════════╧══════════════════════════════╧══════════════════════════════╝

The application properties for the time and log apps can be specified at the time of stream creation as follows:

dataflow:> stream create --definition "time --fixed-delay=5 | log --level=WARN" --name ticktock

Note that, in the preceding example, the fixed-delay and level properties defined for the apps time and log are the "'short-form'" property names provided by the shell completion. These "'short-form'" property names are applicable only for the white-listed properties. In all other cases, only fully qualified property names should be used.

31.2.2. Common Application Properties

In addition to configuration through DSL, Spring Cloud Data Flow provides a mechanism for setting common properties to all the streaming applications that are launched by it. This can be done by adding properties prefixed with spring.cloud.dataflow.applicationProperties.stream when starting the server. When doing so, the server passes all the properties, without the prefix, to the instances it launches.

For example, all the launched applications can be configured to use a specific Kafka broker by launching the Data Flow server with the following options:

--spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.kafka.binder.brokers=192.168.1.100:9092
--spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.kafka.binder.zkNodes=192.168.1.100:2181

Doing so causes the properties spring.cloud.stream.kafka.binder.brokers and spring.cloud.stream.kafka.binder.zkNodes to be passed to all the launched applications.

Properties configured with this mechanism have lower precedence than stream deployment properties. They are overridden if a property with the same key is specified at stream deployment time (for example, app.http.spring.cloud.stream.kafka.binder.brokers overrides the common property).

31.3. Deploying a Stream

This section describes how to deploy a Stream when the Spring Cloud Data Flow server is responsible for deploying the stream. The following section, Stream Lifecycle with Skipper, covers the new deployment and upgrade features when the Spring Cloud Data Flow server delegates to Skipper for stream deployment. The description of how deployment properties applies to both approaches of Stream deployment.

Give the ticktock stream definition:

dataflow:> stream create --definition "time | log" --name ticktock

To deploy the stream, use the following shell command:

dataflow:> stream deploy --name ticktock

The Data Flow Server resolves time and log to maven coordinates and uses those to launch the time and log applications of the stream, as shown in the following listing:

2016-06-01 09:41:21.728  INFO 79016 --- [nio-9393-exec-6] o.s.c.d.spi.local.LocalAppDeployer       : deploying app ticktock.log instance 0
   Logs will be in /var/folders/wn/8jxm_tbd1vj28c8vj37n900m0000gn/T/spring-cloud-dataflow-912434582726479179/ticktock-1464788481708/ticktock.log
2016-06-01 09:41:21.914  INFO 79016 --- [nio-9393-exec-6] o.s.c.d.spi.local.LocalAppDeployer       : deploying app ticktock.time instance 0
   Logs will be in /var/folders/wn/8jxm_tbd1vj28c8vj37n900m0000gn/T/spring-cloud-dataflow-912434582726479179/ticktock-1464788481910/ticktock.time

In the preceding example, the time source sends the current time as a message each second, and the log sink outputs it by using the logging framework. You can tail the stdout log (which has an <instance> suffix). The log files are located within the directory displayed in the Data Flow Server’s log output, as shown in the following listing:

$ tail -f /var/folders/wn/8jxm_tbd1vj28c8vj37n900m0000gn/T/spring-cloud-dataflow-912434582726479179/ticktock-1464788481708/ticktock.log/stdout_0.log
2016-06-01 09:45:11.250  INFO 79194 --- [  kafka-binder-] log.sink    : 06/01/16 09:45:11
2016-06-01 09:45:12.250  INFO 79194 --- [  kafka-binder-] log.sink    : 06/01/16 09:45:12
2016-06-01 09:45:13.251  INFO 79194 --- [  kafka-binder-] log.sink    : 06/01/16 09:45:13

You can also create and deploy the stream in one step by passing the --deploy flag when creating the stream, as follows:

dataflow:> stream create --definition "time | log" --name ticktock --deploy

However, it is not very common in real-world use cases to create and deploy the stream in one step. The reason is that when you use the stream deploy command, you can pass in properties that define how to map the applications onto the platform (for example, what is the memory size of the container to use, the number of each application to run, and whether to enable data partitioning features). Properties can also override application properties that were set when creating the stream. The next sections cover this feature in detail.

31.3.1. Deployment Properties

When deploying a stream, you can specify properties that fall into two groups:

  • Properties that control how the apps are deployed to the target platform. These properties use a deployer prefix and are referred to as deployer properties.

  • Properties that set application properties or override application properties set during stream creation and are referred to as application properties.

The syntax for deployer properties is deployer.<app-name>.<short-property-name>=<value>, and the syntax for application properties app.<app-name>.<property-name>=<value>. This syntax is used when passing deployment properties through the shell. You may also specify them in a YAML file, which is discussed later in this chapter.

The following table shows the difference in behavior between setting deployer and application properties when deploying an application.

Application Properties Deployer Properties

Example Syntax

app.filter.expression=something

deployer.filter.count=3

What the application "sees"

expression=something or, if expression is one of the whitelisted properties, <some-prefix>.expression=something

Nothing

What the deployer "sees"

Nothing

spring.cloud.deployer.count=3. The spring.cloud.deployer prefix is automatically and always prepended to the property name.

Typical usage

Passing/Overriding application properties, passing Spring Cloud Stream binder or partitioning properties

Setting the number of instances, memory, disk, and others

Passing Instance Count

If you would like to have multiple instances of an application in the stream, you can include a deployer property called count with the deploy command:

dataflow:> stream deploy --name ticktock --properties "deployer.time.count=3"

Note that count is the reserved property name used by the underlying deployer. Consequently, if the application also has a custom property named count, it is not supported when specified in 'short-form' form during stream deployment as it could conflict with the instance count deployer property. Instead, the count as a custom application property can be specified in its fully qualified form (for example, app.something.somethingelse.count) during stream deployment or it can be specified by using the 'short-form' or the fully qualified form during the stream creation, where it is processed as an app property.

Inline Versus File-based Properties

When using the Spring Cloud Data Flow Shell, there are two ways to provide deployment properties: either inline or through a file reference. Those two ways are exclusive.

Inline properties use the --properties shell option and list properties as a comma separated list of key=value pairs, as shown in the following example:

stream deploy foo
    --properties "deployer.transform.count=2,app.transform.producer.partitionKeyExpression=payload"

File references use the --propertiesFile option and point it to a local .properties, .yaml or .yml file (that is, a file that resides in the filesystem of the machine running the shell). Being read as a .properties file, normal rules apply (ISO 8859-1 encoding, =, <space> or : delimiter, and others), although we recommend using = as a key-value pair delimiter, for consistency. The following example shows a stream deploy command that uses the --propertiesFile option:

stream deploy something --propertiesFile myprops.properties

Assume that myprops.properties contains the following properties:

deployer.transform.count=2
app.transform.producer.partitionKeyExpression=payload

Both of the properties are passed as deployment properties for the something stream.

If you use YAML as the format for the deployment properties, use the .yaml or .yml file extention when deploying the stream, as shown in the following example:

stream deploy foo --propertiesFile myprops.yaml

In that case, the myprops.yaml file might contain the following content:

deployer:
  transform:
    count: 2
app:
  transform:
    producer:
      partitionKeyExpression: payload
Passing application properties

The application properties can also be specified when deploying a stream. When specified during deployment, these application properties can either be specified as 'short-form' property names (applicable for white-listed properties) or as fully qualified property names. The application properties should have the prefix app.<appName/label>.

For example, consider the following stream command:

dataflow:> stream create --definition "time | log" --name ticktock

The stream in the precedig example can also be deployed with application properties by using the 'short-form' property names, as shown in the following example:

dataflow:>stream deploy ticktock --properties "app.time.fixed-delay=5,app.log.level=ERROR"

Consider the following example:

stream create ticktock --definition "a: time | b: log"

When using the app label, the application properties can be defined as follows:

stream deploy ticktock --properties "app.a.fixed-delay=4,app.b.level=ERROR"
Passing Spring Cloud Stream properties

Spring Cloud Data Flow sets the required Spring Cloud Stream properties for the applications inside the stream. Most importantly, the spring.cloud.stream.bindings.<input/output>.destination is set internally for the apps to bind.

If you want to override any of the Spring Cloud Stream properties, they can be set with deployment properties.

For example, consider the following stream definition:

dataflow:> stream create --definition "http | transform --expression=payload.getValue('hello').toUpperCase() | log" --name ticktock

If there are multiple binders available in the classpath for each of the applications and the binder is chosen for each deployment, then the stream can be deployed with the specific Spring Cloud Stream properties, as follows:

dataflow:>stream deploy ticktock --properties "app.time.spring.cloud.stream.bindings.output.binder=kafka,app.transform.spring.cloud.stream.bindings.input.binder=kafka,app.transform.spring.cloud.stream.bindings.output.binder=rabbit,app.log.spring.cloud.stream.bindings.input.binder=rabbit"
Overriding the destination names is not recommended, because Spring Cloud Data Flow internally takes care of setting this property.
Passing Per-binding Producer and Consumer Properties

A Spring Cloud Stream application can have producer and consumer properties set on a per-binding basis. While Spring Cloud Data Flow supports specifying short-hand notation for per-binding producer properties such as partitionKeyExpression and partitionKeyExtractorClass (as described in Passing Stream Partition Properties), all the supported Spring Cloud Stream producer/consumer properties can be set as Spring Cloud Stream properties for the app directly as well.

The consumer properties can be set for the inbound channel name with the prefix app.[app/label name].spring.cloud.stream.bindings.<channelName>.consumer.. The producer properties can be set for the outbound channel name with the prefix app.[app/label name].spring.cloud.stream.bindings.<channelName>.producer.. Consider the following example:

dataflow:> stream create --definition "time | log" --name ticktock

The stream can be deployed with producer and consumer properties, as follows:

dataflow:>stream deploy ticktock --properties "app.time.spring.cloud.stream.bindings.output.producer.requiredGroups=myGroup,app.time.spring.cloud.stream.bindings.output.producer.headerMode=raw,app.log.spring.cloud.stream.bindings.input.consumer.concurrency=3,app.log.spring.cloud.stream.bindings.input.consumer.maxAttempts=5"

The binder-specific producer and consumer properties can also be specified in a similar way, as shown in the following example:

dataflow:>stream deploy ticktock --properties "app.time.spring.cloud.stream.rabbit.bindings.output.producer.autoBindDlq=true,app.log.spring.cloud.stream.rabbit.bindings.input.consumer.transacted=true"
Passing Stream Partition Properties

A common pattern in stream processing is to partition the data as it is streamed. This entails deploying multiple instances of a message-consuming app and using content-based routing so that messages with a given key (as determined at runtime) are always routed to the same app instance. You can pass the partition properties during stream deployment to declaratively configure a partitioning strategy to route each message to a specific consumer instance.

The following list shows variations of deploying partitioned streams:

  • app.[app/label name].producer.partitionKeyExtractorClass: The class name of a PartitionKeyExtractorStrategy (default: null)

  • app.[app/label name].producer.partitionKeyExpression: A SpEL expression, evaluated against the message, to determine the partition key. Only applies if partitionKeyExtractorClass is null. If both are null, the app is not partitioned (default: null)

  • app.[app/label name].producer.partitionSelectorClass: The class name of a PartitionSelectorStrategy (default: null)

  • app.[app/label name].producer.partitionSelectorExpression: A SpEL expression, evaluated against the partition key, to determine the partition index to which the message is routed. The final partition index is the return value (an integer) modulo [nextModule].count. If both the class and expression are null, the underlying binder’s default PartitionSelectorStrategy is applied to the key (default: null)

In summary, an app is partitioned if its count is > 1 and the previous app has a partitionKeyExtractorClass or partitionKeyExpression (partitionKeyExtractorClass takes precedence). When a partition key is extracted, the partitioned app instance is determined by invoking the partitionSelectorClass, if present, or the partitionSelectorExpression % partitionCount. partitionCount is application count, in the case of RabbitMQ, or the underlying partition count of the topic, in the case of Kafka.

If neither a partitionSelectorClass nor a partitionSelectorExpression is present, the result is key.hashCode() % partitionCount.

Passing application content type properties

In a stream definition, you can specify that the input or the output of an application must be converted to a different type. You can use the inputType and outputType properties to specify the content type for the incoming data and outgoing data, respectively.

For example, consider the following stream:

dataflow:>stream create tuple --definition "http | filter --inputType=application/x-spring-tuple
 --expression=payload.hasFieldName('hello') | transform --expression=payload.getValue('hello').toUpperCase()
 | log" --deploy

The http app is expected to send the data in JSON and the filter app receives the JSON data and processes it as a Spring Tuple. In order to do so, we use the inputType property on the filter app to convert the data into the expected Spring Tuple format. The transform application processes the Tuple data and sends the processed data to the downstream log application.

Consider the following example of sending some data to the http application:

dataflow:>http post --data {"hello":"world","something":"somethingelse"} --contentType application/json --target localhost:<http-port>;

At the log application, you see the content as follows:

INFO 18745 --- [transform.tuple-1] log.sink : WORLD

Depending on how applications are chained, the content type conversion can be specified either as an --outputType in the upstream app or as an --inputType in the downstream app. For instance, in the above stream, instead of specifying the --inputType on the 'transform' application to convert, the option --outputType=application/x-spring-tuple can also be specified on the 'http' application.

For the complete list of message conversion and message converters, please refer to Spring Cloud Stream documentation.

Overriding Application Properties During Stream Deployment

Application properties that are defined during deployment override the same properties defined during the stream creation.

For example, the following stream has application properties defined during stream creation:

dataflow:> stream create --definition "time --fixed-delay=5 | log --level=WARN" --name ticktock

To override these application properties, you can specify the new property values during deployment, as follows:

dataflow:>stream deploy ticktock --properties "app.time.fixed-delay=4,app.log.level=ERROR"

31.4. Destroying a Stream

You can delete a stream by issuing the stream destroy command from the shell, as follows:

dataflow:> stream destroy --name ticktock

If the stream was deployed, it is undeployed before the stream definition is deleted.

31.5. Undeploying a Stream

Often you want to stop a stream but retain the name and definition for future use. In that case, you can undeploy the stream by name.

dataflow:> stream undeploy --name ticktock
dataflow:> stream deploy --name ticktock

You can issue the deploy command at a later time to restart it.

dataflow:> stream deploy --name ticktock

32. Stream Lifecycle with Skipper

An additional lifecycle stage of Stream is available if you run in "skipper" mode.

  1. Upgrade or Rollback applications in the Stream. (Skipper mode)

Skipper is a server that you discover Spring Boot applications and manage their lifecycle on multiple Cloud Platforms.

Applications in Skipper are bundled as packages that contain the application’s resource location, application properties and deployment properites. You can think Skipper packages as analogous to packages found in tools such as apt-get or brew.

When Data Flow deploys a Stream, it will generate and upload a package to Skipper that represents the applications in the Stream. Subsequent commands to upgrade or rollback the applications within the Stream are passed through to Skipper. In addition, the Stream definition is reverse engineered from the package and the status of the Stream is also delegated to Skipper.

32.1. Register a Versioned Stream App

Skipper extends the Register a Stream App lifecycle with support of multi-versioned stream applications. This allows to upgrade or rollback those applications at runtime using the deployment properties.

Register a versioned stream application using the app register command. You must provide a unique name, application type, and a URI that can be resolved to the app artifact. For the type, specify "source", "processor", or "sink". The version is resolved from the URI. Here are a few examples:

dataflow:>app register --name mysource --type source --uri maven://com.example:mysource:0.0.1
dataflow:>app register --name mysource --type source --uri maven://com.example:mysource:0.0.2
dataflow:>app register --name mysource --type source --uri maven://com.example:mysource:0.0.3

dataflow:>app list --id source:mysource
╔══════════════════╤═════════╤════╤════╗
║     source       │processor│sink│task║
╠══════════════════╪═════════╪════╪════╣
║> mysource-0.0.1 <│         │    │    ║
║mysource-0.0.2    │         │    │    ║
║mysource-0.0.3    │         │    │    ║
╚══════════════════╧═════════╧════╧════╝

The application URI should conform to one the following schema formats:

  • maven schema

maven://<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>
  • http schema

http://<web-path>/<artifactName>-<version>.jar
  • file schema

file:///<local-path>/<artifactName>-<version>.jar
  • docker schema

docker:<docker-image-path>/<imageName>:<version>
The URI <version> part is compulsory for the versioned stream applications

Multiple versions can be registered for the same applications (e.g. same name and type) but only one can be set as default. The default version is used for deploying Streams.

The first time an application is registered it will be marked as default. The default application version can be altered with the app default command:

dataflow:>app default --id source:mysource --version 0.0.2
dataflow:>app list --id source:mysource
╔══════════════════╤═════════╤════╤════╗
║     source       │processor│sink│task║
╠══════════════════╪═════════╪════╪════╣
║mysource-0.0.1    │         │    │    ║
║> mysource-0.0.2 <│         │    │    ║
║mysource-0.0.3    │         │    │    ║
╚══════════════════╧═════════╧════╧════╝

The app list --id <type:name> command lists all versions for a given stream application.

The app unregister command has an optional --version parameter to specify the app version to unregister.

dataflow:>app unregister --name mysource --type source --version 0.0.1
dataflow:>app list --id source:mysource
╔══════════════════╤═════════╤════╤════╗
║     source       │processor│sink│task║
╠══════════════════╪═════════╪════╪════╣
║> mysource-0.0.2 <│         │    │    ║
║mysource-0.0.3    │         │    │    ║
╚══════════════════╧═════════╧════╧════╝

If a --version is not specified, the default version is unregistered.

All applications in a stream should have a default version set for the stream to be deployed. Otherwise they will be treated as unregistered application during the deployment. Use the app default to set the defaults.

app default --id source:mysource --version 0.0.3
dataflow:>app list --id source:mysource
╔══════════════════╤═════════╤════╤════╗
║     source       │processor│sink│task║
╠══════════════════╪═════════╪════╪════╣
║mysource-0.0.2    │         │    │    ║
║> mysource-0.0.3 <│         │    │    ║
╚══════════════════╧═════════╧════╧════╝

The stream deploy necessitates default app versions to be set. The stream update and stream rollback commands though can use all (default and non-default) registered app versions.

dataflow:>stream create foo --definition "mysource | log"

This will create stream using the default mysource version (0.0.3). Then we can update the version to 0.0.2 like this:

dataflow:>stream update foo --properties version.mysource=0.0.2

Only pre-registered applications can be used to deploy, update or rollback a Stream.

An attempt to update the mysource to version 0.0.1 (not registered) will fail!

32.2. Creating and Deploying a Stream

You create and deploy a stream by using Skipper in two steps:

  1. Creating the stream definition.

  2. Deploying the stream.

The following example shows the two steps in action:

dataflow:> stream create --name httptest --definition "http --server.port=9000 | log"
dataflow:> stream deploy --name httptest

The stream info command shows useful information about the stream, including the deployment properties, as shown (with its output) in the following example:

dataflow:>stream info httptest
╔══════════════════════════════╤══════════════════════════════╤════════════════════════════╗
║             Name             │             DSL              │          Status            ║
╠══════════════════════════════╪══════════════════════════════╪════════════════════════════╣
║httptest                      │http --server.port=9000 | log │deploying                   ║
╚══════════════════════════════╧══════════════════════════════╧════════════════════════════╝

Stream Deployment properties: {
  "log" : {
    "spring.cloud.deployer.indexed" : "true",
    "spring.cloud.deployer.group" : "httptest",
    "maven://org.springframework.cloud.stream.app:log-sink-rabbit" : "1.1.0.RELEASE"
  },
  "http" : {
    "spring.cloud.deployer.group" : "httptest",
    "maven://org.springframework.cloud.stream.app:http-source-rabbit" : "1.1.0.RELEASE"
  }
}

There is an important optional command argument (called --platformName) to the stream deploy command. Skipper can be configured to deploy to multiple platforms. Skipper is pre-configured with a platform named default, which deploys applications to the local machine where Skipper is running. The default value of the command line argument --platformName is default. If you commonly deploy to one platform, when installing Skipper, you can override the configuration of the default platform. Otherwise, specify the platformName to one of the values returned by the stream platform-list command.

32.3. Updating a Stream

To update the stream, use the command stream update which takes as a command argument either --properties or --propertiesFile. You can pass in values to these command arguments in the same format as when deploy the stream with or without Skipper. There is an important new top level prefix available when using Skipper, which is version. If the Stream http | log was deployed, and the version of log which registered at the time of deployment was 1.1.0.RELEASE, the following command will update the Stream to use the 1.2.0.RELEASE of the log application. Before updating the stream with the specific version of the app, we need to make sure that the app is registered with that version.

dataflow:>app register --name log --type sink --uri maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.2.0.RELEASE
Successfully registered application 'sink:log'
dataflow:>stream update --name httptest --properties version.log=1.2.0.RELEASE

Only pre-registered application versions can be used to deploy, update, or rollback a stream.

To verify the deployment properties and the updated version, we can use stream info, as shown (with its output) in the following example:

dataflow:>stream info httptest
╔══════════════════════════════╤══════════════════════════════╤════════════════════════════╗
║             Name             │             DSL              │          Status            ║
╠══════════════════════════════╪══════════════════════════════╪════════════════════════════╣
║httptest                      │http --server.port=9000 | log │deploying                   ║
╚══════════════════════════════╧══════════════════════════════╧════════════════════════════╝

Stream Deployment properties: {
  "log" : {
    "spring.cloud.deployer.indexed" : "true",
    "spring.cloud.deployer.count" : "1",
    "spring.cloud.deployer.group" : "httptest",
    "maven://org.springframework.cloud.stream.app:log-sink-rabbit" : "1.2.0.RELEASE"
  },
  "http" : {
    "spring.cloud.deployer.group" : "httptest",
    "maven://org.springframework.cloud.stream.app:http-source-rabbit" : "1.1.0.RELEASE"
  }
}

32.4. Stream versions

Skipper keeps a history of the streams that were deployed. After updating a Stream, there will be a second version of the stream. You can query for the history of the versions using the command stream history --name <name-of-stream>.

dataflow:>stream history --name httptest
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║2      │Mon Nov 27 22:41:16 EST 2017│DEPLOYED│httptest    │1.0.0          │Upgrade complete║
║1      │Mon Nov 27 22:40:41 EST 2017│DELETED │httptest    │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

32.5. Stream Manifests

Skipper keeps a “manifest” of the all the applications, their application properties, and their deployment properties after all values have been substituted. This represents the final state of what was deployed to the platform. You can view the manifest for any of the versions of a Stream by using the following command:

stream manifest --name <name-of-stream> --releaseVersion <optional-version>

If the --releaseVersion is not specified, the manifest for the last version is returned.

The following example shows the use of the manifest:

dataflow:>stream manifest --name httptest

Using the command results in the following output:

# Source: log.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: log
spec:
  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit
  version: 1.2.0.RELEASE
  applicationProperties:
    spring.metrics.export.triggers.application.includes: integration**
    spring.cloud.dataflow.stream.app.label: log
    spring.cloud.stream.metrics.key: httptest.log.${spring.cloud.application.guid}
    spring.cloud.stream.bindings.input.group: httptest
    spring.cloud.stream.metrics.properties: spring.application.name,spring.application.index,spring.cloud.application.*,spring.cloud.dataflow.*
    spring.cloud.dataflow.stream.name: httptest
    spring.cloud.dataflow.stream.app.type: sink
    spring.cloud.stream.bindings.input.destination: httptest.http
  deploymentProperties:
    spring.cloud.deployer.indexed: true
    spring.cloud.deployer.group: httptest
    spring.cloud.deployer.count: 1

---
# Source: http.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: http
spec:
  resource: maven://org.springframework.cloud.stream.app:http-source-rabbit
  version: 1.2.0.RELEASE
  applicationProperties:
    spring.metrics.export.triggers.application.includes: integration**
    spring.cloud.dataflow.stream.app.label: http
    spring.cloud.stream.metrics.key: httptest.http.${spring.cloud.application.guid}
    spring.cloud.stream.bindings.output.producer.requiredGroups: httptest
    spring.cloud.stream.metrics.properties: spring.application.name,spring.application.index,spring.cloud.application.*,spring.cloud.dataflow.*
    server.port: 9000
    spring.cloud.stream.bindings.output.destination: httptest.http
    spring.cloud.dataflow.stream.name: httptest
    spring.cloud.dataflow.stream.app.type: source
  deploymentProperties:
    spring.cloud.deployer.group: httptest

The majority of the deployment and application properties were set by Data Flow to enable the applications to talk to each other and to send application metrics with identifying labels.

32.6. Rollback a Stream

You can rollback to a previous version of the stream using the command stream rollback.

dataflow:>stream rollback --name httptest

The optional --releaseVersion command argument adds the version of the stream. If not specified, the rollback goes to the previous stream version.

32.7. Application Count

The application count is a dynamic property of the system. If, due to scaling at runtime, the application to be upgraded has 5 instances running, then 5 instances of the upgraded application are deployed.

32.8. Skipper’s Upgrade Strategy

Skipper has a simple 'red/black' upgrade strategy. It deploys the new version of the applications, using as many instances as the currently running version, and checks the /health endpoint of the application. If the health of the new application is good, then the previous application is undeployed. If the health of the new application is bad, then all new applications are undeployed and the upgrade is considered to be not successful.

The upgrade strategy is not a rolling upgrade, so if five applications of the application are running, then in a sunny-day scenario, five of the new applications are also running before the older version is undeployed.

33. Stream DSL

This section covers additional features of the Stream DSL not covered in the Stream DSL introduction.

33.1. Tap a Stream

Taps can be created at various producer endpoints in a stream. For a stream such as that defined in the following example, taps can be created at the output of http, step1 and step2:

stream create --definition "http | step1: transform --expression=payload.toUpperCase() | step2: transform --expression=payload+'!' | log" --name mainstream --deploy

To create a stream that acts as a 'tap' on another stream requires specifying the source destination name for the tap stream. The syntax for the source destination name is as follows:

:<streamName>.<label/appName>

To create a tap at the output of http in the preceding stream, the source destination name is mainstream.http To create a tap at the output of the first transform app in the stream above, the source destination name is mainstream.step1

The tap stream DSL resembles the following:

stream create --definition ":mainstream.http > counter" --name tap_at_http --deploy

stream create --definition ":mainstream.step1 > jdbc" --name tap_at_step1_transformer --deploy

Note the colon (:) prefix before the destination names. The colon lets the parser recognize this as a destination name instead of an app name.

33.2. Using Labels in a Stream

When a stream is made up of multiple apps with the same name, they must be qualified with labels: stream create --definition "http | firstLabel: transform --expression=payload.toUpperCase() | secondLabel: transform --expression=payload+'!' | log" --name myStreamWithLabels --deploy

33.3. Named Destinations

Instead of referencing a source or sink application, you can use a named destination. A named destination corresponds to a specific destination name in the middleware broker (Rabbit, Kafka, and others). When using the | symbol, applications are connected to each other with messaging middleware destination names created by the Data Flow server. In keeping with the Unix analogy, one can redirect standard input and output using the less-than (<) and greater-than (>) characters. To specify the name of the destination, prefix it with a colon (:). For example, the following stream has the destination name in the source position:

dataflow:>stream create --definition ":myDestination > log" --name ingest_from_broker --deploy

This stream receives messages from the destination called myDestination, located at the broker, and connects it to the log app. You can also create additional streams that consume data from the same named destination.

The following stream has the destination name in the sink position:

dataflow:>stream create --definition "http > :myDestination" --name ingest_to_broker --deploy

It is also possible to connect two different destinations (source and sink positions) at the broker in a stream, as shown in the following example:

dataflow:>stream create --definition ":destination1 > :destination2" --name bridge_destinations --deploy

In the precding stream, both the destinations (destination1 and destination2) are located in the broker. The messages flow from the source destination to the sink destination over a bridge app that connects them.

33.4. Fan-in and Fan-out

By using named destinations, you can support fan-in and fan-out use cases. Fan-in use cases are when multiple sources all send data to the same named destination, as shown in the following example:

s3 > :data
ftp > :data
http > :data

The preceding example directs the data payloads from the Amazon S3, FTP, and HTTP sources to the same named destination called data. Then an additional stream created with the following DSL expression would have all the data from those three sources sent to the file sink:

:data > file

The fan-out use case is when you determine the destination of a stream based on some information that is only known at runtime. In this case, the Router Application can be used to specify how to direct the incoming message to one of N named destinations.

A nice Video showing Fan-in and Fan-out behavior is also available.

34. Stream Java DSL

Instead of using the shell to create and deploy streams, you can use the Java-based DSL provided by the spring-cloud-dataflow-rest-client module. The Java DSL is a convenient wrapper around the DataFlowTemplate class that enables creating and deploying streams programmatically.

To get started, you need to add the following dependency to your project, as follows:

<dependency>
	<groupId>org.springframework.cloud</groupId>
	<artifactId>spring-cloud-dataflow-rest-client</artifactId>
	<version>1.5.1.RELEASE</version>
</dependency>
A complete sample can be found in the Spring Cloud Data Flow Samples Repository.

34.1. Overview

The classes at the heart of the Java DSL are StreamBuilder, StreamDefinition, Stream, StreamApplication, and DataFlowTemplate. The entry point is a builder method on Stream that takes an instance of a DataFlowTemplate. To create an instance of a DataFlowTemplate, you need to provide a URI location of the Data Flow Server.

Spring Boot auto-configuration for StreamBuilder and DataFlowTemplate is also available. The properties in DataFlowClientProperties can be used to configure the connection to the Data Flow server. The common property to start using is spring.cloud.dataflow.client.uri

Consider the following example, using the definition style.

URI dataFlowUri = URI.create("http://localhost:9393");
DataFlowOperations dataFlowOperations = new DataFlowTemplate(dataFlowUri);
dataFlowOperations.appRegistryOperations().importFromResource(
                     "http://bit.ly/Celsius-RC1-stream-applications-rabbit-maven", true);
StreamDefinition streamDefinition = Stream.builder(dataFlowOperations)
                                      .name("ticktock")
                                      .definition("time | log")
                                      .create();

The create method returns an instance of a StreamDefinition representing a Stream that has been created but not deployed. This is called the definition style since it takes a single string for the stream definition, same as in the shell. If applications have not yet been registered in the Data Flow server, you can use the DataFlowOperations class to register them. With the StreamDefinition instance, you have methods available to deploy or destory the stream.

Stream stream = streamDefinition.deploy();

The Stream instance provides getStatus, destroy and undeploy methods to control and query the stream. If you are going to immediately deploy the stream, there is no need to create a separate local variable of the type StreamDefinition. You can just chain the calls together, as follows:

Stream stream = Stream.builder(dataFlowOperations)
                  .name("ticktock")
                  .definition("time | log")
                  .create()
                  .deploy();

The deploy method is overloaded to take a java.util.Map of deployment properties.

The StreamApplication class is used in the 'fluent' Java DSL style and is discussed in the next section. The StreamBuilder class is returned from the method Stream.builder(dataFlowOperations). In larger applications, it is common to create a single instance of the StreamBuilder as a Spring @Bean and share it across the application.

34.2. Java DSL styles

The Java DSL offers two styles to create Streams.

  • The definition style keeps the feel of using the pipes and filters textual DSL in the shell. This style is selected by using the definition method after setting the stream name - for example, Stream.builder(dataFlowOperations).name("ticktock").definition(<definition goes here>).

  • The fluent style lets you chain together sources, processors, and sinks by passing in an instance of a StreamApplication. This style is selected by using the source method after setting the stream name - for example, Stream.builder(dataFlowOperations).name("ticktock").source(<stream application instance goes here>). You then chain together processor() and sink() methods to create a stream definition.

To demonstrate both styles, we include a simple stream that uses both approaches. A complete sample for you to get started can be found in the Spring Cloud Data Flow Samples Repository.

The following example demonstrates the definition approach:

public void definitionStyle() throws Exception{

  DataFlowOperations dataFlowOperations = createDataFlowOperations();
  Map<String, String> deploymentProperties = createDeploymentProperties();

  Stream woodchuck = Stream.builder(dataFlowOperations)
          .name("woodchuck")
          .definition("http --server.port=9900 | splitter --expression=payload.split(' ') | log")
          .create()
          .deploy(deploymentProperties);

  waitAndDestroy(woodchuck)
}

The following example demonstrates the fluent approach:

public void fluentStyle() throws Exception {

  DataFlowOperations dataFlowOperations = createDataFlowOperations();

  StreamApplication source = new StreamApplication("http").addProperty("server.port", 9900);

  StreamApplication processor = new StreamApplication("splitter")
                                 .addProperty("producer.partitionKeyExpression", "payload");

  StreamApplication sink = new StreamApplication("log")
                            .addDeploymentProperty("count", 2);

  Stream woodchuck = Stream.builder(dataFlowOperations).name("woodchuck")
          .source(source)
          .processor(processor)
          .sink(sink)
          .create()
          .deploy(deploymentProperties);

  waitAndDestroy(woodchuck)

}

The waitAndDestroy method uses the getStatus method to poll for the stream’s status, as shown in the following example:

private void waitAndDestroy(Stream stream) throws InterruptedException {

  while(!stream.getStatus().equals("deployed")){
    System.out.println("Wating for deployment of stream.");
    Thread.sleep(5000);
  }

  System.out.println("Letting the stream run for 2 minutes.");
  // Let the stream run for 2 minutes
  Thread.sleep(120000);

  System.out.println("Destroying stream");
  stream.destroy();
}

When using the definition style, the deployment properties are specified as a java.util.Map in the same manner as using the shell. The createDeploymentProperties method is defined as follows:

private Map<String, String> createDeploymentProperties() {
  Map<String, String> deploymentProperties = new HashMap<>();
  deploymentProperties.put("app.splitter.producer.partitionKeyExpression", "payload");
  deploymentProperties.put("deployer.log.memory","512");
  deploymentProperties.put("deployer.log.count", "2");
  return deploymentProperties;
}

Is this case, application properties are also overridden at deployment time in addition to setting the deployer property count for the log application. When using the fluent style, the deployment properties are added by using the method addDeploymentProperty (for example, new StreamApplication("log").addDeploymentProperty("count", 2)), and you do not need to prefix the property with deployer.<app_name>.

In order to create and deploy your streams, you need to make sure that the corresponding apps have been registered in the DataFlow server first. Attempting to create or deploy a stream that contains an unknown app throws an exception. You can register your application by using the DataFlowTemplate, as follows:
dataFlowOperations.appRegistryOperations().importFromResource(
            "http://bit.ly/Celsius-RC1-stream-applications-rabbit-maven", true);

The Stream applications can also be beans within your application that are injected in other classes to create Streams. There are many ways to structure Spring applications, but one way is to have an @Configuration class define the StreamBuilder and StreamApplications, as shown in the following example:

@Configuration
public StreamConfiguration {

  @Bean
  public StreamBuilder builder() {
    return Stream.builder(new DataFlowTemplate(URI.create("http://localhost:9393")));
  }

  @Bean
  public StreamApplication httpSource(){
    return new StreamApplication("http");
  }

  @Bean
  public StreamApplication logSink(){
    return new StreamApplication("log");
  }
}

Then in another class you can @Autowire these classes and deploy a stream.

@Component
public MyStreamApps {

  @Autowired
  private StreamBuilder streamBuilder;

  @Autowired
  private StreamApplication httpSource;

  @Autowired
  private StreamApplication logSink;


  public void deploySimpleStream() {
    Stream simpleStream = streamBuilder.name("simpleStream")
                            .source(httpSource);
                            .sink(logSink)
                            .create()
                            .deploy();
  }
}

This style lets you share StreamApplications across multiple Streams.

34.3. Using the DeploymentPropertiesBuilder

Regardless of style you choose, the deploy(Map<String, String> deploymentProperties) method allows customization of how your streams will be deployed. We made it a easier to create a map with properties by using a builder style, as well as creating static methods for some properties so you don’t need to remember the name of such properties. If you take the previous example of createDeploymentProperties it could be rewritten as:

private Map<String, String> createDeploymentProperties() {
	return new DeploymentPropertiesBuilder()
		.count("log", 2)
		.memory("log", 512)
		.put("app.splitter.producer.partitionKeyExpression", "payload")
		.build();
}

This utility class is meant to help with the creation of a Map and adds a few methods to assist with defining pre-defined properties.

35. Deploying using Skipper

If you desire to deploy your streams using Skipper, you need to pass certain properties to the server specific to a Skipper based deployment, for example selecting the target platfrom. The SkipperDeploymentPropertiesBuilder provides you all the properties in DeploymentPropertiesBuilder and adds those needed for Skipper.

private Map<String, String> createDeploymentProperties() {
	return new SkipperDeploymentPropertiesBuilder()
		.count("log", 2)
		.memory("log", 512)
		.put("app.splitter.producer.partitionKeyExpression", "payload")
		.platformName("pcf")
		.build();
}

36. Stream Applications with Multiple Binder Configurations

In some cases, a stream can have its applications bound to multiple spring cloud stream binders when they are required to connect to different messaging middleware configurations. In those cases, it is important to make sure the applications are configured appropriately with their binder configurations. For example, consider the following stream:

http | transform --expression=payload.toUpperCase() | log

In this stream, each application connects to messaging middleware in the following way:

  1. The HTTP source sends events to RabbitMQ (rabbit1).

  2. The Transform processor receives events from RabbitMQ (rabbit1) and sends the processed events into Kafka (kafka1).

  3. The log sink receives events from Kafka (kafka1).

Here, rabbit1 and kafka1 are the binder names given in the spring cloud stream application properties. Based on this setup, the applications have the following binder(s) in their classpath with the appropriate configuration:

  • HTTP: Rabbit binder

  • Transform: Both Kafka and Rabbit binders

  • Log: Kafka binder

The spring-cloud-stream binder configuration properties can be set within the applications themselves. If not, they can be passed through deployment properties when the stream is deployed as shown in the following example:

dataflow:>stream create --definition "http | transform --expression=payload.toUpperCase() | log" --name mystream

dataflow:>stream deploy mystream --properties "app.http.spring.cloud.stream.bindings.output.binder=rabbit1,app.transform.spring.cloud.stream.bindings.input.binder=rabbit1,
app.transform.spring.cloud.stream.bindings.output.binder=kafka1,app.log.spring.cloud.stream.bindings.input.binder=kafka1"

One can override any of the binder configuration properties by specifying them through deployment properties.

37. Examples

This chapter includes the following examples:

You can find links to more samples in the “Samples” chapter.

37.1. Simple Stream Processing

As an example of a simple processing step, we can transform the payload of the HTTP posted data to upper case by using the following stream definition: http | transform --expression=payload.toUpperCase() | log

To create this stream enter the following command in the shell dataflow:> stream create --definition "http | transform --expression=payload.toUpperCase() | log" --name mystream --deploy

The following example uses a shell command to post some data:

dataflow:> http post --target localhost:1234 --data "hello"

The preceding example results in an upper-case 'HELLO' in the log, as follows:

2016-06-01 09:54:37.749 INFO 80083 --- [ kafka-binder-] log.sink : HELLO

37.2. Stateful Stream Processing

To demonstrate the data partitioning functionality, the following listing deploys a stream with Kafka as the binder:

dataflow:>stream create --name words --definition "http --server.port=9900 | splitter --expression=payload.split(' ') | log"
Created new stream 'words'

dataflow:>stream deploy words --properties "app.splitter.producer.partitionKeyExpression=payload,deployer.log.count=2"
Deployed stream 'words'

dataflow:>http post --target http://localhost:9900 --data "How much wood would a woodchuck chuck if a woodchuck could chuck wood"
> POST (text/plain;Charset=UTF-8) http://localhost:9900 How much wood would a woodchuck chuck if a woodchuck could chuck wood
> 202 ACCEPTED

You should then see the following in the server logs:

2016-06-05 18:33:24.982  INFO 58039 --- [nio-9393-exec-9] o.s.c.d.spi.local.LocalAppDeployer       : deploying app words.log instance 0
   Logs will be in /var/folders/c3/ctx7_rns6x30tq7rb76wzqwr0000gp/T/spring-cloud-dataflow-694182453710731989/words-1465176804970/words.log
2016-06-05 18:33:24.988  INFO 58039 --- [nio-9393-exec-9] o.s.c.d.spi.local.LocalAppDeployer       : deploying app words.log instance 1
   Logs will be in /var/folders/c3/ctx7_rns6x30tq7rb76wzqwr0000gp/T/spring-cloud-dataflow-694182453710731989/words-1465176804970/words.log

When you review the words.log instance 0 logs, you should see the following:

2016-06-05 18:35:47.047  INFO 58638 --- [  kafka-binder-] log.sink                                 : How
2016-06-05 18:35:47.066  INFO 58638 --- [  kafka-binder-] log.sink                                 : chuck
2016-06-05 18:35:47.066  INFO 58638 --- [  kafka-binder-] log.sink                                 : chuck

When you review the words.log instance 1 logs, you shoul see the following:

2016-06-05 18:35:47.047  INFO 58639 --- [  kafka-binder-] log.sink                                 : much
2016-06-05 18:35:47.066  INFO 58639 --- [  kafka-binder-] log.sink                                 : wood
2016-06-05 18:35:47.066  INFO 58639 --- [  kafka-binder-] log.sink                                 : would
2016-06-05 18:35:47.066  INFO 58639 --- [  kafka-binder-] log.sink                                 : a
2016-06-05 18:35:47.066  INFO 58639 --- [  kafka-binder-] log.sink                                 : woodchuck
2016-06-05 18:35:47.067  INFO 58639 --- [  kafka-binder-] log.sink                                 : if
2016-06-05 18:35:47.067  INFO 58639 --- [  kafka-binder-] log.sink                                 : a
2016-06-05 18:35:47.067  INFO 58639 --- [  kafka-binder-] log.sink                                 : woodchuck
2016-06-05 18:35:47.067  INFO 58639 --- [  kafka-binder-] log.sink                                 : could
2016-06-05 18:35:47.067  INFO 58639 --- [  kafka-binder-] log.sink                                 : wood

This example has shown that payload splits that contain the same word are routed to the same application instance.

37.3. Other Source and Sink Application Types

This example shows something a bit more complicated: swapping out the time source for something else. Another supported source type is http, which accepts data for ingestion over HTTP POSTs. Note that the http source accepts data on a different port from the Data Flow Server (default 8080). By default, the port is randomly assigned.

To create a stream using an http source but still using the same log sink, we would change the original command in the Simple Stream Processing example to the following:

`dataflow:> stream create --definition "http | log" --name myhttpstream --deploy

The preceding command produces the following output from the server:

2016-06-01 09:47:58.920  INFO 79016 --- [io-9393-exec-10] o.s.c.d.spi.local.LocalAppDeployer       : deploying app myhttpstream.log instance 0
   Logs will be in /var/folders/wn/8jxm_tbd1vj28c8vj37n900m0000gn/T/spring-cloud-dataflow-912434582726479179/myhttpstream-1464788878747/myhttpstream.log
2016-06-01 09:48:06.396  INFO 79016 --- [io-9393-exec-10] o.s.c.d.spi.local.LocalAppDeployer       : deploying app myhttpstream.http instance 0
   Logs will be in /var/folders/wn/8jxm_tbd1vj28c8vj37n900m0000gn/T/spring-cloud-dataflow-912434582726479179/myhttpstream-1464788886383/myhttpstream.http

Note that we do not see any other output this time until we actually post some data (by using a shell command). In order to see the randomly assigned port on which the http source is listening, run the following command:

dataflow:> runtime apps

You should see that the corresponding http source has a url property containing the host and port information on which it is listening. You are now ready to post to that url, as shown in the following example:

dataflow:> http post --target http://localhost:1234 --data "hello"
dataflow:> http post --target http://localhost:1234 --data "goodbye"

The stream then funnels the data from the http source to the output log implemented by the log sink, yielding output similar to the following:

2016-06-01 09:50:22.121  INFO 79654 --- [  kafka-binder-] log.sink    : hello
2016-06-01 09:50:26.810  INFO 79654 --- [  kafka-binder-] log.sink    : goodbye

We could also change the sink implementation. You could pipe the output to a file (file), to hadoop (hdfs), or to any of the other sink applications that are available. You can also define your own applications.

Streams with Skipper

The Stream Lifecycle with Skipper section covers the overall role of Skipper in Spring Cloud Data Flow.

This section is a continuation of the getting started section on Deploying Streams and shows how Streams can be updated and rolled back by using the Local Data Flow server and Skipper. The “Getting started” chapter leaves off with the Stream httptest deployed. This chapter continues where the “Getting Started” chapter ended. The Stream consists of two applications, the http source and the log sink. If you execute the Unix jps command you can see the two java processes running, as shown in the following listing:

$ jps | grep rabbit
12643 log-sink-rabbit-1.1.0.RELEASE.jar
12645 http-source-rabbit-1.2.0.RELEASE.jar

38. Upgrading

Before we start upgrading the log-sink version to 1.2.0.RELEASE, we will have to register that version in the app registry.

dataflow:>app register --name log --type sink --uri maven://org.springframework.cloud.stream.app:log-sink-rabbit:1.2.0.RELEASE
Successfully registered application 'sink:log'

Since we are using the local server, we need to set the port to a different value (9001) than the currently running log sink’s value of 9000 to avoid a conflict. While we are at it, we update log level to be ERROR. To do so, we create a YAML file, named local-log-update.yml, with the following contents:

version:
  log: 1.2.0.RELEASE
app:
  log:
    server.port: 9002
    log.level: ERROR

Now we update the Stream, as follows:

dataflow:> stream update --name httptest --propertiesFile /home/mpollack/local-log-update.yml
Update request has been sent for the stream 'httptest'

By executing the Unix jps command, you can see the two java processes running, but now the log application is version 1.2.0.RELEASE, as shown in the following listing:

$ jps | grep rabbit
22034 http-source-rabbit-1.2.0.RELEASE.jar
22031 log-sink-rabbit-1.1.0.RELEASE.jar

Now you can look in the log file of the Skipper server. To do so, use the following command:

cd to the directory /tmp/spring-cloud-dataflow-5262910238261867964/httptest-1511749222274/httptest.log-v2 and tail -f stdout_0.log

You should see log entries similar to the following:

INFO 12591 --- [  StateUpdate-1] o.s.c.d.spi.local.LocalAppDeployer       : Deploying app with deploymentId httptest.log-v2 instance 0.
   Logs will be in /tmp/spring-cloud-dataflow-5262910238261867964/httptest-1511749222274/httptest.log-v2
INFO 12591 --- [  StateUpdate-1] o.s.c.s.s.d.strategies.HealthCheckStep   : Waiting for apps in release httptest-v2 to be healthy.
INFO 12591 --- [  StateUpdate-1] o.s.c.s.s.d.s.HandleHealthCheckStep      : Release httptest-v2 has been DEPLOYED
INFO 12591 --- [  StateUpdate-1] o.s.c.s.s.d.s.HandleHealthCheckStep      : Apps in release httptest-v2 are healthy.

Now you can post a message to the http source at port 9000, as follows:

dataflow:> http post --target http://localhost:9000 --data "hello world upgraded"

The log message is now at the error level, as shown in the following example:

ERROR 22311 --- [http.httptest-1] log-sink  : hello world upgraded

If you query the /info endpoint of the application, you can also see that it is at version 1.2.0.RELEASE, as shown in the following example:

$ curl http://localhost:9002/info
{"app":{"description":"Spring Cloud Stream Log Sink Rabbit Binder Application","name":"log-sink-rabbit","version":"1.2.0.RELEASE"}}

38.1. Stream History

The history of the stream can be viewed by running the stream history command, as shown (with its output), in the following example:

dataflow:>stream history --name httptest
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║2      │Mon Nov 27 22:41:16 EST 2017│DEPLOYED│httptest    │1.0.0          │Upgrade complete║
║1      │Mon Nov 27 22:40:41 EST 2017│DELETED │httptest    │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

38.2. Stream Manifest

The manifest is a YAML document that represents the final state of what was deployed to the platform. You can view the manifest for any stream version by using the stream manifest --name <name-of-stream> --releaseVersion <optional-version> command. If the --releaseVersion is not specified, the manifest for the last version is returned. The following listing shows a typical stream manifest command and its output:

dataflow:>stream manifest --name httptest

---
# Source: log.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: log
spec:
  resource: maven://org.springframework.cloud.stream.app:log-sink-rabbit
  version: 1.2.0.RELEASE
  applicationProperties:
    spring.metrics.export.triggers.application.includes: integration**
    spring.cloud.dataflow.stream.app.label: log
    spring.cloud.stream.metrics.key: httptest.log.${spring.cloud.application.guid}
    spring.cloud.stream.bindings.input.group: httptest
    spring.cloud.stream.metrics.properties: spring.application.name,spring.application.index,spring.cloud.application.*,spring.cloud.dataflow.*
    spring.cloud.dataflow.stream.name: httptest
    spring.cloud.dataflow.stream.app.type: sink
    spring.cloud.stream.bindings.input.destination: httptest.http
  deploymentProperties:
    spring.cloud.deployer.indexed: true
    spring.cloud.deployer.group: httptest
    spring.cloud.deployer.count: 1

---
# Source: http.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
  name: http
spec:
  resource: maven://org.springframework.cloud.stream.app:http-source-rabbit
  version: 1.2.0.RELEASE
  applicationProperties:
    spring.metrics.export.triggers.application.includes: integration**
    spring.cloud.dataflow.stream.app.label: http
    spring.cloud.stream.metrics.key: httptest.http.${spring.cloud.application.guid}
    spring.cloud.stream.bindings.output.producer.requiredGroups: httptest
    spring.cloud.stream.metrics.properties: spring.application.name,spring.application.index,spring.cloud.application.*,spring.cloud.dataflow.*
    server.port: 9000
    spring.cloud.stream.bindings.output.destination: httptest.http
    spring.cloud.dataflow.stream.name: httptest
    spring.cloud.dataflow.stream.app.type: source
  deploymentProperties:
    spring.cloud.deployer.group: httptest

The majority of the deployment and application properties were set by Data Flow in order to enable the applications to talk to each other and send application metrics with identifying labels.

If you compare this YAML document to the one for --releaseVersion=1 you will see the difference in the log application version.

39. Rolling back

To go back to the previous version of the stream, use the stream rollback command, as shown (with its output) in the following example:

dataflow:>stream rollback --name httptest
Rollback request has been sent for the stream 'httptest'

By executing the Unix jps command, you can see the two java processes running, but now the log application is back to 1.1.0.RELEASE. The http source process remains unchanged. The following listing shows the jps command and typical output:

$ jps | grep rabbit
22034 http-source-rabbit-1.2.0.RELEASE.jar
23939 log-sink-rabbit-1.1.0.RELEASE.jar

Now look in the log file for the skipper server, by using the following command:

cd to the directory /tmp/spring-cloud-dataflow-3784227772192239992/httptest-1511755751505/httptest.log-v3 and tail -f stdout_0.log

You should see log entries similar to the following:

INFO 21487 --- [  StateUpdate-2] o.s.c.d.spi.local.LocalAppDeployer       : Deploying app with deploymentId httptest.log-v3 instance 0.
   Logs will be in /tmp/spring-cloud-dataflow-3784227772192239992/httptest-1511755751505/httptest.log-v3
INFO 21487 --- [  StateUpdate-2] o.s.c.s.s.d.strategies.HealthCheckStep   : Waiting for apps in release httptest-v3 to be healthy.
INFO 21487 --- [  StateUpdate-2] o.s.c.s.s.d.s.HandleHealthCheckStep      : Release httptest-v3 has been DEPLOYED
INFO 21487 --- [  StateUpdate-2] o.s.c.s.s.d.s.HandleHealthCheckStep      : Apps in release httptest-v3 are healthy.

Now post a message to the http source at port 9000, as follows:

dataflow:> http post --target http://localhost:9000 --data "hello world upgraded"

The log message in the log sink is now back at the info error level, as shown in the following example:

INFO 23939 --- [http.httptest-1] log-sink  : hello world rollback

The history command now shows that the third version of the stream has been deployed, as shown (with its output) in the following listing:

dataflow:>stream history --name httptest
╔═══════╤════════════════════════════╤════════╤════════════╤═══════════════╤════════════════╗
║Version│        Last updated        │ Status │Package Name│Package Version│  Description   ║
╠═══════╪════════════════════════════╪════════╪════════════╪═══════════════╪════════════════╣
║3      │Mon Nov 27 23:01:13 EST 2017│DEPLOYED│httptest    │1.0.0          │Upgrade complete║
║2      │Mon Nov 27 22:41:16 EST 2017│DELETED │httptest    │1.0.0          │Delete complete ║
║1      │Mon Nov 27 22:40:41 EST 2017│DELETED │httptest    │1.0.0          │Delete complete ║
╚═══════╧════════════════════════════╧════════╧════════════╧═══════════════╧════════════════╝

If you look at the manifest for version 3, you can see that it shows version 1.1.0.RELEASE for the log sink.

Stream Developer Guide

This section covers how to create, test, and run Spring Cloud Stream applications on your local machine. It also shows how to map these applications into Spring Cloud Data Flow and deploy them.

40. Prebuilt Applications

The Spring Cloud Stream App Starters project provides many applications that you can start using right away. For example, there is an HTTP source application that receives messages posted to an HTTP endpoint and publishes the data to the messaging middleware. Each existing application comes in three variations, one for each type of messaging middleware that is supported. The current supported messaging middleware systems are RabbitMQ, Apache Kafka 0.9, and Apache Kafka 0.10. All the applications are based on Spring Boot and Spring Cloud Stream.

Applications are published as a Maven artifact as well as a Docker image. For GA releases, the Maven artifacts are published to Maven central and the Spring Release Repository. Milestone and snapshot releases are published to the Spring Milestone and Spring Snapshot repositories, respectively. Docker images are pushed to Docker Hub.

We use the Maven artifacts for our examples. The root location of the Spring Repository that hosts the GA artifacts of prebuilt applications is repo.spring.io/release/org/springframework/cloud/stream/app/

41. Running prebuilt applications

In this example, we use RabbitMQ as the messaging middleware. Follow the directions on rabbitmq.com for your platform. Then install the management plugin.

We will first run the HTTP source application and the log sink as stand alone applications using java -jar. The two applications use RabbitMQ to communicate.

Download each sample application, as follows:

wget https://repo.spring.io/libs-release/org/springframework/cloud/stream/app/http-source-rabbit/1.3.1.RELEASE//http-source-rabbit-1.3.1.RELEASE.jar

wget https://repo.spring.io/release/org/springframework/cloud/stream/app/log-sink-rabbit/1.3.1.RELEASE/log-sink-rabbit-1.3.1.RELEASE.jar

These are Spring Boot applications that include the Spring Boot Actuator and the Spring Security Starter. You can specify common Spring Boot properties to configure each application. The properties that are specific to each application are listed in the documentation for the Spring App Starters - for example, the HTTP source and the log sink

Now you can run the http source application. Just for fun, pass in a few Boot applications options using system properties, as shown in the following example:

java -Dserver.port=8123 -Dhttp.path-pattern=/data -Dspring.cloud.stream.bindings.output.destination=sensorData -jar http-source-rabbit-1.3.1.RELEASE.jar

The server.port property comes from Spring Boot’s Web support, and the http.path-pattern property comes from the HTTP source application, HttpSourceProperties. The HTTP source app is now listening on port 8123 under the the path /data.

The spring.cloud.stream.bindings.output.destination property comes from the Spring Cloud Stream library and is the name of the messaging destination that is shared between the source and the sink. The string sensorData in this property is the name of the Spring Integration channel whose contents will be published to the messaging middleware.

Now you can run the log sink application and change the logging level to WARN, as follows:

java -Dlog.level=WARN -Dspring.cloud.stream.bindings.input.destination=sensorData -jar log-sink-rabbit-1.3.1.RELEASE.jar

The log.level property comes from the log sink application, LogSinkProperties.

The value of the property spring.cloud.stream.bindings.input.destination is set to sensorData so that the source and sink applications can communicate with each other.

You can use the following curl command to send data to the http application:

curl -H "Content-Type: application/json" -X POST -d '{"id":"1","temperature":"100"}' http://localhost:8123/data

The log sink application then shows the following output:

2017-03-17 15:30:17.825  WARN 22710 --- [_qquaYekbQ0nA-1] log-sink                                 : {"id":"1","temperature":"100"}

42. Custom Processor Application

Now you can create and test an application that does some processing on the output of the HTTP source and then sends data to the log sink. You can then use the Processor convenience class, which has both an inbound channel and an outbound channel.

To do so:

  1. Visit the Spring Initialzr site.

    1. Create a new Maven project with a Group name of io.spring.stream.sample and an Artifact name of transformer.

    2. In the Dependencies text box, type stream to select the Spring Cloud Stream dependency.

    3. In the Dependencies text box, type either kafka or rabbit and select which middleware you want to use.

    4. Click the Generate Project button

  2. Unzip the project and bring the project into your favorite IDE.

  3. Create a class called Transformer in the io.spring.stream.sample package with the following contents:

    package io.spring.stream.sample.transformer;
    
    import org.springframework.cloud.stream.annotation.EnableBinding;
    import org.springframework.cloud.stream.annotation.Output;
    import org.springframework.cloud.stream.annotation.StreamListener;
    import org.springframework.cloud.stream.messaging.Processor;
    import org.springframework.messaging.handler.annotation.Payload;
    
    import java.util.HashMap;
    import java.util.Map;
    
    @EnableBinding(Processor.class)
    public class Transformer {
    
        @StreamListener(Processor.INPUT)
        @Output(Processor.OUTPUT)
        public Map<String, Object> transform(@Payload Map<String, Object> doc) {
            Map<String, Object> map = new HashMap<>();
            map.put("sensor_id", doc.getOrDefault("id", "-1"));
            map.put("temp_val", doc.getOrDefault("temperature", "-999"));
            return map;
        }
    }

    All that this processor is doing is changing the names of the keys in the map and providing a default value if one does not exist.

  4. Open the TransformerApplicationTests class (which already exists) and create a simple unit test for the Transformer class, as shown in the following example:

    package io.spring.stream.sample;
    
    
    import org.junit.Test;
    import org.junit.runner.RunWith;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.test.context.SpringBootTest;
    import org.springframework.test.context.junit4.SpringRunner;
    
    import java.util.HashMap;
    import java.util.Map;
    
    import static org.assertj.core.api.Assertions.assertThat;
    import static org.assertj.core.api.Assertions.entry;
    
    @RunWith(SpringRunner.class)
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
    public class TransformApplicationTests {
    
        @Autowired
        private Transformer transformer;
    
        @Test
        public void simpleTest() {
            Map<String, Object> resultMap = transformer.transform(createInputData());
            assertThat(resultMap).hasSize(2)
                    .contains(entry("sensor_id", "1"))
                    .contains(entry("temp_val", "100"));
        }
    
        private Map<String, Object> createInputData() {
            HashMap<String, Object> inputData = new HashMap<>();
            inputData.put("id", "1");
            inputData.put("temperature", "100");
            return inputData;
        }
    }

Executing ./mvnw clean package in the root directory of the transformer project generates the artifact transformer-0.0.1-SNAPSHOT.jar under the target directory.

Now you can run all three applications, as shown in the following listing:

java -Dserver.port=8123 \
     -Dhttp.path-pattern=/data \
     -Dspring.cloud.stream.bindings.output.destination=sensorData \
     -jar http-source-rabbit-1.3.1.RELEASE.jar

java -Dserver.port=8090 \
 -Dspring.cloud.stream.bindings.input.destination=sensorData \
 -Dspring.cloud.stream.bindings.output.destination=normalizedSensorData \
 -jar transformer-0.0.1-SNAPSHOT.jar

java -Dlog.level=WARN \
     -Dspring.cloud.stream.bindings.input.destination=normalizedSensorData \
     -jar log-sink-rabbit-1.3.1.RELEASE.jar

Now you can post some content to the http source application, as follows:

curl -H "Content-Type: application/json" -X POST -d '{"id":"2","temperature":"200"}' http://localhost:8123/data

The preceding curl command results in the log sink showing the following output:

2017-03-24 16:09:42.726  WARN 7839 --- [Raj4gYSoR_6YA-1] log-sink                                 : {sensor_id=2, temp_val=200}

43. Improving the Quality of Service

Without additional configuration, RabbitMQ applications that produce data create a durable topic exchange. Similarly, a RabbitMQ application that consumes data creates an anonymous auto-delete queue. This can result in a message not being stored and forwarded by the producer if the producer application started before the consumer application. Even though the exchange is durable, there needs to be a durable queue bound to the exchange for the message to be stored for later consumption.

To pre-create durable queues and bind them to the exchange, producer applications should set the spring.cloud.stream.bindings.<channelName>.producer.requiredGroups property. The requiredGroups property accepts a comma-separated list of groups to which the producer must ensure message delivery even if they start after it has been created. The consumer applications should then specify the spring.cloud.stream.bindings.<channelName>.group property to consume from the durable queue. The comma-separated list of groups for both properties should generally match. Consumer groups are also the means by which multiple instances of a consuming application can participate in a competing consumer relationship with other members of the same consumer group.

The following listing shows multiple applications sharing the same groups:

java -Dserver.port=8123 \
     -Dhttp.path-pattern=/data \
     -Dspring.cloud.stream.bindings.output.destination=sensorData \
     -Dspring.cloud.stream.bindings.output.producer.requiredGroups=sensorDataGroup \
     -jar http-source-rabbit-1.2.0.BUILD-SNAPSHOT.jar

java -Dserver.port=8090 \
     -Dspring.cloud.stream.bindings.input.destination=sensorData \
     -Dspring.cloud.stream.bindings.input.group=sensorDataGroup \
     -Dspring.cloud.stream.bindings.output.destination=normalizedSensorData \
     -Dspring.cloud.stream.bindings.output.producer.requiredGroups=normalizedSensorDataGroup \
     -jar transformer-0.0.1-SNAPSHOT.jar

java -Dlog.level=WARN \
     -Dspring.cloud.stream.bindings.input.destination=normalizedSensorData \
     -Dspring.cloud.stream.bindings.input.group=normalizedSensorDataGroup \
     -jar log-sink-rabbit-1.1.1.RELEASE.jar

As before, posting data to the http source results in the same log message in the sink.

44. Mapping Applications onto Data Flow

Spring Cloud Data Flow (SCDF) provides a higher level way to create this group of three Spring Cloud Stream applications by introducing the concept of a stream. A stream is defined by using Unix-like pipes and a filtering DSL. Each application is first registered with a simple name, such as http, transformer, and log (for the applications we are using in this example). The stream DSL to connect these three applications is http | transformer | log.

Spring Cloud Data Flow has server and shell components. Through the shell, you can easily register applications under a name and also create and deploy streams. You can also use the JavaDSL to perform the same actions. However, we use the shell for the examples in this chapter.

In the shell application, register the jar files you have on your local machine by using the following commands. In this example, the http and log applications are in the /home/mpollack/temp/dev directory and the transformer application is in the /home/mpollack/dev-marketing/transformer/target directory.

The following commands register the three applications:

dataflow:>app register --type source --name http --uri file://home/mpollack/temp/dev/http-source-rabbit-1.2.0.BUILD-SNAPSHOT.jar

dataflow:>app register --type processor --name transformer --uri file://home/mpollack/dev-marketing/transformer/target/transformer-0.0.1-SNAPSHOT.jar

dataflow:>app register --type sink --name log --uri file://home/mpollack/temp/dev/log-sink-rabbit-1.1.1.RELEASE.jar

Now you can create a stream definition and deploy it with the following command:

stream create --name httpIngest --definition "http --server.port=8123 --path-pattern=/data | transformer --server.port=8090 | log --level=WARN" --deploy

Then, in the shell, you can query for the list of streams, as shown (with output) in the following listing:

dataflow:>stream list
╔═══════════╤════════════════════════════════════════════════════════════════════════════════════════════════╤═════════╗
║Stream Name│                                       Stream Definition                                        │ Status  ║
╠═══════════╪════════════════════════════════════════════════════════════════════════════════════════════════╪═════════╣
║httpIngest │http --server.port=8123 --path-pattern=/data | transformer --server.port=8090 | log --level=WARN│Deploying║
╚═══════════╧════════════════════════════════════════════════════════════════════════════════════════════════╧═════════╝

Eventually, you can see the status column say Deployed.

In the server log, you can see output similar to the following:

2017-03-24 17:12:44.071  INFO 9829 --- [nio-9393-exec-6] o.s.c.d.spi.local.LocalAppDeployer       : deploying app httpIngest.log instance 0
   Logs will be in /tmp/spring-cloud-dataflow-4401025649434774446/httpIngest-1490389964038/httpIngest.log
2017-03-24 17:12:44.153  INFO 9829 --- [nio-9393-exec-6] o.s.c.d.spi.local.LocalAppDeployer       : deploying app httpIngest.transformer instance 0
   Logs will be in /tmp/spring-cloud-dataflow-4401025649434774446/httpIngest-1490389964143/httpIngest.transformer
2017-03-24 17:12:44.285  INFO 9829 --- [nio-9393-exec-6] o.s.c.d.spi.local.LocalAppDeployer       : deploying app httpIngest.http instance 0
   Logs will be in /tmp/spring-cloud-dataflow-4401025649434774446/httpIngest-1490389964264/httpIngest.http

You can go to each directory to see the logs of each application. In the RabbitMQ management console, you can see two exchanges and two durable queues.

The SCDF server has configured the input and output destinations, through the requiredGroups and group properties, for each application, as was done explicitly in the previous example.

Now you can post some content to the http source application, as follows:

curl -H "Content-Type: application/json" -X POST -d '{"id":"1","temperature":"100"}' http://localhost:8123/data

Using the tail command on the stdout_0.log file for the log sink then shows output similar to the following listing:

2017-03-24 17:29:55.280  WARN 11302 --- [er.httpIngest-1] log-sink                                 : {sensor_id=4, temp_val=400}

If you access the Boot actuator endpoint for the applications, you can see the conventions that SCDF has made for the destination names, the consumer groups, and the requiredGroups configuration properties, as shown in the following listing:

# for the http source
"spring.cloud.stream.bindings.output.producer.requiredGroups": "httpIngest",
"spring.cloud.stream.bindings.output.destination": "httpIngest.http",
"spring.cloud.application.group": "httpIngest",


# For the transformer
"spring.cloud.stream.bindings.input.group": "httpIngest",
"spring.cloud.stream.bindings.output.producer.requiredGroups": "httpIngest",


"spring.cloud.stream.bindings.output.destination": "httpIngest.transformer",
"spring.cloud.stream.bindings.input.destination": "httpIngest.http",
"spring.cloud.application.group": "httpIngest",

# for the log sink
"spring.cloud.stream.bindings.input.group": "httpIngest",
"spring.cloud.stream.bindings.input.destination": "httpIngest.transformer",
"spring.cloud.application.group": "httpIngest",

Tasks

This section goes into more detail about how you can work with Spring Cloud Task. It covers topics such as creating and running task applications.

If you are just starting out with Spring Cloud Data Flow, you should probably read the “Getting Started” guide before diving into this section.

45. Introduction

A task executes a process on demand. In the case of Spring Cloud Task, a task is a Spring Boot application that is annotated with @EnableTask. A user launches a task that performs a certain process, and, once complete, the task ends. Unlike a stream where a stream definition can have at most one deployment a single task definition can be launched multiple times simultaneously. An example of a task would be a Spring Boot application that exports data from a JDBC repository to an HDFS instance. Tasks record the start time and the end time as well as the boot exit code in a relational database. The task implementation is based on the Spring Cloud Task project.

45.1. Application properties

Each application takes properties to customize its behavior. As an example, the timestamp task format setting establishes a output format that is different from the default value.

dataflow:> task create --definition "timestamp --format=\"yyyy\"" --name printTimeStamp

This timestamp property is actually the same as the timestamp.format property specified by the timestamp application. Data Flow adds the ability to use the shorthand form format instead of timestamp.format. One may also specify the longhand version as well, as shown in the following example:

dataflow:> task create --definition "timestamp --timestamp.format=\"yyyy\"" --name printTimeStamp

This shorthand behavior is discussed more in the section on Whitelisting application properties. If you have registered application property metadata you can use tab completion in the shell after typing -- to get a list of candidate property names.

The shell provides tab completion for application properties. The shell command app info <appType>:<appName> provides additional documentation for all the supported properties.

The supported Task <appType> is task.

46. The Lifecycle of a Task

Before we dive deeper into the details of creating Tasks, we need to understand the typical lifecycle for tasks in the context of Spring Cloud Data Flow:

46.1. Creating a Task Application

While Spring Cloud Task does provide a number of out-of-the-box applications (at spring-cloud-task-app-starters), most task applications require custom development. To create a custom task application:

  1. Use the Spring Initializer to create a new project, making sure to select the following starters:

    1. Cloud Task: This dependency is the spring-cloud-starter-task.

    2. JDBC: This dependency is the spring-jdbc starter.

  2. Within your new project, create a new class to serve as your main class, as follows:

    @EnableTask
    @SpringBootApplication
    public class MyTask {
    
        public static void main(String[] args) {
    		SpringApplication.run(MyTask.class, args);
    	}
    }
  3. With this class, you need one or more CommandLineRunner or ApplicationRunner implementations within your application. You can either implement your own or use the ones provided by Spring Boot (there is one for running batch jobs, for example).

  4. Packaging your application with Spring Boot into an über jar is done through the standard Spring Boot conventions. The packaged application can be registered and deployed as noted below.

46.1.1. Task Database Configuration

When launching a task application, be sure that the database driver that is being used by Spring Cloud Data Flow is also a dependency on the task application. For example, if your Spring Cloud Data Flow is set to use Postgresql, be sure that the task application also has Postgresql as a dependency.
When you run tasks externally (that is, from the command line) and you want Spring Cloud Data Flow to show the TaskExecutions in its UI, be sure that common datasource settings are shared among the both. By default, Spring Cloud Task uses a local H2 instance, and the execution is recorded to the database used by Spring Cloud Data Flow.

46.2. Registering a Task Application

You can register a Task App with the App Registry by using the Spring Cloud Data Flow Shell app register command. You must provide a unique name and a URI that can be resolved to the app artifact. For the type, specify "task". The following listing shows three examples:

dataflow:>app register --name task1 --type task --uri maven://com.example:mytask:1.0.2

dataflow:>app register --name task2 --type task --uri file:///Users/example/mytask-1.0.2.jar

dataflow:>app register --name task3 --type task --uri http://example.com/mytask-1.0.2.jar

When providing a URI with the maven scheme, the format should conform to the following:

maven://<groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>

If you would like to register multiple apps at one time, you can store them in a properties file where the keys are formatted as <type>.<name> and the values are the URIs. For example, the followinng listing would be a valid properties file:

task.foo=file:///tmp/foo.jar
task.bar=file:///tmp/bar.jar

Then you can use the app import command and provide the location of the properties file by using the --uri option, as follows:

app import --uri /tmp/task-apps.properties

For convenience, we have the static files with application-URIs (for both maven and docker) available for all the out-of-the-box Task app-starters. You can point to this file and import all the application-URIs in bulk. Otherwise, as explained earlier in this chapter, you can register them individually or have your own custom property file with only the required application-URIs in it. It is recommended, however, to have a “focused” list of desired application-URIs in a custom property file.

The following table lists the available static property files:

Artifact Type Stable Release SNAPSHOT Release

Maven

bit.ly/Clark-GA-task-applications-maven

bit.ly/Clark-BUILD-SNAPSHOT-task-applications-maven

Docker

bit.ly/Clark-GA-task-applications-docker

bit.ly/Clark-BUILD-SNAPSHOT-task-applications-docker

For example, if you would like to register all out-of-the-box task applications in bulk, you can do so with the following command:

dataflow:>app import --uri bit.ly/Clark-GA-task-applications-maven

You can also pass the --local option (which is TRUE by default) to indicate whether the properties file location should be resolved within the shell process itself. If the location should be resolved from the Data Flow Server process, specify --local false.

When using either app register or app import, if a task app is already registered with the provided name, it is not overridden by default. If you would like to override the pre-existing task app, then include the --force option.

In some cases, the Resource is resolved on the server side. In other cases, the URI is passed to a runtime container instance where it is resolved. Consult the specific documentation of each Data Flow Server for more detail.

46.3. Creating a Task Definition

You can create a task Definition from a task app by providing a definition name as well as properties that apply to the task execution. Creating a task definition can be done through the RESTful API or the shell. To create a task definition by using the shell, use the task create command to create the task definition, as shown in the following example:

dataflow:>task create mytask --definition "timestamp --format=\"yyyy\""
Created new task 'mytask'

A listing of the current task definitions can be obtained through the RESTful API or the shell. To get the task definition list by using the shell, use the task list command.

46.4. Launching a Task

An adhoc task can be launched through the RESTful API or the shell. To launch an ad-hoc task through the shell, use the task launch command, as shown in the following example:

dataflow:>task launch mytask
 Launched task 'mytask'

When a task is launched, any properties that need to be passed as command line arguments to the task application can be set when launching the task, as follows:

dataflow:>task launch mytask --arguments "--server.port=8080 --custom=value"
The arguments need to be passed as space delimited values.

Additional properties meant for a TaskLauncher itself can be passed in by using a --properties option. The format of this option is a comma-separated string of properties prefixed with app.<task definition name>.<property>. Properties are passed to TaskLauncher as application properties. It is up to an implementation to choose how those are passed into an actual task application. If the property is prefixed with deployer instead of app, it is passed to TaskLauncher as a deployment property and its meaning may be TaskLauncher implementation specific.

dataflow:>task launch mytask --properties "deployer.timestamp.custom1=value1,app.timestamp.custom2=value2"

46.4.1. Common application properties

In addition to configuration through DSL, Spring Cloud Data Flow provides a mechanism for setting common properties to all the task applications that are launched by it. This can be done by adding properties prefixed with spring.cloud.dataflow.applicationProperties.task when starting the server. When doing so, the server passes all the properties, without the prefix, to the instances it launches.

For example, all the launched applications can be configured to use the properties prop1 and prop2 by launching the Data Flow server with the following options:

--spring.cloud.dataflow.applicationProperties.task.prop1=value1
--spring.cloud.dataflow.applicationProperties.task.prop2=value2

This causes the properties, prop1=value1 and prop2=value2, to be passed to all the launched applications.

Properties configured by using this mechanism have lower precedence than task deployment properties. They are overridden if a property with the same key is specified at task launch time (for example, app.trigger.prop2 overrides the common property).

46.5. Reviewing Task Executions

Once the task is launched, the state of the task is stored in a relational DB. The state includes:

  • Task Name

  • Start Time

  • End Time

  • Exit Code

  • Exit Message

  • Last Updated Time

  • Parameters

A user can check the status of their task executions through the RESTful API or the shell. To display the latest task executions through the shell, use the task execution list command.

To get a list of task executions for just one task definition, add --name and the task definition name, for example task execution list --name foo. To retrieve full details for a task execution use the task execution status command with the id of the task execution, for example task execution status --id 549.

46.6. Destroying a Task Definition

Destroying a Task Definition removes the definition from the definition repository. This can be done through the RESTful API or the shell. To destroy a task through the shell, use the task destroy command, as shown in the following example:

dataflow:>task destroy mytask
 Destroyed task 'mytask'

The task execution information for previously launched tasks for the definition remains in the task repository.

This does not stop any currently executing tasks for this definition. Instead, it removes the task definition from the database.

47. Subscribing to Task/Batch Events

You can also tap into various task and batch events when the task is launched. If the task is enabled to generate task or batch events (with the additional dependencies spring-cloud-task-stream and, in the case of Kafka as the binder, spring-cloud-stream-binder-kafka), those events are published during the task lifecycle. By default, the destination names for those published events on the broker (Rabbit, Kafka, and others) are the event names themselves (for instance: task-events, job-execution-events, and so on).

dataflow:>task create myTask --definition “myBatchJob"
dataflow:>task launch myTask
dataflow:>stream create task-event-subscriber1 --definition ":task-events > log" --deploy

You can control the destination name for those events by specifying explicit names when launching the task, as follows:

dataflow:>task launch myTask --properties "spring.cloud.stream.bindings.task-events.destination=myTaskEvents"
dataflow:>stream create task-event-subscriber2 --definition ":myTaskEvents > log" --deploy

The following table lists the default task and batch event and destination names on the broker:

Table 1. Task and Batch Event Destinations

Event

Destination

Task events

task-events

Job Execution events

job-execution-events

Step Execution events

step-execution-events

Item Read events

item-read-events

Item Process events

item-process-events

Item Write events

item-write-events

Skip events

skip-events

48. Composed Tasks

Spring Cloud Data Flow lets a user create a directed graph where each node of the graph is a task application. This is done by using the DSL for composed tasks. A composed task can be created through the RESTful API, the Spring Cloud Data Flow Shell, or the Spring Cloud Data Flow UI.

48.1. Configuring the Composed Task Runner

Composed tasks are executed through a task application called the Composed Task Runner.

48.1.1. Registering the Composed Task Runner

By default, the Composed Task Runner application is not registered with Spring Cloud Data Flow. Consequently, to launch composed tasks, we must first register the Composed Task Runner as an application with Spring Cloud Data Flow, as follows:

app register --name composed-task-runner --type task --uri maven://org.springframework.cloud.task.app:composedtaskrunner-task:<DESIRED_VERSION>

You can also configure Spring Cloud Data Flow to use a different task definition name for the composed task runner. This can be done by setting the spring.cloud.dataflow.task.composedTaskRunnerName property to the name of your choice. You can then register the composed task runner application with the name you set by using that property.

48.1.2. Configuring the Composed Task Runner

The Composed Task Runner application has a dataflow.server.uri property that is used for validation and for launching child tasks. This defaults to localhost:9393. If you run a distributed Spring Cloud Data Flow server, as you would if you deploy the server on Cloud Foundry, YARN, or Kubernetes, you need to provide the URI that can be used to access the server. You can either provide this dataflow.server.uri property for the Composed Task Runner application when launching a composed task or you can provide a spring.cloud.dataflow.server.uri property for the Spring Cloud Data Flow server when it is started. For the latter case, the dataflow.server.uri Composed Task Runner application property is automatically set when a composed task is launched.

In some cases, you may wish to execute an instance of the Composed Task Runner through the Task Launcher sink. In that case, you must configure the Composed Task Runner to use the same datasource that the Spring Cloud Data Flow instance is using. The datasource properties are set with the TaskLaunchRequest through the use of the commandlineArguments or the environmentProperties switches. This is because the Composed Task Runner monitors the task_executions table to check the status of the tasks that it is running. Using information from the table, it determines how it should navigate the graph.

48.2. The Lifecycle of a Composed Task

The lifecycle of a composed task has three parts:

48.2.1. Creating a Composed Task

The DSL for the composed tasks is used when creating a task definition through the task create command, as shown in the following example:

dataflow:> app register --name timestamp --type task --uri maven://org.springframework.cloud.task.app:timestamp-task:<DESIRED_VERSION>
dataflow:> app register --name mytaskapp --type task --uri file:///home/tasks/mytask.jar
dataflow:> task create my-composed-task --definition "mytaskapp && timestamp"
dataflow:> task launch my-composed-task

In the preceding example, we assume that the applications to be used by our composed task have not been registered yet. Consequently, in the first two steps, we register two task applications. We then create our composed task definition by using the task create command. The composed task DSL in the preceding example, when launched, runs mytaskapp and then runs the timestamp application.

But before we launch the my-composed-task definition, we can view what Spring Cloud Data Flow generated for us. This can be done by executing the task list command, as shown (including its output) in the following example:

dataflow:>task list
╔══════════════════════════╤══════════════════════╤═══════════╗
║        Task Name         │   Task Definition    │Task Status║
╠══════════════════════════╪══════════════════════╪═══════════╣
║my-composed-task          │mytaskapp && timestamp│unknown    ║
║my-composed-task-mytaskapp│mytaskapp             │unknown    ║
║my-composed-task-timestamp│timestamp             │unknown    ║
╚══════════════════════════╧══════════════════════╧═══════════╝

In the example, Spring Cloud Data Flow created three task definitions, one for each of the applications that makes up our composed task (my-composed-task-mytaskapp and my-composed-task-timestamp) as well as the composed task (my-composed-task) definition. We also see that each of the generated names for the child tasks is made up of the name of the composed task and the name of the application, separated by a dash - (as in my-composed-task - mytaskapp).

Task Application Parameters

The task applications that make up the composed task definition can also contain parameters, as shown in the following example:

dataflow:> task create my-composed-task --definition "mytaskapp --displayMessage=hello && timestamp --format=YYYY"

48.2.2. Launching a Composed Task

Launching a composed task is done the same way as launching a stand-alone task, as follows:

task launch my-composed-task

Once the task is launched, and assuming all the tasks complete successfully, you can see three task executions when executing a task execution list, as shown in the following example:

dataflow:>task execution list
╔══════════════════════════╤═══╤════════════════════════════╤════════════════════════════╤═════════╗
║        Task Name         │ID │         Start Time         │          End Time          │Exit Code║
╠══════════════════════════╪═══╪════════════════════════════╪════════════════════════════╪═════════╣
║my-composed-task-timestamp│713│Wed Apr 12 16:43:07 EDT 2017│Wed Apr 12 16:43:07 EDT 2017│0        ║
║my-composed-task-mytaskapp│712│Wed Apr 12 16:42:57 EDT 2017│Wed Apr 12 16:42:57 EDT 2017│0        ║
║my-composed-task          │711│Wed Apr 12 16:42:55 EDT 2017│Wed Apr 12 16:43:15 EDT 2017│0        ║
╚══════════════════════════╧═══╧════════════════════════════╧════════════════════════════╧═════════╝

In the preceding example, we see that my-compose-task launched and that it also launched the other tasks in sequential order. All of them executed successfully with Exit Code as 0.

Passing properties to the child tasks

To set the properties for child tasks in a composed task graph at task launch time, you would use the following format of app.<composed task definition name>.<child task app name>.<property>. Using the following Composed Task definition as an example:

dataflow:> task create my-composed-task --definition "mytaskapp  && mytimestamp"

To have mytaskapp display 'HELLO' and set the mytimestamp timestamp format to 'YYYY' for the Composed Task definition, you would use the following task launch format:

task launch my-composed-task --properties "app.my-composed-task.mytaskapp.displayMessage=HELLO,app.my-composed-task.mytimestamp.timestamp.format=YYYY"

Similar to application properties, the deployer properties can also be set for child tasks using the format format of deployer.<composed task definition name>.<child task app name>.<deployer-property>.

task launch my-composed-task --properties "deployer.my-composed-task.mytaskapp.memory=2048m,app.my-composed-task.mytimestamp.timestamp.format=HH:mm:ss"
Launched task 'a1'
Passing arguments to the composed task runner

Command line arguments for the composed task runner can be passed using --arguments option.

For example:

dataflow:>task create my-composed-task --definition "<aaa: timestamp || bbb: timestamp>"
Created new task 'my-composed-task'

dataflow:>task launch my-composed-task --arguments "--increment-instance-enabled=true --max-wait-time=50000 --split-thread-core-pool-size=4" --properties "app.my-composed-task.bbb.timestamp.format=dd/MM/yyyy HH:mm:ss"
Launched task 'my-composed-task'
Exit Statuses

The following list shows how the Exit Status is set for each step (task) contained in the composed task following each step execution:

  • If the TaskExecution has an ExitMessage, that is used as the ExitStatus.

  • If no ExitMessage is present and the ExitCode is set to zero, then the ExitStatus for the step is COMPLETED.

  • If no ExitMessage is present and the ExitCode is set to any non-zero number, the ExitStatus for the step is FAILED.

48.2.3. Destroying a Composed Task

The command used to destroy a stand-alone task is the same as the command used to destroy a composed task. The only difference is that destroying a composed task also destroys the child tasks associated with it. The following example shows the task list before and after using the destroy command:

dataflow:>task list
╔══════════════════════════╤══════════════════════╤═══════════╗
║        Task Name         │   Task Definition    │Task Status║
╠══════════════════════════╪══════════════════════╪═══════════╣
║my-composed-task          │mytaskapp && timestamp│COMPLETED  ║
║my-composed-task-mytaskapp│mytaskapp             │COMPLETED  ║
║my-composed-task-timestamp│timestamp             │COMPLETED  ║
╚══════════════════════════╧══════════════════════╧═══════════╝
...
dataflow:>task destroy my-composed-task
dataflow:>task list
╔═════════╤═══════════════╤═══════════╗
║Task Name│Task Definition│Task Status║
╚═════════╧═══════════════╧═══════════╝

48.2.4. Stopping a Composed Task

In cases where a composed task execution needs to be stopped, you can do so through the:

  • RESTful API

  • Spring Cloud Data Flow Dashboard

To stop a composed task through the dashboard, select the Jobs tab and click the Stop button next to the job execution that you want to stop.

The composed task run is stopped when the currently running child task completes. The step associated with the child task that was running at the time that the composed task was stopped is marked as STOPPED as well as the composed task job execution.

48.2.5. Restarting a Composed Task

In cases where a composed task fails during execution and the status of the composed task is FAILED, the task can be restarted. You can do so through the:

  • RESTful API

  • The shell

  • Spring Cloud Data Flow Dashboard

To restart a composed task through the shell, launch the task with the same parameters. To restart a composed task through the dashboard, select the Jobs tab and click the Restart button next to the job execution that you want to restart.

Restarting a Composed Task job that has been stopped (through the Spring Cloud Data Flow Dashboard or RESTful API) relaunches the STOPPED child task and then launches the remaining (unlaunched) child tasks in the specified order.

49. Composed Tasks DSL

Composed tasks can be run in three ways:

49.1. Conditional Execution

Conditional execution is expressed by using a double ampersand symbol (&&). This lets each task in the sequence be launched only if the previous task successfully completed, as shown in the following example:

task create my-composed-task --definition "task1 && task2"

When the composed task called my-composed-task is launched, it launches the task called task1 and, if it completes successfully, then the task called task2 is launched. If task1 fails, then task2 does not launch.

You can also use the Spring Cloud Data Flow Dashboard to create your conditional execution, by using the designer to drag and drop applications that are required and connecting them together to create your directed graph, as shown in the following image:

Composed Task Conditional Execution
Figure 11. Conditional Execution

The preceding diagram is a screen capture of the directed graph as it being created by using the Spring Cloud Data Flow Dashboard. You can see that are four components in the diagram that comprise a conditional execution:

  • Start icon: All directed graphs start from this symbol. There is only one.

  • Task icon: Represents each task in the directed graph.

  • End icon: Represents the termination of a directed graph.

  • Solid line arrow: Represents the flow conditional execution flow between:

    • Two applications.

    • The start control node and an application.

    • An application and the end control node.

  • End icon: All directed graphs end at this symbol.

You can view a diagram of your directed graph by clicking the Detail button next to the composed task definition on the Definitions tab.

49.2. Transitional Execution

The DSL supports fine- grained control over the transitions taken during the execution of the directed graph. Transitions are specified by providing a condition for equality based on the exit status of the previous task. A task transition is represented by the following symbol ->.

49.2.1. Basic Transition

A basic transition would look like the following:

task create my-transition-composed-task --definition "foo 'FAILED' → bar 'COMPLETED' → baz"

In the preceding example, foo would launch, and, if it had an exit status of FAILED, the bar task would launch. If the exit status of foo was COMPLETED, baz would launch. All other statuses returned by foo have no effect, and the task would terminate normally.

Using the Spring Cloud Data Flow Dashboard to create the same " basic transition " would resemble the following image:

Composed Task Basic Transition
Figure 12. Basic Transition

The preceding diagram is a screen capture of the directed graph as it being created in the Spring Cloud Data Flow Dashboard. Notice that there are two different types of connectors:

  • Dashed line: Represents transitions from the application to one of the possible destination applications.

  • Solid line: Connects applications in a conditional execution or a connection between the application and a control node (start or end).

To create a transitional connector:

  1. When creating a transition, link the application to each possible destination by using the connector.

  2. Once complete, go to each connection and select it by clicking it.

  3. A bolt icon appears.

  4. Click that icon.

  5. Enter the exit status required for that connector.

  6. The solid line for that connector turns to a dashed line.

49.2.2. Transition With a Wildcard

Wildcards are supported for transitions by the DSL, as shown in the following:

task create my-transition-composed-task --definition "foo 'FAILED' → bar '*' → baz"

In the preceding example, foo would launch, and, if it had an exit status of FAILED, the bar task would launch. For any exit status of foo other than FAILED, baz would launch.

Using the Spring Cloud Data Flow Dashboard to create the same “transition with wildcard” would resemble the following image:

Composed Task Basic Transition with Wildcard
Figure 13. Basic Transition With Wildcard

49.2.3. Transition With a Following Conditional Execution

A transition can be followed by a conditional execution so long as the wildcard is not used, as shown in the following example:

task create my-transition-conditional-execution-task --definition "foo 'FAILED' → bar 'UNKNOWN' → baz && qux && quux"

In the preceding example, foo would launch, and, if it had an exit status of FAILED, the bar task would launch. If foo had an exit status of UNKNOWN, baz would launch. For any exit status of foo other than FAILED or UNKNOWN, qux would launch and, upon successful completion, quux would launch.

Using the Spring Cloud Data Flow Dashboard to create the same “transition with conditional execution” would resemble the following image:

Composed Task Transition with Conditional Execution
Figure 14. Transition With Conditional Execution
In this diagram we see the dashed line (transition) connecting the foo application to the target applications, but a solid line connecting the conditional executions between foo, qux, and quux.

49.3. Split Execution

Splits allow multiple tasks within a composed task to be run in parallel. It is denoted by using angle brackets (<>) to group tasks and flows that are to be run in parallel. These tasks and flows are separated by the double pipe || symbol, as shown in the following example:

task create my-split-task --definition "<foo || bar || baz>"

The preceding example above launches tasks foo, bar and baz in parallel.

Using the Spring Cloud Data Flow Dashboard to create the same “split execution” would resemble the following image:

Composed Task Split
Figure 15. Split

With the task DSL, a user may also execute multiple split groups in succession, as shown in the following example:

`task create my-split-task --definition "<foo || bar || baz> && <qux || quux>"'

In the preceding example, tasks foo, bar, and baz are launched in parallel. Once they all complete, then tasks qux and quux are launched in parallel. Once they complete, the composed task ends. However, if foo, bar, or baz fails, the split containing qux and quux does not launch.

Using the Spring Cloud Data Flow Dashboard to create the same “split with multiple groups” would resemble the following image:

Composed Task Split
Figure 16. Split as a part of a conditional execution

Notice that there is a SYNC control node that is inserted by the designer when connecting two consecutive splits.

49.3.1. Split Containing Conditional Execution

A split can also have a conditional execution within the angle brackets, as shown in the following example:

task create my-split-task --definition "<foo && bar || baz>"

In the preceding example, we see that foo and baz are launched in parallel. However, bar does not launch until foo completes successfully.

Using the Spring Cloud Data Flow Dashboard to create the same " split containing conditional execution " resembles the following image:

Composed Task Split With Conditional Execution
Figure 17. Split with conditional execution

50. Launching Tasks from a Stream

You can launch a task from a stream by using one of the available task-launcher sinks. Currently the platforms supported by the task-launcher sinks are:

task-launcher-local is meant for development purposes only.

A task-launcher sink expects a message containing a TaskLaunchRequest object in its payload. From the TaskLaunchRequest object, the task-launcher obtains the URI of the artifact to be launched, as well as the environment properties, command line arguments, deployment properties, and application name to be used by the task.

The task-launcher-local can be added to the available sinks by executing the app register command, as follows (for the Rabbit Binder, in this case):

app register --name task-launcher-local --type sink --uri maven://org.springframework.cloud.stream.app:task-launcher-local-sink-rabbit:jar:1.2.0.RELEASE

In the case of a Maven-based task that is to be launched, the task-launcher application is responsible for downloading the artifact. You must configure the task-launcher with the appropriate configuration of Maven Properties, such as --maven.remote-repositories.repo1.url=http://repo.spring.io/libs-milestone" to resolve artifacts (in this case against a milestone repo). Note that this repostory can be different than the one used to register the task-launcher application itself.

50.1. TriggerTask

One way to launch a task with the task-launcher is to use the triggertask source. The triggertask source emits a message with a TaskLaunchRequest object that contains the required launch information. The triggertask can be added to the available sources by running the app register command, as follows (for the Rabbit Binder, in this case):

app register --type source --name triggertask --uri maven://org.springframework.cloud.stream.app:triggertask-source-rabbit:1.2.0.RELEASE

For example, to launch the timestamp task once every 60 seconds, the stream implementation would be as follows:

stream create foo --definition "triggertask --triggertask.uri=maven://org.springframework.cloud.task.app:timestamp-task:jar:1.2.0.RELEASE --trigger.fixed-delay=60 --triggertask.environment-properties=spring.datasource.url=jdbc:h2:tcp://localhost:19092/mem:dataflow,spring.datasource.username=sa | task-launcher-local --maven.remote-repositories.repo1.url=http://repo.spring.io/libs-release" --deploy

If you run runtime apps, you can find the log file for the task launcher sink. By using the tail command on that file, you can find the log file for the launched tasks. Setting of triggertask.environment-properties establishes the Data Flow Server’s H2 Database as the database where the task executions will be recorded. You can then see the list of task executions by using the shell command task execution list, as shown (with its output) in the following example:

dataflow:>task execution list
╔════════════════════╤══╤════════════════════════════╤════════════════════════════╤═════════╗
║     Task Name      │ID│         Start Time         │          End Time          │Exit Code║
╠════════════════════╪══╪════════════════════════════╪════════════════════════════╪═════════╣
║timestamp-task_26176│4 │Tue May 02 12:13:49 EDT 2017│Tue May 02 12:13:49 EDT 2017│0        ║
║timestamp-task_32996│3 │Tue May 02 12:12:49 EDT 2017│Tue May 02 12:12:49 EDT 2017│0        ║
║timestamp-task_58971│2 │Tue May 02 12:11:50 EDT 2017│Tue May 02 12:11:50 EDT 2017│0        ║
║timestamp-task_13467│1 │Tue May 02 12:10:50 EDT 2017│Tue May 02 12:10:50 EDT 2017│0        ║
╚════════════════════╧══╧════════════════════════════╧════════════════════════════╧═════════╝

50.2. TaskLaunchRequest-transform

Another way to start a task with the task-launcher would be to create a stream by using the Tasklaunchrequest-transform processor to translate a message payload to a TaskLaunchRequest.

The tasklaunchrequest-transform can be added to the available processors by executing the app register command, as follows (for the Rabbit Binder, in this case):

app register --type processor --name tasklaunchrequest-transform --uri maven://org.springframework.cloud.stream.app:tasklaunchrequest-transform-processor-rabbit:1.2.0.RELEASE

The following example shows the creation of a task that includes the tasklaunchrequest-transform:

stream create task-stream --definition "http --port=9000 | tasklaunchrequest-transform --uri=maven://org.springframework.cloud.task.app:timestamp-task:jar:1.2.0.RELEASE | task-launcher-local --maven.remote-repositories.repo1.url=http://repo.spring.io/libs-release"

50.3. Launching a Composed Task From a Stream

A composed task can be launched with one of the task-launcher sinks as discussed here. Since we use the ComposedTaskRunner directly, we need to set up the task definitions it uses prior to the creation of the composed task launching stream. Suppose we wanted to create the following composed task definition: AAA && BBB. The first step would be to create the task definitions, as shown in the following example:

task create AAA --definition "timestamp"
task create BBB --definition "timestamp"

Now that the task definitions we need for composed task definition are ready, we need to create a stream that launches ComposedTaskRunner. So, in this case, we create a stream with

  • A trigger that emits a message once every 30 seconds

  • A transformer that creates a TaskLaunchRequest for each message received

  • A task-launcher-local sink that launches a the ComposedTaskRunner on our local machine

The stream should resemble the following:

stream create ctr-stream --definition "time --fixed-delay=30 | tasklaunchrequest-transform --uri=maven://org.springframework.cloud.task.app:composedtaskrunner-task:<current release> --command-line-arguments='--graph=AAA&&BBB --increment-instance-enabled=true --spring.datasource.url=...' | task-launcher-local"

In the preceding example, we see that the tasklaunchrequest-transform is establishing two primary components:

  • uri: The URI of the ComposedTaskRunner that is used

  • command-line-arguments: To configure the ComposedTaskRunner

For now, we focus on the configuration that is required to launch the ComposedTaskRunner:

  • graph: this is the graph that is to be executed by the ComposedTaskRunner. In this case it is AAA&&BBB.

  • increment-instance-enabled: This lets each execution of ComposedTaskRunner be unique. ComposedTaskRunner is built by using Spring Batch. Thus, we want a new Job Instance for each launch of the ComposedTaskRunner. To do this, we set increment-instance-enabled to be true.

  • spring.datasource.*: The datasource that is used by Spring Cloud Data Flow, which lets the user track the tasks launched by the ComposedTaskRunner and the state of the job execution. Also, this is so that the ComposedTaskRunner can track the state of the tasks it launched and update its state.

Releases of ComposedTaskRunner can be found here.

51. Sharing Spring Cloud Data Flow’s Datastore with Tasks

As discussed in the Tasks documentation Spring Cloud Data Flow allows a user to view Spring Cloud Task App executions. So in this section we will discuss what is required by a Task Application and Spring Cloud Data Flow to share the task execution information.

51.1. A Common DataStore Dependency

Spring Cloud Data Flow supports many database types out-of-the-box, so all the user typically has to do is declare the spring_datasource_* environment variables to establish what data store Spring Cloud Data Flow will need. So whatever database you decide to use for Spring Cloud Data Flow make sure that the your task also includes that database dependency in its pom.xml or gradle.build file. If the database dependency that is used by Spring Cloud Data Flow is not present in the Task Application, the task will fail and the task execution will not be recorded.

51.2. A Common Data Store

Spring Cloud Data Flow and your task application must access the same datastore instance. This is so that the task executions recorded by the task application can be read by Spring Cloud Data Flow to list them in the Shell and Dashboard views. Also the task app must have read & write privileges to the task data tables that are used by Spring Cloud Data Flow.

Given the understanding of Datasource dependency between Task apps and Spring Cloud Data Flow, let’s review how to apply them in various Task orchestration scenarios.

51.2.1. Simple Task Launch

When launching a task from Spring Cloud Data Flow, Data Flow adds its datasource properties (spring.datasource.url, spring.datasource.driverClassName, spring.datasource.username, spring.datasource.password) to the app properties of the task being launched. Thus a task application will record its task execution information to the Spring Cloud Data Flow repository.

51.2.2. Task Launcher Sink

The Task Launcher Sink allows tasks to be launched via a stream as discussed here. Since tasks launched by the Task Launcher Sink may not want their task executions recorded to the same datastore as Spring Cloud Data Flow, each TaskLaunchRequest received by the Task Launcher Sink must have the required datasource information established as app properties or command line arguments. Both TaskLaunchRequest-Transform and TriggerTask Source are examples of how a source and a processor allow a user to set the datasource properties via the app properties or command line arguments.

51.2.3. Composed Task Runner

Spring Cloud Data Flow allows a user to create a directed graph where each node of the graph is a task application and this is done via the Composed Task Runner. In this case the rules that applied to a Simple Task Launch or Task Launcher Sink apply to the composed task runner as well. All child apps must also have access to the datastore that is being used by the composed task runner Also, All child apps must have the same database dependency as the composed task runner enumerated in their pom.xml or gradle.build file.

51.2.4. Launching a task externally from Spring Cloud Data Flow

Users may wish to launch Spring Cloud Task applications via another method (scheduler for example) but still track the task execution via Spring Cloud Data Flow. This can be done so long as the task applications observe the rules specified here and here.

If a user wishes to use Spring Cloud Data Flow to view their Spring Batch jobs, the user must make sure that their batch application use the @EnableTask annotation and follow the rules enumerated here and here. More information is available here.

Task Developer Guide

This section covers how to create, test, and run Spring Cloud Task applications on your local machine. It also shows how to map these applications into Spring Cloud Data Flow and deploy them.

52. Prebuilt Applications

The Spring Cloud Task App Starters project provides many applications that you can start using right away. For example, there is a timestamp application that prints the timestamp to the console. All the applications are based on Spring Boot and Spring Cloud Task.

Applications are published as Maven artifacts as well as Docker images. For GA releases, the Maven artifacts are published to Maven central and the Spring Release Repository. Milestone and snapshot releases are published to the Spring Milestone and Spring Snapshot repositories, respectively. Docker images are pushed to Docker Hub

The root location of the Spring Repository that hosts the GA artifacts of prebuilt applications is repo.spring.io/release/org/springframework/cloud/task/app/

53. Running Prebuilt Applications

You can run the timestamp application by using java -jar.

To get started, download the sample application, as follows:

wget https://repo.spring.io/libs-release/org/springframework/cloud/task/app/timestamp-task/1.3.0.RELEASE/timestamp-task-1.3.0.RELEASE.jar

That file contains a Spring Boot applications that includes the Spring Boot Actuator and the Spring Security Starter. You can specify common Spring Boot properties to configure each application.

Now you can run the timestamp application, as follows:

java -jar timestamp-task-1.3.0.RELEASE.jar --logging.level.org.springframework.cloud.task=DEBUG
The --logging.level.org.springframework.cloud.task=DEBUG option lets you see output that would not otherwise be written to the console. Because Spring Cloud Task uses an in-memory database to store its results (and that in-memory database is destroyed at the end of the run), the DEBUG option is the only way to see the output from the timestamp task.

The timestamp application shows the following output (in the midst of much other output):

2018-03-12 13:45:14.583  INFO 4810 --- [           main] TimestampTaskConfiguration$TimestampTask : 2018-03-12 13:45:14.583
2018-03-12 13:45:14.609 DEBUG 4810 --- [           main] o.s.c.t.r.support.SimpleTaskRepository   : Updating: TaskExecution with executionId=1 with the following {exitCode=0, endTime=Mon Mar 12 13:45:14 CDT 2018, exitMessage='null', errorMessage='null'}

The first line shows the timestamp generated by the Timestamp task. The second line shows an exit code of 0 and no error. Had an error occurred, the exit code would be something other than 0, and the errorMessage would show the exception that was thrown.

If you have debug mode turned on, you can get even more information, in a line similar to the following (which appears just prior to the timestamp if you have debug mode turned on):

2018-03-14 13:47:16.659 DEBUG 78382 --- [ main] o.s.c.t.r.support.SimpleTaskRepository : Creating: TaskExecution{executionId=0, parentExecutionId=null, exitCode=null, taskName='application', startTime=Wed Mar 14 13:47:16 EDT 2018, endTime=null, exitMessage='null', externalExecutionId='null', errorMessage='null', arguments=[]}

54. Building a Timestamp Task

To build your own timestamp task, follow each of these procedures:

54.1. Setting up the Environment

Before we can do anything else, we have to set up our work environment. First, we must install RabbitMQ, as described in this document. Then we need to create a directory and add a starter project (which we created to simplify this setup). To do so:

  1. From the command line, run git clone github.com/cppwfs/DNDataflow.git.

  2. From the command line, run cd DNDataflow.

54.2. Getting Started

To get started on making a task, we must first make a Spring Boot application. The DNDataflow project that we cloned in the preceding section took care of that for us, but we need to build and run it, as follows:

  1. From the command line, run cd labs/lab2.

  2. From the command line, run mvn clean package.

    You should see a typical set of Maven build output for a Spring Boot application.

  3. From the command line, run java -jar target/tasklab-0.0.1-SNAPSHOT.jar.

    You should see a Spring application start, print “Hello World” to the console, and stop.

54.3. Making a Spring Boot Application into a Spring Cloud Task

Now that we have a Boot Application, we can turn it into a Spring Cloud Task, to make the following changes:

  • Add a starter-task dependency (which makes a Spring Boot application into a Spring Cloud Task in the pom.xml file).

  • Add an H2 (in-memory database), because all Spring Cloud Task applications require a database.

  • Add the @EnableTask annotation (which makes a Spring Boot application into a Spring Cloud Task in Java).

To do all that:

  1. Open the pom.xml file.

  2. At line 34, add the following block:

    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-task</artifactId>
    </dependency>
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>
  3. Save your changes to pom.xml.

  4. Open src/main/java/io/spring/TasklabApplication.java in either an IDE or a text editor.

  5. On Line 13, add the @EnableTask annotation.

    If you do not use an IDE, you also need to un-comment lines 6 through 9.
  6. Save your changes to TasklabApplication.java.

  7. Open src/main/resources/application.properties.

  8. Add the following properties:

    logging.level.org.springframework.cloud.task=DEBUG
    spring.application.name=lab2-task

    Setting the logging level for the task to DEBUG creates output to let us know that the task works. Setting the application name lets us store a meaningful name in the database, so that we can find our task in the TASK_EXECUTION table.

  9. Save your change to application.properties.

Now that we have made our changes, we naturally want to run it and see it work. To do so:

  1. From the command line, run mvn clean package.

    You should see a typical set of Maven build output for a Spring Boot application (with some additional output, because it is now a Spring Cloud Task).

  2. From the command line, run java -jar target/tasklab-0.0.1-SNAPSHOT.jar.

    You should see output for a typical (though very basic) Spring Cloud Task, including a line similar to (differing only by its timestamp) the following:

    2018-03-12 15:13:48.930 DEBUG 5202 --- [ main] o.s.c.t.r.support.SimpleTaskRepository : Creating: TaskExecution{executionId=0, exitCode=null, taskName='lab2-task', startTime=Mon Mar 12 15:13:48 CDT 2018, endTime=null, exitMessage='null', errorMessage='null', arguments=[]}

54.4. Recording an Error

Now that we have a working task, we can intentionally create an error, to show how a Spring Cloud Task handles errors. To do so:

  1. Open src/main/java/io/spring/TasklabApplication.java in either an IDE or a text editor.

  2. Copy the following line into the file at line 26:

    throw new IllegalStateException("No Task For You!");
  3. From the command line, run mvn clean package -DSkipTests.

    We must add -DSkipTests, because the tests would catch the Exception we added and prevent us from seeing it.
  4. From the command line, run java -jar target/tasklab-0.0.1-SNAPSHOT.jar.

    Now we can see the Exception we added coming through in the output, as an Exception with a stack trace.

  5. Remove or comment out the Exception that we throw on line 26 (so that the next lessons work correctly).

54.5. Adding Pre- and Post-processing

Spring Cloud Task includes the ability to run additional processing both before and after the task. To add both features to our current sample application:

  1. Open src/main/java/io/spring/TasklabApplication.java in either an IDE or a text editor.

  2. Copy the following code below line 30:

    @BeforeTask
    public void beforeTask(TaskExecution taskExecution) {
      System. out.println("Before TASK");
    }
    
    @AfterTask
    public void afterTask(TaskExecution taskExecution) {
      System. out.println("After TASK");
    }
  3. From the command line, run mvn clean package.

  4. From the command line, run java -jar target/tasklab-0.0.1-SNAPSHOT.jar.

    Now the output includes lines that print both BEFORE TASK and AFTER TASK.

54.6. Bonus Step: Adding a MySQL Database

Nearly always, a real-world Spring Cloud Task needs to use a persistent (rather than an in-memory) database. In this example, we show how to add a MySQL database (MariaDB) to our Task. To do so:

  1. Open the pom.xml file.

  2. On line 46, add the following dependency:

    <dependency>
      <groupId>org.mariadb.jdbc</groupId>
      <artifactId>mariadb-java-client</artifactId>
    </dependency>
  3. From the command line, run mvn clean package.

  4. From the command line, run java -jar target/tasklab-0.0.1-SNAPSHOT.jar.

    If you examine the contents of your database, you should now see the task in the TASK_EXECUTION table.

55. Adding Spring Cloud Task to a Spring Batch Application

This project expects that you have completed the previous project.

You can use Spring Cloud Task within a Spring Batch application. In fact, that was a key goal of Spring Could Task. Because a Task has a finite duration (that is, it is not a continuing process), it is a natural fit for Spring Batch, which naturally deals with processes that have finite durations.

This guide walks through integrating Spring Cloud Task with Spring Batch in a sample application. It consists of the following procedures:

55.1. Setting up the Environment

Before we can do anything else, we have to set up our work environment. First, we must install RabbitMQ, as described in this document. Then we need to create a directory and add a starter project (which we created to simplify this setup). To do so:

  1. From the command line, run git clone github.com/cppwfs/DNDataflow.git.

  2. From the command line, run cd DNDataflow.

55.2. Creating Your First Task

If you have not already done so, install Spring Cloud Data Flow. This document walks through how to do so.

Once you have Spring Cloud Data Flow Server and Shell running, you can use the following procedure to create your first task:

  1. Register a basic suite of tasks by importing their registrations through the Spring Cloud Data Flow Shell with the following command:

    app register --name timestamp --type task --uri maven://org.springframework.cloud.task.app:timestamp-task:1.3.0.RELEASE

    This example shows how to register a task from a Maven repository.
  2. Verify that the timestamp-task app registered by running the following command in the Spring Cloud Data Flow Shell:

    app list

    The following output should appear:

    dataflow shell app list

  3. Create a task definition that uses timestamp task by using the following command in the Spring Cloud Data Flow Shell:

    task create --name myStamp --definition "timestamp"

    You should see a message saying "Created new task 'myStamp'".

  4. Launch your new task by using the following command:

    task launch myStamp

    You should see a message saying "Launched task `myStamp`".

  5. Verify that your task was successfully run by running the following command in the Spring Cloud Data Flow Shell: task execution list

    You should see output similar to the following:

    dataflow task execution list timestamp

    The exit code of 0 tells us that the task ran without errors.

55.3. Creating Your First Batch-Task

Essentially, a Batch-Task is a Spring Batch application that includes the @EnableTask annotation, which serves as an indicator that the Spring Batch application uses Spring Cloud Task. Spring Boot takes care of the rest of the set up for us. We often call it “Taskifying a Batch.” To taskify your first batch:

  1. In Spring Cloud Data Flow Shell, register a Spring Batch-Task application by using the following command:

    app register --name batch-events --type task --uri /<FOLDER>/DNDataflow/labs/jars/simplebatch-0.0.1-SNAPSHOT.jar

    where <Folder> is where you stored your work from the previous project.

    This example shows how to use the file protocol. When you do so, you must use the fully qualified path.
  2. To verify that your application has been registered, run the following command in the Spring Cloud Data Flow Shell:

    app list

    You should see output similar to the following:

    dataflow app list batch event

    Timestamp still appears because we did not clear the database after the previous exercise. Its presence does no harm, and having multiple applications is more realistic.
  3. Create a task definition that uses the batch-events task, by running the following command:

    task create --name myBatchTask --definition "batch-events"

    You should see a message saying "Created new task 'myBatchTask'".

  4. Launch your batch-task by running the following command:

    task launch myBatchTask

    You should see a message saying "Launched task `myBatchTask`".

  5. Verify that the task ran, run the following command:

    task execution list

    You should see output similar to the following:

    dataflow task execution list batch events

    We can now verify that the task worked as a batch job. The next section describes how to do so.

55.3.1. Verifying that Your Task is a Batch

When you create and run a Batch-Task, it is both a Spring Cloud Task instance and a Spring Batch instance. In the previous section, we saw how to verify that your first batch-task worked as a batch. This section steps through how to verify that it also worked as a batch. To do so:

  1. Run the following command to see the list of jobs that have run:

    job execution list

    You should see output similar to the following:

    dataflow job execution list

  2. Note the Job ID from the ID column (in this case, we want to look at 2).

  3. To get the details of the job execution, we can use the Job ID in the following command:

    job execution display --id 2

    You should see output similar to the following:

    dataflow job execution details

We built the demo from which this documentation gets its images such that it creates two jobs. The first of those jobs always fails, because we intentionally throw an exception in it. Doing so lets us test the job output, and it lets us show you what a failed job looks like.

To see the failed job’s details, run the following command in the Spring Cloud Data Flow Shell:

job execution display --id 1

You should see output similar to the following:

dataflow job execution failed

Dashboard

This section describes how to use the dashboard of Spring Cloud Data Flow.

56. Introduction

Spring Cloud Data Flow provides a browser-based GUI called the dashboard to manage the following information:

  • Apps: The Apps tab lists all available applications and provides the controls to register/unregister them.

  • Runtime: The Runtime tab provides the list of all running applications.

  • Streams: The Streams tab lets you list, design, create, deploy, and destroy Stream Definitions.

  • Tasks: The Tasks tab lets you list, create, launch and, destroy Task Definitions.

  • Jobs: The Jobs tab lets you perform batch job related functions.

  • Analytics: The Analytics tab lets you create data visualizations for the various analytics applications.

Upon starting Spring Cloud Data Flow, the dashboard is available at:

For example, if Spring Cloud Data Flow is running locally, the dashboard is available at http://localhost:9393/dashboard.

If you have enabled https, then the dashboard will be located at https://localhost:9393/dashboard. If you have enabled security, a login form is available at http://localhost:9393/dashboard/#/login.

The default Dashboard server port is 9393.

The following image shows the opening page of the Spring Cloud Data Flow dashboard:

The Spring Cloud Data Flow Dashboard
Figure 18. The Spring Cloud Data Flow Dashboard

57. Apps

The Apps section of the dashboard lists all the available applications and provides the controls to register and unregister them (if applicable). It is possible to import a number of applications at once by using the Bulk Import Applications action.

The following image shows a typical list of available apps within the dashboard:

List of available applications
Figure 19. List of Available Applications

57.1. Bulk Import of Applications

The Bulk Import Applications page provides numerous options for defining and importing a set of applications all at once. For bulk import, the application definitions are expected to be expressed in a properties style, as follows:

<type>.<name> = <coordinates>

The following examples show a typical application definitions:

task.timestamp=maven://org.springframework.cloud.task.app:timestamp-task:1.2.0.RELEASE
processor.transform=maven://org.springframework.cloud.stream.app:transform-processor-rabbit:1.2.0.RELEASE

At the top of the bulk import page, a URI can be specified that points to a properties file stored elsewhere, it should contain properties formatted as shown in the previous example. Alternatively, by using the textbox labeled “Apps as Properties”, you can directly list each property string. Finally, if the properties are stored in a local file, the “Select Properties File” option opens a local file browser to select the file. After setting your definitions through one of these routes, click Import.

The following image shows the Bulk Import Applications page:

Bulk Import Applications
Figure 20. Bulk Import Applications

58. Runtime

The Runtime section of the Dashboard application shows the list of all running applications. For each runtime app, the state of the deployment and the number of deployed instances is shown. A list of the used deployment properties is available by clicking on the App Id.

The following image shows an example of the Runtime tab in use:

List of running applications
Figure 21. List of Running Applications

59. Streams

The Streams tab has two child tabs: Definitions and Create Stream. The following topics describe how to work with each one:

59.1. Working with Stream Definitions

The Streams section of the Dashboard includes the Definitions tab that provides a listing of Stream definitions. There you have the option to deploy or undeploy those stream definitions. Additionally, you can remove the definition by clicking on Destroy. Each row includes an arrow on the left, which you can click to see a visual representation of the definition. Hovering over the boxes in the visual representation shows more details about the apps, including any options passed to them.

In the following screenshot, the timer stream has been expanded to show the visual representation:

List of Stream Definitions
Figure 22. List of Stream Definitions

If you click the details button, the view changes to show a visual representation of that stream and any related streams. In the preceding example, if you click details for the timer stream, the view changes to the following view, which clearly shows the relationship between the three streams (two of them are tapping into the timer stream):

Stream Details Page
Figure 23. Stream Details Page

59.2. Creating a Stream

The Streams section of the Dashboard includes the Create Stream tab, which makes available the Spring Flo designer: a canvas application that offers an interactive graphical interface for creating data pipelines.

In this tab, you can:

  • Create, manage, and visualize stream pipelines using DSL, a graphical canvas, or both

  • Write pipelines via DSL with content-assist and auto-complete

  • Use auto-adjustment and grid-layout capabilities in the GUI for simpler and interactive organization of pipelines

You should watch this screencast that highlights some of the "Flo for Spring Cloud Data Flow" capabilities. The Spring Flo wiki includes more detailed content on core Flo capabilities.

The following image shows the Flo designer in use:

Flo for Spring Cloud Data Flo
Figure 24. Flo for Spring Cloud Data Flow

59.3. Deploying a Stream

The stream deploy page includes tabs that provide different ways to setup the deployment properties and deploy the stream. The following screenshots show the stream deploy page for foobar (time | log).

You can define deployments properties using:

  • Form builder tab: a builder which help you to define deployment properties (deployer, application properties…​)

  • Free text tab: a free textarea (key/value pairs)

You can switch between the both views, the form builder provides a more stronger validation of the inputs.

Form builder
Figure 25. The following image shows the form builder
Free text
Figure 26. The following image shows the same properties in the free text

59.4. Creating Fan-In/Fan-Out Streams

In chapter Fan-in and Fan-out you learned how we can support fan-in and fan-out use cases using named destinations. The UI provides dedicated support for named destinations as well:

Fan-in and Fan-out example
Figure 27. Flo for Spring Cloud Data Flow

In this example we have data from an HTTP Source and a JDBC Source that is being sent to the sharedData channel which represents a Fan-in use case. On the other end we have a Cassandra Sink and a File Sink subscribed to the sharedData channel which represents a Fan-out use case.

59.5. Creating a Tap Stream

Creating Taps using the Dashboard is straightforward. Let’s say you have stream consisting of an HTTP Source and a File Sink and you would like to tap into the stream to also send data to a JDBC Sink. In order to create the tap stream simply connect the output connector of the HTTP Source to the JDBC Sink. The connection will be displayed as a dotted line, indicating that you created a tap stream.

Tap stream example
Figure 28. Creating a Tap Stream

The primary stream (HTTP Source to File Sink) will be automatically named, in case you did not provide a name for the stream, yet. When creating tap streams, the primary stream must always be explicitly named. In the picture above, the primary stream was named HTTP_INGEST.

Using the Dashboard, you can also switch the primary stream to become the secondary tap stream.

Switch tap stream to primary stream
Figure 29. Change Primary Stream to Secondary Tap Stream

Simply hover over the existing primary stream, the line between HTTP Source and File Sink. Several control icons will appear, and by clicking on the icon labeled Switch to/from tap, you change the primary stream into a tap stream. Do the same for the tap stream and switch it to a primary stream.

End result of switching the tap stream to a primary stream
Figure 30. End Result of Switching the Primary Stream
When interacting directly with named destinations, there can be "n" combinations (Inputs/Outputs). This allows you to create complex topologies involving a wide variety of data sources and destinations.

60. Tasks

The Tasks section of the Dashboard currently has three tabs:

60.1. Apps

Each app encapsulates a unit of work into a reusable component. Within the Data Flow runtime environment, apps let users create definitions for streams as well as tasks. Consequently, the Apps tab within the Tasks section lets users create task definitions.

You can also use this tab to create Batch Jobs.

The following image shows a typical list of task apps:

List of Task Apps
Figure 31. List of Task Apps

On this screen, you can perform the following actions:

  • View details, such as the task app options.

  • Create a task definition from the respective app.

60.1.1. View Task App Details

On this page you can view the details of a selected task app, including the list of available options (properties) for that app.

60.1.2. Create a Task Definition

List of Task Apps

At a minimum, you must provide a name for the new definition. You also have the option to specify various properties that are used during the deployment of the app.

Each parameter is included only if the Include checkbox is selected.

60.2. Definitions

This page lists the Data Flow task definitions and provides actions to launch or destroy those tasks. It also provides a shortcut operation to define one or more tasks with simple textual input, indicated by the Bulk Define Tasks button.

The following image shows the Definitions page:

List of Task Definitions
Figure 32. List of Task Definitions

60.2.1. Creating Composed Task Definitions

The dashboard includes the Create Composed Task tab, which provides an interactive graphical interface for creating composed tasks.

In this tab, you can:

  • Create and visualize composed tasks using DSL, a graphical canvas, or both.

  • Use auto-adjustment and grid-layout capabilities in the GUI for simpler and interactive organization of the composed task.

On the Create Composed Task screen, you can define one or more task parameters by entering both the parameter key and the parameter value.

Task parameters are not typed.

The following image shows the composed task designer:

Composed Task Designer
Figure 33. Composed Task Designer

60.2.2. Launching Tasks

Once the task definition has been created, the tasks can be launched through the dashboard. To do so, click the Definitions tab and select the task you want to launch by pressing Launch.

60.3. Executions

The Executions tab shows the current running and completed tasks.

The following image shows the Executions tab:

List of Task Executions
Figure 34. List of Task Executions

61. Jobs

The Jobs section of the Dashboard lets you inspect batch jobs. The main section of the screen provides a list of job executions. Batch jobs are tasks that each execute one or more batch jobs. Each job execution has a reference to the task execution ID (in the Task Id column).

The list of Job Executions also shows the state of the underlying Job Definition. Thus, if the underlying definition has been deleted, “No definition found” appears in the Status column.

You can take the following actions for each job:

  • Restart (for failed jobs).

  • Stop (for running jobs).

  • View execution details.

Note: Clicking the stop button actually sends a stop request to the running job, which may not immediately stop.

The following image shows the Jobs page:

List of Job Executions
Figure 35. List of Job Executions

61.1. Job Execution Details

After having launched a batch job, the Job Execution Details page will show information about the job.

The following image shows the Job Execution Details page:

Job Execution Details
Figure 36. Job Execution Details

The Job Execution Details page contains a list of the executed steps. You can further drill into the details of each step’s execution by clicking the magnifying glass icon.

61.2. Step Execution Details

The Step Execution Details page provides information about an individual step within a job.

The following image shows the Step Execution Details page:

Step Execution History
Figure 37. Step Execution Details

On the top of the page, you can see a progress indicator the respective step, with the option to refresh the indicator. A link is provided to view the step execution history.

The Step Execution Details screen provides a complete list of all Step Execution Context key/value pairs.

For exceptions, the Exit Description field contains additional error information. However, this field can have a maximum of 2500 characters. Therefore, in the case of long exception stack traces, trimming of error messages may occur. When that happens, refer to the server log files for further details.

61.3. Step Execution Progress

On this screen, you can see a progress bar indicator in regards to the execution of the current step. Under the Step Execution History, you can also view various metrics associated with the selected step, such as duration, read counts, write counts, and others.

62. Analytics

The Analytics page of the Dashboard provides the following data visualization capabilities for the various analytics applications available in Spring Cloud Data Flow:

  • Counters

  • Field-Value Counters

  • Aggregate Counters

For example, if you create a stream with a Counter application, you can create the corresponding graph from within the Dashboard tab. To do so:

  1. Under Metric Type, select Counters from the select box.

  2. Under Stream, select tweetcount.

  3. Under Visualization, select the desired chart option, Bar Chart.

Using the icons to the right, you can add additional charts to the Dashboard, re-arange the order of created dashboards, or remove data visualizations.

Samples

Several samples have been created to help you get started on implementing higher-level use cases than the basic Streams and Tasks shown in the reference guide. The samples are part of a separate repository and have their own reference documentation.

Analytics
Data Science



REST API Guide

This section describes the Spring Cloud Data Flow REST API.

63. Overview

Spring Cloud Data Flow provides a REST API that lets you access all aspects of the server. In fact, the Spring Cloud Data Flow shell is a first-class consumer of that API.

If you plan to use the REST API with Java, you should consider using the provided Java client (DataflowTemplate) that uses the REST API internally.

63.1. HTTP verbs

Spring Cloud Data Flow tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs, as described in the following table:

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates. Also used for resources that imply the concept of restarts, such as Tasks.

DELETE

Used to delete an existing resource.

63.2. HTTP Status Codes

Spring Cloud Data Flow tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes, as shown in the following table:

Status code Usage

200 OK

The request completed successfully.

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header.

204 No Content

An update to an existing resource has been applied successfully.

400 Bad Request

The request was malformed. The response body includes an error description that provides further information.

404 Not Found

The requested resource did not exist.

409 Conflict

The requested resource already exists. For example, the task already exists or the stream was already being deployed

422 Unprocessable Entity

Returned in cases where the Job Execution cannot be stopped or restarted.

63.3. Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, e.g. application/hal+json

63.4. Errors

Path Type Description

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

String

The time, in milliseconds, at which the error occurred

63.5. Hypermedia

Spring Cloud Data Flow uses hypermedia, and resources include links to other resources in their responses. Responses are in the Hypertext Application from resource to resource Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves. Instead. they should use the above-described links to navigate.

64. Resources

The API includes the following resources:

64.1. Index

The index provides the entry point into Spring Cloud Data Flow’s REST API. The following topics provide more detail:

64.1.1. Accessing the index

Use a GET request to access the index.

Request Structure
GET / HTTP/1.1
Host: localhost:9393
Example Request
$ curl 'http://localhost:9393/' -i
Response Structure
Path Type Description

_links

Object

Links to other resources

['api.revision']

Number

Incremented each time a change is implemented in this REST API

Example Response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3986

{
  "_links" : {
    "dashboard" : {
      "href" : "http://localhost:9393/dashboard"
    },
    "streams/definitions" : {
      "href" : "http://localhost:9393/streams/definitions"
    },
    "streams/definitions/definition" : {
      "href" : "http://localhost:9393/streams/definitions/{name}",
      "templated" : true
    },
    "runtime/apps" : {
      "href" : "http://localhost:9393/runtime/apps"
    },
    "runtime/apps/app" : {
      "href" : "http://localhost:9393/runtime/apps/{appId}",
      "templated" : true
    },
    "runtime/apps/instances" : {
      "href" : "http://localhost:9393/runtime/apps/{appId}/instances",
      "templated" : true
    },
    "metrics/streams" : {
      "href" : "http://localhost:9393/metrics/streams"
    },
    "streams/deployments" : {
      "href" : "http://localhost:9393/streams/deployments"
    },
    "streams/deployments/deployment" : {
      "href" : "http://localhost:9393/streams/deployments/{name}",
      "templated" : true
    },
    "tasks/definitions" : {
      "href" : "http://localhost:9393/tasks/definitions"
    },
    "tasks/definitions/definition" : {
      "href" : "http://localhost:9393/tasks/definitions/{name}",
      "templated" : true
    },
    "tasks/executions" : {
      "href" : "http://localhost:9393/tasks/executions"
    },
    "tasks/executions/name" : {
      "href" : "http://localhost:9393/tasks/executions{?name}",
      "templated" : true
    },
    "tasks/executions/execution" : {
      "href" : "http://localhost:9393/tasks/executions/{id}",
      "templated" : true
    },
    "jobs/executions" : {
      "href" : "http://localhost:9393/jobs/executions"
    },
    "jobs/executions/name" : {
      "href" : "http://localhost:9393/jobs/executions{?name}",
      "templated" : true
    },
    "jobs/executions/execution" : {
      "href" : "http://localhost:9393/jobs/executions/{id}",
      "templated" : true
    },
    "jobs/executions/execution/steps" : {
      "href" : "http://localhost:9393/jobs/executions/{jobExecutionId}/steps",
      "templated" : true
    },
    "jobs/executions/execution/steps/step" : {
      "href" : "http://localhost:9393/jobs/executions/{jobExecutionId}/steps/{stepId}",
      "templated" : true
    },
    "jobs/executions/execution/steps/step/progress" : {
      "href" : "http://localhost:9393/jobs/executions/{jobExecutionId}/steps/{stepId}/progress",
      "templated" : true
    },
    "jobs/instances/name" : {
      "href" : "http://localhost:9393/jobs/instances{?name}",
      "templated" : true
    },
    "jobs/instances/instance" : {
      "href" : "http://localhost:9393/jobs/instances/{id}",
      "templated" : true
    },
    "tools/parseTaskTextToGraph" : {
      "href" : "http://localhost:9393/tools"
    },
    "tools/convertTaskGraphToText" : {
      "href" : "http://localhost:9393/tools"
    },
    "counters" : {
      "href" : "http://localhost:9393/metrics/counters"
    },
    "counters/counter" : {
      "href" : "http://localhost:9393/metrics/counters/{name}",
      "templated" : true
    },
    "field-value-counters" : {
      "href" : "http://localhost:9393/metrics/field-value-counters"
    },
    "field-value-counters/counter" : {
      "href" : "http://localhost:9393/metrics/field-value-counters/{name}",
      "templated" : true
    },
    "aggregate-counters" : {
      "href" : "http://localhost:9393/metrics/aggregate-counters"
    },
    "aggregate-counters/counter" : {
      "href" : "http://localhost:9393/metrics/aggregate-counters/{name}",
      "templated" : true
    },
    "apps" : {
      "href" : "http://localhost:9393/apps"
    },
    "about" : {
      "href" : "http://localhost:9393/about"
    },
    "completions/stream" : {
      "href" : "http://localhost:9393/completions/stream{?start,detailLevel}",
      "templated" : true
    },
    "completions/task" : {
      "href" : "http://localhost:9393/completions/task{?start,detailLevel}",
      "templated" : true
    }
  },
  "api.revision" : 14
}

The main element of the index are the links, as they let you traverse the API and execute the desired functionality:

Relation Description

about

Access meta information, including enabled features, security info, version information

dashboard

Access the dashboard UI

apps

Handle registered applications

completions/stream

Exposes the DSL completion features for Stream

completions/task

Exposes the DSL completion features for Task

metrics/streams

Exposes metrics for the stream applications

jobs/executions

Provides the JobExecution resource

jobs/executions/execution

Provides details for a specific JobExecution

jobs/executions/execution/steps

Provides the steps for a JobExecution

jobs/executions/execution/steps/step

Returns the details for a specific step

jobs/executions/execution/steps/step/progress

Provides progress information for a specific step

jobs/executions/name

Retrieve Job Executions by Job name

jobs/instances/instance

Provides the job instance resource for a specific job instance

jobs/instances/name

Provides the Job instance resource for a specific job name

runtime/apps

Provides the runtime application resource

runtime/apps/app

Exposes the runtime status for a specific app

runtime/apps/instances

Provides the status for app instances

tasks/definitions

Provides the task definition resource

tasks/definitions/definition

Provides details for a specific task definition

tasks/executions

Returns Task executions and allows lanching of tasks

tasks/executions/name

Returns all task executions for a given Task name

tasks/executions/execution

Provides details for a specific task execution

streams/definitions

Exposes the Streams resource

streams/definitions/definition

Handle a specific Stream definition

streams/deployments

Provides Stream deployment operations

streams/deployments/deployment

Request (un-)deployment of an existing stream definition

counters

Exposes the resource for dealing with Counters

counters/counter

Handle a specific counter

aggregate-counters

Provides the resource for dealing with aggregate counters

aggregate-counters/counter

Handle a specific aggregate counter

field-value-counters

Provides the resource for dealing with field-value-counters

field-value-counters/counter

Handle a specific field-value-counter

tools/parseTaskTextToGraph

Parse a task definition into a graph structure

tools/convertTaskGraphToText

Convert a graph format into DSL text format

64.2. Server Meta Information

The server meta information endpoint provides more information about the server itself. The following topics provide more detail:

64.2.1. Retrieving information about the server

A GET request returns meta information for Spring Cloud Data Flow, including:

  • Runtime environment information

  • Information regarding which features are enabled

  • Dependency information of Spring Cloud Data Flow Server

  • Security information

Request Structure
GET /about HTTP/1.1
Accept: application/json
Host: localhost:9393
Example Request
$ curl 'http://localhost:9393/about' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2134

{
  "featureInfo" : {
    "analyticsEnabled" : true,
    "streamsEnabled" : true,
    "tasksEnabled" : true,
    "skipperEnabled" : false
  },
  "versionInfo" : {
    "implementation" : {
      "name" : "spring-cloud-starter-dataflow-server-local",
      "version" : "1.5.1.RELEASE"
    },
    "core" : {
      "name" : "Spring Cloud Data Flow Core",
      "version" : "1.5.1.RELEASE"
    },
    "dashboard" : {
      "name" : "Spring Cloud Dataflow UI",
      "version" : "1.5.1.RELEASE"
    },
    "shell" : {
      "name" : "Spring Cloud Data Flow Shell",
      "version" : "1.5.1.RELEASE",
      "url" : "https://repo.spring.io/libs-release/org/springframework/cloud/spring-cloud-dataflow-shell/1.5.1.RELEASE/spring-cloud-dataflow-shell-1.5.1.RELEASE.jar"
    }
  },
  "securityInfo" : {
    "authenticationEnabled" : false,
    "authorizationEnabled" : false,
    "formLogin" : false,
    "authenticated" : false,
    "username" : null,
    "roles" : [ ]
  },
  "runtimeEnvironment" : {
    "appDeployer" : {
      "deployerImplementationVersion" : "1.3.6.RELEASE",
      "deployerName" : "LocalAppDeployer",
      "deployerSpiVersion" : "1.3.2.RELEASE",
      "javaVersion" : "1.8.0_144",
      "platformApiVersion" : "Linux 4.4.0-127-generic",
      "platformClientVersion" : "4.4.0-127-generic",
      "platformHostVersion" : "4.4.0-127-generic",
      "platformSpecificInfo" : { },
      "platformType" : "Local",
      "springBootVersion" : "1.5.10.RELEASE",
      "springVersion" : "4.3.14.RELEASE"
    },
    "taskLauncher" : {
      "deployerImplementationVersion" : "1.3.6.RELEASE",
      "deployerName" : "LocalTaskLauncher",
      "deployerSpiVersion" : "1.3.2.RELEASE",
      "javaVersion" : "1.8.0_144",
      "platformApiVersion" : "Linux 4.4.0-127-generic",
      "platformClientVersion" : "4.4.0-127-generic",
      "platformHostVersion" : "4.4.0-127-generic",
      "platformSpecificInfo" : { },
      "platformType" : "Local",
      "springBootVersion" : "1.5.10.RELEASE",
      "springVersion" : "4.3.14.RELEASE"
    }
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/about"
    }
  }
}

64.3. Registered Applications

The registered applications endpoint provides information about the applications that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.3.1. Listing Applications

A GET request will list all applications known to Spring Cloud Data Flow. The following topics provide more detail:

Request Structure
GET /apps?type=source HTTP/1.1
Accept: application/json
Host: localhost:9393
Request Parameters
Parameter Description

type

Restrict the returned apps to the type of the app. One of [source, processor, sink, task]

Example Request
$ curl 'http://localhost:9393/apps?type=source' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 911

{
  "_embedded" : {
    "appRegistrationResourceList" : [ {
      "name" : "http",
      "type" : "source",
      "uri" : "maven://org.springframework.cloud.stream.app:http-source-rabbit:1.2.0.RELEASE",
      "version" : null,
      "defaultVersion" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/apps/source/http"
        }
      }
    }, {
      "name" : "time",
      "type" : "source",
      "uri" : "maven://org.springframework.cloud.stream.app:time-source-rabbit:1.2.0.RELEASE",
      "version" : null,
      "defaultVersion" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/apps/source/time"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/apps?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.3.2. Getting Information on a Particular Application

A GET request on /apps/<type>/<name> gets info on a particular application. The following topics provide more detail:

Request Structure
GET /apps/source/http HTTP/1.1
Accept: application/json
Host: localhost:9393
Path Parameters
Table 2. /apps/{type}/{name}
Parameter Description

type

The type of application to query. One of [source, processor, sink, task]

name

The name of the application to query

Example Request
$ curl 'http://localhost:9393/apps/source/http' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2436

{
  "name" : "http",
  "type" : "source",
  "uri" : "maven://org.springframework.cloud.stream.app:http-source-rabbit:1.2.0.RELEASE",
  "version" : null,
  "defaultVersion" : false,
  "options" : [ {
    "id" : "http.path-pattern",
    "name" : "path-pattern",
    "type" : "java.lang.String",
    "description" : "An Ant-Style pattern to determine which http requests will be captured.",
    "shortDescription" : "An Ant-Style pattern to determine which http requests will be captured.",
    "defaultValue" : "/",
    "hints" : {
      "keyHints" : [ ],
      "keyProviders" : [ ],
      "valueHints" : [ ],
      "valueProviders" : [ ]
    },
    "deprecation" : null,
    "sourceType" : "org.springframework.cloud.stream.app.http.source.HttpSourceProperties",
    "sourceMethod" : null,
    "deprecated" : false
  }, {
    "id" : "http.mapped-request-headers",
    "name" : "mapped-request-headers",
    "type" : "java.lang.String[]",
    "description" : "Headers that will be mapped.",
    "shortDescription" : "Headers that will be mapped.",
    "defaultValue" : null,
    "hints" : {
      "keyHints" : [ ],
      "keyProviders" : [ ],
      "valueHints" : [ ],
      "valueProviders" : [ ]
    },
    "deprecation" : null,
    "sourceType" : "org.springframework.cloud.stream.app.http.source.HttpSourceProperties",
    "sourceMethod" : null,
    "deprecated" : false
  }, {
    "id" : "http.secured",
    "name" : "secured",
    "type" : "java.lang.Boolean",
    "description" : "Secure or not HTTP source path.",
    "shortDescription" : "Secure or not HTTP source path.",
    "defaultValue" : false,
    "hints" : {
      "keyHints" : [ ],
      "keyProviders" : [ ],
      "valueHints" : [ ],
      "valueProviders" : [ ]
    },
    "deprecation" : null,
    "sourceType" : "org.springframework.cloud.stream.app.http.source.HttpSourceProperties",
    "sourceMethod" : null,
    "deprecated" : false
  }, {
    "id" : "server.port",
    "name" : "port",
    "type" : "java.lang.Integer",
    "description" : "Server HTTP port.",
    "shortDescription" : "Server HTTP port.",
    "defaultValue" : null,
    "hints" : {
      "keyHints" : [ ],
      "keyProviders" : [ ],
      "valueHints" : [ ],
      "valueProviders" : [ ]
    },
    "deprecation" : null,
    "sourceType" : "org.springframework.boot.autoconfigure.web.ServerProperties",
    "sourceMethod" : null,
    "deprecated" : false
  } ],
  "shortDescription" : null
}

64.3.3. Registering a New Application

A POST request on /apps/<type>/<name> allows registration of a new application. The following topics provide more detail:

Request Structure
POST /apps/source/http HTTP/1.1
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

uri=maven%3A%2F%2Forg.springframework.cloud.stream.app%3Ahttp-source-rabbit%3A1.1.0.RELEASE
Request Parameters
Parameter Description

uri

URI where the application bits reside

metadata-uri

URI where the application metadata jar can be found

force

Must be true if a registration with the same name and type already exists, otherwise an error will occur

Path Parameters
Table 3. /apps/{type}/{name}
Parameter Description

type

The type of application to register. One of [source, processor, sink, task]

name

The name of the application to register

Example Request
$ curl 'http://localhost:9393/apps/source/http' -i -X POST -d 'uri=maven%3A%2F%2Forg.springframework.cloud.stream.app%3Ahttp-source-rabbit%3A1.1.0.RELEASE'
Response Structure
HTTP/1.1 201 Created

64.3.4. Unregistering an Application

A DELETE request on /apps/<type>/<name> unregisters a previously registered application. The following topics provide more detail:

Request Structure
DELETE /apps/source/http HTTP/1.1
Host: localhost:9393
Path Parameters
Table 4. /apps/{type}/{name}
Parameter Description

type

The type of application to unregister. One of [source, processor, sink, task]

name

The name of the application to unregister

Example Request
$ curl 'http://localhost:9393/apps/source/http' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.3.5. Registering Applications in Bulk

A POST request on /apps allows registering multiple applications at once. The following topics provide more detail:

Request Structure
POST /apps HTTP/1.1
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

apps=source.http%3Dmaven%3A%2F%2Forg.springframework.cloud.stream.app%3Ahttp-source-rabbit%3A1.1.0.RELEASE&force=false
Request Parameters
Parameter Description

uri

URI where a properties file containing registrations can be fetched. Exclusive with apps.

apps

Inline set of registrations. Exclusive with uri.

force

Must be true if a registration with the same name and type already exists, otherwise an error will occur

Example Request
$ curl 'http://localhost:9393/apps' -i -X POST -d 'apps=source.http%3Dmaven%3A%2F%2Forg.springframework.cloud.stream.app%3Ahttp-source-rabbit%3A1.1.0.RELEASE&force=false'
Response Structure
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 587

{
  "_embedded" : {
    "appRegistrationResourceList" : [ {
      "name" : "http",
      "type" : "source",
      "uri" : "maven://org.springframework.cloud.stream.app:http-source-rabbit:1.1.0.RELEASE",
      "version" : null,
      "defaultVersion" : false,
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/apps/source/http"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/apps?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.4. Stream Definitions

The registered applications endpoint provides information about the stream definitions that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.4.1. Creating a New Stream Definition

Creating a stream definition is achieved by creating a POST request to the stream definitions endpoint. A curl request for a ticktock stream might resemble the following:

curl -X POST -d "name=ticktock&definition=time | log" localhost:9393/streams/definitions?deploy=false

A stream definition can also contain additional parameters. For instance, in the example shown under “Request Structure”, we also provide the date-time format.

The following topics provide more detail:

Request Structure
POST /streams/definitions HTTP/1.1
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

name=timelog&definition=time+--format%3D%27YYYY+MM+DD%27+%7C+log&deploy=false
Request Parameters
Parameter Description

name

The name for the created task definitions

definition

The definition for the stream, using Data Flow DSL

deploy

If true, the stream is deployed upon creation (default is false

Example Request
$ curl 'http://localhost:9393/streams/definitions' -i -X POST -d 'name=timelog&definition=time+--format%3D%27YYYY+MM+DD%27+%7C+log&deploy=false'
Response Structure
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 307

{
  "name" : "timelog",
  "dslText" : "time --format='YYYY MM DD' | log",
  "status" : "undeployed",
  "statusDescription" : "The app or group is known to the system, but is not currently deployed",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/streams/definitions/timelog"
    }
  }
}

64.4.2. List All Stream Definitions

The streams endpoint lets you list all the stream definitions. The following topics provide more detail:

Request Structure
GET /streams/definitions?page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

Example Request
$ curl 'http://localhost:9393/streams/definitions?page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 628

{
  "_embedded" : {
    "streamDefinitionResourceList" : [ {
      "name" : "timelog",
      "dslText" : "time --format='YYYY MM DD' | log",
      "status" : "undeployed",
      "statusDescription" : "The app or group is known to the system, but is not currently deployed",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/streams/definitions/timelog"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/streams/definitions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

The streams endpoint lets you list related stream definitions. The following topics provide more detail:

GET /streams/definitions/timelog/related?nested=true HTTP/1.1
Host: localhost:9393
Parameter Description

nested

Should we recursively findByNameLike for related stream definitions (optional)

$ curl 'http://localhost:9393/streams/definitions/timelog/related?nested=true' -i
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 644

{
  "_embedded" : {
    "streamDefinitionResourceList" : [ {
      "name" : "timelog",
      "dslText" : "time --format='YYYY MM DD' | log",
      "status" : "undeployed",
      "statusDescription" : "The app or group is known to the system, but is not currently deployed",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/streams/definitions/timelog"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/streams/definitions/timelog/related?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.4.4. Delete a Single Stream Definition

The streams endpoint lets you delete a single stream definition. (See also: Delete All Stream Definitions.) The following topics provide more detail:

Request Structure
DELETE /streams/definitions/timelog HTTP/1.1
Host: localhost:9393
Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/streams/definitions/timelog' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.4.5. Delete All Stream Definitions

The streams endpoint lets you delete all single stream definitions. (See also: Delete a Single Stream Definition.) The following topics provide more detail:

Request Structure
DELETE /streams/definitions HTTP/1.1
Host: localhost:9393
Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/streams/definitions' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.5. Stream Deployments

The deployment definitions endpoint provides information about the deployments that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.5.1. Deploying Stream Definition

The stream definition endpoint lets you deploy a single stream definition. Optionally, you can pass application parameters as properties in the request body. The following topics provide more detail:

Request Structure
POST /streams/deployments/timelog HTTP/1.1
Content-Type: application/json
Host: localhost:9393
Content-Length: 36

{"app.time.timestamp.format":"YYYY"}
Table 5. /streams/deployments/{timelog}
Parameter Description

timelog

The name of an existing stream definition (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/streams/deployments/timelog' -i -X POST -H 'Content-Type: application/json' -d '{"app.time.timestamp.format":"YYYY"}'
Response Structure
HTTP/1.1 201 Created

64.5.2. Undeploy Stream Definition

The stream definition endpoint lets you undeploy a single stream definition. The following topics provide more detail:

Request Structure
DELETE /streams/deployments/timelog HTTP/1.1
Host: localhost:9393
Table 6. /streams/deployments/{timelog}
Parameter Description

timelog

The name of an existing stream definition (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/streams/deployments/timelog' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.5.3. Undeploy All Stream Definitions

The stream definition endpoint lets you undeploy all single stream definitions. The following topics provide more detail:

Request Structure
DELETE /streams/deployments HTTP/1.1
Host: localhost:9393
Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/streams/deployments' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.5.4. Update Deployed Stream

When using Spring Cloud Data Flow in Skipper mode, you can update deployed streams, and provide additional deployment properties.

In order to use this feature, the Data Flow server must be in Skipper Mode

64.5.5. Rollback Stream Definition

Rollback the stream to the previous or a specific version of the stream.

In order to use this feature, the Data Flow server must be in Skipper Mode

64.5.6. Get Manifest

Return a manifest of a released version. For packages with dependencies, the manifest includes the contents of those dependencies.

In order to use this feature, the Data Flow server must be in Skipper Mode

64.5.7. Get Deployment History

Get the stream’s deployment history.

In order to use this feature, the Data Flow server must be in Skipper Mode

64.5.8. Get Deployment Platforms

Retrieve a list of supported deployment platforms.

In order to use this feature, the Data Flow server must be in Skipper Mode

64.6. Task Definitions

The task definitions endpoint provides information about the task definitions that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.6.1. Creating a New Task Definition

The task definition endpoint lets you create a new task definition. The following topics provide more detail:

Request Structure
POST /tasks/definitions HTTP/1.1
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

name=my-task&definition=timestamp+--format%3D%27YYYY+MM+DD%27
Request Parameters
Parameter Description

name

The name for the created task definition

definition

The definition for the task, using Data Flow DSL

Example Request
$ curl 'http://localhost:9393/tasks/definitions' -i -X POST -d 'name=my-task&definition=timestamp+--format%3D%27YYYY+MM+DD%27'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 225

{
  "name" : "my-task",
  "dslText" : "timestamp --format='YYYY MM DD'",
  "composed" : false,
  "status" : "unknown",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/definitions/my-task"
    }
  }
}

64.6.2. List All Task Definitions

The task definition endpoint lets you get all task definitions. The following topics provide more detail:

Request Structure
GET /tasks/definitions?page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

Example Request
$ curl 'http://localhost:9393/tasks/definitions?page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 542

{
  "_embedded" : {
    "taskDefinitionResourceList" : [ {
      "name" : "my-task",
      "dslText" : "timestamp --format='YYYY MM DD'",
      "composed" : false,
      "status" : "unknown",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/tasks/definitions/my-task"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/definitions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.6.3. Retrieve Task Definition Detail

The task definition endpoint lets you get a single task definition. The following topics provide more detail:

Request Structure
GET /tasks/definitions/my-task HTTP/1.1
Host: localhost:9393
Table 7. /tasks/definitions/{my-task}
Parameter Description

my-task

The name of an existing task definition (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/tasks/definitions/my-task' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 225

{
  "name" : "my-task",
  "dslText" : "timestamp --format='YYYY MM DD'",
  "composed" : false,
  "status" : "unknown",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/definitions/my-task"
    }
  }
}

64.6.4. Delete Task Definition

The task definition endpoint lets you delete a single task definition. The following topics provide more detail:

Request Structure
DELETE /tasks/definitions/my-task HTTP/1.1
Host: localhost:9393
Table 8. /tasks/definitions/{my-task}
Parameter Description

my-task

The name of an existing task definition (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/tasks/definitions/my-task' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.7. Task Executions

The task executions endpoint provides information about the task executions that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.7.1. Launching a Task

Launching a task is done by requesting the creation of a new task execution. The following topics provide more detail:

Request Structure
POST /tasks/executions HTTP/1.1
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

name=taskA&properties=app.my-task.foo%3Dbar%2Cdeployer.my-task.something-else%3D3&arguments=--server.port%3D8080+--foo%3Dbar
Request Parameters
Parameter Description

name

The name of the task definition to launch

properties

Application and Deployer properties to use while launching

arguments

Command line arguments to pass to the task

Example Request
$ curl 'http://localhost:9393/tasks/executions' -i -X POST -d 'name=taskA&properties=app.my-task.foo%3Dbar%2Cdeployer.my-task.something-else%3D3&arguments=--server.port%3D8080+--foo%3Dbar'
Response Structure
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 1

1

64.7.2. List All Task Executions

The task executions endpoint lets you list all task executions. The following topics provide more detail:

Request Structure
GET /tasks/executions?page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

Example Request
$ curl 'http://localhost:9393/tasks/executions?page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1155

{
  "_embedded" : {
    "taskExecutionResourceList" : [ {
      "executionId" : 2,
      "exitCode" : 0,
      "taskName" : "taskB",
      "startTime" : null,
      "endTime" : null,
      "exitMessage" : null,
      "arguments" : [ ],
      "jobExecutionIds" : [ ],
      "errorMessage" : null,
      "externalExecutionId" : "taskB-e27a47ca-7a42-4ce5-bcda-deacb9e13ee9",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/tasks/executions/2"
        }
      }
    }, {
      "executionId" : 1,
      "exitCode" : 0,
      "taskName" : "taskA",
      "startTime" : null,
      "endTime" : null,
      "exitMessage" : null,
      "arguments" : [ ],
      "jobExecutionIds" : [ ],
      "errorMessage" : null,
      "externalExecutionId" : "taskA-22ae2f73-392b-4d67-9f68-a276a842ac03",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/tasks/executions/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/executions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.7.3. List All Task Executions With a Specified Task Name

The task executions endpoint lets you list task executions with a specified task name. The following topics provide more detail:

Request Structure
GET /tasks/executions?name=taskB&page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

name

The name associated with the task execution

Example Request
$ curl 'http://localhost:9393/tasks/executions?name=taskB&page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 714

{
  "_embedded" : {
    "taskExecutionResourceList" : [ {
      "executionId" : 2,
      "exitCode" : 0,
      "taskName" : "taskB",
      "startTime" : null,
      "endTime" : null,
      "exitMessage" : null,
      "arguments" : [ ],
      "jobExecutionIds" : [ ],
      "errorMessage" : null,
      "externalExecutionId" : "taskB-e27a47ca-7a42-4ce5-bcda-deacb9e13ee9",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/tasks/executions/2"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/executions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.7.4. Task Execution Detail

The task executions endpoint lets you get the details about a task execution. The following topics provide more detail:

Request Structure
GET /tasks/executions/1 HTTP/1.1
Host: localhost:9393
Table 9. /tasks/executions/{id}
Parameter Description

id

The id of an existing task execution (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/tasks/executions/1' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 375

{
  "executionId" : 1,
  "exitCode" : 0,
  "taskName" : "taskA",
  "startTime" : null,
  "endTime" : null,
  "exitMessage" : null,
  "arguments" : [ ],
  "jobExecutionIds" : [ ],
  "errorMessage" : null,
  "externalExecutionId" : "taskA-22ae2f73-392b-4d67-9f68-a276a842ac03",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/tasks/executions/1"
    }
  }
}

64.7.5. Delete Task Execution

The task executions endpoint lets you delete a task execution. The following topics provide more detail:

Request Structure
DELETE /tasks/executions/1 HTTP/1.1
Host: localhost:9393
Table 10. /tasks/executions/{id}
Parameter Description

id

The id of an existing task execution (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/tasks/executions/1' -i -X DELETE
Response Structure
HTTP/1.1 200 OK

64.8. Job Executions

The job executions endpoint provides information about the job executions that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.8.1. List All Job Executions

The job executions endpoint lets you list all job executions. The following topics provide more detail:

Request Structure
GET /jobs/executions?page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

Example Request
$ curl 'http://localhost:9393/jobs/executions?page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 3357

{
  "_embedded" : {
    "jobExecutionResourceList" : [ {
      "executionId" : 2,
      "stepExecutionCount" : 0,
      "jobId" : 2,
      "taskExecutionId" : 2,
      "name" : "DOCJOB_1",
      "startDate" : "2018-06-05",
      "startTime" : "10:34:42",
      "duration" : "00:00:00",
      "jobExecution" : {
        "id" : 2,
        "version" : 1,
        "jobParameters" : {
          "parameters" : { },
          "empty" : true
        },
        "jobInstance" : {
          "id" : 2,
          "version" : null,
          "jobName" : "DOCJOB_1",
          "instanceId" : 2
        },
        "stepExecutions" : [ ],
        "status" : "STOPPED",
        "startTime" : "2018-06-05T10:34:42.004Z",
        "createTime" : "2018-06-05T10:34:42.001Z",
        "endTime" : null,
        "lastUpdated" : "2018-06-05T10:34:42.004Z",
        "exitStatus" : {
          "exitCode" : "UNKNOWN",
          "exitDescription" : "",
          "running" : true
        },
        "executionContext" : {
          "dirty" : false,
          "empty" : true,
          "values" : [ ]
        },
        "failureExceptions" : [ ],
        "jobConfigurationName" : null,
        "running" : true,
        "stopping" : false,
        "jobId" : 2,
        "allFailureExceptions" : [ ]
      },
      "jobParameters" : { },
      "jobParametersString" : "",
      "restartable" : true,
      "abandonable" : true,
      "stoppable" : false,
      "defined" : true,
      "timeZone" : "UTC",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/jobs/executions/2"
        }
      }
    }, {
      "executionId" : 1,
      "stepExecutionCount" : 0,
      "jobId" : 1,
      "taskExecutionId" : 1,
      "name" : "DOCJOB",
      "startDate" : "2018-06-05",
      "startTime" : "10:34:41",
      "duration" : "00:00:00",
      "jobExecution" : {
        "id" : 1,
        "version" : 2,
        "jobParameters" : {
          "parameters" : { },
          "empty" : true
        },
        "jobInstance" : {
          "id" : 1,
          "version" : null,
          "jobName" : "DOCJOB",
          "instanceId" : 1
        },
        "stepExecutions" : [ ],
        "status" : "STOPPING",
        "startTime" : "2018-06-05T10:34:41.994Z",
        "createTime" : "2018-06-05T10:34:41.991Z",
        "endTime" : null,
        "lastUpdated" : "2018-06-05T10:34:42.040Z",
        "exitStatus" : {
          "exitCode" : "UNKNOWN",
          "exitDescription" : "",
          "running" : true
        },
        "executionContext" : {
          "dirty" : false,
          "empty" : true,
          "values" : [ ]
        },
        "failureExceptions" : [ ],
        "jobConfigurationName" : null,
        "running" : true,
        "stopping" : true,
        "jobId" : 1,
        "allFailureExceptions" : [ ]
      },
      "jobParameters" : { },
      "jobParametersString" : "",
      "restartable" : false,
      "abandonable" : true,
      "stoppable" : false,
      "defined" : false,
      "timeZone" : "UTC",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/jobs/executions/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.8.2. List All Job Executions With a Specified Job Name

The job executions endpoint lets you list all job executions. The following topics provide more detail:

Request Structure
GET /jobs/executions?name=DOCJOB&page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

name

The name associated with the job execution

Example Request
$ curl 'http://localhost:9393/jobs/executions?name=DOCJOB&page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1813

{
  "_embedded" : {
    "jobExecutionResourceList" : [ {
      "executionId" : 1,
      "stepExecutionCount" : 0,
      "jobId" : 1,
      "taskExecutionId" : 1,
      "name" : "DOCJOB",
      "startDate" : "2018-06-05",
      "startTime" : "10:34:41",
      "duration" : "00:00:00",
      "jobExecution" : {
        "id" : 1,
        "version" : 2,
        "jobParameters" : {
          "parameters" : { },
          "empty" : true
        },
        "jobInstance" : {
          "id" : 1,
          "version" : null,
          "jobName" : "DOCJOB",
          "instanceId" : 1
        },
        "stepExecutions" : [ ],
        "status" : "STOPPING",
        "startTime" : "2018-06-05T10:34:41.994Z",
        "createTime" : "2018-06-05T10:34:41.991Z",
        "endTime" : null,
        "lastUpdated" : "2018-06-05T10:34:42.040Z",
        "exitStatus" : {
          "exitCode" : "UNKNOWN",
          "exitDescription" : "",
          "running" : true
        },
        "executionContext" : {
          "dirty" : false,
          "empty" : true,
          "values" : [ ]
        },
        "failureExceptions" : [ ],
        "jobConfigurationName" : null,
        "running" : true,
        "stopping" : true,
        "jobId" : 1,
        "allFailureExceptions" : [ ]
      },
      "jobParameters" : { },
      "jobParametersString" : "",
      "restartable" : false,
      "abandonable" : true,
      "stoppable" : false,
      "defined" : false,
      "timeZone" : "UTC",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/jobs/executions/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.8.3. Job Execution Detail

The job executions endpoint lets you get the details about a job execution. The following topics provide more detail:

Request Structure
GET /jobs/executions/2 HTTP/1.1
Host: localhost:9393
Table 11. /jobs/executions/{id}
Parameter Description

id

The id of an existing job execution (required)

Request Parameters

There are no request parameter for this endpoint.

Example Request
$ curl 'http://localhost:9393/jobs/executions/2' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1311

{
  "executionId" : 2,
  "stepExecutionCount" : 0,
  "jobId" : 2,
  "taskExecutionId" : 2,
  "name" : "DOCJOB_1",
  "startDate" : "2018-06-05",
  "startTime" : "10:34:42",
  "duration" : "00:00:00",
  "jobExecution" : {
    "id" : 2,
    "version" : 1,
    "jobParameters" : {
      "parameters" : { },
      "empty" : true
    },
    "jobInstance" : {
      "id" : 2,
      "version" : 0,
      "jobName" : "DOCJOB_1",
      "instanceId" : 2
    },
    "stepExecutions" : [ ],
    "status" : "STOPPED",
    "startTime" : "2018-06-05T10:34:42.004Z",
    "createTime" : "2018-06-05T10:34:42.001Z",
    "endTime" : null,
    "lastUpdated" : "2018-06-05T10:34:42.004Z",
    "exitStatus" : {
      "exitCode" : "UNKNOWN",
      "exitDescription" : "",
      "running" : true
    },
    "executionContext" : {
      "dirty" : false,
      "empty" : true,
      "values" : [ ]
    },
    "failureExceptions" : [ ],
    "jobConfigurationName" : null,
    "running" : true,
    "stopping" : false,
    "jobId" : 2,
    "allFailureExceptions" : [ ]
  },
  "jobParameters" : { },
  "jobParametersString" : "",
  "restartable" : true,
  "abandonable" : true,
  "stoppable" : false,
  "defined" : true,
  "timeZone" : "UTC",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions/2"
    }
  }
}

64.8.4. Stop Job Execution

The job executions endpoint lets you stop a job execution. The following topics provide more detail:

Request structure
PUT /jobs/executions/1 HTTP/1.1
Accept: application/json
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

stop=true
Table 12. /jobs/executions/{id}
Parameter Description

id

The id of an existing job execution (required)

Request parameters
Parameter Description

stop

Sends signal to stop the job if set to true

Example request
$ curl 'http://localhost:9393/jobs/executions/1' -i -X PUT -H 'Accept: application/json' -d 'stop=true'
Response structure
HTTP/1.1 200 OK

64.8.5. Restart Job Execution

The job executions endpoint lets you restart a job execution. The following topics provide more detail:

Request Structure
PUT /jobs/executions/2 HTTP/1.1
Accept: application/json
Host: localhost:9393
Content-Type: application/x-www-form-urlencoded

restart=true
Table 13. /jobs/executions/{id}
Parameter Description

id

The id of an existing job execution (required)

Request Parameters
Parameter Description

restart

Sends signal to restart the job if set to true

Example Request
$ curl 'http://localhost:9393/jobs/executions/2' -i -X PUT -H 'Accept: application/json' -d 'restart=true'
Response Structure
HTTP/1.1 200 OK

64.9. Job Instances

The job instances endpoint provides information about the job instances that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.9.1. List All Job Instances

The job instances endpoint lets you list all job instances. The following topics provide more detail:

Request Structure
GET /jobs/instances?name=DOCJOB&page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

name

The name associated with the job instance

Example Request
$ curl 'http://localhost:9393/jobs/instances?name=DOCJOB&page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2002

{
  "_embedded" : {
    "jobInstanceResourceList" : [ {
      "jobName" : "DOCJOB",
      "jobInstanceId" : 1,
      "jobExecutions" : [ {
        "executionId" : 1,
        "stepExecutionCount" : 0,
        "jobId" : 1,
        "taskExecutionId" : 1,
        "name" : "DOCJOB",
        "startDate" : "2018-06-05",
        "startTime" : "10:34:36",
        "duration" : "00:00:00",
        "jobExecution" : {
          "id" : 1,
          "version" : 1,
          "jobParameters" : {
            "parameters" : { },
            "empty" : true
          },
          "jobInstance" : {
            "id" : 1,
            "version" : 0,
            "jobName" : "DOCJOB",
            "instanceId" : 1
          },
          "stepExecutions" : [ ],
          "status" : "STARTED",
          "startTime" : "2018-06-05T10:34:36.925Z",
          "createTime" : "2018-06-05T10:34:36.919Z",
          "endTime" : null,
          "lastUpdated" : "2018-06-05T10:34:36.925Z",
          "exitStatus" : {
            "exitCode" : "UNKNOWN",
            "exitDescription" : "",
            "running" : true
          },
          "executionContext" : {
            "dirty" : false,
            "empty" : true,
            "values" : [ ]
          },
          "failureExceptions" : [ ],
          "jobConfigurationName" : null,
          "running" : true,
          "stopping" : false,
          "jobId" : 1,
          "allFailureExceptions" : [ ]
        },
        "jobParameters" : { },
        "jobParametersString" : "",
        "restartable" : false,
        "abandonable" : false,
        "stoppable" : true,
        "defined" : false,
        "timeZone" : "UTC"
      } ],
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/jobs/instances/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/instances?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.9.2. Job Instance Detail

The job instances endpoint lets you list all job instances. The following topics provide more detail:

Request Structure
GET /jobs/instances/1 HTTP/1.1
Host: localhost:9393
Table 14. /jobs/instances/{id}
Parameter Description

id

The id of an existing job instance (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/jobs/instances/1' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1487

{
  "jobName" : "DOCJOB",
  "jobInstanceId" : 1,
  "jobExecutions" : [ {
    "executionId" : 1,
    "stepExecutionCount" : 0,
    "jobId" : 1,
    "taskExecutionId" : 1,
    "name" : "DOCJOB",
    "startDate" : "2018-06-05",
    "startTime" : "10:34:36",
    "duration" : "00:00:00",
    "jobExecution" : {
      "id" : 1,
      "version" : 1,
      "jobParameters" : {
        "parameters" : { },
        "empty" : true
      },
      "jobInstance" : {
        "id" : 1,
        "version" : 0,
        "jobName" : "DOCJOB",
        "instanceId" : 1
      },
      "stepExecutions" : [ ],
      "status" : "STARTED",
      "startTime" : "2018-06-05T10:34:36.925Z",
      "createTime" : "2018-06-05T10:34:36.919Z",
      "endTime" : null,
      "lastUpdated" : "2018-06-05T10:34:36.925Z",
      "exitStatus" : {
        "exitCode" : "UNKNOWN",
        "exitDescription" : "",
        "running" : true
      },
      "executionContext" : {
        "dirty" : false,
        "empty" : true,
        "values" : [ ]
      },
      "failureExceptions" : [ ],
      "jobConfigurationName" : null,
      "running" : true,
      "stopping" : false,
      "jobId" : 1,
      "allFailureExceptions" : [ ]
    },
    "jobParameters" : { },
    "jobParametersString" : "",
    "restartable" : false,
    "abandonable" : false,
    "stoppable" : true,
    "defined" : false,
    "timeZone" : "UTC"
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/instances/1"
    }
  }
}

64.10. Job Step Executions

The job step executions endpoint provides information about the job step executions that are registered with the Spring Cloud Data Flow server. The following topics provide more detail:

64.10.1. List All Step Executions For a Job Execution

The job step executions endpoint lets you list all job step executions. The following topics provide more detail:

Request Structure
GET /jobs/executions/1/steps?page=0&size=10 HTTP/1.1
Host: localhost:9393
Request Parameters
Parameter Description

page

The zero-based page number (optional)

size

The requested page size (optional)

Example Request
$ curl 'http://localhost:9393/jobs/executions/1/steps?page=0&size=10' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1669

{
  "_embedded" : {
    "stepExecutionResourceList" : [ {
      "jobExecutionId" : 1,
      "stepExecution" : {
        "id" : 1,
        "version" : 0,
        "stepName" : "DOCJOB_STEP",
        "status" : "STARTING",
        "readCount" : 0,
        "writeCount" : 0,
        "commitCount" : 0,
        "rollbackCount" : 0,
        "readSkipCount" : 0,
        "processSkipCount" : 0,
        "writeSkipCount" : 0,
        "startTime" : "2018-06-05T10:34:23.411Z",
        "endTime" : null,
        "lastUpdated" : "2018-06-05T10:34:23.411Z",
        "executionContext" : {
          "dirty" : false,
          "empty" : true,
          "values" : [ ]
        },
        "exitStatus" : {
          "exitCode" : "EXECUTING",
          "exitDescription" : "",
          "running" : true
        },
        "terminateOnly" : false,
        "filterCount" : 0,
        "failureExceptions" : [ ],
        "jobParameters" : {
          "parameters" : { },
          "empty" : true
        },
        "jobExecutionId" : 1,
        "skipCount" : 0,
        "summary" : "StepExecution: id=1, version=0, name=DOCJOB_STEP, status=STARTING, exitStatus=EXECUTING, readCount=0, filterCount=0, writeCount=0 readSkipCount=0, writeSkipCount=0, processSkipCount=0, commitCount=0, rollbackCount=0"
      },
      "stepType" : "",
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/jobs/executions/1/steps/1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions/1/steps?page=0&size=10"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

64.10.2. Job Step Execution Detail

The job step executions endpoint lets you get details about a job step execution. The following topics provide more detail:

Request Structure
GET /jobs/executions/1/steps/1 HTTP/1.1
Host: localhost:9393
Table 15. /jobs/executions/{id}/steps/{stepid}
Parameter Description

id

The id of an existing job execution (required)

stepid

The id of an existing step execution for a specific job execution (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/jobs/executions/1/steps/1' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1211

{
  "jobExecutionId" : 1,
  "stepExecution" : {
    "id" : 1,
    "version" : 0,
    "stepName" : "DOCJOB_STEP",
    "status" : "STARTING",
    "readCount" : 0,
    "writeCount" : 0,
    "commitCount" : 0,
    "rollbackCount" : 0,
    "readSkipCount" : 0,
    "processSkipCount" : 0,
    "writeSkipCount" : 0,
    "startTime" : "2018-06-05T10:34:23.411Z",
    "endTime" : null,
    "lastUpdated" : "2018-06-05T10:34:23.411Z",
    "executionContext" : {
      "dirty" : false,
      "empty" : true,
      "values" : [ ]
    },
    "exitStatus" : {
      "exitCode" : "EXECUTING",
      "exitDescription" : "",
      "running" : true
    },
    "terminateOnly" : false,
    "filterCount" : 0,
    "failureExceptions" : [ ],
    "jobParameters" : {
      "parameters" : { },
      "empty" : true
    },
    "jobExecutionId" : 1,
    "skipCount" : 0,
    "summary" : "StepExecution: id=1, version=0, name=DOCJOB_STEP, status=STARTING, exitStatus=EXECUTING, readCount=0, filterCount=0, writeCount=0 readSkipCount=0, writeSkipCount=0, processSkipCount=0, commitCount=0, rollbackCount=0"
  },
  "stepType" : "",
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions/1/steps/1"
    }
  }
}

64.10.3. Job Step Execution Progress

The job step executions endpoint lets you get details about the progress of a job step execution. The following topics provide more detail:

Request Structure
GET /jobs/executions/1/steps/1/progress HTTP/1.1
Host: localhost:9393
Table 16. /jobs/executions/{id}/steps/{stepid}/progress
Parameter Description

id

The id of an existing job execution (required)

stepid

The id of an existing step execution for a specific job execution (required)

Request Parameters

There are no request parameters for this endpoint.

Example Request
$ curl 'http://localhost:9393/jobs/executions/1/steps/1/progress' -i
Response Structure
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2714

{
  "stepExecution" : {
    "id" : 1,
    "version" : 0,
    "stepName" : "DOCJOB_STEP",
    "status" : "STARTING",
    "readCount" : 0,
    "writeCount" : 0,
    "commitCount" : 0,
    "rollbackCount" : 0,
    "readSkipCount" : 0,
    "processSkipCount" : 0,
    "writeSkipCount" : 0,
    "startTime" : "2018-06-05T10:34:23.411Z",
    "endTime" : null,
    "lastUpdated" : "2018-06-05T10:34:23.411Z",
    "executionContext" : {
      "dirty" : false,
      "empty" : true,
      "values" : [ ]
    },
    "exitStatus" : {
      "exitCode" : "EXECUTING",
      "exitDescription" : "",
      "running" : true
    },
    "terminateOnly" : false,
    "filterCount" : 0,
    "failureExceptions" : [ ],
    "jobParameters" : {
      "parameters" : { },
      "empty" : true
    },
    "jobExecutionId" : 1,
    "skipCount" : 0,
    "summary" : "StepExecution: id=1, version=0, name=DOCJOB_STEP, status=STARTING, exitStatus=EXECUTING, readCount=0, filterCount=0, writeCount=0 readSkipCount=0, writeSkipCount=0, processSkipCount=0, commitCount=0, rollbackCount=0"
  },
  "stepExecutionHistory" : {
    "stepName" : "DOCJOB_STEP",
    "count" : 0,
    "commitCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "rollbackCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "readCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "writeCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "filterCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "readSkipCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "writeSkipCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "processSkipCount" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "duration" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    },
    "durationPerRead" : {
      "count" : 0,
      "min" : 0.0,
      "max" : 0.0,
      "mean" : 0.0,
      "standardDeviation" : 0.0
    }
  },
  "percentageComplete" : 0.5,
  "finished" : false,
  "duration" : 142.0,
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/jobs/executions/1/steps/1"
    }
  }
}

64.11. Runtime Information about Applications

It is possible to get information about running apps known to the system, either globally or individually. The following topics provide more detail:

64.11.1. Listing All Applications at Runtime

To retrieve information about all instances of all apps, query the /runtime/apps endpoint by using GET. The following topics provide more detail:

Request Structure
GET /runtime/apps HTTP/1.1
Accept: application/json
Host: localhost:9393
Example Request
$ curl 'http://localhost:9393/runtime/apps' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2555

{
  "_embedded" : {
    "appStatusResourceList" : [ {
      "deploymentId" : "mystream.http",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.http-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "47677",
              "pid" : "19312",
              "port" : "47677",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stdout_0.log",
              "url" : "http://10.194.6.15:47677",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.http/instances/mystream.http-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.http"
        }
      }
    }, {
      "deploymentId" : "mystream.log",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.log-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "40725",
              "pid" : "19310",
              "port" : "40725",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stdout_0.log",
              "url" : "http://10.194.6.15:40725",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.log/instances/mystream.log-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.log"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/runtime/apps?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.11.2. Querying All Instances of a Single App

To retrieve information about all instances of a particular app, query the /runtime/apps/<appId>/instances endpoint by using GET. The following topics provide more detail:

Request Structure
GET /runtime/apps HTTP/1.1
Accept: application/json
Host: localhost:9393
Example Request
$ curl 'http://localhost:9393/runtime/apps' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2555

{
  "_embedded" : {
    "appStatusResourceList" : [ {
      "deploymentId" : "mystream.http",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.http-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "47677",
              "pid" : "19312",
              "port" : "47677",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stdout_0.log",
              "url" : "http://10.194.6.15:47677",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.http/instances/mystream.http-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.http"
        }
      }
    }, {
      "deploymentId" : "mystream.log",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.log-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "40725",
              "pid" : "19310",
              "port" : "40725",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stdout_0.log",
              "url" : "http://10.194.6.15:40725",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.log/instances/mystream.log-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.log"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/runtime/apps?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.11.3. Querying a Single Instance of a Single App

Finally, to retrieve information about a particular instance of a particular app, query the /runtime/apps/<appId>/instances/<instanceId> endpoint by using GET. The following topics provide more detail:

Request Structure
GET /runtime/apps HTTP/1.1
Accept: application/json
Host: localhost:9393
Example Request
$ curl 'http://localhost:9393/runtime/apps' -i -H 'Accept: application/json'
Response Structure
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2555

{
  "_embedded" : {
    "appStatusResourceList" : [ {
      "deploymentId" : "mystream.http",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.http-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "47677",
              "pid" : "19312",
              "port" : "47677",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http/stdout_0.log",
              "url" : "http://10.194.6.15:47677",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834646/mystream.http"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.http/instances/mystream.http-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.http"
        }
      }
    }, {
      "deploymentId" : "mystream.log",
      "state" : "deploying",
      "instances" : {
        "_embedded" : {
          "appInstanceStatusResourceList" : [ {
            "instanceId" : "mystream.log-0",
            "state" : "deploying",
            "attributes" : {
              "guid" : "40725",
              "pid" : "19310",
              "port" : "40725",
              "stderr" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stderr_0.log",
              "stdout" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log/stdout_0.log",
              "url" : "http://10.194.6.15:40725",
              "working.dir" : "/tmp/spring-cloud-deployer-7523322796227723684/mystream-1528194834638/mystream.log"
            },
            "_links" : {
              "self" : {
                "href" : "http://localhost:9393/runtime/apps/mystream.log/instances/mystream.log-0"
              }
            }
          } ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:9393/runtime/apps/mystream.log"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:9393/runtime/apps?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

64.12. Metrics for Stream Applications

This REST endpoint exposes metrics for stream applications. It requires the Metrics Collector application to be running as a separate service. If it is not running, this endpoint returns an empty response.

In order to learn more about the Metrics Collector, please also refer to the “Monitoring Deployed Stream Applications” chapter.

The following topics provide more detail:

64.12.1. Request Structure

For example, a typical request might resemble the following:

GET /metrics/streams HTTP/1.1
Accept: application/json
Host: localhost:9393

64.12.2. Example Request

$ curl 'http://localhost:9393/metrics/streams' -i -H 'Accept: application/json'

64.12.3. Response Structure

This REST endpoint uses Hystrix through the Spring Cloud Netflix project under the covers to make a proxy HTTP request to the Metrics Collector.

64.12.4. Example Response

The endpoint does not generate an error when the Metrics Collector is not running. Rather, it gracefully degrades and returns an empty response such as the following:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 3

[ ]

However, if metrics are being collected and the Metrics Collector is running, you should see a response similar to the listing below. The metrics data returned in the listing below is based on the example stream definition created in the “Monitoring Deployed Stream Applications” chapter, where we created time | log with two instances of each application deployed.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 30240

[ {
  "name" : "foostream",
  "applications" : [ {
    "name" : "log120RS",
    "instances" : [ {
      "guid" : "13208",
      "index" : 1,
      "properties" : {
        "spring.cloud.dataflow.stream.app.label" : "log120RS",
        "spring.application.index" : "1",
        "spring.application.name" : "log-sink",
        "spring.cloud.dataflow.stream.name" : "foostream",
        "spring.cloud.application.guid" : "13208",
        "spring.cloud.dataflow.stream.app.type" : "sink",
        "spring.cloud.application.group" : "foostream"
      },
      "metrics" : [ {
        "name" : "integration.channel.input.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.sendCount",
        "value" : 373.0
      }, {
        "name" : "integration.channel.input.sendRate.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.input.sendRate.max",
        "value" : 2.01
      }, {
        "name" : "integration.channel.input.sendRate.min",
        "value" : 0.7
      }, {
        "name" : "integration.channel.input.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.sendRate.count",
        "value" : 373.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendCount",
        "value" : 74.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.max",
        "value" : 13.49
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.min",
        "value" : 5.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.count",
        "value" : 74.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.mean",
        "value" : 0.22
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.max",
        "value" : 5.42
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.min",
        "value" : 0.11
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.stdev",
        "value" : 0.17
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.count",
        "value" : 373.0
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handler.logSinkHandler.duration.mean",
        "value" : 0.22
      }, {
        "name" : "integration.handler.logSinkHandler.duration.max",
        "value" : 5.4
      }, {
        "name" : "integration.handler.logSinkHandler.duration.min",
        "value" : 0.11
      }, {
        "name" : "integration.handler.logSinkHandler.duration.stdev",
        "value" : 0.17
      }, {
        "name" : "integration.handler.logSinkHandler.duration.count",
        "value" : 373.0
      }, {
        "name" : "integration.handler.logSinkHandler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.mean",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.max",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.min",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handlerCount",
        "value" : 3.0
      }, {
        "name" : "integration.channelCount",
        "value" : 4.0
      }, {
        "name" : "integration.sourceCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.send.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.errorChannel.send.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.send.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.nullChannel.send.mean",
        "value" : 0.0
      } ]
    }, {
      "guid" : "60633",
      "index" : 0,
      "properties" : {
        "spring.cloud.dataflow.stream.app.label" : "log120RS",
        "spring.application.index" : "0",
        "spring.application.name" : "log-sink",
        "spring.cloud.dataflow.stream.name" : "foostream",
        "spring.cloud.application.guid" : "60633",
        "spring.cloud.dataflow.stream.app.type" : "sink",
        "spring.cloud.application.group" : "foostream"
      },
      "metrics" : [ {
        "name" : "integration.channel.input.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.sendCount",
        "value" : 372.0
      }, {
        "name" : "integration.channel.input.sendRate.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.input.sendRate.max",
        "value" : 1.98
      }, {
        "name" : "integration.channel.input.sendRate.min",
        "value" : 0.8
      }, {
        "name" : "integration.channel.input.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.sendRate.count",
        "value" : 372.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendCount",
        "value" : 74.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.max",
        "value" : 13.09
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.min",
        "value" : 5.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.count",
        "value" : 74.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.mean",
        "value" : 0.22
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.max",
        "value" : 3.46
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.min",
        "value" : 0.12
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.stdev",
        "value" : 0.18
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.duration.count",
        "value" : 372.0
      }, {
        "name" : "integration.handler.org.springframework.cloud.stream.app.log.sink.LogSinkConfiguration.logSinkHandler.serviceActivator.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handler.logSinkHandler.duration.mean",
        "value" : 0.21
      }, {
        "name" : "integration.handler.logSinkHandler.duration.max",
        "value" : 2.84
      }, {
        "name" : "integration.handler.logSinkHandler.duration.min",
        "value" : 0.11
      }, {
        "name" : "integration.handler.logSinkHandler.duration.stdev",
        "value" : 0.18
      }, {
        "name" : "integration.handler.logSinkHandler.duration.count",
        "value" : 372.0
      }, {
        "name" : "integration.handler.logSinkHandler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.mean",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.max",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.min",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.handlerCount",
        "value" : 3.0
      }, {
        "name" : "integration.channelCount",
        "value" : 4.0
      }, {
        "name" : "integration.sourceCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.input.send.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.errorChannel.send.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.send.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.nullChannel.send.mean",
        "value" : 0.0
      } ]
    } ],
    "aggregateMetrics" : [ {
      "name" : "integration.channel.nullChannel.send.mean",
      "value" : 0.0
    }, {
      "name" : "integration.channel.applicationMetrics.send.mean",
      "value" : 0.4
    }, {
      "name" : "integration.channel.errorChannel.send.mean",
      "value" : 0.0
    }, {
      "name" : "integration.channel.input.send.mean",
      "value" : 2.0
    } ]
  }, {
    "name" : "time120RS",
    "instances" : [ {
      "guid" : "50467",
      "index" : 0,
      "properties" : {
        "spring.cloud.dataflow.stream.app.label" : "time120RS",
        "spring.application.index" : "0",
        "spring.application.name" : "time-source",
        "spring.cloud.dataflow.stream.name" : "foostream",
        "spring.cloud.application.guid" : "50467",
        "spring.cloud.dataflow.stream.app.type" : "source",
        "spring.cloud.application.group" : "foostream"
      },
      "metrics" : [ {
        "name" : "integration.channel.output.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.sendCount",
        "value" : 369.0
      }, {
        "name" : "integration.channel.output.sendRate.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.sendRate.max",
        "value" : 1.02
      }, {
        "name" : "integration.channel.output.sendRate.min",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.sendRate.count",
        "value" : 369.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendCount",
        "value" : 73.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.max",
        "value" : 11.05
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.min",
        "value" : 5.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.count",
        "value" : 73.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.mean",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.max",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.min",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.source.org.springframework.cloud.stream.app.time.source.TimeSourceConfiguration.publishTime.inboundChannelAdapter.source.messageCount",
        "value" : 369.0
      }, {
        "name" : "integration.handlerCount",
        "value" : 1.0
      }, {
        "name" : "integration.channelCount",
        "value" : 4.0
      }, {
        "name" : "integration.sourceCount",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.send.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.errorChannel.send.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.send.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.nullChannel.send.mean",
        "value" : 0.0
      } ]
    }, {
      "guid" : "61434",
      "index" : 1,
      "properties" : {
        "spring.cloud.dataflow.stream.app.label" : "time120RS",
        "spring.application.index" : "1",
        "spring.application.name" : "time-source",
        "spring.cloud.dataflow.stream.name" : "foostream",
        "spring.cloud.application.guid" : "61434",
        "spring.cloud.dataflow.stream.app.type" : "source",
        "spring.cloud.application.group" : "foostream"
      },
      "metrics" : [ {
        "name" : "integration.channel.output.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.sendCount",
        "value" : 375.0
      }, {
        "name" : "integration.channel.output.sendRate.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.sendRate.max",
        "value" : 1.02
      }, {
        "name" : "integration.channel.output.sendRate.min",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.output.sendRate.count",
        "value" : 375.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.errorChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendCount",
        "value" : 74.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.max",
        "value" : 12.88
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.min",
        "value" : 5.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.sendRate.count",
        "value" : 74.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.errorRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendCount",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.max",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.min",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.channel.nullChannel.sendRate.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.mean",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.max",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.min",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.stdev",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.duration.count",
        "value" : 0.0
      }, {
        "name" : "integration.handler._org.springframework.integration.errorLogger.handler.activeCount",
        "value" : 0.0
      }, {
        "name" : "integration.source.org.springframework.cloud.stream.app.time.source.TimeSourceConfiguration.publishTime.inboundChannelAdapter.source.messageCount",
        "value" : 375.0
      }, {
        "name" : "integration.handlerCount",
        "value" : 1.0
      }, {
        "name" : "integration.channelCount",
        "value" : 4.0
      }, {
        "name" : "integration.sourceCount",
        "value" : 1.0
      }, {
        "name" : "integration.channel.output.send.mean",
        "value" : 1.0
      }, {
        "name" : "integration.channel.errorChannel.send.mean",
        "value" : 0.0
      }, {
        "name" : "integration.channel.applicationMetrics.send.mean",
        "value" : 0.2
      }, {
        "name" : "integration.channel.nullChannel.send.mean",
        "value" : 0.0
      } ]
    } ],
    "aggregateMetrics" : [ {
      "name" : "integration.channel.output.send.mean",
      "value" : 2.0
    }, {
      "name" : "integration.channel.nullChannel.send.mean",
      "value" : 0.0
    }, {
      "name" : "integration.channel.applicationMetrics.send.mean",
      "value" : 0.4
    }, {
      "name" : "integration.channel.errorChannel.send.mean",
      "value" : 0.0
    } ]
  } ]
} ]

Appendices

Having trouble with Spring Cloud Data Flow, We’d like to help!

Appendix A: Data Flow Template

As described in the previous chapter, Spring Cloud Data Flow’s functionality is completely exposed through REST endpoints. While you can use those endpoints directly, Spring Cloud Data Flow also provides a Java-based API, which makes using those REST endpoints even easier.

The central entry point is the DataFlowTemplate class in the org.springframework.cloud.dataflow.rest.client package.

This class implements the DataFlowOperations interface and delegates to the following sub-templates that provide the specific functionality for each feature-set:

Interface Description

StreamOperations

REST client for stream operations

CounterOperations

REST client for counter operations

FieldValueCounterOperations

REST client for field value counter operations

AggregateCounterOperations

REST client for aggregate counter operations

TaskOperations

REST client for task operations

JobOperations

REST client for job operations

AppRegistryOperations

REST client for app registry operations

CompletionOperations

REST client for completion operations

RuntimeOperations

REST Client for runtime operations

When the DataFlowTemplate is being initialized, the sub-templates can be discovered through the REST relations, which are provided by HATEOAS.[1]

If a resource cannot be resolved, the respective sub-template results in NULL. A common cause is that Spring Cloud Data Flow offers for specific sets of features to be enabled/disabled when launching. For more information, see “Feature Toggles”.

A.1. Using the Data Flow Template

When you use the Data Flow Template, the only needed Data Flow dependency is the Spring Cloud Data Flow Rest Client, as shown in the following Maven snippet:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-dataflow-rest-client</artifactId>
  <version>1.5.1.RELEASE</version>
</dependency>

With that dependency, you get the DataFlowTemplate class as well as all the dependencies needed to make calls to a Spring Cloud Data Flow server.

When instantiating the DataFlowTemplate, you also pass in a RestTemplate. Please be aware that the needed RestTemplate requires some additional configuration to be valid in the context of the DataFlowTemplate. When declaring a RestTemplate as a bean, the following configuration suffices:

  @Bean
  public static RestTemplate restTemplate() {
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.setErrorHandler(new VndErrorResponseErrorHandler(restTemplate.getMessageConverters()));
    for(HttpMessageConverter<?> converter : restTemplate.getMessageConverters()) {
      if (converter instanceof MappingJackson2HttpMessageConverter) {
        final MappingJackson2HttpMessageConverter jacksonConverter =
            (MappingJackson2HttpMessageConverter) converter;
        jacksonConverter.getObjectMapper()
            .registerModule(new Jackson2HalModule())
            .addMixIn(JobExecution.class, JobExecutionJacksonMixIn.class)
            .addMixIn(JobParameters.class, JobParametersJacksonMixIn.class)
            .addMixIn(JobParameter.class, JobParameterJacksonMixIn.class)
            .addMixIn(JobInstance.class, JobInstanceJacksonMixIn.class)
            .addMixIn(ExitStatus.class, ExitStatusJacksonMixIn.class)
            .addMixIn(StepExecution.class, StepExecutionJacksonMixIn.class)
            .addMixIn(ExecutionContext.class, ExecutionContextJacksonMixIn.class)
            .addMixIn(StepExecutionHistory.class, StepExecutionHistoryJacksonMixIn.class);
      }
    }
    return restTemplate;
  }

Now you can instantiate the DataFlowTemplate with the following code:

DataFlowTemplate dataFlowTemplate = new DataFlowTemplate(
    new URI("http://localhost:9393/"), restTemplate);         (1)
1 The URI points to the ROOT of your Spring Cloud Data Flow Server.

Depending on your requirements, you can now make calls to the server. For instance, if you want to get a list of currently available applications you can run the following code:

PagedResources<AppRegistrationResource> apps = dataFlowTemplate.appRegistryOperations().list();

System.out.println(String.format("Retrieved %s application(s)",
    apps.getContent().size()));

for (AppRegistrationResource app : apps.getContent()) {
  System.out.println(String.format("App Name: %s, App Type: %s, App URI: %s",
    app.getName(),
    app.getType(),
    app.getUri()));
}

Appendix B: “How-to” guides

This section provides answers to some common ‘how do I do that…​’ type of questions that often arise when using Spring Cloud Data Flow.

If you are having a specific problem that we do not cover here, you might want to check out stackoverflow.com to see if someone has already provided an answer. That is also a great place to ask new questions (please use the spring-cloud-dataflow tag).

We are also more than happy to extend this section. If you want to add a “how-to”, you can send us a pull request.

B.1. Configure Maven Properties

You can set the maven properties such as local maven repository location, remote maven repositories, authentication credentials, and proxy server properties through command line properties when starting the Data Flow server. Alternatively, you can set the properites using SPRING_APPLICATION_JSON environment property for the Data Flow server.

The remote maven repositories need to be configured explicitly if the apps are resolved using maven repository, except for a local Data Flow server. The other Data Flow server implementations (that use maven resources for app artifacts resolution) have no default value for remote repositories. The local server has repo.spring.io/libs-snapshot as the default remote repository.

To pass the properties as commandline options, run the server with a command similar to the following:

$ java -jar <dataflow-server>.jar --maven.localRepository=mylocal
--maven.remote-repositories.repo1.url=https://repo1
--maven.remote-repositories.repo1.auth.username=repo1user
--maven.remote-repositories.repo1.auth.password=repo1pass
--maven.remote-repositories.repo2.url=https://repo2 --maven.proxy.host=proxyhost
--maven.proxy.port=9018 --maven.proxy.auth.username=proxyuser
--maven.proxy.auth.password=proxypass

You can also use the SPRING_APPLICATION_JSON environment property:

export SPRING_APPLICATION_JSON='{ "maven": { "local-repository": "local","remote-repositories": { "repo1": { "url": "https://repo1", "auth": { "username": "repo1user", "password": "repo1pass" } },
"repo2": { "url": "https://repo2" } }, "proxy": { "host": "proxyhost", "port": 9018, "auth": { "username": "proxyuser", "password": "proxypass" } } } }'

Here is the same content in nicely formatted JSON:

SPRING_APPLICATION_JSON='{
  "maven": {
    "local-repository": "local",
    "remote-repositories": {
      "repo1": {
        "url": "https://repo1",
        "auth": {
          "username": "repo1user",
          "password": "repo1pass"
        }
      },
      "repo2": {
        "url": "https://repo2"
      }
    },
    "proxy": {
      "host": "proxyhost",
      "port": 9018,
      "auth": {
        "username": "proxyuser",
        "password": "proxypass"
      }
    }
  }
}'
Depending on the Spring Cloud Data Flow server implementation, you may have to pass the environment properties by using the platform specific environment-setting capabilities. For instance, in Cloud Foundry, you would pass them as cf set-env SPRING_APPLICATION_JSON.

B.2. Logging

Spring Cloud Data Flow is built upon several Spring projects, but ultimately the dataflow-server is a Spring Boot app, so the logging techniques that apply to any Spring Boot application are applicable here as well.

While troubleshooting, the two primary areas where enabling the DEBUG logs could be useful are

B.2.1. Deployment Logs

Spring Cloud Data Flow builds upon Spring Cloud Deployer SPI, and the platform-specific dataflow server uses the respective SPI implementations. Specifically, if we were to troubleshoot deployment specific issues, such as network errors, it would be useful to enable the DEBUG logs at the underlying deployer and the libraries used by it.

To enable DEBUG logs for the local-deployer, start the server as follows:

$ java -jar <dataflow-server>.jar --logging.level.org.springframework.cloud.deployer.spi.local=DEBUG

(where org.springframework.cloud.deployer.spi.local is the global package for everything local-deployer related.)

To enable DEBUG logs for the cloudfoundry-deployer, set the following environment variable and, after restaging the dataflow server, you can see more logs around request and response and see detailed stack traces for failures. The cloudfoundry deployer uses cf-java-client, so you must also enable DEBUG logs for this library.

$ cf set-env dataflow-server JAVA_OPTS '-Dlogging.level.cloudfoundry-client=DEBUG'
$ cf restage dataflow-server

(where cloudfoundry-client is the global package for everything cf-java-client related.)

To review Reactor logs, which are used by the cf-java-client, then the following commad would be helpful:

$ cf set-env dataflow-server JAVA_OPTS '-Dlogging.level.cloudfoundry-client=DEBUG -Dlogging.level.reactor.ipc.netty=DEBUG'
$ cf restage dataflow-server

(where reactor.ipc.netty is the global package for everything reactor-netty related.)

Similar to the local-deployer and cloudfoundry-deployer options as discussed above, there are equivalent settings available for Apache YARN, Apache Mesos, and Kubernetes variants. See the respective SPI implementations for more detail about the packages to configure for logging.

B.2.2. Application Logs

The streaming applications in Spring Cloud Data Flow are Spring Cloud Stream applications, which are in turn based on Spring Boot. They can be independently setup with logging configurations.

For instance, if you must troubleshoot the header and payload specifics that are being passed around source, processor, and sink channels, you should deploy the stream with the following options:

dataflow:>stream create foo --definition "http --logging.level.org.springframework.integration=DEBUG | transform --logging.level.org.springframework.integration=DEBUG | log --logging.level.org.springframework.integration=DEBUG" --deploy

(where org.springframework.integration is the global package for everything Spring Integration related, which is responsible for messaging channels.)

These properties can also be specified with deployment properties when deploying the stream, as follows:

dataflow:>stream deploy foo --properties "app.*.logging.level.org.springframework.integration=DEBUG"

B.2.3. Remote Debugging

The Data Flow local server lets you debug the deployed applications. This is accomplished by enabling the remote debugging feature of the JVM through deployment properites, as shown in the following example:

stream deploy --name mystream --properties "deployer.fooApp.local.debugPort=9999"

The preceding example starts the fooApp application in debug mode, allowing a remote debugger to be attached on port 9999. By default, the application starts in a ’suspend’ mode and waits for the remote debug session to be attached (started). Otherwise, you can provide an additional debugSuspend property with value n.

Also, when there is more then one instance of the application, the debug port for each instance is the value of debugPort + instanceId.

Unlike other properties you must NOT use a wildcard for the application name, since each application must use a unique debug port.

B.2.4. Log Redirect

Given that each application is a separate process that maintains its own set of logs, accessing individual logs could be a bit inconvenient, especially in the early stages of development, when logs are accessed more often. Since it is also a common pattern to rely on a local SCDF Server that deploys each application as a local JVM process, you can redirect the stdout and stdin from the deployed applications to the parent process. Thus, with a local SCDF Server, the application logs appear in the logs of the running local SCDF Server.

Typically when you deploy the stream, you see something resembling the following in the server logs:

017-06-28 09:50:16.372  INFO 41161 --- [nio-9393-exec-7] o.s.c.d.spi.local.LocalAppDeployer       : Deploying app with deploymentId mystream.myapp instance 0.
   Logs will be in /var/folders/l2/63gcnd9d7g5dxxpjbgr0trpw0000gn/T/spring-cloud-dataflow-5939494818997196225/mystream-1498661416369/mystream.myapp

However, by setting local.inheritLogging=true as a deployment property, you can see the following:

017-06-28 09:50:16.372  INFO 41161 --- [nio-9393-exec-7] o.s.c.d.spi.local.LocalAppDeployer       : Deploying app with deploymentId mystream.myapp instance 0.
   Logs will be inherited.

After that, the application logs appear alongside the server logs, as shown in the following example:

stream deploy --name mystream --properties "deployer.*.local.inheritLogging=true”

The preceding stream definition enables log redirection for each application in the stream. The following stream definition enables log redirection for only the application named ‘my app’.

stream deploy --name mystream --properties "deployer.myapp.local.inheritLogging=true”
Log redirect is only supported with local-deployer.

B.3. Frequently Asked Questions

In this section, we review the frequently asked questions in Spring Cloud Data Flow.

B.3.1. Advanced SpEL Expressions

One of the powerful features of SpEL expressions is functions. If the appropriate libraries are in the classpath, Spring Integration provides the jsonPath() and xpath() SpEL-functions. All the provided Spring Cloud Stream application starters are have with the json-path and spring-integration-xml in their uber-jar. Consequently, we can use those SpEL-functions in Spring Cloud Data Flow streams whenever expressions are possible. For example, we can transform JSON-aware payload from the HTTP request by using a few jsonPath() expressions, as follows:

dataflow:>stream create jsonPathTransform --definition "http | transform --expression=#jsonPath(payload,'$.price') | log" --deploy
...
dataflow:> http post --target http://localhost:8080 --data {"symbol":"SCDF","price":72.04}
dataflow:> http post --target http://localhost:8080 --data {"symbol":"SCDF","price":72.06}
dataflow:> http post --target http://localhost:8080 --data {"symbol":"SCDF","price":72.08}

In the preceding example, we apply jsonPath for the incoming payload to extract only the price field value. Similar syntax can be used with splitter or filter expression options. Actually, any available SpEL-based option has access to the built-in SpEL-functions. For example, we can extract some value from JSON data to calculate the partitionKey before sending output to the Binder, as follows:

dataflow:>stream deploy foo --properties "deployer.transform.count=2,app.transform.producer.partitionKeyExpression=#jsonPath(payload,'$.symbol')"

The same syntax can be applied for xpath() SpEL-function when you deal with XML data. Any other custom SpEL-function can also be used. However, for this purpose, you should build a library with a @Configuration class containing an appropriate SpelFunctionFactoryBean @Bean definition. The target Spring Cloud Stream application starter should be repackaged to supply such a custom extension with a built-in Spring Boot @ComponentScan mechanism or auto-configuration hook.

B.3.2. How to Use JDBC-sink?

The JDBC-sink can be used to insert message payload data into a relational database table. By default, it inserts the entire payload into a table named after the jdbc.table-name property. If it is not set, by default, the application expects to use a table with a name of messages. To alter this behavior, the JDBC sink accepts several options that you can pass by using the --param=value notation in the stream or change globally. The JDBC sink has a jdbc.initialize property that, if set to true, results in the sink creating a table based on the specified configuration when it starts. If that initialize property is false, which is the default, you must make sure that the table to use is already available.

A stream definition using jdbc sink and relying on all defaults with MySQL as the backing database looks like the following example:

dataflow:>stream create --name mydata --definition "time | jdbc --spring.datasource.url=jdbc:mysql://localhost:3306/test --spring.datasource.username=root --spring.datasource.password=root --spring.datasource.driver-class-name=org.mariadb.jdbc.Driver" --deploy

In the preceding example, the system time is persisted in MySQL for every second. For this to work, you must have the following table in the MySQL database:

CREATE TABLE test.messages
(
  payload varchar(255)
);
mysql> desc test.messages;
+---------+--------------+------+-----+---------+-------+
| Field   | Type         | Null | Key | Default | Extra |
+---------+--------------+------+-----+---------+-------+
| payload | varchar(255) | YES  |     | NULL    |       |
+---------+--------------+------+-----+---------+-------+
1 row in set (0.00 sec)
mysql> select * from test.messages;
+-------------------+
| payload           |
+-------------------+
| 04/25/17 09:10:04 |
| 04/25/17 09:10:06 |
| 04/25/17 09:10:07 |
| 04/25/17 09:10:08 |
| 04/25/17 09:10:09 |
.............
.............
.............

B.3.3. How to Use Multiple Message-binders?

For situations where the data is consumed and processed between two different message brokers, Spring Cloud Data Flow provides easy-to-override global configurations, an out-of-the-box bridge-processor, and DSL primitives to build these type of topologies.

Assume that data is queueing up in RabbitMQ (for example, queue = myRabbit) and the requirement is to consume all the payloads and publish them to Apache Kafka (for example, topic = myKafka), as the destination for downstream processing.

In that case, you should follow the global application of configurations to define multiple binder configurations, as shown in the following configuration

# Apache Kafka Global Configurations (that is, identified by "kafka1")
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.kafka1.type=kafka
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.kafka1.environment.spring.cloud.stream.kafka.binder.brokers=localhost:9092
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.kafka1.environment.spring.cloud.stream.kafka.binder.zkNodes=localhost:2181

# RabbitMQ Global Configurations (that is, identified by "rabbit1")
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.rabbit1.type=rabbit
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.rabbit1.environment.spring.rabbitmq.host=localhost
spring.cloud.dataflow.applicationProperties.stream.spring.cloud.stream.binders.rabbit1.environment.spring.rabbitmq.port=5672
In the preceding example, both message brokers are running locally and are reachable at localhost through their respective ports.

These properties can be supplied in a .properties file that is accessible to the server directly or through config-server, as follows:

java -jar spring-cloud-dataflow-server-local/target/spring-cloud-dataflow-server-local-1.5.1.RELEASE.jar --spring.config.location=/foo.properties

Spring Cloud Data Flow internally uses bridge-processor to directly connect different named channel destinations. Since we are publishing and subscribing from two different messaging systems, you must build the bridge-processor with both RabbitMQ and Apache Kafka binders in the classpath. To do that, head over to start-scs.cfapps.io/ and select Bridge Processor, Kafka binder starter, and Rabbit binder starter as the dependencies and follow the patching procedure described in the reference guide. Specifically, for the bridge-processor, you must import the BridgeProcessorConfiguration provided by the starter.

Once you have the necessary adjustments, you can build the application. The following example registers the name of the application as multiBinderBridge:

dataflow:>app register --type processor --name multiBinderBridge --uri file:///<PATH-TO-FILE>/multipleBinderBridge-0.0.1-SNAPSHOT.jar

It is time to create a stream definition with the newly registered processor application, as follows:

dataflow:>stream create fooRabbitToBarKafka --definition ":fooRabbit > multiBinderBridge --spring.cloud.stream.bindings.input.binder=rabbit1 --spring.cloud.stream.bindings.output.binder=kafka1 > :barKafka" --deploy
Since we want to consume messages from RabbitMQ (identified by rabbit1) and then publish the payload to Apache Kafka (identified by kafka1), we are supplying them as the input and output channel settings respectively.
The stream consumes events from the myRabbit queue in RabbitMQ and sends the data to the myKafka topic in Apache Kafka.

Appendix C: Spring XD to SCDF

This appendix describes how to migrate from Spring XD to Spring Cloud Data Flow, along with some tips and tricks that may be helpful.

C.1. Terminology Changes

The following table describes the changes in terminology from Spring XD to Spring Cloud Data Flow:

Old New

XD-Admin

Server (implementations: local, Cloud Foundry, Apache Yarn, Kubernetes, and Apache Mesos)

XD-Container

N/A

Modules

Applications

Admin UI

Dashboard

Message Bus

Binders

Batch / Job

Task

C.2. Modules to Applications

If you have custom Spring XD modules, you need refactor them to use Spring Cloud Stream and Spring Cloud Task annotations. As part of that work, you need to update dependencies and build them as normal Spring Boot applications.

C.2.1. Custom Applications

As you convert custom applications, keep the following information in mind:

C.2.2. Application Registration

As you register your applications, keep the following information in mind:

  • Custom Stream/Task applications require being installed to a Maven repository for local, Yarn, and Cloud Foundry implementations or, as docker images, when deploying to Kubernetes or Mesos. Other than Maven and docker resolution, you can also resolve application artifacts from http, file, or as hdfs coordinates.

  • Unlike Spring XD, you do not have to upload the application bits while registering custom applications anymore. Instead, you need to register the application coordinates that are hosted in the Maven repository or by other means as discussed in the previous bullet.

  • By default, none of the out-of-the-box applications are preloaded. It is intentionally designed to provide the flexibility to register apps as you find appropriate for the given use-case requirement.

  • Depending on the binder choice, you can manually add the appropriate binder dependency to build applications specific to that binder-type. Alternatively, you can follow the Spring Initializr procedure to create an application with binder embedded in it.

C.2.3. Application Properties

As you modify your applications' properties, keep the following information in mind:

  • Counter-sink:

    • The peripheral redis is not required in Spring Cloud Data Flow. If you intend to use the counter-sink, then redis is required, and you need to have your own running redis cluster.

  • field-value-counter-sink:

    • The peripheral redis is not required in Spring Cloud Data Flow. If you intend to use the field-value-counter-sink, then redis becomes required, and you need to have your own running redis cluster.

  • Aggregate-counter-sink:

    • The peripheral redis is not required in Spring Cloud Data Flow. If you intend to use the aggregate-counter-sink, then redis becomes required, and you need to have your own running redis cluster.

C.3. Message Bus to Binders

Terminology wise, in Spring Cloud Data Flow, the message bus implementation is commonly referred to as binders.

C.3.1. Message Bus

Similar to Spring XD, Spring Cloud Data Flow includes an abstraction that you can use to extend the binder interface. By default, we take the opinionated view of Apache Kafka and RabbitMQ as the production-ready binders. They are available as GA releases.

C.3.2. Binders

Selecting a binder requires providing the right binder dependency in the classpath. If you choose Kafka as the binder, you need to register stream applications that are pre-built with Kafka binder in it. If you to create a custom application with Kafka binder, you need add the following dependency in the classpath:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-stream-binder-kafka</artifactId>
    <version>1.0.2.RELEASE</version>
</dependency>
  • Spring Cloud Stream supports Apache Kafka and RabbitMQ. All binder implementations are maintained and managed in their individual repositories.

  • Every Stream/Task application can be built with the binder implementation of your choice. All the out-of-the-box applications are pre-built for both Kafka and Rabbit and are readily available for use as Maven artifacts (Spring Cloud Stream or Spring Cloud Task) or as Docker images (Spring Cloud Stream or Spring Cloud Task). Changing the binder requires selecting the right binder dependency. Alternatively, you can download the pre-built application from this version of Spring Initializr with the desired “binder-starter” dependency.

C.3.3. Named Channels

Fundamentally, all the messaging channels are backed by pub/sub semantics. Unlike Spring XD, the messaging channels are backed only by topics or topic-exchange and there is no representation of queues in the new architecture.

  • ${xd.module.index} is no longer supported. Instead, you can directly interact with named destinations.

  • stream.index changes to :<stream-name>.<label/app-name>

    • For example, ticktock.0 changes to :ticktock.time.

  • “topic/queue” prefixes are not required to interact with named-channels.

    • For example, topic:mytopic changes to :mytopic.

    • For example, stream create stream1 --definition ":foo > log".

C.3.4. Directed Graphs

If you build non-linear streams, you can take advantage of named destinations to build directed graphs.

Consider the following example from Spring XD:

stream create f --definition "queue:foo > transform --expression=payload+'-sample1' | log" --deploy
stream create b --definition "queue:bar > transform --expression=payload+'-sample2' | log" --deploy
stream create r --definition "http | router --expression=payload.contains('a')?'queue:sample1':'queue:sample2'" --deploy

You can do the following in Spring Cloud Data Flow:

stream create f --definition ":foo > transform --expression=payload+'-sample1' | log" --deploy
stream create b --definition ":bar > transform --expression=payload+'-sample2' | log" --deploy
stream create r --definition "http | router --expression=payload.contains('a')?'sample1':'sample2'" --deploy

C.4. Batch to Tasks

A Task, by definition, is any application that does not run forever, and they end at some point. Tasks include Spring Batch jobs. Task applications can be used for on-demand use cases, such as database migration, machine learning, scheduled operations, and others. With Spring Cloud Task, you can build Spring Batch jobs as microservice applications.

  • Spring Batch jobs from Spring XD are being refactored to Spring Boot applications, also known as Spring Cloud Task applications.

  • Unlike Spring XD, these tasks do not require explicit deployment. Instead, a task is ready to be launched directly once the definition is declared.

C.5. Shell and DSL Command Changes

The following table shows the changes to shell and DSL commands:

Old Command New Command

module upload

app register / app import

module list

app list

module info

app info

admin config server

dataflow config server

job create

task create

job launch

task launch

job list

task list

job status

task status

job display

task display

job destroy

task destroy

job execution list

task execution list

runtime modules

runtime apps

C.6. REST API Changes

The following table shows the changes to the REST API:

Old API New API

/modules

/apps

/runtime/modules

/runtime/apps

/runtime/modules/{moduleId}

/runtime/apps/{appId}

/jobs/definitions

/task/definitions

/jobs/deployments

/task/deployments

C.7. UI (including Flo)

The Admin-UI is now named Dashboard. The URI for accessing the Dashboard is changed from localhost:9393/admin-ui to localhost:9393/dashboard.

  • Apps (a new view): Lists all the registered applications that are available for use. This view includes details such as the URI and the properties supported by each application. You can also register/unregister applications from this view.

  • Runtime (was Container): Container changes to Runtime. The notion of xd-container is gone, replaced by out-of-the-box applications running as autonomous Spring Boot applications. The Runtime tab displays the applications running in the runtime platforms (implementations: Cloud Foundry, Apache Yarn, Apache Mesos, or Kubernetes). You can click on each application to review relevant details, such as where it is running, what resources it uses, and other details.

  • Spring Flo is now an OSS product. Flo for Spring Cloud Data Flow’s “Create Stream” is now the designer-tab in the Dashboard.

  • Tasks (a new view):

    • The “Modules” sub-tab is renamed to “Apps”.

    • The “Definitions” sub-tab lists all the task definitions, including Spring Batch jobs that are orchestrated as tasks.

    • The “Executions” sub-tab lists all the task execution details in a fashion similar to the listing of Spring XD’s Job executions.

C.8. Architecture Components

Spring Cloud Data Flow comes with a significantly simplified architecture. In fact, when compared with Spring XD, you need fewer peripherals to use Spring Cloud Data Flow.

C.8.1. ZooKeeper

ZooKeeper is not used in the new architecture.

C.8.2. RDBMS

Spring Cloud Data Flow uses an RDBMS instead of Redis for stream/task definitions, application registration, and for job repositories. The default configuration uses an embedded H2 instance, but Oracle, DB2, SqlServer, MySQL/MariaDB, PostgreSQL, H2, and HSQLDB databases are supported. To use Oracle, DB2, and SqlServer, you need to create your own Data Flow Server by using Spring Initializr and add the appropriate JDBC driver dependency.

C.8.3. Redis

Running a Redis cluster is only required for analytics functionality. Specifically, when you use the counter-sink, field-value-counter-sink, or aggregate-counter-sink applications, you also need to have a running instance of Redis cluster.

C.8.4. Cluster Topology

Spring XD’s xd-admin and xd-container server components are replaced by stream and task applications that are themselves running as autonomous Spring Boot applications. The applications run natively on various platforms, including Cloud Foundry, Apache YARN, Apache Mesos, and Kubernetes. You can develop, test, deploy, scale up or down, and interact with (Spring Boot) applications individually, and they can evolve in isolation.

C.9. Central Configuration

To support centralized and consistent management of an application’s configuration properties, Spring Cloud Config client libraries have been included in the Spring Cloud Data Flow server as well as the Spring Cloud Stream applications provided by the Spring Cloud Stream App Starters. You can also pass common application properties to all streams when the Data Flow Server starts.

C.10. Distribution

Spring Cloud Data Flow is a Spring Boot application. Depending on the platform of your choice, you can download the respective release uber jar and deploy or push it to the runtime platform (Cloud Foundry, Apache Yarn, Kubernetes, or Apache Mesos). For example, if you run Spring Cloud Data Flow on Cloud Foundry, you can download the Cloud Foundry server implementation and do a cf push, as explained in the Cloud Foundry Reference Guide.

C.11. Hadoop Distribution Compatibility

The hdfs-sink application builds upon Spring Hadoop 2.4.0 release, so this application is compatible with the following Hadoop distributions:

  • Cloudera: cdh5

  • Pivotal Hadoop: phd30

  • Hortonworks Hadoop: hdp24

  • Hortonworks Hadoop: hdp23

  • Vanilla Hadoop: hadoop26

  • Vanilla Hadoop: 2.7.x (default)

C.12. YARN Deployment

Spring Cloud Data Flow can be deployed and used with Apche YARN in two different ways:

  • Deploy the server directly in a YARN cluster.

  • Use the Apache Ambari plugin to provision Spring Cloud Data Flow as a service.

C.13. Use Case Comparison

The remainder of this appendix reviews some use cases to show the differences between Spring XD and Spring Cloud Data Flow.

C.13.1. Use Case #1: Ticktock

This use case assumes that you have already downloaded both the XD and the SCDF distributions.

Description: Simple ticktock example using local/singlenode.

The following table describes the differences:

Spring XD Spring Cloud Data Flow

Start an xd-singlenode server from CLI

→ xd-singlenode

Start a binder of your choice

Start a local-server implementation of SCDF from the CLI

→ java -jar spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar

Start an xd-shell server from the CLI

→ xd-shell

Start dataflow-shell server from the CLI

→ java -jar spring-cloud-dataflow-shell-1.0.0.BUILD-SNAPSHOT.jar

Create ticktock stream

xd:>stream create ticktock --definition “time | log” --deploy

Create ticktock stream

dataflow:>stream create ticktock --definition “time | log” --deploy

Review ticktock results in the xd-singlenode server console

Review ticktock results by using the tail commang to view the ticktock.log/stdout_log application logs

C.13.2. Use Case #2: Stream with Custom Module or Application

This use case assumes that you have already downloaded both the XD and the SCDF distributions.

Description: Stream with custom module or application.

The following table describes the differences:

Spring XD Spring Cloud Data Flow

Start an xd-singlenode server from CLI

→ xd-singlenode

Start a binder of your choice

Start a local-server implementation of SCDF from the CLI

→ java -jar spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar

Start an xd-shell server from the CLI

→ xd-shell

Start dataflow-shell server from the CLI

→ java -jar spring-cloud-dataflow-shell-1.0.0.BUILD-SNAPSHOT.jar

Register a custom “processor” module to transform the payload to the desired format

xd:>module upload --name toupper --type processor --file <CUSTOM_JAR_FILE_LOCATION>

Register custom “processor” application to transform payload to a desired format

dataflow:>app register --name toupper --type processor --uri <MAVEN_URI_COORDINATES>

Create a stream with a custom module

xd:>stream create testupper --definition “http | toupper | log” --deploy

Create a stream with custom application

dataflow:>stream create testupper --definition “http | toupper | log” --deploy

Review results in the xd-singlenode server console

Review results by using the tail command to view the testupper.log/stdout_log application logs

C.13.3. Use Case #3: Batch Job

This use case assumes that you have already downloaded both the XD and the SCDF distributions.

Description: batch-job.

Spring XD Spring Cloud Data Flow

Start an xd-singlenode server from CLI

→ xd-singlenode

Start a local-server implementation of SCDF from the CLI

→ java -jar spring-cloud-dataflow-server-local-1.0.0.BUILD-SNAPSHOT.jar

Start an xd-shell server from the CLI

→ xd-shell

Start dataflow-shell server from the CLI

→ java -jar spring-cloud-dataflow-shell-1.0.0.BUILD-SNAPSHOT.jar

Register a custom “batch job” module

xd:>module upload --name simple-batch --type job --file <CUSTOM_JAR_FILE_LOCATION>

Register a custom “batch-job” as task application

dataflow:>app register --name simple-batch --type task --uri <MAVEN_URI_COORDINATES>

Create a job with custom batch-job module

xd:>job create batchtest --definition “simple-batch”

Create a task with a custom batch-job application

dataflow:>task create batchtest --definition “simple-batch”

Deploy job

xd:>job deploy batchtest

NA

Launch job

xd:>job launch batchtest

Launch task

dataflow:>task launch batchtest

Review results in the xd-singlenode server console as well as the Jobs tab in the UI (executions sub-tab should include all step details)

Review results by using the tail command to view the batchtest/stdout_log application logs as well as the Task tab in UI (the executions sub-tab should include all step details)

Appendix D: Building

To build the source, you need to install JDK 1.8.

The build uses the Maven wrapper so that you do not have to install a specific version of Maven. To enable the tests for Redis, run the server before building. More information on how to run Redis appears later in this appendix.

The main build command is as follows:

$ ./mvnw clean install

If you like, you can add '-DskipTests' to avoid running the tests.

You can also install Maven (>=3.3.3) yourself and run the mvn command in place of ./mvnw in the examples below. If you do that, you also might need to add -P spring if your local Maven settings do not contain repository declarations for Spring pre-release artifacts.
You might need to increase the amount of memory available to Maven by setting a MAVEN_OPTS environment variable with a value similar to -Xmx512m -XX:MaxPermSize=128m. We try to cover this in the .mvn configuration, so, if you find you have to do it to make a build succeed, please raise a ticket to get the settings added to source control.

D.1. Documentation

There is a full profile that generates documentation. You can build only the documentation by using the following command:

$ ./mvnw clean package -DskipTests -P full -pl spring-cloud-dataflow-docs -am

D.2. Working with the Code

If you do not have an IDE preference, we recommend that you use Spring Tools Suite or Eclipse when working with the code. We use the m2eclipse Eclipse plugin for Maven support. Other IDEs and tools generally also work without issue.

D.2.1. Importing into Eclipse with m2eclipse

We recommend the m2eclipe eclipse plugin when working with Eclipse. If you do not already have m2eclipse installed, it is available from the Eclipse marketplace.

Unfortunately, m2e does not yet support Maven 3.3. Consequently, once the projects are imported into Eclipse, you also need to tell m2eclipse to use the .settings.xml file for the projects. If you do not do this, you may see many different errors related to the POMs in the projects. To do so:

  1. Open your Eclipse preferences.

  2. Expand the Maven preferences.

  3. Select User Settings.

  4. In the User Settings field, click Browse and navigate to the Spring Cloud project you imported.

  5. Select the .settings.xml file in that project.

  6. Click Apply.

  7. Click OK.

Alternatively, you can copy the repository settings from Spring Cloud’s .settings.xml file into your own ~/.m2/settings.xml.

D.2.2. Importing into Eclipse without m2eclipse

If you prefer not to use m2eclipse, you can generate Eclipse project metadata by using the following command:

$ ./mvnw eclipse:eclipse

The generated Eclipse projects can be imported by selecting Import existing projects from the File menu.

Appendix E: Contributing

Spring Cloud is released under the non-restrictive Apache 2.0 license and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master. If you want to contribute even something trivial, please do not hesitate, but follow the guidelines below.

E.1. Sign the Contributor License Agreement

Before we accept a non-trivial patch or pull request, we need you to sign the contributor’s agreement. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team and be given the ability to merge pull requests.

E.2. Code Conventions and Housekeeping

None of the following guidelines is essential for a pull request, but they all help your fellow developers understand and work with your code. They can also be added after the original pull request but before a merge.

  • Use the Spring Framework code format conventions. If you use Eclipse, you can import formatter settings by using the eclipse-code-formatter.xml file from the Spring Cloud Build project. If using IntelliJ, you can use the Eclipse Code Formatter Plugin to import the same file.

  • Make sure all new .java files have a simple Javadoc class comment with at least an @author tag identifying you, and preferably at least a paragraph describing the class’s purpose.

  • Add the ASF license header comment to all new .java files (to do so, copy from existing files in the project).

  • Add yourself as an @author to the .java files that you modify substantially (more than cosmetic changes).

  • Add some Javadocs and, if you change the namespace, some XSD doc elements.

  • A few unit tests would help a lot as well. Someone has to do it, and your fellow developers appreciate the effort.

  • If no one else uses your branch, rebase it against the current master (or other target branch in the main project).

  • When writing a commit message, follow these conventions. If you fix an existing issue, add Fixes gh-XXXX (where XXXX is the issue number) at the end of the commit message.


1. HATEOAS stands for Hypermedia as the Engine of Application State