Python

Supported Technologies

Confirm that the tCell agent supports your Python configuration, as shown below:

VersionApp ServersWeb FrameworksOSAuthentication Frameworks
2.7.x, 3.5 - 3.10.0***uWSGI 2.0.x
Gunicorn 19.10 - 20.1.0		Flask 0.8.0 - 2.0.2
Django 1.7.0 - 4.0.1*, **		Ubuntu 14+
Debian 8+
Alpine 3.7.1+		Not applicable

Python Support Legend

* - Login support only works with Django.
** - Django appfirewall events and account takeover features display an integer instead of the username/email. You must manually query the application's database to get those values. For example, if ID=2 and you want a corresponding 'User' object in the database (for example, user.email):
python manage.py shell

>>> from django.contrib.auth.models import User
>>> user = User.objects.get(id=2)
>>> user.email # or user.username or user

*** - Local File Inclusion (LFI) is not supported for Python 2.

Prerequisites

  • tCell account
  • Application created with tCell (Admin > Applications)
  • Outbound HTTPS connections to the tCell cloud allowed What IPs do tCell agents connect to?
  • Agent and config file downloads

To download the agent and config file:

  1. Click on "tCell Admin" in top nav bar.
  2. Click "Download Agent".
  3. Select "Python" agent.
  4. Select "Create New API Key" (default).
  5. Click "Download Config File" to download the agent's config file. The config file is pre-populated with the application and API key information.

Installation

  1. Install the tcell agent.

    tCell agent install
    1
    pip install tcell_agent

  2. Add the tcell_agent.config to your tcell directory, generally /var/www/html/tcell.

  3. Load tcell_agent with one of these methods:

    • Use the tcell_agent binary to run your app.

      If you previously started your web app like this,

      $ python manage.py runserver 0.0.0.0:8000

      you should now start it like this:

      $ tcell_agent run python manage.py runserver 0.0.0.0:8000

    • Load the tcell_agent via a wsgi.py file.

      Assuming your wsgi.py (Django) file looks something like this,

      python
      1
      import os
      2
      from django.core.wsgi import get_wsgi_application
      3
      

      4
      os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_waitlist.settings")
      5
      application = get_wsgi_application()

      modify it accordingly:

      python
      1
      import os
      2
      from django.core.wsgi import get_wsgi_application
      3
      

      4
      # optional: change default settings via ENV
      5
      # os.environ['TCELL_AGENT_CONFIG'] = '/var/www/html/tcell/tcell_agent.config'
      6
      # os.environ['TCELL_AGENT_HOME'] = '/var/www/html/tcell'
      7
      import tcell_agent
      8
      tcell_agent.init()
      9
      

      10
      os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_waitlist.settings")
      11
      application = get_wsgi_application()

Update the Agent

To update the Python agent to the newest version, run:

tCell agent update
1
pip install --upgrade tcell_agent

With this command, pip automatically updates the agent to the latest release in the Python Package Index.

Verification

To verify that data is being sent to tCell go to your tCell console and ensure that the number of app server agents listed for the application you just created is more than 0.

Troubleshooting

Log files can be found in the tcell/logs directory. If you don't see a tcell/logs directory, it's likely that the tCell agent has not started. If so:

  1. Verify that the tCell agent is being added to the server startup by running the following command: 
     
    1
    ps aux | grep --color tcell
  2. Check for errors in your catalina.out log. Alternatively, running bin/catalina.sh run or bin/catalina.bat run on Windows will start tomcat in the foreground, and print any errors while starting up.

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

json
1
"logging_options": {
2
    "enabled": true,
3
    "level": "INFO"
4
}

See tcell/tcell_agent.config.template for an example.

Valid log levels are:

  • ERROR
  • WARN
  • INFO (default)
  • DEBUG
  • TRACE

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.