cct-lce v4.0.3

CCT-LCE Documentation

CCT-LCE is specifically tailored for managing and monitoring data centers, with a primary focus on measuring and analyzing latency and bandwidth metrics. This documentation provides a comprehensive overview of the methods and properties available in the cct-lce.

Table of Contents

• Properties
  • allDatacenters
  • datacenters
  • runningLatency
  • runningBandwidth
  • compatibleDCsWithSockets
• Methods
  • fetchDatacenterInformation
  • fetchCompatibleDCsWithSockets
  • setFilters
  • stopMeasurements
  • startLatencyChecks
  • startBandwidthChecks
  • getCurrentDatacentersSorted
  • getAddress
  • store
  • getClosestDatacenters
• Events
• Types
  • Datacenter
  • LatencyChecksParams
  • BandwidthChecksParams
  • Location
  • LatencyEventData
  • IterationLatencyEventData
  • BandwidthEventData
  • IterationBandwidthEventData
  • FilterKeys

Properties

allDatacenters

An array initially empty, designated to store all known data centers. It is populated following the execution of the fetchDatacenterInformation request.

datacenters

A dynamically managed subset of the allDatacenters array. Initially, it is filled following the successful execution of the fetchDatacenterInformation request. Subsequently, its contents can be modified in response to the setFilters request, which adjusts which data centers are included based on the specified filtering criteria.

runningLatency

A boolean flag indicating whether latency measurements are currently active. When set to true, it signifies that latency monitoring processes are ongoing.

runningBandwidth

A boolean flag indicating whether bandwidth measurements are currently active. When set to true, it signifies that bandwidth monitoring processes are ongoing.

compatibleDCsWithSockets

An array containing data centers that have been identified as compatible with socket connections. It is populated following the execution of the fetchCompatibleDCsWithSockets request.

Methods

fetchDatacenterInformation

This method retrieves information about data centers from a specified URL and stores the data internally for further processing.

Parameters:

• dictionaryUrl (string, optional): The URL from which data center information is fetched.
  • default: https://cct.demo-education.cloud.sap/datacenters?isActive=true

Example Usage:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

console.log(cct.allDatacenters, cct.datacenters) // fetched datacenters is here.

fetchCompatibleDCsWithSockets

Identifies data centers that are equipped to handle socket connections and updates the internal records with this information.

Returns:

• Promise<Datacenter[]>: Returns a promise that resolves to an array of data centers that support socket connections.

Example:

const cct = new CCT();

const compatibleDCs = await cct.fetchCompatibleDCsWithSockets();

console.log(cct.compatibleDCsWithSockets) // fetched datacenters is here.

setFilters

Applies filtering criteria to the list of data centers based on various attributes.

Parameters:

• filters(FilterKeys, optional): Criteria to filter the data centers. Possible keys include:
  • name (string[], optional): Datacenter names.
  • cloud (string[], optional): Associated cloud services.
  • town (string[], optional): Towns.
  • country (string[], optional): Countries.
  • tags (string[], optional): Miscellaneous tags.

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

cct.setFilters({ country: ['USA', 'Canada'] });

console.log(cct.datacenters) // filtered datacenters

stopMeasurements

Stops all ongoing measurement processes and clears related resources.

Example:

// TODO
cct.stopMeasurements();

startLatencyChecks

This method initiates the process of measuring latency for data centers according to specified criteria.

Parameters:

• params (LatencyChecksParams): Configuration options for latency tests.
  • interval (number, optional): Time in milliseconds between each latency check.
    • default: 0
  • iterations (number, optional): Total number of latency checks to be performed.
    • default: 16
  • save (boolean, optional): Specifies whether to save the latency results.
    • default: true
  • from (string, optional): The ID of the data center from which latency is specifically measured.
    • default: undefined

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

await cct.startLatencyChecks({ iterations: 10, interval: 1000 });

startBandwidthChecks

This method initiates the process of measuring bandwidth for data centers according to specified criteria.

Parameters:

• params (BandwidthChecksParams): Configuration options for bandwidths measurements.
  • interval (number, optional): Time in milliseconds between each bandwidth check.
    • default: 0
  • iterations (number, optional): Total number of bandwidth checks to be performed.
    • default: 4
  • save (boolean, optional): Specifies whether to save the bandwidth results.
    • default: true
  • from (string, optional): The ID of the data center from which bandwidth is specifically measured.
    • default: undefined

  • bandwidthMode (BandwidthMode, optional): The mode of bandwidth measurement, either 'big' or 'small'.

    • default: big

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

