Tasks Resource

This resource exposes endpoints to support operations at the tasks scope. The initial implementation includes the ability to list all the tasks for a particular job. This is a sub-resource of the Jobs Resource » and is not intended to be used independently.

Responses of individual endpoints will vary in accordance with their functionality and scope. However, the error messages of all of the tasks resource end points will be of the following form.

Error Message

Every error response will have the following structure:

{
    "message": "Unrecognized status parameter: null"
}

message is the only field in the response and contains a description of the problem.

Get All Tasks

Lists the complete details about all the tasks for a particular job

Request
GET /v1/jobs/{jobName}/{jobId}/tasks
Response

Status: 200 OK

[
{
   "preferredHost" : "samza-preferredHost",
   "taskName" : "Samza task",
   "containerId" : "0",
   "partitions" : [{
                      "system" : "kafka",
                      "stream" : "topic-name",
                      "partitionId" : "0"
                    }]
 }
 ]
Response codes
Status Description
200 OKThe operation completed successfully and all the tasks that for the job are returned.
404 Not FoundInvalid job instance was provided as an argument.
{
    "message": "Invalid arguments for getTasks. jobName: SamzaJobName jobId: SamzaJobId."
}
500 Server ErrorThere was an error executing the command on the server. e.g. The command timed out.
{
    "message": "Timeout waiting for get all tasks."
}



Design

Abstractions

There are two primary abstractions that are required by the TasksResource that users can implement to handle any details specific to their environment.

  1. TaskProxy: This interface is the central point of interacting with Samza tasks. It exposes a method to get all the tasks of a Samza job.
  2. InstallationFinder: The InstallationFinder provides a generic interface to discover all the installed jobs, hiding any customizations in the job package structure and its location. The InstallationFinder also resolves the job configuration, which is used to validate and identify the job.

Configuration

The TasksResource properties should be specified in the same file as the Samza REST configuration.

Name Description
task.proxy.factory.classRequired: The TaskProxyFactory that will be used to create the TaskProxy instances. The value is a fully-qualified class name which must implement TaskProxyFactory. Samza ships with one implementation:
org.apache.samza.rest.proxy.task.SamzaTaskProxy
  • gets the details of all the tasks of a job. It uses the
    SimpleInstallationRecord
    to interact with Samza jobs installed on disk.
  • job.installations.pathRequired: The file system path which contains the Samza job installations. The path must be on the same host as the Samza REST Service. Each installation must be a directory with structure conforming to the expectations of the InstallationRecord implementation used by the JobProxy.
    job.config.factory.classThe config factory to use for reading Samza job configs. This is used to fetch the job.name and job.id properties for each job instance in the InstallationRecord. It’s also used to validate that a particular directory within the installation path actually contains Samza jobs. If not specified
    org.apache.samza.config.factories.PropertiesConfigFactory
    will be used.