mtap.deployment

Module for deploying a set of processing services and the events server all at once.

Examples

See python/mtap/examples/exampleDeploymentConfiguration.yml for an example of the yaml deployment configuration which can be loaded using from_yaml_file()

An example configuration

>>> deploy = Deployment(
>>>     GlobalSettings(host='0.0.0.0'),
>>>     EventsDeployment(port=10100, workers=8),
>>>     SharedProcessorConfig(workers=8, jvm_args=['-Xms32m', '-Xmx8g'], classpath='blah.jar'),
>>>     ProcessorDeployment(implementation='python',
>>>                         entry_point='mtap.examples.example_processor',
>>>                         instances=4,
>>>                         port=10101,
>>>                         workers=4),
>>>     ProcessorDeployment(implementation='java',
>>>                         entry_point='edu.umn.nlpie.mtap.WordOccurrencesExampleProcessor',
>>>                         port=10105)
>>> )
>>> deploy.run_servers()
class mtap.deployment.Deployment(global_settings=None, events_deployment=None, shared_processor_config=None, *processors)[source]

An automatic deployment configuration which launches a configurable set of MTAP services.

Parameters:
global_settings

Settings shared among all services.

Type:

Optional[GlobalSettings]

events_deployment

Deployment settings for the events service.

Type:

Optional[EventsDeployment]

shared_processor_config

Shared configuration settings for all processors.

Type:

Optional[SharedProcessorConfig]

processors

Configurations for individual processors.

Type:

List[ProcessorDeployment]

static load_configuration(conf)[source]

Creates a deployment object from a configuration dictionary.

Parameters:

conf (Dict) – The configuration dictionary.

Returns:

Deployment object created.

static from_yaml_file(conf_path)[source]

Loads a deployment configuration from a yaml file.

Parameters:

conf_path (str or pathlib.Path) – The path to the yaml configuration file.

Returns:

Deployment object created from the configuration.

run_servers()[source]

A context manager that starts all the configured services in subprocesses and returns.

Raises:

ServiceDeploymentException – If one or more of the services fails to launch.

Examples

>>> deploy = Deployment.from_yaml_file('deploy_config.yml')
>>> with deploy.run_servers():
>>>     # do something that requires the servers.
>>> # servers are automatically shutdown / terminated when the block is exited
run_servers_and_wait()[source]

Starts the specified servers and blocks until KeyboardInterrupt, SIGINT, or SIGTERM are received.

shutdown()[source]

Shuts down all processors.

Returns:

class mtap.deployment.GlobalSettings(*, host=None, mtap_config=None, log_level=None, register=None)[source]

Settings shared by event service and all processors.

Keyword Arguments:

  • host (Optional[str]) – The global host override, forces all services to use a specific host name.

  • mtap_config (Optional[str]) – The path to an MTAP config file to load for all services.

  • log_level (Optional[str]) – A python logging level to pass to all services.

  • register (Optional[bool]) – Whether services should register with service discovery.

host

The global host override, forces all services to use a specific host name.

Type:

Optional[str]

mtap_config

The path to an MTAP config file to load for all services.

Type:

Optional[str]

log_level

A python logging level to pass to all services.

Type:

Optional[str]

register

Whether services should register with service discovery.

Type:

Optional[bool]

static from_conf(conf)[source]

Creates a global settings object from a configuration dictionary.

Keyword Arguments:

conf (Optional[Dict]) – The configuration dictionary.

Returns:

The global settings object.

Return type:

GlobalSettings

class mtap.deployment.SharedProcessorConfig(*, events_addresses=None, workers=None, additional_args=None, jvm_args=None, java_classpath=None, java_additional_args=None, startup_timeout=None, mp_spawn_method=None)[source]

Configuration that is shared between multiple processor services.

Keyword Arguments:

  • events_addresses (Optional[List[str]]) – An optional GRPC-compatible target for the events service to be used by all processors.

  • workers (Optional[int]) – The default number of worker threads which will perform processing.

  • additional_args (Optional[List[str]]) – a list of additional arguments that should be appended to every processor.

  • jvm_args (Optional[List[str]]) – a list of JVM arguments for all java processors.

  • java_classpath (Optional[str]) – A classpath string that will be passed to all java processors.

  • startup_timeout (Optional[int]) – The default startup timeout for processors.

  • mp_spawn_method (Optional[str]) – A multiprocessing.get_context() argument to create the multiprocessing context.

events_addresses

An optional GRPC-compatible target for the events service to be used by all processors.

Type:

Optional[List[str]]

workers

The default number of worker threads which will perform processing.

Type:

Optional[int]

additional_args

a list of additional arguments that should be appended to every processor.

Type:

Optional[List[str]]

jvm_args

a list of JVM arguments for all java processors.

Type:

Optional[List[str]]

java_classpath

A classpath string that will be passed to all java processors.

Type:

Optional[str]

startup_timeout

The default startup timeout for processors.

Type:

Optional[int]

mp_spawn_method

A multiprocessing.get_context() argument to create the multiprocessing context.

Type:

Optional[str]

static from_conf(conf)[source]

