lightrun 1.78.0
Add logs and snapshots (virtual breakpoints) to live applications - without stopping them.
License: Apache License, Version 2.0
Keywords: Lightrun

# Lightrun for Python

[Lightrun](https://lightrun.com) 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](https://lght.run/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](https://app.lightrun.com/api/oauth/register).
2. A Lightrun Plugin - you'll have instructions to download it once you create an account, but you can also check them out [here](https://docs.lightrun.com/python/plugin/).
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:

``` python
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.

3. 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](https://docs.lightrun.com/logs/), [snapshots](https://docs.lightrun.com/snapshots-plugin/) and [metrics](https://docs.lightrun.com/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:

```bash
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:

``` python
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):

``` python
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:

``` python
@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.