manpages

osloservice(1)

OSLOSERVICE(1) oslo.service OSLOSERVICE(1)

NAME

osloservice - oslo.service 4.1.1

oslo.service provides a framework for defining new long-running services using the patterns established by other OpenStack applications. It also includes utilities long-running applications might need for working with SSL or WSGI, performing periodic operations, interacting with systemd, etc.

CONTENTS

Installation

At the command line:

$ pip install oslo.service


Using oslo.service

Usage

To use oslo.service in a project:

import oslo_service


Migrating to oslo.service

The oslo.service library no longer assumes a global configuration object is available. Instead the following functions and classes have been changed to expect the consuming application to pass in an oslo.config configuration object:

  • initialize_if_enabled()
  • oslo_service.periodic_task.PeriodicTasks
  • launch()
  • oslo_service.service.ProcessLauncher
  • oslo_service.service.ServiceLauncher
  • is_enabled()
  • wrap()

When using service from oslo-incubator

from foo.openstack.common import service
launcher = service.launch(service, workers=2)


When using oslo.service

from oslo_config import cfg
from oslo_service import service
CONF = cfg.CONF
launcher = service.launch(CONF, service, workers=2)


Using oslo.service with oslo-config-generator

The oslo.service provides several entry points to generate configuration files.

•
oslo.service.service
The options from the service and eventlet_backdoor modules for the [DEFAULT] section.

•
oslo.service.periodic_task
The options from the periodic_task module for the [DEFAULT] section.

•
oslo.service.sslutils
The options from the sslutils module for the ssl section.

•
oslo.service.wsgi
The options from the wsgi module for the [DEFAULT] section.


ATTENTION: The library doesn't provide an oslo.service entry point.

$ oslo-config-generator --namespace oslo.service.service \
--namespace oslo.service.periodic_task \
--namespace oslo.service.sslutils


Launching and controlling services

The oslo_service.service module provides tools for launching OpenStack services and controlling their lifecycles.

A service is an instance of any class that subclasses oslo_service.service.ServiceBase. ServiceBase is an abstract class that defines an interface every service should implement. oslo_service.service.Service can serve as a base for constructing new services.

Launchers

The oslo_service.service module provides two launchers for running services:

  • oslo_service.service.ServiceLauncher - used for running one or more service in a parent process.
  • oslo_service.service.ProcessLauncher - forks a given number of workers in which service(s) are then started.

It is possible to initialize whatever launcher is needed and then launch a service using it.

from oslo_config import cfg
from oslo_service import service
CONF = cfg.CONF
service_launcher = service.ServiceLauncher(CONF)
service_launcher.launch_service(service.Service())
process_launcher = service.ProcessLauncher(CONF, wait_interval=1.0)
process_launcher.launch_service(service.Service(), workers=2)


Or one can simply call oslo_service.service.launch() which will automatically pick an appropriate launcher based on a number of workers that are passed to it (ServiceLauncher if workers=1 or None and ProcessLauncher in other case).

from oslo_config import cfg
from oslo_service import service
CONF = cfg.CONF
launcher = service.launch(CONF, service.Service(), workers=3)


NOTE:

It is highly recommended to use no more than one instance of the ServiceLauncher or ProcessLauncher class per process.


Signal handling

oslo_service.service provides handlers for such signals as SIGTERM, SIGINT, and SIGHUP.

SIGTERM is used for graceful termination of services. This can allow a server to wait for all clients to close connections while rejecting new incoming requests. Config option graceful_shutdown_timeout specifies how many seconds after receiving a SIGTERM signal a server should continue to run, handling the existing connections. Setting graceful_shutdown_timeout to zero means that the server will wait indefinitely until all remaining requests have been fully served.

To force instantaneous termination the SIGINT signal must be sent.

The behavior on receiving SIGHUP varies based on how the service is configured. If the launcher uses restart_method='reload' (the default), then the service will reload its configuration and any threads will be completely restarted. If restart_method='mutate' is used, then only the configuration options marked as mutable will be reloaded and the service threads will not be restarted.

See oslo_service.service.Launcher for more details on the restart_method parameter.

NOTE:

SIGHUP is not supported on Windows.


NOTE:

Config option graceful_shutdown_timeout is not supported on Windows.


Below is an example of a service with a reset method that allows reloading logging options by sending a SIGHUP.

from oslo_config import cfg
from oslo_log import log as logging
from oslo_service import service
CONF = cfg.CONF
LOG = logging.getLogger(__name__)
class FooService(service.ServiceBase):


    def start(self):


        pass


    def wait(self):


        pass


    def stop(self):


        pass


    def reset(self):


        logging.setup(cfg.CONF, 'foo')


Profiling

