Python Troubleshooting

The Instana package has been designed to be fully automatic but if something goes wrong, please file a ticket and let us know! We love to hear feedback (good or bad) so we can continually improve.

The following page outlines some steps you can take to potentially diagnose any issues that may arise.

Supported Components

Before spending too much time diagnosing an issue, first make sure that the component in question is supported. A list of all supported components can be found in the Python Supported Versions page.

Logging & Environment Variables

By default, the package will only log messages that indicate if any problems are encountered. If you want a more verbose logging output, set the INSTANA_DEBUG environment variable. It enables debug level logging in the Instana gem.

There are even more methods to control logging output. See the Python Configuration page for more details.

Problem Areas

Python Process doesn’t show up in dashboard

1. Check Instana Host Agent logs for any messages related to this Python process.

Many Python processes will be remotely instrumented automatically. In the cases where this is not possible, the Host Agent will may log a message indicating a problem.

2. Validate that your environment is supported and you are running a supported version of Python

Before spending too much time diagnosing an issue, first make sure that the component and environment in question is supported. A list of all supported components can be found in the Python Supported Versions page.

3. Validate the Install steps

Was this process instrumented via AutoTrace or manual?

If via AutoTrace, make sure that the configured whitelist matches the candidate process you want instrumented.

If manual, validate that the Manual Installation steps were properly followed.

4. Validate that the Instana Python package is installed and available to the application

This can be validated by seeing instana in the Python application requirements.txt file.

Alternatively, from the Python application environment, you can run pip list. This will list all of the Python packages available to the Python application. Validate that the Instana Python packages is in that list.

5. Assure that the Instana package is the latest version.

The latest version released can be found on Pypi.

In the requirements.txt, you should see the latest version of the Instana Python package noted alongside the name such as instana==x.x.x. pip list also outputs version numbers in the generated list.

6. Validate that Instana is mentioned in the application log output.

Application and/or container logs should always have a boot message similar to Stan is on the scene. Starting Instana instrumentation version x.x.x

If this isn’t there, then it is very likely that the package isn’t installed or manual installation steps were not properly followed.

7. Enable debug output and re-check application or container logs.

Set the environment variable INSTANA_DEBUG=true for the Python process and revalidate the application or container logs (same as #6).

Pay special attention to see if there are any Instana related error messages.

8. Try booting the Python application in verbose mode from a console

An example on how to do this depends largely on the Python application in question. As an example, if the Python application is contained in you can run the following commands:

export INSTANA_DEBUG=true

Pay special attention to see if there are any Instana related error messages in the Python application output.

9. File a Support Ticket.

If you validated all of the above and the Python process still doesn’t show up in the Instana dashboard, please file a Support Ticket so that we can investigate further.

The support ticket should include:

  1. Environment details; platform, Python version, frameworks in use
  2. Summary of all of the above validations.

AutoTrace is Crashing a Python process

1. File a Support Ticket

If you haven’t done so already, please file a support ticket so we can investigate the situation.

2. Update the Instana Agent Host configuration.yaml to modify AutoTrace behavior

This documentation page explains how to configure Python AutoTrace. With this, you can blacklist the crashing process or disable AutoTrace entirely. This can act as a temporary work-around until the root cause of the crash is identified and fixed.

3. Use the Manual Installation Method

In the interim, you can alternatively use the manual installation method for Python visibility.

Migrating to Python AutoTrace

AutoTrace is now the default method of instrumentation for Python applications monitored by Instana. It will automatically instrument Python applications that pass the whitelist and blacklist filter configured in the host agent configuration.yaml. For details on this, see the Configuring Python AutoTrace section of the documentation.

For existing customers, you may still have Python applications that were manually instrumented previously. This will not cause any issues for Instana or Python AutoTrace. Python AutoTrace will not attempt to re-instrument those applications.

If you prefer to fully migrate to Python AutoTrace for your environment, to see Python processes as they come and go automatically, this section will outline the steps required.

To fully migrate to Python AutoTrace, you must remove the following from your applications:

1. The Instana Python package

Python AutoTrace will independently manage the Instana Python package for your application. There is no need for you or your organization to install it manually.

Make sure to remove the instana Python package from your requirements.txt, Pipfile or virtualenv.

Note: If you are making OpenTracing API calls, you should explicitly import opentracing instead and make sure that your calls are made against that package (e.g. `opentracing.tracer.startactivespan`). Instana will still receive resulting traces.

2. Remove AUTOWRAPT_BOOTSTRAP environment variable

This environment variable is used to load the Instana Python package without any code changes required. With Python AutoTrace, this is no longer needed.

3. Remove any import instana calls

Python AutoTrace will automatically apply the Instana Python package to your Python applications. Manual imports of the Instana Python package can be removed.

See Also