How to get logs from the Ruby agent

Objective

In rare scenarios, bad instrumentation causes a web server process to crash or a specific page to error out. If you ever encounter a crash or error caused by Contrast, please report the error via the Submit a Request link at the bottom of this page.

If possible, follow the steps below to gather agent logs and process dumps; this additional information is vital to reproducing and fixing these types of bugs.

Process

Agent Logs Directory

The Ruby agent logs information based on the configuration provided by the YAML configuration. By default, agent logs are written to the current working directory under the name contrast_agent.log.

You can change which information is logged by changing the logging level in the Ruby agent configuration.

Types of Bugs

There are two primary types of agent bugs for which Contrast needs to gather logs and other information:

• Process Crash
• Unhandled Managed Exception

Process Crash Bugs

Verify that the web server process crashed

Check your scenario against the following indicators to confirm that the web server process crashed.

• The web application is unresponsive after installing the Ruby agent.
• The console log for the process has a Segmentation Fault. This will probably result in an error message containing [BUG] Segmentation fault at:  followed by a memory address.

Once you confirm that the observed bug is a process crash, you're ready to gather information to file a support request.

Gather information on the process crash

Complete the following steps to gather information to send to Contrast.

• Add the following configuration to the YAML file to enable verbose logging and logging of every interaction between the agent and the Contrast Service.

agent:
  logger:
    level: DEBUG
    path: ./contrast_agent_debug.log

If your application is running in an SaaS/CaaS environment where the logs are not easily accessible, logging can be sent to STDOUT instead by setting
path: /dev/stdout

• Verify that the Contrast-Service is no longer running. If the Service is still running in your environment, terminate it manually.
• In Windows, you can run tasklist /fi "imagename eq Contrast-Service.exe".
• In Linux or Mac, you can run ps aux | grep Contrast-Service.
• Clear your console.
• Exercise the application to reproduce the crash.

Once you've reproduced the crash, gather the following items and include them in your bug report:

• Agent logs: The contrast_agent_debug.log and contrast_service_debug.log files; both files should be in the application's root directory.
• Application logs: The logs from your application run, which are most likely in the logs directory of the application.
• Console logs: The results of the process crash in your terminal.
• State logs: While the agent logs capture much of the operating system information, it's helpful to know what, if any, third-party Gems are being used. Even though it's not strictly a log, include your Gemfile.lock as part of the reproduction information collected.

You should restore your logging levels to their original settings at the end of this process.

Unhandled Managed Exception or Page Error Bugs

Verify an unhandled exception

The process described in the previous section can also help the Ruby agent team resolve issues such as application errors caused by the Ruby agent. Use the following indicators to determine if the Ruby agent is causing an application error.

• You've observed the application working normally without the agent.
• You've observed a page of the application "crashing" (returning a 500 error) under the agent.
• There are no errors in the application logs in the logs directory.

Gather information on the exception

Follow the process outlined in the previous section to Gather information on the process crash, but omit the Console logs step.

Additional Logging

In rare cases, additional information may be required to properly diagnose the root cause of the undesired behavior. To facilitate this, the Ruby agent provides a convenience wrapper around Ruby's built in heap dump utility. To take a heap dump of your application with the agent enabled, add the following to your YAML configuration and restart the application. A background thread is then spawned and begin to automatically take heap dumps.

agent:
  heap_dump:
    enable: true
    path: ./contrast_heap_dumps

The results are saved to the contrast_heap_dumps directory in the root of your application. By default, the Ruby agent takes five heap dumps spanning 10 seconds with a 10 second pause between each. You can find additional configurations in the Ruby agent configuration articles.

Note: Taking these measurements will adversely impact performance; you should restore your configuration to the original settings at the end of this process.

Other Bugs

If you encountered a bug other than a process crash or unhandled exception - such as a false positive found by the agent - please contact us via the Submit a Request link at the bottom of this page. Contrast doesn't usually need console error logs, but debug-level logs and a detailed description of the problem are very helpful when it's time to fix these bugs.