Processes spawned through oslo_service.service can be profiled (function calltrace) through the eventlet_backdoor module. The service must be configured with the backdoor_port option to enable its workers to listen on TCP ports. The user can then send the prof() command to capture the worker process's function calltrace.

1.
To start profiling send the prof() command on the process's listening port
2.
To stop profiling and capture pstat calltrace to a file, send the prof() command with a file basename as an argument (prof(basename)) to the worker process's listening port. A stats file (in pstat format) will be generated in the temp directory with the user-provided basename with a .prof suffix .

For example, to profile a neutron server process (which is listening on port 8002 configured through the backdoor_port option):

$ echo "prof()" | nc localhost 8002
$ neutron net-create n1; neutron port-create --name p1 n1;
$ neutron port-delete p1; neutron port-delete p1
$ echo "prof('neutron')" | nc localhost 8002


This will generate a stats file in /tmp/neutron.prof. Stats can be printed from the trace file as follows:

import pstats
stats = pstats.Stats('/tmp/neutron.prof')
stats.print_stats()


CHANGES

4.1.1

•
Fix removed public API

4.1.0

  • Migrate Eventlet components to the new backend system
  • Introduce configurable backend system in oslo.service

4.0.0

•
reno: Update master for unmaintained/2023.1

3.6.0

  • Add note about requirements lower bounds
  • Run pyupgrade to clean up Python 2 syntaxes
  • Remove Python 3.8 support
  • Fix outdated tox minversion
  • Declare Python 3.12 support
  • Remove workaround for eventlet < 0.27.0
  • Update master for stable/2024.2

3.5.0

  • reno: Update master for unmaintained/zed
  • Remove old excludes
  • Update sslutils.wrap for newer Pythons
  • Remove deprecated ssl options
  • Make signal handling order predictable
  • Update master for stable/2024.1
  • reno: Update master for unmaintained/xena
  • reno: Update master for unmaintained/wallaby
  • reno: Update master for unmaintained/victoria

3.4.0

  • Switch to coverage command
  • reno: Update master for unmaintained/yoga
  • pre-commit: Integrate doc8 and bandit
  • pre-commit: Bump versions
  • Bump hacking
  • Update python classifier in setup.cfg

3.3.0

•
Update master for stable/2023.2

3.2.0

  • Imported Translations from Zanata
  • Bump bandit
  • Revert "Moves supported python runtimes from version 3.8 to 3.10"
  • Moves supported python runtimes from version 3.8 to 3.10
  • Update master for stable/2023.1

3.1.1

•
Fix issues related to tox4

3.1.0

  • Fix misuse of assertTrue
  • Imported Translations from Zanata
  • Add Python3 antelope unit tests
  • Update master for stable/zed
  • Fix native threads on child process

3.0.0

  • Imported Translations from Zanata
  • Drop python3.6/3.7 support in testing runtime
  • Add Python3 zed unit tests
  • Update master for stable/yoga

2.8.0

•
Make debug option of wsgi server configurable

2.7.0

  • Fix fo() backdoor command for non-class objects
  • Fix BackOffLoopingCall error so it is not misleading
  • Add Python3 yoga unit tests
  • Update master for stable/xena

2.6.0

  • setup.cfg: Replace dashes with underscores
  • Remove references to 'sys.version_info'
  • Move flake8 as a pre-commit local target
  • Add Python3 xena unit tests
  • Update master for stable/wallaby
  • Remove lower-constraints remnants

2.5.0

  • remove unicode from code
  • Use TOX_CONSTRAINTS_FILE
  • Dropping lower constraints testing
  • Drop custom implementation of EVENTLET_HUB
  • Use TOX_CONSTRAINTS_FILE
  • Use py3 as the default runtime for tox
  • Use TOX_CONSTRAINTS_FILE
  • Add Python3 wallaby unit tests
  • Update master for stable/victoria
  • Adding pre-commit

2.4.0

  • [goal] Migrate testing to ubuntu focal
  • Bump bandit version

2.3.2

•
Do not import "oslo.log" in the main module

2.3.1

2.3.0

  • Fix wsgi SSL tests for wsgi module under python 3
  • Reactivate wsgi test related to socket option under python 3
  • Fix wsgi/SSL/ipv6 tests for wsgi module under python 3
  • Fix some SSL tests for wsgi module under python 3
  • Raise minimum version of eventlet to 0.25.2
  • Fix pygments style
  • Stop to use the __future__ module

