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.