tomodachi
Documentation
tomodachi

Running a service

✨

Make sure to follow the recommendations for production when running services in a production or staging environment.

Running a Service with the CLI

The tomodachi command-line interface (CLI) is used to run services defined as tomodachi service classes. You can start a service with its class definition defined in ./service/app.py by running tomodachi run service/app.py. The service can be stopped with the keyboard interrupt <ctrl+c>.

The CLI endpoint tomodachi is installed automatically when the package is installed in the environment.

Command Line Arguments

The run command has several options available that can be specified with arguments to the CLI. Here are the available arguments:

  • --loop [auto|asyncio|uvloop]: This argument allows you to specify the event loop implementation. The value for --loop can either be set to asyncio, uvloop or auto. The uvloop value can only be used if uvloop is installed in the execution environment. Note that the default auto value will currently end up using the event loop implementation that is preferred by the Python interpreter, which in most cases will be asyncio.

  • --production: This argument disables the file watcher that restarts the service on file changes and hides the startup info banner. It's highly recommended to enable this option for built docker images and for builds of services that are to be released to any environment.

  • --log-level [debug|info|warning|error|critical]: This argument sets the minimum log level for which the loggers will emit logs to their handlers. By default, the minimum log level is set to info.

  • --logger [console|json|python|disabled]: This argument changes the log formatter that is used by the library. The default value console is mostly suited for local development environments as it provides a structured and colorized view of log records. The console colors can be disabled by setting the env value NO_COLOR=1.

  • --custom-logger <module.attribute|module>: This argument allows you to specify a custom logger. If your logger is initialized in for example the module yourapp.logging and the initialized (structlog) logger is aptly named logger, then use --custom-logger yourapp.logging.logger.

  • --opentelemetry-instrument: Enables OpenTelemetry auto instrumentation of the service (including libraries for which the env has instrumentors installed). Mostly equivalent to starting the service using the opentelemetry-instrument CLI, where OTEL distros, configurators and instrumentors will be loaded automatically and OTEL_* environment values will be processed in the same way.

Environment Variables

Most options can also be set as an environment variable value. For example, setting environment TOMODACHI_LOGGER=json will yield the same change to the logger as if running the service using the argument --logger json. Here are the corresponding environment variables for the command line arguments:

  • TOMODACHI_LOOP=...: Corresponds to --loop.
  • TOMODACHI_PRODUCTION=1: Corresponds to --production.
  • TOMODACHI_LOG_LEVEL=...: Corresponds to --log-level.
  • TOMODACHI_LOGGER=...: Corresponds to --logger.
  • TOMODACHI_CUSTOM_LOGGER=...: Corresponds to --custom-logger.
  • TOMODACHI_OPENTELEMETRY_INSTRUMENT=1: Corresponds to --opentelemetry-instrument
# generic execution of services
app/ $ tomodachi run <service.py ...>

# example: if our service class exists in service/app.py
app/ $ tomodachi run service/app.py

Defaults to output startup banner on stdout and log output on stderr.

app/ $ tomodachi run service/app.py

HTTP services acts like a normal web server.

~/ $ curl -v "http://127.0.0.1:9700/resource/1234"
> HTTP/1.1 200 OK
> Content-Type: text/plain; charset=utf-8
> Server: tomodachi
> Content-Length: 9
> Date: Sun, 16 Oct 2022 13:38:02 GMT
>
> id = 1234

Updated 8 months ago

Related sections