Configuring Individual Subscriber Tracing for EDGW

Individual subscriber tracing is supported for External Diameter Gateway using OpenTelemetry so that tracing can be enabled for either an individual subscriber or for a list of subscribers.

Subscriber identifiers are configured in Helm values files for the MATRIXX gateway components. When components process the messages and the subscriber ID matches the configured subscriber ID, the gateway component creates a span. This enables administrators to view in isolation the trace information relating to a specific subscription, device, or session. Traces can be viewed in the Jaeger UI.

Before you configure individual subscriber tracing, you must have access to the Vertx common library using OpenTelemetry.

Note: Only OLTP exporter is supported.

To configure tracing for individual subscribers, or a list of subscribers, add the configuration details described in OpenTelemetry Configuration Options to your MATRIXX Helm chart.

Table 1. OpenTelemetry Configuration Options
Configuration	Description
tracing.enable	Set to true to enable tracing; false to disable.
tracing.type	Tracing modes are: `ALL` — Collects all trace data. `SAMPLING` — Collects trace data that only matches the custom sampling condition. `RATIO` — Collects trace data that matches the configuration of the ratio based on the TraceID.
tracing.sampling[].key	The attribute key used to extract from the `Span` attribute and perform sampling. This is a string value, for example: `imsi`.
tracing.sampling[].values	List of string values that are collected as a sample only, for example: `[ 11, 12, 13 ]`.
tracing.ratio	The ratio for sampling traces based on TraceID values to control the volume of collected trace data: Only applicable when the `tracing.type` is RATIO. The ratio must be in the range 0.0 - 1.0.
tracing.openTelemetry.serviceName	This sets the value of the `service.name` resource attribute in Span, for example: `edgw` for External Diameter Gateway. For a list of all service name options, see the discussion about OpenTelemetry Tracing.
tracing.openTelemetry.propagators	Context propagation, a mechanism where identifiers for a trace are sent to remote processes. This is set as a List (Enum): `TRACE_CONTEXT` `BAGGAGE` `B3` `B3MULTI` `JAEGER`
tracing.openTelemetry.resourceAttributes	Sets the custom key and fixed value for the resource attribute in Span. Configure this string in the following format: `"key1=val1,key2=val2,key3=val3."`
tracing.openTelemetry.oltpType	Sets the OLTP exporter connection type. Options are: `GRPC` `HTTP`
tracing.openTelemetry.oltpEndPointUrl	The OLTP exporter endpoint URL, for example: http://localhost:4317.

The following code shows an example configuration for custom subscriber-based sampling for the External Diameter Gateway:

tracing:
  enable: true
  type: SAMPLING
  sampling:
    - key: sessionId
      values:
        - ses;222333444
        - ses;222333445
  openTelemetry:
    serviceName: edgw
    propagators:
      - B3MULTI
    resourceAttributes: "key1=value1,key2=value2"
    oltpType: GRPC
    oltpEndPointUrl: http://localhost:4317

With the following sample environment:

 environment:
      tracing.enable: 'true'
      tracing.type: 'SAMPLING'
      tracing.sampling: '[ {"key": "sessionId", "values": ["ses;222333444", "ses;222333445"]} ]'
      tracing.openTelemetry.serviceName: 'edgw'
      tracing.openTelemetry.propagators: '["B3MULTI", "TRACE_CONTEXT"]'
      tracing.openTelemetry.resourceAttributes: 'aaa=a1,bbb=b1'
      tracing.openTelemetry.oltpType: 'GRPC'
      tracing.openTelemetry.oltpEndPointUrl: 'http://collector:5555'

The following code shows the configuration for ratio-based sampling in External Diameter Gateway as an example:

tracing:
 enable: true
 type: RATIO
 ratio: 0.6
 openTelemetry:
   serviceName: edgw
   propagators: b3multi
   oltpType: GRPC
   oltpEndPointUrl: http://localhost:4317

To collect all traces in External Diameter Gateway, for example:

tracing:
 enable: true
 type: ALL
 openTelemetry:
   serviceName: edgw
   propagators: b3multi
   oltpType: GRPC
   oltpEndPointUrl: http://localhost:4317

The following code samples provides details for using the Maven dependency and calling init() from OpenTelemetry Tracing.

Note: The init() function ensures thread safety by using synchronized to restrict simultaneous creation of GlobalOpenTelemetry.

<dependency>
  <groupId>com.matrixx.common.vertx</groupId>
  <artifactId>vertx-tracing</artifactId>
</dependency>

OpenTelemetryTracing openTelemetryTracing = new OpenTelemetryTracing(tracingConfig);
openTelemetryTracing.init();

For more information about OpenTelemetry tracing in MATRIXX, see the discussion about OpenTelemetry Tracing.

For more information about Vertx or Open Telemetry, see Vertx or OpenTelemetry product documentation.