Configuring OpenTelemetry tracing for integration runtimes

If you are deploying an integration runtime for a Toolkit integration, you can configure OpenTelemetry tracing for all message flows in the integration runtime, and export span data to an OpenTelemetry collector.

When OpenTelemetry is enabled for an integration runtime, spans are created for all message flow nodes that support OpenTelemetry, including callable flow nodes.

For supported transport input nodes, spans are created and then run until the message flow transaction for the flow is completed or rolled back. For supported transport request nodes, spans are created and then run for the duration of the node interaction with the transport (for example, sending and receiving an HTTP message). For information about the transport message flow nodes that support OpenTelemetry trace, see Configuring OpenTelemetry trace for an integration server in the IBM® App Connect Enterprise documentation.

An Observability agent or backend system such as Instana, Jaeger, or Zipkin must be available and configured to receive OpenTelemetry data. When you deploy an integration runtime, configuration options are provided for you to enable OpenTelemetry tracing.

Instana-specific configuration

If you are using an Instana agent for observability, you must activate OpenTelemetry support in the host agent to enable the reception of OpenTelemetry data in that host agent. You can do so by updating your host agent's configuration.yaml file as follows: 
com.instana.plugin.opentelemetry:
  enabled: true

For more information, see Activating OpenTelemetry Support in the Instana documentation. For information about using Instana in IBM Cloud Pak for Integration, see Enabling IBM Instana monitoring.

Configuring additional OpenTelemetry properties by using the server.conf.yaml file

While creating an integration runtime from a Toolkit integration, you can use the options provided to configure OpenTelemetry tracing for all message flows in the integration. The server.conf.yaml file (from an IBM App Connect Enterprise 12.0.7.0 or later Modification Pack) contains an additional set of OpenTelemetry properties. If you want to configure these additional properties, you can use the server.conf.yaml file to create a configuration object that can be applied to the integration runtime as follows:

  1. Obtain a copy of the server.conf.yaml configuration file from the /home/aceuser/ace-server directory in the pod, or from the local directory installDir/server/sample/configuration where IBM App Connect Enterprise Toolkit is installed. A sample file is provided in server.conf.yaml type.
  2. In the ResourceManagers section of the file, edit the OpenTelemetryManager subsection as required. For more information, see Configuring OpenTelemetry trace for an integration server in the IBM App Connect Enterprise documentation.

    The following example shows the OpenTelemetry settings in a 13.0.2.0 server.conf.yaml file that is supported in IBM App Connect Operator 12.7.0 or later.

      OpenTelemetryManager:
    #openTelemetryEnabled: false          # Enable or disable OpenTelemetry tracing.
    #openTelemetryServiceName: ''         # Override the Service Name attribute for telemetry spans. Defaults to integration server name.
    #openTelemetryHostName: ''            # Override the value of the Hostname attribute for telemetry spans.
    #exporterOtlpGrpcEndpoint: ''         # Specify a GRPC endpoint to which OpenTelemetry span data is sent. For example, '<hostname>:4317'.
    #exporterOtlpHttpUrl: ''              # Specify a HTTP Url to which OpenTelemetry span data (json) is sent. For example, 'http://<hostname>:<port>/v1/traces'.
    #openTelemetryHttpSecurityId: ''      # Specify an opentelemetry credential used in the HTTP exporter.
    #openTelemetryGrpcSecurityId: ''      # Specify an opentelemetry credential used in the GRPC exporter.
    #openTelemetryTruststoreType: ''      # The type of the open telemetry truststore [PKCS12, PEM or JKS]. Only used for the GRPC exporter.
    #openTelemetryTruststoreFile: ''      # The location of the open telemetry truststore. Only used for the GRPC exporter.
    #openTelemetryTruststorePass: ''      # Credential or resource alias containing the truststore password. Only used for the GRPC exporter.
    #openTelemetryTrustAlias: ''          # The alias of the trust certificate in the PKCS12 or JKS truststore.
    #openTelemetrySpanProcessor: 'batch'  # Specify the OpenTelemetry span processor ['batch' or 'simple'].
    #openTelemetryBatchSpanOptions: ''    # Specify the OpenTelemetry batch span processor options. For example, 'max_queue_size=4096:schedule_delay_millis=5000:max_export_batch_size=4096'
  3. Use the edited server.conf.yaml file to create a configuration object of type server.conf.yaml. For more information, see server.conf.yaml type.
  4. Ensure that this configuration object is specified as a configuration that you want to apply to the integration runtime. (You can reference this configuration object in the spec.configurations setting in the integration runtime custom resource.)