lightbus inspect

The lightbus inspect command allows for inspecting activity on the bus. This is currently limited to debugging only events, not RPCs.

The querying facilities provided here are not very performant. The lightbus inspect command will pull a large number of messages from the bus and apply filters locally.


lightbus inspect will only return results for APIs which are currently being served by worker processes. If you have no workers running you will see no results. This is because lightbus inspect relies on the schema being present on the bus.


You can query the bus for a specific lightbus event ID:

# Will produce JSON output
lightbus inspect --id 1bff06d0-fa9b-11e9-b8ca-f218986bf8ce

# Will produce human-readable output
lightbus inspect --id 1bff06d0-fa9b-11e9-b8ca-f218986bf8ce --format human

You can also query the bus using the message ID native to the underlying broker (in this case, this will be the Redis streams message ID):

lightbus inspect --native-id 1572389392059-0

You can also query by API and/or event name:

# Event/api filtering
lightbus inspect --event user_registered 
lightbus inspect --api my_company.auth 

Wildcards are also supported in event & api filtering:

# Wildcard filtering
lightbus inspect --event user_* 
lightbus inspect --api my_company.*

Unexpected results when using wildcards?

You may need to quote wilcard strings in order to prevent your shell expanding them. For example:

lightbus inspect --api "my_company.*"

You can see a continually updating stream of all events for a single API:

# Continually show events for the given API 
lightbus inspect --follow --api auth

You can query based on the data sent in the event. For example, to query based on the value of the email parameter of a fired event:

lightbus inspect --json-path

You can also query on more complex JSON path expressions:

lightbus inspect --json-path


This command will maintain an cache of fetched messages in ~/.lightbus/. This will speed up subsequent executions and reduce the load on the bus.

Option reference

$ lightbus inspect -h
usage: lightbus inspect [-h] [--json-path JSON_SEARCH]
                        [--id LIGHTBUS_EVENT_ID] [--native-id NATIVE_EVENT_ID]
                        [--api API_NAME] [--event EVENT_NAME]
                        [--version VERSION_NUMBER] [--format FORMAT]
                        [--cache-only] [--follow] [--validate]
                        [--show-casting] [--internal] [--bus BUS_MODULE]
                        [--service-name SERVICE_NAME]
                        [--process-name PROCESS_NAME] [--config FILE]
                        [--log-level LOG_LEVEL]

optional arguments:
  -h, --help            show this help message and exit

Inspect command arguments:
  --json-path JSON_SEARCH, -j JSON_SEARCH
                        Search event body json for the givn value. Eg.
               (default: None)
                        Find a single event with this Lightbus event ID
                        (default: None)
                        Find a single event with this broker-native ID
                        (default: None)
  --api API_NAME, -a API_NAME
                        Find events for this API name. Supports the '*'
                        wildcard. (default: None)
                        Find events for this event name. Supports the '*'
                        wildcard. (default: None)
                        Find events with the specified version number. Can be
                        prefixed by <, >, <=, >= (default: None)
  --format FORMAT, -F FORMAT
                        Formatting style. One of json, pretty, or human.
                        (default: json)
  --cache-only, -c      Search the local cache only (default: False)
  --follow, -f          Continually listen for new events matching the search
                        criteria. May only be used on a single API (default:
  --validate, -d        Validate displayed events against the bus schema. Only
                        available when --format is set to 'human'
                        (experimental) (default: False)
  --show-casting, -C    Show how the message values will be casted for each
                        event listener (experimental) (default: False)
  --internal, -I        Include internal APIs (default: False)

Common arguments:
                        The bus module to import. Example 'bus',
                        'my_project.bus'. Defaults to the value of the
                        LIGHTBUS_MODULE environment variable, or 'bus'
                        (default: None)
  --service-name SERVICE_NAME, -s SERVICE_NAME
                        Name of service in which this process resides. YOU
                        SHOULD LIKELY SET THIS IN PRODUCTION. Can also be set
                        using the LIGHTBUS_SERVICE_NAME environment. Will
                        default to a random string. (default: None)
  --process-name PROCESS_NAME, -p PROCESS_NAME
                        A unique name of this process within the service. Can
                        also be set using the LIGHTBUS_PROCESS_NAME
                        environment. Will default to a random string.
                        (default: None)
  --config FILE         Config file to load, JSON or YAML (default: None)
  --log-level LOG_LEVEL
                        Set the log level. Overrides any value set in config.
                        One of debug, info, warning, critical, exception.
                        (default: None)