To deploy the APM Java agent, follow the below steps:

1. Before proceeding, confirm you have completed the prerequisites and provisioned the APM Java agent.
   Note
   
   When provisioning the APM Java agent, it's recommended to provision it in any location of your local machine and then copy it to a Docker image.
2. Modify your Dockerfile to copy the APM Java agent to a Docker image:

   COPY <DESTINATION_DIRECTORY>/oracle-apm-agent <Docker_Image_Directory>/oracle-apm-agent/

   Note that <DESTINATION_DIRECTORY> denotes the location on your local machine where you provisioned the APM Java agent and <Docker_Image_Directory> denotes the directory in the Docker image to which you're copying the APM Java agent. The <Docker_Image_Directory> could also be the application server destination directory in Docker, for example, $DOMAIN_HOME, if you're working with Oracle WebLogic Server.

3. Add the following -javaagent option to the startup script of your application server:

   java -javaagent:<Docker_Image_Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar target/<appserver.jar>

4. Build a new Docker image with the built-in APM Java agent and the modified startup script, and push the image to the registry.

If you use Kubernetes to manage your Docker containers, then update your Kubernetes configuration to use the new Docker image, and restart the Kubernetes pod.

Also, you can set additional dimensions to be reported from the Kubernetes pod using the Downward API, by copying the following environment and volume settings in the deployment specification (yaml file) of the Kubernetes pod. For information on the Downward API, see The Downward API in Kubernetes documentation.

Environment Settings

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    env:
      - name: APM_ATTRIBUTES_K8S_POD_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.name
      - name: APM_ATTRIBUTES_K8S_NAMESPACE_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.namespace
      - name: APM_ATTRIBUTES_K8S_NODE_NAME
        valueFrom:
          fieldRef:
            fieldPath: spec.nodeName

Volume Settings

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    volumeMounts:
      - name: apm-attributes-k8s
        mountPath: /etc/apm-attributes-k8s
    volumes:
      - name: apm-attributes-k8s
        downwardAPI:
         items:
           - path: "labels"
             fieldRef:
               fieldPath: metadata.labels
           - path: "annotations"
             fieldRef:
               fieldPath: metadata.annotations

Prerequisite: Install the OpenTelemetry Operator into the Kubernetes cluster.

There are three different options available: Operator release manifest, Operator helm chart, or Operator Hub.

In most cases, a cert-manager should be installed. If the helm chart option is used, there is an option to generate a self-signed cert instead.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.2/cert-manager.yaml

To install the OpenTelemetry operator, run the following:

kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

Deploy the APM Java agent

To deploy the APM Java agent, follow these steps:

1. Create a Kubernetes Custom Resource (CR).

   To manage automatic instrumentation, the OpenTelemetry Operator needs to be provided with information about the APM Java agent and its configuration which it's done using the Custom Resource Definition (CRD).

   This Custom Resource will be used by the operator to copy the agent into the pod and add to it the required configuration.

   To create the CR, run the following:

   kubectl apply -f - <<EOF
   apiVersion: opentelemetry.io/v1alpha1
   kind: Instrumentation
   metadata:
     name: inst-apm-java
     namespace: opentelemetry-operator-system
   spec:
     java:
       image: container-registry.oracle.com/oci_observability_management/oci-apm-java-agent:1.15.0.516
       env:
         - name: OTEL_com_oracle_apm_agent_data_upload_endpoint
           value: <data-upload-endpoint>
         - name: OTEL_com_oracle_apm_agent_private_data_key
           value: <private-data-key>
   EOF

   Where:

   • <data-upload-endpoint> is the data upload endpoint URL that is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
   • <private-data-key> is the APM Java agent installation private data key which is generated when the APM domain is created. For information, see Obtain Data Upload Endpoint and Data Keys.
   The created CR can be queried by running the following command:

   kubectl get otelinst -n opentelemetry-operator-system

   All endpoints and environment variables required to be correct for auto-instrumentation to work properly.
