TIBCO BusinessEvents Application Tracing

In the TIBCO BusinessEvents application, the tracing feature for artifacts is provided out-of-the-box and can be enabled and configured in CDD through TIBCO BusinessEvents Studio.

Using OpenTelemetry, TIBCO BusinessEvents trace all units of work starting from the incoming event processing to post RTC by creating a span and using the span context to correlate them. All spans for a processed event in a TIBCO BusinessEvents application have the same trace-id and can be viewed as a unique transaction using analyzing software. The following analyzing software support is provided out-of-the-box with TIBCO BusinessEvents:

OpenTelemetry Collector
Jaeger
Zipkin

To use or add analyzing software other than the out-of-the-box supported software, see TIBCO BusinessEvents Contributions repository on GitHub.

To activate the instrumentation of your TIBCO BusinessEvents application, see Enabling the Application Tracing.

Components Tracing

The following table lists the components for which span is created by default if the telemetry data collection is configured in the TIBCO BusinessEvents application. Telemetry is initialized and your application code is instrumented only when a Span Exporter (value other than None) is configured for the application. For details about the Telemetry configurations in your TIBCO BusinessEvents application, see Telemetry Configurations Settings.

Note: If required, you can configure your application to ignore some of the entities for tracing. Use the telemetry configurations in the CDD to ignore entities using the specific URI or partial URI.

TIBCO BusinessEvents Components Telemetry Data
Component	Tracing operation
Destination	Deserializer- A message received on a channel destination is deserialized to an event. While deserializing, if the message is carrying a span context from a remote application, it is used to initialize a new span using propagators. Serializer - When an event is sent, it is serialized to transport a specific message. The span context is added to the message to pass on the `trace-id` and other information using propagators.
Rule function	A rule function invocation including a preprocessor execution creates a new span using the current context.
Rule	A rule action creates a new span using the current context.
State machine	As the state transition in state machines happens on events, each state transition is different execution and they could spread over one or many JVM processes (TIBCO BusinessEvents engine). The OpenTelemetry span is limited to a single process hence state machine state scope cannot be traced using a single `trace_id`. Instead, the state machine `instance_id` is added as an attribute to each span and all the state transitions related to an instance can be searched using that `instance_id`.
Post-RTC	Applicable only for cache OM (with or without store) or store OM. Cache provider - A span is created for each cache operation. Store provider - A span is created for each `save` transaction on the configured store.
Virtual rule function	A span is created for each `invoke` call of VRF catalog functions.
DataGrid catalog functions	A span is created for every call to `Cluster.DataGrid` catalog functions.
HTTP Catalog Functions	A span is created for each `send` call to HTTP client catalog functions.

Note: Tracing is not supported for the TIBCO BusinessEvents Process Orchestration.

Span Attributes

The following attributes are added to every span created in the TIBCO BusinessEvents application.

Cluster name
Engine name
Processing unit name
Thread name
Thread ID
Class name and method of catalog function or call origin
Artifact URI for the following artifacts:
- Destination
- Rule
- Rule function
- Virtual rule function
- State machine
Attributes based on span context by the TIBCO BusinessEvents engine:
- Destination Serializer/Deserializer - Default event URI and the serializer name.
- Rule - ExtId of business objects in scope. Other properties are not added as span attribute because it might impact the performance; however, if needed you can enable them by adding the following properties in CDD:
  - otel.trace.payload - when set to true, event payload is added as the span attribute for all events. The default value is false.
  - otel.trace.properties - when set to true, entity properties are added as the span attribute for all entities. The default value is false.
  - otel.trace.payload.Events/Application - when set to true, the event payload is added as the span attribute for this specific event. The default value is false.
  - otel.trace.properties.Concepts/Account - when set to true, entity properties are added as the span attribute for this specific entity. The default value is false.

Sampling

You can use the sampling strategy to control the noise and overhead by reducing the number of samples of traces collected and sent to the back end. TIBCO BusinessEvents provides you the option to select the sampling strategy as per your requirement. These sampling strategies are designed as per the OpenTelemetry specification:

Send all the spans
Don't send any span
Send only a fraction of spans

For more details, see:

Catalog Functions

Use OpenTelemetry catalog functions to add tracing to specific code in rules, rule functions or custom catalog functions. Each Span created using the catalog function uses the current context only.

The three major groups of OpenTelemetry catalog functions provided with TIBCO BusinessEvents Studio are:

Scope
Span
SpanBuilder

For the complete list of OpenTelemetry catalog functions and their syntax, see the TIBCO BusinessEvents Functions Reference.

Logging

Contextual information such as, trace_id, span_id and trace_flags can be added to application logs. A custom log configuration must be used by adding below pattern to the PatternLayout tag under the Appenders tag in the log4j2.xml file.

trace_id[%X{trace_id}] span_id[%X{span_id}] trace_flags[%X{trace_flags}]

The application log with trade_id and span_id can be used to correlate telemetry traces by exporting the log files to the OpenTelemetry collector. You can use a third-party (open-source or commercial) log processor and forwarder agent to export log files to the OpenTelemetry collector.