1. Home
  2. Guides
  3. Implementation
  4. Replacing Stackify Retrace Agents: Java, PHP, Node.js, Python and Ruby
IntermediateImplementation

Replacing Stackify Retrace Agents: Java, PHP, Node.js, Python and Ruby

Swap the Stackify Retrace agent for the Atatus agent in Java, PHP, Node.js, Python and Ruby apps, one app at a time, so nothing goes unmonitored before Retrace shuts down on March 31, 2027.

9 min readAtatus TeamUpdated November 16, 202610 sections

01Before you start: what Retrace installed

Each language has its own Retrace profiler. Know what you are removing.

Stackify Retrace shuts down on March 31, 2027, and BMC says there is no automated way to move to another tool. Retrace instruments each language with its own profiler or package, and on servers it also runs the Retrace agent, a background service that sends the data to Stackify. Both have to go.

Java: the Stackify Java profiler, turned on with a -javaagent JVM option that points at stackify-java-apm.jar.

PHP: a PHP extension, loaded with extension=stackify.so from php.ini or from a 99-stackify.ini file.

Node.js: the stackify-node-apm package, required at the top of your main module, with a stackify.js config file.

Python: the stackify-python-apm package, added as Django middleware or with StackifyAPM(app) in Flask.

Ruby: the stackify-ruby-apm gem, configured in config/stackify_apm.yml.

Export the logs and dashboards you must keep before you change anything. See how to export Stackify Retrace data. For .NET apps, use the .NET migration guide.

02Use one APM agent per app

Remove Retrace from an app before you add Atatus to it.

Stackify's Ruby docs tell you to check that no other profiler is installed in the project, and neither vendor documents running two APM agents in the same process for these languages. Treat it as one agent per app.

For a side-by-side comparison, run Atatus on a staging copy of the app, or on one server while the other servers keep reporting to Retrace. Compare request rate, response times, error count and the slowest endpoints for a few days before you move the rest.

03Java

Swap one -javaagent option for another. No code changes.

Install Atatus: download atatus-java-agent.jar and start the JVM with -javaagent:/path/to/atatus-java-agent.jar, plus -Datatus.license_key and -Datatus.app_name. The Java install guide has the full command.

What it covers: JDK 7 and above, on Spring Boot, Tomcat, GlassFish, JBoss, Jetty, WebLogic, WebSphere Liberty, WildFly and Akka.

Remove Retrace: the Stackify Java profiler is turned on by its -javaagent option, so take that option out of your JVM arguments, along with any STACKIFY_ settings, before you add the Atatus one.

Logs: log correlation is on by default for SLF4J, Logback and Log4j 2. For java.util.logging it works through log reformatting, which you turn on. See Java log correlation.

04PHP

Replace one PHP extension with another. No code changes.

Install Atatus: install the atatus-php-agent package with your license key and app name, then check that it loaded with php -i | grep atatus. The PHP install guide covers Debian and Ubuntu, and the docs also cover Red Hat, musl-based Linux, macOS and tarball installs.

What it covers: PHP 5.6 and above. Laravel, Symfony, WordPress, Magento, Drupal, Yii, Zend, Slim, CakePHP and Silex are instrumented without extra setup. CodeIgniter, Lumen and Phalcon need a small config change.

Remove Retrace: Retrace loads as the stackify.so extension. Remove that line from php.ini, or delete the 99-stackify.ini file, then restart PHP-FPM or your web server so only the Atatus extension loads.

Settings: the license key, app name and on/off switch live in atatus.ini as atatus.license_key, atatus.app_name and atatus.enabled.

05Node.js

One package out, one package in.

Install Atatus: run npm install --save atatus-nodejs, create an atatus.js file that calls atatus.start() with your license key and app name, and preload it with node -r ./atatus.js. See the Node.js install guide.

What it covers: Node.js 14 and above, with Express, Hapi, Restify, Koa and NestJS.

Remove Retrace: delete the require('stackify-node-apm') line and the stackify.js file, then run npm uninstall stackify-node-apm.

Logs: set ATATUS_CAPTURE_LOGS=true to capture console and winston 3.x logs, linked to the request that wrote them. See Node.js log correlation.

06Python

Change the middleware and the package.

Install Atatus: run pip install atatus. For Django, add atatus.contrib.django to INSTALLED_APPS and an ATATUS settings block with APP_NAME and LICENSE_KEY. For Flask, install atatus[flask] and wrap your app with Atatus(app). FastAPI works through atatus.contrib.starlette. See the Django install guide.

Remove Retrace: take out stackifyapm.contrib.django and its TracingMiddleware (Django) or StackifyAPM(app) (Flask), then run pip uninstall stackify-python-apm.

Logs: Atatus links logs to traces through its log formatter, with a processor for structlog. See Python log correlation.

07Ruby

Switch Retrace off, then swap the gem.

Install Atatus: add gem 'atatus' to your Gemfile, run bundle install and put your license_key and app_name in config/atatus.yml. Rails 4.2 and above, Sinatra and Grape are supported. See the Rails install guide.