await cct.startBandwidthChecks({ from: 'datacenterId', iterations: 5, bandwidthMode: 'small' });

getCurrentDatacentersSorted

Returns a list of currently managed data centers, sorted by average latency.

Returns:

• Datacenter[]: An array of sorted data centers.

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

const sortedDatacenters = cct.getCurrentDatacentersSorted();

getAddress

Retrieves your current geographical address.

Returns:

• Promise<Location | null>: A promise that resolves to the current location, or null if the location cannot be determined.

Example:

const location = await cct.getAddress();

store

Saves measurement data to a designated endpoint. The minimum threshold to initiate saving is 16 latencies.

Parameters:

• location (Location): Location data to be included in the storage payload.
• url (string, optional): The endpoint URL where the data will be sent.
  • default: https://cct.demo-education.cloud.sap/measurement

Returns:

Promise<boolean>: True if the data was successfully stored, false otherwise.

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

await Promise.all([cct.startLatencyChecks(), cct.startBandwidthChecks()]);

const success = await cct.store({ latitude: 34.0522, longitude: -118.2437, address: "some adress" }, "urlToSave");

getClosestDatacenters

Calculates and retrieves the closest data centers to a specified geographical point.

Parameters:

• latitude (number): Latitude of the target location.
• longitude (number): Longitude of the target location.
• url (string, optional): URL to fetch data center information if not already loaded.
• top (number, optional): Number of top closest data centers to return.

Returns:

Promise<Datacenter[]>: An array of the top closest data centers.

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation('https://api.example.com/datacenters');

const closestDCs = await cct.getClosestDatacenters({
  latitude: 34.0522,
  longitude: -118.2437,
  top: 5
});

Events

The CCT class extends an event emitter, enabling full utilization of its capabilities.

• latency: This event is emitted for each latency measurement for each data center. Event data is passed to callback LatencyEventData

• latency:iteration: This event is triggered whenever a new round of latency measurements has been completed for all data centers. It occurs sequentially; for instance, it is emitted after each data center has logged its first set of latency data, again after each has logged its second set, and so forth. Event data is passed to callback LatencyEventData[]

• latency:end: This event is emitted when the latency measurement process has either concluded or been prematurely stopped.

• bandwidth: Emitted for each bandwidth measurement obtained from each data center. Event data is passed to callback BandwidthEventData

• bandwidth:iteration: Emitted each time a complete round of bandwidth measurements is calculated for all data centers. This event is triggered sequentially, such as after each data center has logged its first set of bandwidth data, its second set, and so on. Event data is passed to callback BandwidthEventData[]

• bandwidth:end: This event is emitted when the bandwidth measurement process has either concluded or been prematurely stopped.

Example:

const cct = new CCT();

await cct.fetchDatacenterInformation();

cct.on('latency:iteration', (eventData) => {
    // react to event
});

await cct.startLatencyChecks();

cct.removeAllListeners();

Types

Datacenter

    type Datacenter = {
      id: string;
      position: number;
      cloud: string;
      name: string;
      town: string;
      country: string;
      latitude: string;
      longitude: string;
      ip: string;
      tags: string;
      lastUpdate: string;
      averageLatency: number;
      latencyJudgement?: Speed;
      averageBandwidth: BandwidthPerSecond;
      bandwidthJudgement?: Speed;
      latencies: Latency[];
      bandwidths: Bandwidth[];
      storedLatencyCount: number;
      storedBandwidthCount: number;
    };

LatencyChecksParams

  type LatencyChecksParams = {
    interval?: number;
    iterations?: number;
    save?: boolean;
    from?: string;
  }

BandwidthChecksParams

    type BandwidthChecksParams = LatencyChecksParams & {bandwidthMode?: 'big' | 'small'} 

Location

  type Location = {
      address: string;
      latitude: number;
      longitude: number;
  };

LatencyEventData

  type LatencyEventData = {
    id: string;
    data: {
      value: number;
      timestamp: number;
    };
  }

IterationLatencyEventData

LatencyEventData

BandwidthEventData

  type BandwidthEventData = {
    id: string;
    data: { 
      value: {
        bitsPerSecond: number;
        kiloBitsPerSecond: number;
        megaBitsPerSecond: number;
      }
    };
    timestamp: number;
  }

IterationBandwidthEventData

BandwidthEventData[]

FilterKeys

    type FilterKeys = { 
        name?: string[];
        cloud?: string[];
        town?: string[];
        country?: string[];
        tags?: string[];
    };