Stream

A Stream is an ASCII or UTF-8 text stream, typically logs.

cmd

An array of strings. The first string is the command, and the subsequent strings are the arguments.

reaction will execute the command to fetch the text stream. Command's stdout and stderr are read and treated equally by reaction.

See FAQ "Why start, stop, stream and action commands are arrays" for an explanation.

See Streams for details on how to write correct Stream commands for reaction.

{
  streams: {
    ssh: {
      cmd: ['journalctl', '-f', '-n0', ...],
    },
    nginx: {
      cmd: ['tail', '-F', '-n0', ...],
    },
  },
}

streams:
  ssh:
    cmd: ['journalctl', '-f', '-n0', ...]
  web:
    cmd: ['tail', '-F', '-n0', ...]

type

Available since v2.3.0.

Defaults to "cmd", in which case a cmd must be provided.

{
  streams: {
    stream1: {
      type: "cmd",
      cmd: [...],
    }
  }
}

streams:
  stream1:
    type: cmd
    cmd: [...]

Otherwise, defines the Plugin that will be used for that Stream.

options

Available since v2.3.0.

Used in conjunction with type.

The value of options depends on the Plugin selected, see their documentation.

{
  streams: {
    stream1: {
      type: "plugin1",
      options: {
        option1: "value1",
        ...
      }
    }
  }
}

streams:
  stream1:
    type: cmd
    options:
      option1: value1
      ...

filters

We must attach one or more Filters to a Stream.

{
  streams: {
    ssh: {
      cmd: ['journalctl', '-f', '-n0', ...],
      filters: {
        myfilter: {
          ...
        },
        myotherfilter: {
          ...
        },
      },
    },
    nginx: {
      cmd: ['tail', '-F', '-n0', ...],
      filters: {
        ...
      },
    },
  },
}

streams:
  ssh:
    cmd: ['journalctl', '-f', '-n0', ...]
    filters:
      myfilter:
        ...
      myotherfilter:
        ...
  web:
    cmd: ['tail', '-F', '-n0', ...]
    filters:
      ...

eof

Available since v2.5.0.

Optional. Defines what reaction does when the cmd command quits (i.e. when EOF is reached).

Examples:

{
  streams: {
    nginx: {
      cmd: ["..."],
      eof: {
        behavior: "restart",
        after: "30s",
      },
    },
    ssh: {
      cmd: ["..."],
      eof: {
        behavior: "restart",
        after: "2s",
        retry: 20,
        finally: "exit",
      }
    },
    not_important: {
      cmd: ["..."],
      eof: {
        behavior: "ignore",
      }
    }
  }
}

streams:
  nginx:
    cmd: ["..."]
    eof:
      behavior: "restart"
      after: "30s"

  ssh:
    cmd: ["..."]
    eof:
      behavior: "restart"
      after: "2s"
      retry: 20
      finally: "exit"

  not_important:
    cmd: ["..."]
    eof:
      behavior: "ignore"

eof.behavior

One of:

• ignore: reaction logs an error but continue operating the other streams, as long as there is at least one ongoing stream.
• exit: reaction exits when the command quits.
• restart: the default. reaction restarts the command.

ignore was the only behavior possible before 2.5.0.

eof.after

Only when eof.behavior is set to restart.

How long reaction pauses before restarting the command.

Defaults to 5s, to avoid a fast infinite loop that would drain the server resources.

Format is defined as follows: <number> <unit>

• whitespace between the integer and unit is optional
• number must be a positive integer (>= 0, no floating point)
• unit can be one of:
  • ms / millis / millisecond / milliseconds
  • s / sec / secs / second / seconds
  • m / min / mins / minute / minutes
  • h / hour / hours
  • d / day / days

eof.retry

Only when eof.behavior is set to restart.

Must be paired with eof.finally.

How much tries reaction must give before doing something else.

eof.finally

Only when eof.behavior is set to restart.

Must be paired with eof.retry.

What reaction does when the retry limit is reached.

Same behavior as eof.behavior, one of ignore or exit.