2.2.0

  • Drop six usages
  • Fix hacking min version to 3.0.1
  • Switch to newer openstackdocstheme and reno versions
  • Remove the unused coding style modules
  • Remove translation sections from setup.cfg
  • Align tests with monkey patch original current_thread _active
  • Remove monotonic usage
  • Align contributing doc with oslo's policy
  • Monkey patch original current_thread _active
  • Bump default tox env from py37 to py38
  • Add py38 package metadata
  • Use unittest.mock instead of third party mock
  • Add release notes links to doc index
  • Add Python3 victoria unit tests
  • Update master for stable/ussuri
  • Cleanup py27 support

2.1.1

•
Update hacking for Python3

2.1.0

  • Update eventlet
  • Update the minversion parameter
  • remove outdated header
  • reword releasenote for py27 support dropping

2.0.0

  • [ussuri][goal] Drop python 2.7 support and testing
  • tox: Trivial cleanup

1.41.1

  • Add 'is_available' function
  • tox: Keeping going with docs
  • Switch to official Ussuri jobs
  • Extend test cert validity to 2049
  • Update the constraints url

1.41.0

•
Update master for stable/train

1.40.2

•
Reno for SIGHUP fix

1.40.1

  • Polish usage.rst
  • restart: don't stop process on sighup when mutating
  • Move doc related modules to doc/requirements.txt
  • Add Python 3 Train unit tests

1.40.0

  • Stop using pbr to build docs
  • Make PID availabe as formatstring in backdoor path

1.39.0

  • Cap Bandit below 1.6.0 and update Sphinx requirement
  • Add workers' type check before launching the services
  • Replace git.openstack.org URLs with opendev.org URLs
  • OpenDev Migration Patch
  • Dropping the py35 testing
  • Update master for stable/stein

1.38.0

  • Update oslo.service to require yappi 1.0 or newer
  • add python 3.7 unit test job
  • Update hacking version

1.37.0

•
Bump oslo.utils lower constraint to 3.40.2

1.36.0

  • Profile Oslo Service processes
  • Use eventletutils Event class
  • Avoid eventlet_backdoor listing on same port

1.35.0

  • Use template for lower-constraints
  • Deprecate the ThreadGroup.cancel() API
  • Document the threadgroup module
  • Actually test child SIGHUP signal
  • Restore correct signal handling in Python3
  • Add stop_on_exception to TG timers
  • Add better timer APIs to ThreadGroup
  • Update mailinglist from dev to discuss
  • Use SleepFixture in looping call test suite

1.33.0

  • Fixture to mock loopingcall wait()
  • Limit monotonic to py2

1.32.1

  • Fix stop of loopingcall
  • Use eventlet Event for loopingcall events
  • Clean up .gitignore references to personal tools
  • Always build universal wheels

1.32.0

  • Ensure connection is active in graceful shutdown tests
  • Stop asserting on Eventlet internals
  • Skips signal handling on Windows
  • add lib-forward-testing-python3 test job
  • add python 3.6 unit test job
  • import zuul job settings from project-config
  • Update reno for stable/rocky

1.31.3

  • Remove unnecessary pyNN testenv
  • Convert oslo.service to using stestr
  • Add release notes link to README
  • Fix oslo.service ProcessLauncher fails to call stop
  • fix tox python3 overrides
  • Add test dependency on requests
  • Remove moxstubout

1.31.2

  • [ThreadGroup] Don't remove timer when stop timers
  • Make lower-constraints job voting
  • tox.ini: Use python3.5 in py35 environment
  • Python 3: Fix eventlet wakeup after signal
  • Python 3: Fix non-deterministic test
  • Remove stale pip-missing-reqs tox test
  • Trivial: Update pypi url to new url
  • add lower-constraints job
  • move doc8 test to pep8 job
  • set default python to python3

1.31.1

•
Revert "Revert "Permit aborting loopingcall while sleeping""

1.31.0

  • Remove eventlet cap
  • Fixup certificates and skip failing test

1.30.0

  • Imported Translations from Zanata
  • Imported Translations from Zanata
  • Update links in README
  • Imported Translations from Zanata
  • Updated from global requirements
  • Update reno for stable/queens
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.29.0

  • Maintain shared memory after fork in Python >=3.7
  • Updated from global requirements
  • Revert "Permit aborting loopingcall while sleeping"

1.28.1

1.28.0

  • Remove -U from pip install
  • Avoid tox_install.sh for constraints support
  • Updated from global requirements
  • Remove setting of version/release from releasenotes
  • Updated from global requirements

1.27.0

  • Updated from global requirements
  • change periodic_task to catch all exceptions including BaseException
  • Fix bandit scan and make it voting
  • Imported Translations from Zanata

1.26.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Imported Translations from Zanata
  • Updated from global requirements
  • Updated from global requirements
  • Update reno for stable/pike
  • Updated from global requirements

1.25.0

•
Update URLs in documents according to document migration

1.24.1

  • rearrange existing documentation to fit the new standard layout
  • switch from oslosphinx to openstackdocstheme

