Usage Guide

Butler Services

Saturnin currently supports two types of Butler services:

  • Standard Butler services. These services use the FBSP protocol and work in client/server mode.

    To use these services, you need client software that is capable of calling their APIs. Subsequently, it is sufficient to start the service with the required configuration in the Saturnin container, and enter the address of the service entry point to the client program.

    To save system resources and simplify management, multiple services can be run in a single container.

  • Microservices. These are primarily data processing services that use the FBDP protocol to echange data with other services.

    These services are typically combined into data processing pipelines. All services involved in processing are typically run within a single Saturnin container.

Saturnin recipes

To run services within Saturnin container, you need a special configuration file (with classic .INI file structure) called Saturnin recipe. Each service to be started in the container must have its own section with the appropriate configuration (an overview of configuration parameters can be found in the description of individual services).

See also

The creation and use of recipes is described in the Saturnin Usage Guide.

Service endpoints

The most important element of the configuration of any service is the specification of its endpoints. Each Butler service communicates through messages passed by the ZeroMQ library. This library makes it possible to use a whole range of communication protocols (transports).

Endpoint address

A Service endpoint is a string consisting of a transport :// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to bind/connect to.

ZeroMQ provides the the following transports:

tcp:

Unicast transport using TCP.

For the TCP transport, the transport is tcp, and the meaning of the address part is TCP address followed by a colon and the TCP port number to use.

Tip

This protocol is the most appropriate choice for all endpoints to be accessible outside the container in which the service is operated.

See also

For detailed information about TCP endpoints, see zmq-tcp documentation.

ipc:

Local inter-process communication transport. This transport passes messages between local processes using a system-dependent IPC mechanism.

Important

The inter-process transport is currently only implemented on operating systems that provide UNIX domain sockets.

For the inter-process transport, the transport is ipc, and the meaning of the address part is arbitrary string identifying the pathname to create.

See also

For detailed information about IPC endpoints, see zmq-ipc documentation.

inproc:

Local in-process (inter-thread) communication transport. This transport passes messages via memory directly between threads sharing a single ØMQ context.

For the in-process transport, the transport is inproc, and the meaning of the address part is an arbitrary string identifying the name to create. The name must be unique within the Saturnin container context.

Tip

This protocol is the most appropriate choice for all endpoints that are used only for communication between services running within the same container.

See also

For detailed information about INPROC endpoints, see zmq-inproc documentation.

pgm, epgm:

Reliable multicast transport using PGM.

See also

For detailed information about PGM, EPGM endpoints, see zmq-pgm documentation.

vmci:

Virtual machine communications interface (VMCI).

See also

For detailed information about VMCI endpoints, see zmq-vmci documentation.

Bind vs Connect

The context (and thus the internal creation method) of endpoints is mostly given by the way they are used by the service.

  • Endpoints for standard services define the addresses and transport protocols to which the service binds and through which clients connect to the service.

  • Endpoints used by a service to communicate with other services are used to connect to those services.

However, some services may use endpoints, requiring the specification of whether the service should bind or connect to them. These are typically endpoints used to transfer data between services via the FBDP protocol. In this scenario, the endpoint represents a data pipe, where one of the services is the provider and the other is the consumer of the data. According to the specification of the FBDP protocol, the party that binds to the endpoint determines the basic parameters of the communication. As a practical matter, the endpoint through which the service provides its outputs should be bound, and the endpoint used by the service for its inputs should be connected.

Note

Exceptions to this recommendation are scenarios that use a data-bus service that defines a fixed connection point for all data pipes that other services connect to, regardless of whether they are producers or consumers.

Here is a sample recipe to print Firebird log on screen using two Saturnin microservices that are composed to data processing pipeline connected via INPROC transport:

; 1. Recipe parameters
[saturnin.recipe]
recipe_type = bundle
execution_mode = normal
description = Simple recipe that print log from local Firebird server.

; 2. Bundle content
[bundle]
agents = from-server, writer

; Helper section to centralize definition of shared parameters
[pipe]
name = pipe-1
address = inproc://pipe-1

; 3. Confguration of components
[from-server]
agent = 212657dc-2618-5f4b-a8f5-d8d42e99fe7e
pipe = ${pipe:name}
pipe_address = ${pipe:address}
pipe_mode = bind
pipe_format = text/plain;charset=utf-8
server = local

[writer]
agent = 4e606fdf-3fa9-5d18-a714-9448a8085aab
pipe = ${pipe:name}
pipe_address = ${pipe:address}
pipe_mode = connect
pipe_format = text/plain;charset=utf-8
filename = stdout
file_format = text/plain;charset=utf-8
file_mode = write