Server Hooks Usage Example

[polly-want-a-kraken]

Despite reading the documentation (below) and searching elsewhere, it's not clear to me how I can interface with gunicorn's server hooks.

Could someone provide an example of how this could be done from within the scope of a (Python 3) application?

I would be willing to add this content to the documentation as thanks.

Server Hooks Documentation

https://docs.gunicorn.org/en/stable/settings.html#server-hooks

[polly-want-a-kraken]

Solved.

You want to use a configuration file written in Python, use the argument --config my_config.py, and set the variable of the hook to a function pointer.

Example

config.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import server

bind = '0.0.0.0:8000'
workers = 4
loglevel = "info"

# Server Hooks
on_starting = server.on_starting

server.py

def on_starting(server):
    app.logger.info("Starting Server")

Invocation

gunicorn server:app --config config.py

[polly-want-a-kraken]

Leaving the issue open to address the matter of documentation, which I think should be improved for clarity's sake.

I had to do a decent amount of digging to figure out how this works.

[tilgovi]

We could link to this more prominently, but there are examples for this here: https://github.com/benoitc/gunicorn/blob/master/examples/example_config.py

[polly-want-a-kraken]

@tilgovi, yeah I think would definitely be a good idea. I found that after I had already determined how the configuration file works by going through other issues.

[benoitc]

@polly-want-a-kraken any PR is welcome ;)

[multimeric]

I'm guessing that on_starting = server.on_starting is superfluous? The linked config example suggests like you should be able to just define a hook function in the config file and have it work.

[tilgovi]

@TMiguelT correct.

[boxydog]

Thanks for your work on gunicorn.

If I have a custom server, how do I override a method like pre_fork?

The custom server example has config right in the python code, so it has no config file.

[boxydog]

I traced code execution and figured this out. Leaving it here in case it helps someone else. Based on custom server example.

def pre_fork(server, worker):
    print(f"pre-fork server {server} worker {worker}", file=sys.stderr)

# ...
if __name__ == '__main__':
    options = {
        'bind': '%s:%s' % ('127.0.0.1', '8080'),
        'workers': number_of_workers(),
        'pre_fork': pre_fork,
    }

[radekjezdik]

I would also like to add that documentation doesn't mention which process executes which hook. I thought it was always called by the master process but to my surprise, it seems not to be the case (e.g. *_request hooks are called on the worker process).

In my case, I wanted to export a metric of the number of concurrently executed requests but had to resolve to shared objects to keep track of the global number of currently executed requests.

[tilgovi]

PR's are welcome, but I'll close this issue as no one has made any specific PR to propose any changes.

[thomasf1]

+1 For adding it to the docs. Had to dig around after reading https://docs.gunicorn.org/en/stable/settings.html#server-hooks, too. A simple example at the top of the docs server-hooks section would be great.

[boxydog]

Put up #3214 with a proposed doc change for this.