1.24.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Permit aborting loopingcall while sleeping
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.23.0

•
Add min_interval to BackOffLoopingCall

1.22.0

  • Updated from global requirements
  • Updated from global requirements

1.21.0

  • Remove log translations
  • Use Sphinx 1.5 warning-is-error
  • Fix some reST field lists in docstrings
  • Updated from global requirements

1.20.0

  • Updated from global requirements
  • [Fix gate]Update test requirement
  • Updated from global requirements
  • Updated from global requirements
  • Fix race condition with fast threads
  • pbr.version.VersionInfo needs package name (oslo.xyz and not oslo_xyz)
  • Remove duplicated register_opts call
  • Update reno for stable/ocata
  • Remove references to Python 3.4

1.19.0

  • Add FixedIntervalWithTimeoutLoopingCall
  • Add Constraints support
  • Show team and repo badges on README

1.18.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Imported Translations from Zanata
  • Update .coveragerc after the removal of respective directory
  • Delete python bytecode file

1.17.0

  • Changed the home-page link
  • Updated from global requirements
  • Replace 'MagicMock' with 'Mock'
  • Enable release notes translation
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.16.0

  • Updated from global requirements
  • Stay alive on double SIGHUP

1.15.0

•
Updated from global requirements

1.14.0

  • Updated from global requirements
  • Fix parameters of assertEqual are misplaced

1.13.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Add reno for release notes management
  • Updated from global requirements

1.12.0

  • Imported Translations from Zanata
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.11.0

•
Trivial: ignore openstack/common in flake8 exclude list

1.10.0

•
[Trivial] Remove executable privilege of doc/source/conf.py

1.9.0

  • Updated from global requirements
  • Offer mutate_config_files
  • Make _spawn_service more flexible
  • Remove direct dependency on babel
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Fix argument type for _sd_notify() on python3
  • Use a timeutils.StopWatch for cancel timing
  • Add ability to cancel Threads and ThreadGroups
  • Exception: message need '_' function
  • Fix Heartbeats stop when time is changed
  • Updated from global requirements

1.7.0

  • Updated from global requirements
  • Correct some help text
  • Fix typo in help text
  • wsgi: decrease the default number of greenthreads in pool
  • Updated from global requirements

1.6.0

  • Updated from global requirements
  • Allow the backdoor to serve from a local unix domain socket
  • Updated from global requirements

1.5.0

•
Use requests in TestWSGIServerWithSSL instead of raw socket client

1.4.0

  • Updated from global requirements
  • Updated from global requirements
  • Fix misspelling and rewrite sentence
  • Add a more useful/detailed frame dumping function
  • Updated from global requirements
  • Update translation setup
  • Fix race condition on handling signals
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Fix artificial service.wait()

1.3.0

  • Graceful shutdown added to ServiceLauncher
  • Fix test execution on CentOS 7
  • Updated from global requirements
  • Fix some inconsistency in docstrings
  • Refactoring of tests/eventlet_service.py
  • Updated from global requirements
  • Remove argument ServiceLauncher.wait() method
  • fix a couple of assert issues
  • Run sslutils and wsgi tests for python3
  • Updated from global requirements

1.2.0

  • Updated from global requirements
  • Fix a race condition in signal handlers
  • Enable py3 mock.patch of RuntimeError
  • Delete python bytecode before every test run
  • Trival: Remove 'MANIFEST.in'

1.1.0

  • Avoid warning when time taken is close to zero
  • Update the _i18n.py file and fix the domain value
  • Add Bandit to tox for security static analysis
  • Code refactoring of ThreadGroup::stop_timers()

1.0.0

  • Updated from global requirements
  • Updated from global requirements
  • Add functionality for creating Unix domain WSGI servers
  • Use reflection.get_class_name() from oslo.utils
  • Remove Python 2.6 classifier
  • Remove openstack-common.conf
  • cleanup tox.ini
  • Change "started child" messages to DEBUG
  • Support for SSL protocol and cipher controls

0.13.0

  • Default value of graceful_shutdown_timeout is set to 60sec
  • Updated from global requirements
  • Logger name argument was added into wsgi.Server constructor
  • Avoid the dual-naming confusion
  • Forbid launching services with 0 or negative number of workers

0.12.0

  • Document graceful_shutdown_timeout config option
  • Remove py26 env from test list
  • Added config option graceful_shutdown_timeout
  • Updated from global requirements
  • Add docstring for LoopingCallBase._start()
  • Updated from global requirements

0.11.0

  • Updated from global requirements
  • Add doc8 to py27 tox env and fix raised issues
  • Document termination of children on SIGHUP
  • Updated from global requirements
  • Updated from global requirements