2. Add the Kubernetes annotation.

   The OpenTelemetry operator uses Kubernetes annotation to decide which pods should be auto-injected with the APM Java agent.

   The annotation can be added to a namespace. In that case, all the pods within that namespace will get injected. The annotation can also be added to individual PodSpec objects, available as part of Deployment, Statefulset, and other resources.

   Annotation:

   instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"

   To start editing your namespace, do the following:

   • Run the command:

     kubectl edit namespace <your-namespace-name>

   • Edit the namespace once the editor is opened. For example, vi editor.
   • Add the annotation to the namespace. Keep in mind indentation is very important to make it as a valid YAML file.
   Example:

   apiVersion: v1
   kind: Namespace
   metadata:
     labels:
       kubernetes.io/metadata.name: mynamespace
     annotations:
       instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"
     name: mynamespace
   spec:

3. Restart the Kubernetes pod.

   To restart the pod where you want to auto-inject the APM Java agent, run the following:

   kubectl delete pod <your-pod-name> -n <your-namespace-name>

4. Verify the Kubernetes pod.
   To verify that your pod has been auto-injected with the APM Java agent after it was restarted, run the following:

   kubectl get pod <your-pod-name> -n <your-namespace-name> -o yaml

You can now go to the next step: Verify APM Java Agent Deployment.

To deploy the APM Java agent on a mounted volume, follow these steps:

1. Confirm you completed the APM Java agent prerequisite tasks.

   Make a note of the data upload endpoint and data key when the APM Domain was created.

2. Create a new file system that will mount the pods.

   When creating the file system, it's important to ensure to select the same Virtual Cloud Network (VCN) Compartment that Kubernetes is using. Do the same for the Subnet Compartment.

3. Mount the file system into the pods.

   This step requires edits to the corresponding yaml files.

   Create the PersistentVolume and related entities in Kubernetes, using the below yaml file. Note the following fields you need to edit for your environment: mntTargetId, server and path.

   kind: StorageClass
   apiVersion: storage.k8s.io/v1
   metadata:
     name: oci-fss
   provisioner: oracle.com/oci-fss
   parameters:
     mntTargetId: ocid1.mounttarget.oc1.iad.xxxxxxxxxxxxxxxxxxxxxx
   ---
   apiVersion: v1
   kind: PersistentVolume
   metadata:
    name: oke-fsspv
   spec:
    storageClassName: oci-fss
    capacity:
     storage: 10Gi
    accessModes:
     - ReadWriteMany
    mountOptions:
     - nosuid
    nfs:
   # Replace this with the IP of your FSS file system in OCI
     server: 10.0.10.39
   # Replace this with the Path of your FSS file system in OCI
     path: "/fss-for-kub"
     readOnly: false
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
    name: oke-fsspvc
   spec:
    storageClassName: oci-fss
    accessModes:
    - ReadWriteMany
    resources:
     requests:
    # Although storage is provided here it is not used for FSS file systems
       storage: 10Gi
    volumeName: oke-fsspv

   To apply the changes, run kubectl apply -f <filename.yaml>

   Then, update the yaml file that manages the pods and add the volume and volume mount.

   To take effect, recreate the pods.

4. Download the APM Java agent file.

   Download and copy the file to the mounted volume.

   For download instructions, see Download the APM Java Agent Software.

   After downloading, copy it to the mounted volume.

5. Provision the APM Java Agent.

   Log in to one of the containers to provision the APM Java Agent, locate the apm-java-agent-installer jar file and run the following:

   java -jar ./apm-java-agent-installer-<version>.jar provision-agent -service-name=<Name of the Service> -destination=<Destination_Directory> -private-data-key=<Agent installation key generated during APM domain creation> -data-upload-endpoint=<dataUploadEndpoint URL generated during APM domain creation>

   For provisioning instructions, see Provision the APM Java Agent.

6. Deploy the APM Java Agent.

   Deploy the APM Java Agent by providing the oracle-apm-agent location to the microservice in the yaml file.

   Add the -javaagent argument and the APM agent jar file location to the java command of each microservice:

   java -javaagent:<Mounted Volume>/oracle-apm-agent/bootstrap/ApmAgent.jar

7. Restart Kubernetes.

   Recreate the pods by running: kubectl apply -f <filename.yaml>.

   You can now go to the next step: Verify APM Java Agent Deployment.