New Relic APM agent configuration rollback after schema change

Direct answer

Restoring newrelic.yml with an application rollback does not by itself roll back New Relic APM agent configuration. For any key that has a documented environment-variable equivalent, a persisted environment variable overrides the restored YAML value when the agent starts. New Relic APM agents do not roll back database or application schema changes, and they do not automatically clear stale environment variables during a deployment rollback.

Expected behavior and version assumptions

Assumptions: containerized deployment, configuration split between newrelic.yml and environment variables, and the agent is restarted as part of deployment or rollback. The exact agent language and version are not specified, so exact overridable keys cannot be listed here.

Environment variables override newrelic.yml only for keys with documented equivalents in that agent version; keys without an equivalent remain YAML-only. Do not assume every newrelic.yml key has an environment-variable equivalent. Dockerfile ENV instructions survive an image rollback. Kubernetes Deployment env fields revert with kubectl rollout undo only when they are part of the changed pod-template spec; separately managed ConfigMaps, Secrets, and image-built ENV do not automatically revert. If the variable remains set, it can re-enable the previous configuration after rollback.

Steps for this case

1. Tag and store the known-good newrelic.yml with the application release being rolled back.
2. Inspect current New Relic environment sources without changing anything:

kubectl exec deployment/example -- env | grep -i newrelic
kubectl get deployment example -o yaml | grep -i -A8 'env:'
docker history --format '{{.CreatedBy}}' example:tag | grep -i newrelic
kubectl logs deployment/example -c app | grep -iE 'newrelic|config|override'

Replace example, app, and tag with your deployment, container, and image values.

1. Revert newrelic.yml to the known-good version in the same change set as the application rollback.
2. Revert or remove New Relic environment variables in the image, Deployment, ConfigMap, or Secret. Do not rely on kubectl rollout undo to clear image-built ENV or separately managed ConfigMaps and Secrets.
3. Restart the affected instances so the agent rereads configuration, only after the manifest and env changes are reviewed:

kubectl rollout restart deployment/example

1. Verify after rollback: review agent logs or configuration reporting for effective values and configuration source. Confirm no stale New Relic environment variable remains and that restored YAML values are effective for YAML-only keys.

Schema change separation

Script agent-configuration rollback independently from application and database schema rollback. A database schema rollback does not undo agent instrumentation or configuration, and a config rollback should not be used as a substitute for schema rollback. Test the combined sequence in staging before production.

Missing diagnostic detail

Which New Relic agent language and exact version are in use? This changes the recommendation because the set of keys with environment-variable overrides, and therefore the YAML-only keys, differs by agent and version. Exact key names require verification against the agent documentation for your version.