0.10.0

  • RetryDecorator should not log warnings/errors for expected exceptions
  • Termination children on SIGHUP added
  • Fix coverage configuration and execution
  • Add register_opts function to sslutils
  • Move the common thread manipulating routine to a shared routine
  • Update log string to correctly denote what it waits on
  • Avoid removing entries for timers that didn't stop
  • Cleanup thread on thread done callback
  • Move 'history' -> release notes section
  • Add unit tests for sslutils
  • Expand README and clean up intro to sphinx docs
  • Add shields.io version/downloads links/badges into README.rst
  • add auto-generated docs for config options
  • Move backoff looping call from IPA to oslo.service
  • Change ignore-errors to ignore_errors
  • Fix the home-page value in setup.cfg
  • WSGI module was corrected
  • Updated from global requirements
  • ThreadGroup's stop didn't recognise the current thread correctly
  • doing monkey_patch for unittest

0.9.0

  • Handling corner cases in dynamic looping call
  • Change DEBUG log in loopingcall to TRACE level log
  • Updated from global requirements

0.8.0

•
Added wsgi functionality

0.7.0

  • Updated from global requirements
  • Update "Signal handling" section of usage docs
  • Use oslo_utils reflection to get 'f' callable name
  • Updated from global requirements
  • Prefix the 'safe_wrapper' function to be '_safe_wrapper'
  • Setup translations
  • Check that sighup is supported before accessing signal.SIGHUP
  • Use contextlib.closing instead of try ... finally: sock.close
  • Avoid using the global lockutils semaphore collection
  • Updated from global requirements

0.6.0

  • Added newline at end of file
  • Added class SignalHandler
  • Updated from global requirements
  • Activate pep8 check that _ is imported
  • Denote what happens when no exceptions are passed in
  • Allow LoopingCall to continue on exception in callee

0.5.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Add oslo_debug_helper to tox.ini
  • Add usage documentation for oslo_service.service module

0.4.0

  • Updated from global requirements
  • save docstring, name etc using six.wraps
  • Move backdoor-related tests from test_service
  • Add mock to test_requirements
  • Remove usage of mox in test_eventlet_backdoor

0.3.0

  • Copy RetryDecorator from oslo.vmware
  • Increase test coverage of systemd
  • Ensure we set the event and wait on the timer in the test
  • Make it easier to use the eventlet backdoor locally
  • Track created thread and disallow more than one start being active

0.2.0

  • Documentation on the use of the oslo-config-generator
  • Add greenlet to requirements
  • Add tox target to find missing requirements
  • Enforce H405 check
  • Enforce H301 check
  • Return timer after adding it to internal list
  • Updated from global requirements
  • Have all the looping calls share a common run loop
  • Move service abstract base class check to launch_service methods
  • Fix a typo in a comment
  • Updated from global requirements
  • Use a signal name->sigval and sigval->signal name mapping

