Installing the Python Agent
Installing the Python agent¶
The Lightrun agent is at the core of the Lightrun platform. It's the component that enables you to add information during runtime, without the need for redeployments or restarts.
Before running the agent, it must be installed on the server and its credentials declared either inside the application code, in the agent.config
file, or as environment variables entered at the command line.
Version Support
The instructions below apply to Python v2.7 and Python v3.6 onwards If you're interested in support for other versions, please reach out and let us know!
Windows Support
The Python agent currently is not supported on Windows. Please check the Python agent system requirements here.
Lightrun can be installed both directly and inside of a Docker container.
Direct installation¶
-
Install the python agent by running
python -m pip install lightrun
. -
Import Lightrun inside your
main
function, by adding the following code at the beginning of the function.try: import lightrun lightrun.enable(company_key="<COMPANY_SECRET>") except ImportError as e: print("Error importing Lightrun: ", e)
Note: Add the
server_url
parameter when using Lightrun on-prem.Alternatively, when running your Python application from the command line, you can pass the
<COMPANY_SECRET>
parameter as environment variables.python -m lightrun --company_secret=<COMPANY_SECRET> -- app.py
-
Run the application as you normally would; for example,
python app.py
.
Important
Lightrun actions in Python must only be applied to a function before it is called. Actions inserted within a function while it is executing take effect only once the function is exited and called again.
Getting Company Details
You can get <COMPANY_NAME>
and <COMPANY_SECRET>
by logging into the the Management Portal and inspecting the Download the Agent section.
Docker installation¶
Docker containers are epehmeral.
If you were to create a shell into a Docker container (by docker exec -it <container-id>
, for example) and add the Lightrun files there, they would disappear the next time the container would spin up due to the ephemeral nature of that container.
Instead, we suggest you install Lightrun by adding it to the underlying Docker image directly, i.e. by "baking" the agent into the image.
This is an example Dockerfile
that installs Lightrun with a simple dummy application, assuming the credentials were added to the source code of your application as shown above:
FROM python:3.8
RUN pip install lightrun
COPY prime_main.py /app/prime_main.py
CMD ["python", "/app/prime_main.py"]
If you prefer passing the credentials via the command line, here's how to do it inside a Dockerfile
:
FROM python:3.8
RUN pip install lightrun
COPY prime_main.py /app/prime_main.py
CMD ["python", "-m", "lightrun", "--company_secret=<COMPANY_SECRET>", "--", "app/prime_main.py"]
Note: Add the server_url
parameter when using Lightrun on-prem.
Important
Installing Lightrun in this fashion does not absolve you of the need to import
Lightrun to your application. Please make sure to add Lightrun as an import
to your application file.