lightrun

Lightrun for Python

Lightrun is a developer-native observabity platform. It's a way to add logs, inspect the state of the current execution (in a familiar, debugger-like view), and extract any type of code-level metric on the fly - without redeploying, restarting or even stopping the running application.

Check out our docs to learn more.

Getting Started

To get started with Lightrun you'll need three things:

1. A Lightrun Account - you can get one here.
2. A Lightrun Plugin - you'll have instructions to download it once you create an account, but you can also check them out here.
3. A Lightrun Agent - which is this very PyPI package! It's the thing that actually does the magic.

Once you've signed up for an account and downloaded the plugin, you can install the agent in your application.

Installing the Lightrun Agent - Directly

In order to install the Lightrun Python Agent please follow these steps:

1. Install the python agent by running python -m pip install lightrun.

2. Add the following code to the beginning of your main function:

try:
    import lightrun
    lightrun.enable(company_key='<COMPANY_SECRET>')
except ImportError as e:
    print("Error importing Lightrun: ", e)

You will have a <COMPANY-SECRET> auto-generated for you during the onboarding process, right after signing up for an account.

1. Run the application as you normally would, i.e. python app.py.

You should see the application's agent popping up in the Lightrun Plugin's sidebar - you can now add logs, snapshots and metrics to your application.

Providing Credentials Via Program Arguments

You can optionally choose to provide the <COMPANY-SECRET> as program argument. To do so, run your application in the following way:

python -m lightrun --company_key='<COMAPNY-SECRET>' -- app.py

Notice - The method above won't work well with applications based on gunicorn or any other multiprocessing libraries, as the debugger won't attach to the spawned sub-processes. Please use the import method instead.

Installing the Lightrun Agent - Django

In order to run a Django web server with the Lightrun agent please follow these steps:

1. In the application folder, install the python agent by running python -m pip install lightrun
2. Add the following code to your manage.py file and run your Django application as you did normally before:

try:
    if os.environ.get('RUN_MAIN') or '--noreload' in sys.argv:
        import lightrun
        lightrun.enable(company_key='<COMAPNY-SECRET>')
except ImportError as e:
    print("Error importing Lightrun: ", e)

Installing the Lightrun Agent - Flask

In order to run a Flask web app with the Lightrun agent please follow these steps:

1. In the application folder, install the python agent by running python -m pip install lightrun
2. Add the following code to your application's main init.py or app.py (the import shouldn't be added to a specific routed method, but to the main file code instead):

try: 
    import lightrun
    lightrun.enable(company_key='<COMAPNY-SECRET>')
except ImportError as e:
    print("Error importing Lightrun: ", e)

# Example route
@app.route("/")
def hello_world():
    return '<p>Hello world!</p>'

Installing the Lightrun Agent - Apache Airflow

In order to run Lightrun for Python with Apache Airflow you'll need to decide which step of the DAG you'd like to debug. Choose one (or more) steps and:

1. Find a place in your system that has access to the same Python interpreter that is used by Airflow, and install the python agent by running python -m pip install lightrun.
2. In an Airflow DAG file, add the following decorator above the operators you'd like to use Lightrun with:

@lightrun_airflow_task()
def operator_name():
    # Operator code

Debugging Airflow Multi-step DAGs with Lightrun's Free Tier

Please note that the Lightrun free tier limits usage to one agent per user. In practice, note this means that each operator can be debugged individually, but you cannot debug multiple operators simultaneously.