0.1.0

  • Test for instantaneous shutdown fixed
  • Graceful shutdown WSGI/RPC server
  • Use monotonic.monotonic and stopwatches instead of time.time
  • Updated from global requirements
  • Eventlet service fixed
  • Add documentation for the service module
  • Improve test coverage for loopingcall module
  • Add oslo.service documentation
  • Remove usage of global CONF
  • Make logging option values configurable
  • Introduce abstract base class for services
  • Add entrypoints for option discovery
  • Updated from global requirements
  • Move the option definitions into a private file
  • Fix unit tests
  • Fix pep8
  • exported from oslo-incubator by graduate.sh
  • Clean up logging to conform to guidelines
  • Port service to Python 3
  • Test for shutting down eventlet server on signal
  • service child process normal SIGTERM exit
  • Revert "Revert "Revert "Optimization of waiting subprocesses in ProcessLauncher"""
  • Revert "Revert "Optimization of waiting subprocesses in ProcessLauncher""
  • Revert "Optimization of waiting subprocesses in ProcessLauncher"
  • ProcessLauncher: reload config file in parent process on SIGHUP
  • Add check to test__signal_handlers_set
  • Store ProcessLauncher signal handlers on class level
  • Remove unused validate_ssl_version
  • Update tests for optional sslv3
  • Fixed ssl.PROTOCOL_SSLv3 not supported by Python 2.7.9
  • Optimization of waiting subprocesses in ProcessLauncher
  • Switch from oslo.config to oslo_config
  • Change oslo.config to oslo_config
  • Remove oslo.log code and clean up versionutils API
  • Replace mox by mox3
  • Allow overriding name for periodic tasks
  • Separate add_periodic_task from the metaclass __init__
  • Upgrade to hacking 0.10
  • Remove unnecessary import of eventlet
  • Added graceful argument on Service.stop method
  • Remove extra white space in log message
  • Prefer delayed %r formatting over explicit repr use
  • ServiceRestartTest: make it more resilient
  • threadgroup: don't log GreenletExit
  • add list_opts to all modules with configuration options
  • Remove code that moved to oslo.i18n
  • Remove graduated test and fixtures libraries
  • rpc, notifier: remove deprecated modules
  • Let oslotest manage the six.move setting for mox
  • Remove usage of readlines()
  • Allow test_service to run in isolation
  • Changes calcuation of variable delay
  • Use timestamp in loopingcall
  • Remove unnecessary setUp function
  • Log the function name of looping call
  • pep8: fixed multiple violations
  • Make periodic tasks run on regular spacing interval
  • Use moxstubout and mockpatch from oslotest
  • Implement stop method in ProcessLauncher
  • Fix parenthesis typo misunderstanding in periodic_task
  • Fix docstring indentation in systemd
  • Remove redundant default=None for config options
  • Make unspecified periodic spaced tasks run on default interval
  • Make stop_timers() method public
  • Remove deprecated LoopingCall
  • Fixed several typos
  • Add graceful stop function to ThreadGroup.stop
  • Use oslotest instead of common test module
  • Remove duplicated "caught" message
  • Move notification point to a better place
  • Remove rendundant parentheses of cfg help strings
  • Adds test condition in test_periodic
  • Fixed spelling error - occured to occurred
  • Add missing _LI for LOG.info in service module
  • notify calling process we are ready to serve
  • Reap child processes gracefully if greenlet thread gets killed
  • Improve help strings for sslutils module
  • Remove unnecessary usage of noqa
  • Removes use of timeutils.set_time_override
  • Update oslo log messages with translation domains
  • Refactor unnecessary arithmetic ops in periodic_task
  • Refactor if logic in periodic_task
  • Use timestamp in periodic tasks
  • Add basic Python 3 tests
  • Clear time override in test_periodic
  • Don't share periodic_task instance data in a class attr
  • Revert "service: replace eventlet event by threading"
  • Simplify launch method
  • Simple typo correction
  • Cleanup unused log related code
  • Utilizes assertIsNone and assertIsNotNone
  • Fix filter() usage due to python 3 compability
  • Use hacking import_exceptions for gettextutils._
  • threadgroup: use threading rather than greenthread
  • disable SIGHUP restart behavior in foreground
  • service: replace eventlet event by threading
  • Allow configurable ProcessLauncher liveness check
  • Make wait & stop methods work on all threads
  • Typos fix in db and periodic_task module
  • Remove vim header
  • os._exit in _start_child may cause unexpected exception
  • Adjust import order according to PEP8 imports rule
  • Add a link method to Thread
  • Use multiprocessing.Event to ensure services have started
  • Apply six for metaclass
  • Removed calls to locals()
  • Move comment in service.py to correct location
  • Fixes issue with SUGHUP in services on Windows
  • Replace using tests.utils part2
  • Bump hacking to 0.7.0
  • Replace using tests.utils with openstack.common.test
  • Refactors boolean returns
  • Add service restart function in oslo-incubator
  • Fix stylistic problems with help text
  • Enable H302 hacking check
  • Convert kombu SSL version string into integer
  • Allow launchers to be stopped multiple times
  • Ignore any exceptions from rpc.cleanup()
  • Add graceful service shutdown support to Launcher
  • Improve usability when backdoor_port is nonzero
  • Enable hacking H404 test
  • Enable hacking H402 test
  • Enable hacking H401 test
  • Fixes import order nits
  • Add DynamicLoopCall timers to ThreadGroups
  • Pass backdoor_port to services being launched
  • Improve python3 compatibility
  • Use print_function __future__ import
  • Improve Python 3.x compatibility
  • Import nova's looping call
  • Copy recent changes in periodic tasks from nova
  • Fix IBM copyright strings
  • Removes unused imports in the tests module
  • update OpenStack, LLC to OpenStack Foundation
  • Add function for listing native threads to eventlet backdoor
  • Use oslo-config-2013.1b3
  • Support for SSL in wsgi.Service
  • Replace direct use of testtools BaseTestCase
  • Use testtools as test base class
  • ThreadGroup remove unused name parameters
  • Implement importutils.try_import
  • Fix test cases in tests.unit.test_service
  • Don't rely on os.wait() blocking
  • Use Service thread group for WSGI request handling
  • Make project pyflakes clean
  • Replace try: import with extras.try_import
  • raise_on_error parameter shouldn't be passed to task function
  • Account for tasks duration in LoopingCall delay
  • updating sphinx documentation
  • Enable eventlet_backdoor to return port
  • Use the ThreadGroup for the Launcher
  • Change RPC cleanup ordering
  • threadgroup : greethread.cancel() should be kill()
  • Use spawn_n when not capturing return value
  • Make ThreadGroup derived from object to make mocking possible
  • Don't log exceptions for GreenletExit and thread_done
  • Log CONF from ProcessLauncher.wait, like ServiceLauncher
  • Import order clean-up
  • Added a missing `cfg` import in service.py
  • Log config on startup
  • Integrate eventlet backdoor
  • Add the rpc service and delete manager
  • Use pep8 v1.3.3
  • Add threadgroup to manage timers and greenthreads
  • Add basic periodic task infrastructure
  • Add multiprocess service launcher
  • Add signal handling to service launcher
  • Basic service launching infrastructure
  • Move manager.py and service.py into common
  • Copy eventlet_backdoor into common from nova
  • Copy LoopingCall from nova for service.py
  • initial commit
  • Initial skeleton project

