Cut over the Java agent

Switch a Java application from dual-signal reporting to OpenTelemetry-only reporting or replace the combined agent with Splunk OpenTelemetry Java instrumentation.

Overview

Use this procedure to stop Java application reporting to Splunk AppDynamics while preserving OpenTelemetry telemetry to Splunk Observability Cloud.

Prerequisites

Confirm that the Java application passed Phase 5 validation and that you have:

  • The installed Java Agent version and its matching documentation.
  • A restorable copy of the last verified dual-signal configuration.
  • The approved OpenTelemetry endpoint and resource attributes.
  • A change window, representative traffic, and an approved rollback procedure.

Select the cutover method approved for the application:

  • Switch the combined agent to OpenTelemetry-only mode. Use this method when the installed Java Agent supports OpenTelemetry-only mode.
  • Replace the combined agent with Splunk OpenTelemetry Java instrumentation. Use this method only when replacement is part of the approved deployment plan.

Switch the combined agent to OpenTelemetry-only mode

  1. Open the OpenTelemetry-only mode instructions for reference, then select the documentation version that matches the installed Java Agent.
  2. Record the current Java command line, environment variables, OpenTelemetry route, and resource attributes.
  3. Change the agent deployment mode from dual to otel by using one supported method for the installed release:
    • Java command-line option: -Dagent.deployment.mode=otel
    • Environment variable: AGENT_DEPLOYMENT_MODE=otel
  4. Keep the verified OpenTelemetry endpoint, protocol, service name, namespace, deployment environment, and other approved resource attributes unchanged.
  5. Restart or redeploy the application through the approved change process.
  6. Generate representative traffic.
  7. Complete the checks in Validate and Stabilize After Cutover.

Do not copy agent options from a different Java Agent release. Do not configure both deployment-mode methods with conflicting values.

Replace the combined agent

Use this method only when the approved design requires standalone Splunk OpenTelemetry Java instrumentation.

  1. Record the current agent startup options and preserve the rollback package and configuration.
  2. Confirm the supported Splunk OpenTelemetry Java distribution and version for the application runtime.
  3. Configure the approved OpenTelemetry endpoint and the same service-identity values validated during dual-platform operation.
  4. Remove the Splunk AppDynamics Java Agent startup option and add the approved Splunk OpenTelemetry Java Agent startup option in the same controlled deployment.
  5. Confirm that the application starts with only the intended automatic instrumentation.
  6. Generate representative traffic and complete the post-cutover checks.

If validation fails or a rollback trigger occurs, use Roll Back the Cutover.