Instana U

Authors: Peng Deng, Hui Gao

The Instana AutoTrace WebHook is a Kubernetes and OpenShift-compatible admission controller mutating webhook. It automatically configures the Instana tracing on App Connect that run in IBM Cloud Pak for Integration.

IBM Cloud Pak for Integration is a hybrid integration platform with an automated, closed-loop approach that supports multiple styles of integration within a single and unified experience. It includes IBM MQ, IBM App Connect Enterprise (ACE), and other products.

Instana AutoTrace WebHook automatically enables tracing for ACE instances that are based on IBM App Connect server Docker image. However, manual configuration is needed to enable tracing for ACE instances that are based on a customized Docker image.

Requirements

Before you enable ACE Tracing, ensure that the following requirements are met:

• Red Hat OpenShift 4.5 or later is installed.

• Helm 3.2 or later (some automation relies on Helm lookup function) is installed.

• IBM App Connect Enterprise server image versions 11 and 12 or later are installed.

• If ACE OpenTelemetry Tracing is applied, OpenTelemetry data ingestion for Instana is enabled.

For more information about configuring OpenTelemetry data ingestion for Instana, see Configuring OpenTelemetry data ingestion.

Enabling tracing automatically through Instana AutoTrace WebHook

To enable tracing through Instana AutoTrace WebHook, complete the following steps:

1. Install Instana AutoTrace Webhook by running the following command by using your administrator privileges for your cluster:

helm install --create-namespace --namespace instana-autotrace-webhook instana-autotrace-webhook \
--repo https://agents.instana.io/helm instana-autotrace-webhook \
--set webhook.imagePullCredentials.password=<download_key> --set openshift.enabled=true \
--set autotrace.ace.enabled=true

• Note: Replace <download_key> with a valid Instana download key.

2. Restart the ACE pod to activate ACE Tracing.

• For ACE versions before 12.0.8, the Instana user exit for ACE Tracing is deployed automatically into the ACE integration server instance.

• For ACE 12.0.8 or later, the native OpenTelemetry Tracing for ACE is automatically enabled for the ACE integration server instance.

Viewing traces

After the ACE Tracing is enabled, you can view traces in the Instana UI. To check the tracing call details, complete the following steps:

1. From the sidebar in the Instana UI, click Applications > Services. The service name includes Pod IP and integration server name of ACE. The format is <ACE_Pod_IP>-<IntegrationServer_Name>:<IntegrationServer_Name>, for example, 10.254.17.125-is-01-1206:is-01-1206.
   
   

2. Click a service name to view its tracing call details in the Summary tab of the service dashboard.

Enabling ACE OpenTelemetry Tracing manually

If you don't use the official ACE Docker image or tag the official ACE Docker image with a new name, Instana AutoTrace WebHook can't support ACE Tracing. So you need to enable ACE OpenTelemetry tracing manually.

Note: ACE OpenTelemetry Tracing is only applicable for App Connect Enterprise 12.0.7.0 or later.

To enable ACE OpenTelemetry Tracing manually, complete the following steps:

1. Specify environment variable HOSTALIAS in an existing Integration Server custom resourse (CR) or a new Integration Server CR.

spec:
  env:
    - name: HOSTALIAS
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: status.hostIP

2. On the App Connect Dashboard UI, create a server.conf.yaml configuration or edit the server.conf.yaml file, which is used by an Integration Server instance, by adding following lines:
   

 3. Apply the server.conf.yaml configuration to a new or an existing Integration Server instance.

4. Check the Integration Server instance log to confirm that the ACE OpenTelemetry Tracing is enabled successfully. For example:

2023-12-06T02:42:28.484Z Enabled otel tracing in server.conf.yaml
2023-12-06 02:42:39.599408: BIP9577I: Configured OpenTelemetry 'OTLP/GRPC' exporter with attributes [ SSL=false, URL=10.22.45.178:4317 ].

Viewing traces

After the ACE tracing is enabled, you can view traces in the Instana UI. To check the tracing call details, complete the following steps:

1. From the sidebar in the Instana UI, click Applications > Services. The service name includes the integration server name, and the format is IBM App Connect Enterprise-<IntegrationServer_Name>, for example, IBM App Connect Enterprise-is-01-customer.

2. Click a service name to view its tracing call details in the Summary tab of the service dashboard.