Configuration Options

oslo.service uses oslo.config to define and manage configuration options to allow the deployer to control how an application uses this library.

periodic_task

These options apply to services using the periodic task features of oslo.service.

DEFAULT

run_external_periodic_tasks
Type
boolean
Default
True

Some periodic tasks can be run in a separate process. Should we run them here?


service

These options apply to services using the basic service framework.

DEFAULT

backdoor_port
Type
string
Default
<None>

Enable eventlet backdoor. Acceptable values are 0, <port>, and <start>:<end>, where 0 results in listening on a random tcp port number; <port> results in listening on the specified port number (and not enabling backdoor if that port is in use); and <start>:<end> results in listening on the smallest unused port number within the specified range of port numbers. The chosen port is displayed in the service's log file.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'backdoor_port' option is deprecated and will be removed in a future release.




backdoor_socket
Type
string
Default
<None>

Enable eventlet backdoor, using the provided path as a unix socket that can receive connections. This option is mutually exclusive with 'backdoor_port' in that only one should be provided. If both are provided then the existence of this option overrides the usage of that option. Inside the path {pid} will be replaced with the PID of the current process.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'backdoor_socket' option is deprecated and will be removed in a future release.




log_options
Type
boolean
Default
True

Enables or disables logging values of all registered options when starting a service (at DEBUG level).


graceful_shutdown_timeout
Type
integer
Default
60

Specify a timeout after which a gracefully shutdown server will exit. Zero value means endless wait.


sslutils

These options apply to services using the SSL utilities module.

ssl

ca_file
Type
string
Default
<None>

CA certificate file to use to verify connecting clients.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'ca_file' option is deprecated and will be removed in a future release.




cert_file
Type
string
Default
<None>

Certificate file to use when starting the server securely.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'cert_file' option is deprecated and will be removed in a future release.




key_file
Type
string
Default
<None>

Private key file to use when starting the server securely.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'key_file' option is deprecated and will be removed in a future release.




version
Type
string
Default
<None>

SSL version to use (valid only if SSL enabled). Valid values are TLSv1 and SSLv23. SSLv2, SSLv3, TLSv1_1, and TLSv1_2 may be available on some distributions.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'version' option is deprecated and will be removed in a future release.




ciphers
Type
string
Default
<None>

Sets the list of available ciphers. value should be a string in the OpenSSL cipher list format.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'ciphers' option is deprecated and will be removed in a future release.




wsgi

These options apply to services using the WSGI (Web Service Gateway Interface) module.

DEFAULT

api_paste_config
Type
string
Default
api-paste.ini

File name for the paste.deploy config for api service

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'api_paste_config' option is deprecated and will be removed in a future release.




wsgi_log_format
Type
string
Default
%(client_ip)s "%(request_line)s" status: %(status_code)s len: %(body_length)s time: %(wall_seconds).7f

A python format string that is used as the template to generate log lines. The following values can beformatted into it: client_ip, date_time, request_line, status_code, body_length, wall_seconds.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'wsgi_log_format' option is deprecated and will be removed in a future release.




tcp_keepidle
Type
integer
Default
600

Sets the value of TCP_KEEPIDLE in seconds for each server socket. Not supported on OS X.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'tcp_keepidle' option is deprecated and will be removed in a future release.




wsgi_default_pool_size
Type
integer
Default
100

Size of the pool of greenthreads used by wsgi

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'wsgi_default_pool_size' option is deprecated and will be removed in a future release.




max_header_line
Type
integer
Default
16384

Maximum line size of message headers to be accepted. max_header_line may need to be increased when using large tokens (typically those generated when keystone is configured to use PKI tokens with big service catalogs).

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'max_header_line' option is deprecated and will be removed in a future release.




wsgi_keep_alive
Type
boolean
Default
True

If False, closes the client socket connection explicitly.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'wsgi_keep_alive' option is deprecated and will be removed in a future release.