Builds a configuration from a dictionary representation.

Parameters:

conf (Optional[Dict]) – The configuration dictionary.

Returns:

SharedProcessorConfig object.

class mtap.deployment.EventsDeployment(*, enabled=True, addresses=None, workers=None, register=None, mtap_config=None, log_level=None)[source]

Deployment configuration for the events service.

Keyword Arguments:

  • enabled (bool) – Whether an events service should be created.

  • addresses (Optional[Sequence[str]]) – The host address of the events service.

  • workers (Optional[int]) – The number of worker threads the events service should use.

  • register (Optional[bool]) – Whether to register the events service with discovery.

  • mtap_config (Optional[str]) – Path to an mtap configuration file.

  • log_level (Optional[str]) – The log level for the events service.

enabled

Whether an events service should be created.

Type:

bool

addresses

The host address of the events service.

Type:

Optional[Sequence[str]]

service_deployment

The service deployment settings (workers, registration, config, logging).

Type:

ServiceDeployment

static from_conf(conf)[source]

Creates the EventsDeployment configuration option from a configuration dictionary.

Parameters:

conf (Optional[Dict]) – The configuration dictionary

Returns:

EventsDeployment or None from the configuration dictionary.

class mtap.deployment.ServiceDeployment(*, workers, register, mtap_config, log_level)[source]

Shared configuration for services, both events and processors.

Keyword Arguments:

  • workers (Optional[int]) – The number of workers.

  • register (Optional[bool]) – Whether to use service discovery.

  • mtap_config (Optional[str]) – A path to the mtap configuration.

  • log_level (Optional[str]) – The log level.

workers

The number of workers.

Type:

Optional[int]

register

Whether to use service discovery.

Type:

Optional[bool]

mtap_config

A path to the mtap configuration.

Type:

Optional[str]

log_level

The log level.

Type:

Optional[str]

class mtap.deployment.ProcessorDeployment(implementation, entry_point, *, enabled=None, instances=None, host=None, port=None, workers=None, register=None, mtap_config=None, log_level=None, name=None, unique_service_identifier=None, pre_args=None, additional_args=None, startup_timeout=None, mp_spawn_method=None)[source]

Deployment configuration for an MTAP processor.

Used to construct the command for launching the processor. The processor should be a Java Class with a main method or a Python module with a main block. It should accept the standard MTAP processor deployment arguments and launch an MTAP processor using mtap.run_processor() or the equivalent Java method.

Parameters:

  • implementation (str) – Either “java” or “python”.

  • entry_point (str) – Either the java main class, or the python main module.

Keyword Arguments:

  • enabled (Optional[bool]) – Whether the processor should be launched as part of deployment. Default is True if None.

  • instances (Optional[int]) – The number of instances of the processor to launch. Default is 1 if None.

  • host (Optional[str]) – The listening host for the processor service.

  • port (Optional[int]) – The listening port for the processor service.

  • workers (Optional[int]) – The number of worker threads per instance.

  • register (Optional[bool]) – Whether the processor should register with the discovery service specified in the MTAP configuration

  • mtap_config (Optional[str]) – Path to the MTAP configuration file.

  • log_level (Optional[str]) – The log level for the processor.

  • identifier (Optional[str]) – An optional identifier override to use for registration.

  • pre_args (Optional[List[str]]) – Arguments that occur prior to the MTAP service arguments (like host, port, etc).

  • additional_args (Optional[List[str]]) – Arguments that occur after the MTAP service arguments.

  • startup_timeout (Optional[int]) – Optional override startup timeout.

  • mp_spawn_method (Optional[str]) – A multiprocessing.get_context() argument to create the multiprocessing context.

implementation

Either “java” or “python”.

Type:

str

entry_point

Either the java main class, or the python main module.

Type:

str

enabled

Whether the processor should be launched as part of deployment.

Type:

bool

instances

The number of instances of the processor to launch.

Type:

int

host

The listening host for the processor service.

Type:

Optional[str]

port

The listening port for the processor service.

Type:

Optional[int]

service_deployment

The service deployment settings (workers, registration, config, logging).

Type:

ServiceDeployment

pre_args

Arguments that occur prior to the MTAP service arguments (like host, port, etc).

Type:

Optional[List[str]]

additional_args

Arguments that occur after the MTAP service arguments.

Type:

Optional[List[str]]

startup_timeout

Optional override startup timeout.

Type:

Optional[int]

mp_spawn_method

A multiprocessing.get_context() argument to create the multiprocessing context.

Type:

Optional[str]

static from_conf(conf)[source]

Creates an MTAP processor deployment configuration from a configuration dictionary.

Parameters:

conf (Dict) – The configuration dictionary.

Returns:

ProcessorDeployment object that can be used to constuct the call for the processor.

mtap.deployment.deployment_parser()[source]

Creates a parser for configuration that can be passed to the deployment main method.

Returns:

The argument parser object that will create a namespace that can be passed to main().

Return type:

ArgumentParser

exception mtap.deployment.ServiceDeploymentException(*args, **kwargs)[source]

Exception raised in the case of a service failing to launch.