Data Collection Masking¶

If you only need to globally modify or mask fields by name, use setDataModifier, which has lower performance overhead. Use setLineDataModifier only when you need to evaluate or replace values based on multiple fields within a single record.

Do not perform complex, time-consuming, or asynchronous operations in callbacks, as this will affect SDK data write performance.

DataModifier processes the tags and fields of raw Log, native RUM, and WebView RUM. Returning null means the original value is kept.

LineDataModifier runs after the SDK merges tags and fields; the callback receives the complete Map of the record. The return value is a patch containing only the fields to be replaced: only fields that already exist in the original data will be replaced. Returning null, an empty Map, null field values, or non-existent fields will not modify the data.

import {
  DataModifier,
  DataModifierValue,
  FTSDK,
  FTSDKConfig,
  LineDataModifier
} from '@guancecloud/ft_sdk/Index';

class FieldMasker implements DataModifier {
  /**
   * Modify a single tag or field.
   * Return null to keep the original value unchanged.
   */
  modify(key: string, _value: DataModifierValue): DataModifierValue | null {
    if (key === 'device_uuid' || key === 'authorization') {
      return '[masked]';
    }
    return null;
  }
}

class RecordMasker implements LineDataModifier {
  /**
   * Modify a single record.
   * measurement is the data measurement type, for example view, action, resource, longtask, error, or df_rum_harmonyos_log.
   * Return a Map containing only the fields to modify; returning null or an empty Map does not modify the data.
   */
  modify(measurement: string, data: Map<string, DataModifierValue>): Map<string, DataModifierValue> | null {
    const patch = new Map<string, DataModifierValue>();

    if (measurement === 'view' && data.has('view_url')) {
      patch.set('view_url', '[masked]');
    }
    if (data.get('message') === 'sensitive message') {
      patch.set('message', '[masked]');
    }

    return patch.size > 0 ? patch : null;
  }
}

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setDataModifier(new FieldMasker())
  .setLineDataModifier(new RecordMasker());

FTSDK.install(sdkConfig, this.context);

When data modification and blacklist filtering are configured together, the execution order for new data is: DataModifier → LineDataModifier → local and pulled remote blacklist filtering → write to local cache. Rules are evaluated based on the modified data.

After being pulled, remote blacklist rules also check the local cache before upload and delete historical data that matches the rules. Local blacklist rules only take effect before data is written to the cache and do not retroactively clean up cached data.

DataModifierValue supports string, number, boolean, and object. Objects are serialized to strings before being written to the local cache. Neither type of callback can add or remove fields, nor move data between tags and fields.