Configuring OpenTelemetry trace for an integration server

You can configure OpenTelemetry trace for IBM® App Connect Enterprise integration servers on the Linux® x86-64, Linux zSeries, Linux on POWER® Systems - Little Endian, AIX®, and Windows platforms.

Configure OpenTelemetry trace for all flows on an integration server by completing the following steps:

1. Open the server.conf.yaml configuration file for your integration server.

   You can edit the file by using the built-in YAML editor that is provided in the IBM App Connect Enterprise Toolkit, either by double-clicking the file in the Application Development view or by right-clicking the file and selecting Open with > YAML editor. If you choose to edit the file by using a plain text editor, ensure that you do not include any tab characters (which are not valid in YAML) and use a YAML validation tool to validate the contents of your file.

2. In the ResourceManagers section of the server.conf.yaml file, set the properties that you require in the OpenTelemetryManager subsection:
   • Set the openTelemetryEnabled property to true to enable OpenTelemetry for all message flows on the integration server. By default, this property is set to false. For information about disabling OpenTelemetry for an individual message flow after it has been enabled on the integration server, see Turning off OpenTelemetry for a message flow.
   • Use the openTelemetryServiceName property to override the Service Name attribute for telemetry spans. By default, this property is set to App Connect Enterprise-<integration server name>.
   • Use the openTelemetryHostName property to override the Hostname attribute for telemetry spans.
   • Use the exporterOtlpGrpcEndpoint property to specify the GRPC endpoint to which the OpenTelemetry span data is to be exported. For example: 'telemetryagent.host.com:4317'.
   • Use the exporterOtlpHttpUrl property to specify the HTTP/JSON URL to which the OpenTelemetry span data is to be exported. For example, 'http://<hostname>:<port>/v1/traces'.
   • Use the openTelemetryTruststoreType property to specify the type of the OpenTelemetry truststore. Valid values are PKCS12, PEM, and JKS. This property is used only for the GRPC exporter.
   • Use the openTelemetryTruststoreFile property to specify the location of the OpenTelemetry truststore. This property is used only for the GRPC exporter.
   • Use the openTelemetryTruststorePass property to specify the credential or resource alias containing the truststore password. This property is used only for the GRPC exporter.
   • Use the openTelemetryTrustAlias property to specify the alias of the trust certificate in the PKCS12 or JKS truststore.
   • Use the openTelemetrySpanProcessor property to specify the type of OpenTelemetry span processor to be used. You can specify either batch or simple. By default, this property is set to batch.
   • Use the openTelemetryBatchSpanOptions property to specify the OpenTelemetry batch span processor options that you want to use. You can specify multiple options, separated by colons (:). For example: 'max_queue_size=4096:schedule_delay_millis=5000:max_export_batch_size=4096' .

     For more information about the OpenTelemetry batch span processor options, see the OpenTelemetry documentation.

   For example:

   
   ResourceManagers:
       JVM:
          #jvmVerboseOption: 'none'
          #jvmDisableClassGC: ''
          #jvmEnableIncGC: ''
          #jvmShareClasses: ''
           .......
           .......
           ....... etc..
           ....... 
       OpenTelemetryManager:
          openTelemetryEnabled: true                           # Enable or disable OpenTelemetry tracing. Available on Linux/x86-64. 
          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: 'localhost:4317'           # The GRPC endpoint to which the OpenTelemetry span data is sent. 
                                                               # For example, 'telemetryagent.host.com:4317'.
          exporterOtlpHttpUrl: ''                              # The HTTP/JSON URL to which the OpenTelemetry span data is sent. 
                                                               # For example, 'http://<hostname>:<port>/v1/traces'.
          openTelemetryTruststoreType: ''                      # Type of OpenTelemetry truststore. Valid values are PKCS12, PEM, or JKS.
                                                               # Used only for the GRPC exporter. 
          openTelemetryTruststoreFile: ''                      # Location of the OpenTelemetry truststore. Used only for GRPC exporter.
          openTelemetryTruststorePass: 'truststore::password'  # Credential or resource alias containing the truststore password.
          openTelemetryTrustAlias: ''                          # Alias of the trust certificate in the PKCS12 or JKS truststore.
          openTelemetrySpanProcessor: 'batch'                  # OpenTelemetry span processor. Set to either 'batch' or 'simple'. 
                                                               # Default is 'batch'.
          openTelemetryBatchSpanOptions: 'max_queue_size=4096' # OpenTelemetry batch span processor options, separated by colons (:). 
                                                               # For example, 'max_queue_size=4096:max_export_batch_size=4096'

3. Save the changes and restart the integration server for the changes to take effect.
4. You can check the OpenTelemetry settings that are active for an integration server by using one of the following methods:
   • Use the administration REST API to issue a GET on /apiv2/resource-managers/opentelemetry-manager for independent integration servers
   • Run the mqsireportproperties command using the object name opentelemetry-manager on a managed integration server.