1.4 Jobfile Format

prefs:
    logPath: /path/to/logfile
    runLog:
        type: file
        path: /path/to/runlog
        maxFileLen: 10m
        maxHistories: 5

resultSinks:
    - &email_summary
        type: email
        email: [email protected]
        data: [stdout] # stdout, stderr
                
    - &email_summary_and_stderr
        type: email
        email: [email protected]
        data: [stderr] # stdout, stderr
    
    - &save_stdout
        type: filesystem
        path: /some/dir
        data: [stdout] # stdout, stderr
        maxAgeDays: 10
    
    - &my_telegram
        type: telegram
        chat_id: '987654'
        token: abcdef987654
            
    - &program
        type: program
        path: /notifyHandler.sh
            
    - &socket
        type: socket
        proto: tcp # tcp, tcp4, tcp6, unix
        address: :12345 # port or path

    - &stdout
        type: stdout
        data: [stdout, stderr]  # stdout, stderr

jobs:
    job#1:
      notifyOnError:
          - *email_summary
          - *my_telegram
      notifyOnSuccess:
          - *program
          - *socket

Result Sinks

Result sinks are little modules that take the results of job runs and do something useful with them --- e.g., email them, publish them to a socket, write them to a file. Different jobs can use different result sinks, and a particular job can use different result sinks depending on the job's status.

Users define result sinks in their jobfiles in the resultSinks section, which consists of a YAML sequence; result sinks are defined as YAML mappings:

resultSinks:
    - &fsSink
        type: filesystem
        path: /some/dir
        data: [stdout]
        maxAgeDays: 10

(The &fsSink gives a name to the following mapping, so that it can be referenced (using *fsSink) in a job definition.) All result sink definitions must contain a type key specifying the type of the result sink being defined; the rest of the keys are determined by that result sink type. In this example, we define a filesystem result sink, and such a result sink requires additional parameters specifying a directory in which to store jobs' output (path), whether stdout, stderr, or both should be saved (data), and for how long (maxAgeDays).

Making a new type of result sink

Result sink types are implemented in package jobfile, as structures that implement the interface jobfile.ResultSink. I'll use the filesystem result sink type as an example in the following steps.

1. Chose a name of the result sink type. It should be all-lowercase; words should be separated with "-". In our example, the type name is "filesystem".
2. Make a new Go file in module jobfile called "result_sink_TYPE.go". In our example, it's "result_sink_filesystem.go".
3. Define a struct named "TYPEResultSink" --- e.g., "FilesystemResultSink".
4. Decide what parameters your result sink type needs. Define them as fields in your struct, and include yaml tags specifying the YAML keys they will use. E.g.:

type FilesystemResultSink struct {
	Path       string              `yaml:"path"`
	Data       ResultSinkDataParam `yaml:"data"`
	MaxAgeDays int                 `yaml:"maxAgeDays"`
}

(ResultSinkDataParam is a special uint type defined in result_sink.go.)

5. Implement the methods demanded by the ResultSink interface. The String method should return the name of your result sink type. IMPORTANT: None of them should modify the struct.
6. In function MakeResultSinkFromConfig in result_sink.go, add a case to the switch statement that maps the name of your type to an instance of your type's struct. E.g.:

    case "filesystem":
        var sink FilesystemResultSink
        if err := loadSinkParams(params, &sink); err != nil {
            return nil, err
        }
        return sink, nil

5. Finally, change the unit tests so that they test the parsing of your new result sink type. In job_file_v3_parse_test.go, modify the jobfile starting on line 161 so that it uses your result sink type in a job, and then modify as appropriate the expected parsed JobFile beginning on line 226.