Switch Retrace off: Stackify documents turning its Ruby agent off with instrument: false in config/stackify_apm.yml, or with the STACKIFY_INSTRUMENT=false environment variable. Then remove the stackify-ruby-apm gem.

Logs: Atatus can add trace IDs to your Rails logs. See Ruby log correlation.

08Remove Stackify logging libraries

Some apps send logs to Retrace through a Stackify library. Take those out too.

Besides the APM agent, some Retrace apps send their logs through a Stackify logging library, either directly with your Retrace API key or through the Retrace agent. Remove it along with the agent, so no log calls keep trying to reach a service that is shutting down.

Java: the stackify-log-log4j12, stackify-log-log4j2 and stackify-log-logback artifacts add a Stackify appender to log4j, Log4j 2 or Logback. Remove the appender from log4j.properties or log4j.xml, log4j2.xml or log4j2.properties, or logback.xml, and the dependency from your build.

PHP: the stackify/monolog package adds a Stackify handler to Monolog, stackify/logger is a standalone logger, and Stackify also published a log4php appender. Remove the handler or appender and the Composer package.

Node.js: the stackify-logger and winston-stackify packages add a Stackify transport to winston. Remove the transport and both packages.

Python: the stackify-api-python package adds a StackifyHandler to the standard logging module. Remove the handler and the package.

Ruby: the stackify-api-ruby gem sends logs to Retrace. On Rails it is set up in config/initializers/stackify.rb, plus any Stackify::LoggerProxy in config/environments. Elsewhere it uses Stackify.setup and Stackify::LoggerProxy. Remove that setup and the gem.

The Retrace agent can also collect some server logs itself, such as PHP, Nginx and Apache logs and syslog. That stops when you remove the agent from the server.

Then send your logs to Atatus. Node.js apps can turn on the agent's log capture for console and winston 3.x logs written inside a traced transaction. The Java, Python and Ruby agents add trace IDs to your log lines but don't send the logs, and the PHP agent doesn't capture logs. For those languages, ship your log files with the Atatus Infra Agent or send logs over HTTP with the log ingest API.

09Remove the Retrace agent from each server

Last step, once every app on the server has moved.

On Linux, Stackify documents stopping and removing its agent with sudo service stackify-agent stop, followed by sudo ./agent-install.sh --remove from the installer directory.

Only do this after every app on that server reports to Atatus, because the agent serves all the Retrace profilers on the machine.

10After the switch: alerts and dashboards

Start with the alerts that page people.

Rebuild these first: high error rate, slow responses on key endpoints and servers running low on memory or disk. Set them up in Atatus alerting once you have a few days of data, so the thresholds match what normal looks like.

Recreate the views your team checks during an incident in Atatus dashboards, most important first.

Prefer an open standard over vendor agents? See moving from Stackify Retrace to OpenTelemetry. Still comparing tools? See Atatus as a Stackify alternative.

FAQ

Frequently asked questions

Talk to an engineer
  • Yes. Retrace's own agents cover .NET, Java, PHP, Node.js, Python and Ruby, and Atatus has agents for all six, plus Go. Atatus also accepts OpenTelemetry data from any language with an OpenTelemetry SDK.

  • Neither vendor documents it, and Stackify's Ruby docs tell you to make sure no other profiler is installed. Use one APM agent per app: compare the two on a staging copy or on separate servers, then remove Retrace from each app as you move it.

  • For Java and PHP, no: you swap a JVM option or a PHP extension. For Node.js you swap the package, add an atatus.js file and change the start command. For Python you change the middleware or app wrapper, and for Ruby a gem and a config file.

  • Yes. Atatus accepts OpenTelemetry traces, metrics and logs over OTLP, so you can instrument with OpenTelemetry SDKs and send the data to Atatus.

Get started today

Monitor your applications with Atatus

Put the concepts from this guide into practice. Set up full-stack observability in minutes with no credit card required.

  • No credit card required
  • 14-day free trial
  • Setup in minutes
Keep reading
ImplementationBeginner

How to Export Your Stackify Retrace Data Before March 31, 2027

Stackify Retrace shuts down on March 31, 2027, and its data does not move to any other tool. Here is what you can export, the limits, what you have to write down by hand, and how to keep your history going in your next tool.

6 min
Read guide
ImplementationIntermediate

Migrating .NET Apps from Stackify Retrace to Atatus

Replace the Stackify Retrace .NET profiler with the Atatus .NET agent on IIS, .NET Framework and .NET 5+, one app at a time, so every app stays monitored until Retrace shuts down on March 31, 2027.

10 min
Read guide
ImplementationIntermediate

Moving from Stackify Retrace to OpenTelemetry

BMC recommends OpenTelemetry as the standard to replace the Stackify Retrace agents. What OpenTelemetry captures compared with the Retrace profilers, how to send the same data to two tools while you choose, and how to send it to Atatus.

9 min
Read guide