Opentelemetry Support in BW5 Adapters

Opentelemetry Support in BW5 Adapters

book

Article ID: KB0137881

calendar_today

Updated On:

Products Versions
TIBCO ActiveMatrix Adapter for SAP 7.3.2 Hotfix-01
TIBCO ActiveMatrix Adapter for Database 7.3.2 Hotfix-02
TIBCO ActiveMatrix Adapter for Files for Unix/Win 7.1.1 Hotfix-02

Description

The Opentelemetry features are supported in the following BW5 adapters:

 

TIBCO ActiveMatrix® Adapter for Database  version: 7.3.2 HF-02

TIBCO ActiveMatrix® Adapter for SAP version: 7.3.2 HF-01

TIBCO ActiveMatrix® Adapter for Files for Unix/Win version: 7.1.1 HF-02

Opentelemetry Tracing:

The following property must be set in the tra file of the adapter in order to enable Opentelemetry tracing:

bw.engine.opentelemetry.traces.enable true

The supported protocols are GRPC and HTTP. By default, GRPC protocol will be used. The protocol may be set explicitly as follows:

bw.engine.opentelemetry.span.exporter HTTP

or

bw.engine.opentelemetry.span.exporter GRPC

 

The endpoints are used according to the span exporter protocol used. The default values are:

With HTTP protocol:

bw.engine.opentelemetry.span.exporter.endpoint=http://localhost:4318/v1/traces

 

With GRPC protocol:

bw.engine.opentelemetry.span.exporter.endpoint=http://localhost:4317

 

When the above property is not added, the default endpoint will be set for the protocol chosen.

 

To enable Opentelemetry traces for adapter applications on the TIBCO Control Plane, follow these steps:

 

Halt the application by stopping both service instances after the deployment to the BW5 administration domain.

Add the following properties in the adapter service configuration TRA file:

bw.engine.opentelemetry.traces.enable true

java.property.bw.engine.opentelemetry.span.exporter=OTLP-HTTP

java.property.bw.engine.opentelemetry.span.exporter.endpoint=

http://<FQDN>/tibco/agent/o11y/<data plane id>/traces



In the process archive TRA file:

java.property.bw.engine.opentelemetry.traces.enable=true

java.property.otel.exporter.otlp.traces.protocol=http/protobuf

java.property.otel.exporter.otlp.traces.endpoint=

http://<FQDN>/tibco/agent/o11y/<data plane id>/traces

 

In case of port forwarding please execute below command:
kubectl port-forward -n <bm-dp-namespace> svc/otel-userapp-traces 4318:4318

 

The files are located at: <TRA_HOME>/domain/<domain_name>/application/<application>/

Restart both service instances and confirm the execution in the log files.

 
TIBCO ActiveMatrix® Adapter for Database:

When multiple processes are configured with more than one service, and each with its own message subject, there is no clear way to determine which service is in execution at any given time. So, the transport name is associated with the service name as a default service name attribute in the traces.

Opentelemetry Logging:

The following property must be set in the tra file of the adapter in order to enable Opentelemetry logging:

bw.engine.opentelemetry.traces.enable true

 

In BW engine:

java.property.bw.engine.opentelemetry.traces.enable=true

 

This will enable the Opentelemetry compliant logging of the application. This will ensure that in addition to the other attributes of the log messages, the trace id and span ids of the application trace will be appended to the messages.

 

TIBCO ActiveMatrix® Adapter for SAP:

In activities involving non-process starters using RV transport, the span context is initialized and the trace and the span ids are injected after the RVCM session starts. Hence the ids are not available in the logs before the session. However, the activity trace and the spans are collected and exported correctly and can be viewed at the span exporter endpoints. The trace and span ids are displayed correctly here.

Log4J support:

Please refer to the documentation, TIB_adr3_7.3.2_configuration_deployment for enabling Log4j logging. Additionally, the following property should be added to ensure the loading of the logging context by referencing the right properties file:

 

java.property.log4j2.configurationFile=file:/<adapter_home>/adr3/7.3/bin/adr3.log4j.properties

 

Opentelemetry Metrics:

By default, Opentelemetry metrics is configured to operate in Auto Configuration mode.

 

To enable support for metrics, the following properties must be added to the tra file of each adapter:

bw.engine.opentelemetry.metrics.enable true

 

The desired protocol can be set as shown below:

bw.engine.opentelemetry.metrics.exporter.protocol http/protobuf

 

The supported protocols are GRPC and HTTP. If the property is not set, then GRPC protocol will be used by default.

 

The endpoint depends on the protocol chosen. The default endpoints are:

With GRPC protocol: 

bw.engine.opentelemetry.metrics.exporter.endpoint http://localhost:4317

 

With HTTP protocol: 

bw.engine.opentelemetry.metrics.exporter.endpoint http://localhost:4318/v1/metrics

When the above property is not added, the default endpoint will be set for the protocol chosen.

When the metrics is auto configured, the metrics data is exported at an interval of 60000 milliseconds. To reduce the default value of the export interval, the system property given below may be added to the adapter tra file:

java.property.otel.metric.export.interval=30000

 

The auto configuration of Opentelemetry metrics can be disabled by using the property:

bw.engine.opentelemetry.metrics.disableAutoConfiguration true

 

In this case, an optimal value of 30000 milliseconds will be programmatically set into the configuration of the metrics exporters.

 

The adapter application stands for a distributed configuration with adapter service and the associated BW process, the following properties may be added to the BW engine to view the metrics with respect to the BW activities associated with the application:

 

java.property.bw.engine.opentelemetry.metrics.enable=true

java.property.bw.engine.opentelemetry.metrics.exporter.protocol=http/protobuf

TIBCO ActiveMatrix® Adapter for Database: 

When the ADB adapter initializes, by default the duplicate instance is detected. This operation initializes the counters for completed jobs in the adapter. Hence the counter will initialize to a non-zero offset. Therefore, duplicate detection must be disabled using the configuration property:

adb.noDupDetection on

Issue/Introduction

Opentelemetry Support in BW5 Adapters