IBM Performance Management

Configuring the Python agent

You must configure the Monitoring Agent for Python so that the agent can collect data from the Python application that is being monitored.

Before you begin

Ensure that the Apache HTTPD server is started before you configure the agent.

Open the Apache HTTPD server httpd.conf configuration files and ensure that mod_status is loaded.

Make sure the command apachectl status works properly in the monitored Apache server with no code changes to the httpd.conf configuration file. If it doesn't work fine you might not be able to see some metrics in the dashboards, for example, Busy worker and Idle worker.

Note: You must have Lynx installed for the command apachectl status work properly. For more information about enabling the command, see apachectl - Apache HTTP Server Control Interface.

If this is not the first time you configure the agent instance, follow the steps:

Stop the agent instance.
Follow one of the procedures to configure the agent instance:
- Configure the agent by editing the silent response file.
- Configure the agent by responding to prompts.
Make sure that the new middleware is deployed to the Django setting folder. To do that, make sure the kpg_numeric_string.py file in the Django setting folder is updated.
Restart the Apache server.

About this task

To avoid permission issues when you configure the agent, be sure to use the same root user or non-root user ID that was used for installing the agent. If you installed your agent as a selected user and want to configure the agent as a different user, see Configuring agents as a non-root user. If you installed and configured your agent as a selected user and want to start the agent as a different user, see Starting agents as a non-root user.

The Python agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify Python2 as your instance name, your managed system name is Python2:hostname:PG.

Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly.

Procedure

To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps:
1. Open install_dir/samples/python_silent_config.txt in a text editor, where install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent.
2. For HTTPD listening port, specify the port number to distinguish one group of HTTPD processes from others. The default is 80.
  Note:
  - If your Apache server is listening on multiple ports, you can specify any one of them for this parameter.
  - If you have more than one Apache server running on the same system, you must specify a port from the server in which the Django applications are running.
  - If you want to use multiple agent instances to monitor Python application instances that are using different ports on the same Apache server, besides specifying the ports, you must also specify different Django WSGI entry points in the next step. If you only specify the ports, the agent instances monitor the same server and the data is the same.
3. For Is Python 3, if the value of this field is false, your Python environment is regarded as Python version 2.x. If your Python version is 3.x, change the value to be not false, for example, true. The default value is false.
4. For Django WSGI entry points, specify the Django WSGI entry points. Use a colon to separate multiple entry points.
  For example, in an Apache configuration file, you might see the following configuration line:
  WSGIScriptAlias / /var/www/html/mysite/mysite/wsgi.py
  In this example, /var/www/html/mysite/mysite/wsgi.py is provided as the entry point.
  
  To include all the entry points that are discovered in the Apache configuration files, leave this parameter blank.
  Note: Do not specify the same Django WSGI entry point for different agent instances. If you use the default option to configure one agent instance to monitor an Apache server, do not configure other agent instances to monitor the same server.
5. For Django settings for the monitored application, specify the Django settings for the monitored application, for example, my_project.settings. If you are using default values, leave this field empty.
6. For Minimum recorded response time, set the average response time in milliseconds. Requests that are faster or equal to this number are not recorded. The default is 300.
7. For Slow request threshold, set the slow request threshold in milliseconds. The default is 500.
8. For Extreme slow request threshold, set the extreme slow request threshold in milliseconds. The default value is 7000.
9. For Profiler report interval, set the interval in minutes, at which the agent generates the profiler report for slow requests. The minimum setting for this value is 10, which ensures your applications are not slowed down because of excessive profiling. Typical users set this value greater than 10. The default is 10.
  This parameter also tells the agent script how to aggregate the monitoring data. At the beginning of each minute, the monitoring middleware resets its data, which is collected from the previous minute and starts to write a new raw data file. The agent script summarizes raw data based on this parameter and returns the result. For example, if this number is 10 minutes, agent scripts aggregate all raw data for the previous 10 minutes and return the results. The final result might be an average, such as response time for one particular URL, or the result might be a sum, such as total requests or traffic bytes.
10. Save and close the python_silent_config.txt file, then enter:
  install_dir/bin/python-agent.sh config instance_name install_dir/samples/python_silent_config.txt
  Where instance_name is the name that you want to give to the instance, and install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent.
11. To start the agent, enter:
  install_dir/bin/python-agent.sh start instance_name
To configure the agent by running the script and responding to prompts, complete the following steps:
1. Enter:
  install_dir/bin/python-agent.sh config instance_name
  Where instance_name is the name you want to give to the instance, and install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent.
2. When prompted to Edit Monitoring Agent for Python settings, enter 1 to continue.
3. When prompted for HTTP listening port, press Enter to accept the default or specify a port number.
  Note:
  - If your Apache server is listening on multiple ports, you can specify any one of them for this parameter.
  - If you have more than one Apache server running on the same system, you must specify a port from the server in which the Django applications are running.
  - If you want to use multiple agent instances to monitor Python application instances that are using different ports on the same Apache server, besides specifying the ports, you must also specify different Django WSGI entry points in the next step. If you only specify the ports, the agent instances monitor the same server and the data is the same.
4. When prompted for Is Python 3, type false if your Python version is not 3. If your Python version is 3.x, specify a value that is not false, for example, true. The default value is false.
5. When prompted for Django WSGI entry points, leave this parameter blank or specify the entry points.
  Note: Do not specify the same Django WSGI entry point for different agent instances. If you use the default option to configure one agent instance to monitor an Apache server, do not configure other agent instances to monitor the same server.
6. When prompted for Django settings for the monitored application, specify the Django settings for the monitored application, for example, my_project.settings. If you are using default values, leave this field empty and press Enter.
7. When prompted for Minimum recorded response time, press Enter to accept the default or specify the time.
8. When prompted for Slow request threshold, press Enter to accept the default or specify a threshold.
9. When prompted for Extreme slow request threshold, press Enter to accept the default or specify a threshold
10. When prompted for Profiler report interval, press Enter to accept the default or specify an interval.
11. To start the agent, enter:
  install_dir/bin/python-agent.sh start instance_name

What to do next

After you start the agent instance, an injection script to customize your monitoring middleware is generated and provided in a temporary directory.

The injection shell script runs automatically after the agent starts. If you want to make sure that this step was correctly executed, you can make sure that the following files exist:

install_dir/tmp/kpg/inject_numeric_string.sh
Django_setting_folder/kpg_numeric_string.py

Important: The suffix numeric string identifies a Django application. If you have multiple injection scripts that were generated in that temp folder, you see the same number of kpg_numeric_string.py files.

Generally, an injection script does the following jobs:

Backs up the original WSGI setting file for each Django application.
Copies the customized WSGI setting file to override the original file
Moves the customized middleware to the Django application folder.
Enables module status for Apache server.

The injection script also generates the uninstallation scripts to help you uninstall the middleware from each Django application.

Note: Multiple injection scripts might include the enablement of the Apache status module, however, when executing the scripts the module is only added once.

For your reference, you can use the following stop and restart commands for the Apache server:

Stop: apache_bin_directory/httpd -k graceful-stop
Restart: apache_bin_directory/httpd -k graceful