Open topic with navigation

TIBCO BusinessEvents® Enterprise Edition 6.3.1

# 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.

## 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:

- OpenTelemetry documentation

- OpenTelemetry Specification on GitHub

## 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.

## Using OpenTelemetry Tracing with TIBCO BusinessEvents and TIBCO FTL

To use the same OpenTelemetry transaction when using OpenTelemetry tracing with TIBCO BusinessEvents and TIBCO FTL, add the `_traceparent` field of type String to the TIBCO FTL message format. You can either set this field in the `tibrealm.json` file before starting the TIBCO FTL server or configure it through the TIBCO FTL server GUI.

Did you find this helpful?

YesNo
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO BusinessEvents® Enterprise Edition

Copyright © 2004-2024. Cloud Software Group, Inc. All Rights Reserved.