# Inspector

The Sanic Inspector is a feature of Sanic Server. It is only available when running Sanic with the built-in worker manager.

It is an HTTP application that optionally runs in the background of your application to allow you to interact with the running instance of your application.

INFO

The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher.

# Getting Started

The inspector is disabled by default. To enable it, you have two options.

Set a flag when creating your application instance.

app = Sanic("TestApp", inspector=True)

Or, set a configuration value.

app = Sanic("TestApp")
app.config.INSPECTOR = True

WARNING

If you are using the configuration value, it must be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above.

# Using the Inspector

Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP.

Via CLI

$ sanic inspect

Via HTTP

$ curl http://localhost:6457

TIP

Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket.

# Built-in Commands

The Inspector comes with the following built-in commands.

CLI Command HTTP Action Description
inspect GET / Display basic details about the running application.
inspect reload POST /reload Trigger a reload of all server workers.
inspect shutdown POST /shutdown Trigger a shutdown of all processes.
inspect scale N POST /scale
{"replicas": N}
Scale the number of workers. Where N is the target number of replicas.

# Custom Commands

The Inspector is easily extendable to add custom commands (and endpoints).

Subclass the Inspector class and create arbitrary methods. As long as the method name is not preceded by an underscore (_), then the name of the method will be a new subcommand on the inspector.

from sanic import json
from sanic.worker.inspector import Inspector
class MyInspector(Inspector):
    async def something(self, *args, **kwargs):
        print(args)
        print(kwargs)
app = Sanic("TestApp", inspector_class=MyInspector, inspector=True)

This will expose custom methods in the general pattern:

  • CLI: sanic inspect <method_name>
  • HTTP: POST /<method_name>

It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above something method accepts all positional and keyword based parameters.

In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a str with the following exceptions:

  • A keyword parameter with no assigned value will be: True
  • Unless the parameter is prefixed with no-, then it will be: False
$ sanic inspect something one two three --four --no-five --six=6

In your application log console, you will see:

('one', 'two', 'three')
{'four': True, 'five': False, 'six': '6'}

The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as {"args": [...]}.

$ curl http://localhost:6457/something \
  --json '{"args":["one", "two", "three"], "four":true, "five":false, "six":6}'

In your application log console, you will see:

('one', 'two', 'three')
{'four': True, 'five': False, 'six': 6}

# Using in production

WARNING

Before exposing the Inspector on a product, please consider all of the options in this section carefully.

When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication.

# TLS encryption

To the Inspector HTTP instance over TLS, pass the paths to your certificate and key.

app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem"
app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem"

This will require use of the --secure flag, or https://.

$ sanic insect --secure --host=<somewhere>
$ curl https://<somewhere>:6457

# API Key Authentication

You can secure the API with bearer token authentication.

app.config.INSPECTOR_API_KEY = "Super-Secret-200"

This will require the --api-key parameter, or bearer token authorization header.

$ sanic inspect --api-key=Super-Secret-200
$ curl http://localhost:6457  -H "Authorization: Bearer Super-Secret-200"

# Configuration

See configuration

MIT Licensed
Copyright © 2018-present Sanic Community Organization

~ Made with ❤️ and ☕️ ~