client_socket_timeout
Type
integer
Default
900

Timeout for client connections' socket operations. If an incoming connection is idle for this number of seconds it will be closed. A value of '0' means wait forever.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'client_socket_timeout' option is deprecated and will be removed in a future release.




wsgi_server_debug
Type
boolean
Default
False

True if the server should send exception tracebacks to the clients on 500 errors. If False, the server will respond with empty bodies.

WARNING:

This option is deprecated for removal. Its value may be silently ignored in the future.
Reason
The 'wsgi_server_debug' option is deprecated and will be removed in a future release.




API Reference

eventlet_backdoor

exception oslo_service.eventlet_backdoor.EventletBackdoorConfigValueError(port_range, help_msg, ex)
Bases: Exception

oslo_service.eventlet_backdoor.initialize_if_enabled(conf)

fixture

class oslo_service.fixture.SleepFixture
Bases: Fixture

A fixture for mocking the wait() within loopingcall events.

This exists so test cases can exercise code that uses loopingcall without actually incurring wall clock time for sleeping.

The mock for the wait() is accessible via the fixture's mock_wait attribute.

NOTE:

It is not recommended to assert specific arguments (i.e. timeout values) to the mock, as this relies on the internals of loopingcall not changing.


Example usage:

from oslo.service import fixture
...
class MyTest(...):


    def setUp(self):


        ...


        self.sleepfx = self.useFixture(fixture.SleepFixture())


        ...


    def test_this(self):


        ...


        thing_that_hits_a_loopingcall()


        ...


        self.assertEqual(5, self.sleepfx.mock_wait.call_count)


        ...



loopingcall

periodic_task

exception oslo_service.periodic_task.InvalidPeriodicTaskArg
Bases: Exception
message = 'Unexpected argument for periodic task creation: %(arg)s.'


class oslo_service.periodic_task.PeriodicTasks(conf)
Bases: object
add_periodic_task(task)
Add a periodic task to the list of periodic tasks.

The task should already be decorated by @periodic_task.


run_periodic_tasks(context, raise_on_error=False)
Tasks to be run at a periodic interval.


oslo_service.periodic_task.list_opts()
Entry point for oslo-config-generator.

oslo_service.periodic_task.periodic_task(*args, **kwargs)
Decorator to indicate that a method is a periodic task.

This decorator can be used in two ways:

1.
Without arguments @periodic_task''@periodic_task', this will be run on the default interval of 60 seconds.
2.
With arguments: @periodic_task(spacing=N [, run_immediately=[True|False]] [, name=[None|"string"]) this will be run on approximately every N seconds. If this number is negative the periodic task will be disabled. If the run_immediately argument is provided and has a value of 'True', the first run of the task will be shortly after task scheduler starts. If run_immediately is omitted or set to 'False', the first time the task runs will be approximately N seconds after the task scheduler starts. If name is not provided, __name__ of function is used.




service

Generic Node base class for all workers that run on hosts.

oslo_service.service.list_opts()
Entry point for oslo-config-generator.

sslutils

oslo_service.sslutils.is_enabled(conf)

oslo_service.sslutils.list_opts()
Entry point for oslo-config-generator.

oslo_service.sslutils.register_opts(conf)
Registers sslutils config options.

oslo_service.sslutils.wrap(conf, sock)

systemd

Helper module for systemd service readiness notification.

oslo_service.systemd.notify()
Send notification to Systemd that service is ready.

For details see http://www.freedesktop.org/software/systemd/man/sd_notify.html


oslo_service.systemd.notify_once()
Send notification once to Systemd that service is ready.

Systemd sets NOTIFY_SOCKET environment variable with the name of the socket listening for notifications from services. This method removes the NOTIFY_SOCKET environment variable to ensure notification is sent only once.


oslo_service.systemd.onready(notify_socket, timeout)
Wait for systemd style notification on the socket.
Parameters
  • notify_socket (string) -- local socket address
  • timeout (float) -- socket timeout

Returns
0 service ready 1 service not ready 2 timeout occurred


threadgroup

Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html

If you would like to contribute to the development of OpenStack, you must follow the steps in this page: http://docs.openstack.org/infra/manual/developers.html

Once those steps have been completed, changes to OpenStack should be submitted for review via the Gerrit tool, following the workflow documented at: http://docs.openstack.org/infra/manual/developers.html#development-workflow

Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub: https://bugs.launchpad.net/oslo.service

RELEASE NOTES

Read also the oslo.service Release Notes.

INDICES AND TABLES

  • Index
  • Module Index
  • Search Page

AUTHOR

Author name not set

COPYRIGHT

2025, OpenStack Foundation

April 2, 2025 4.1.1