CAMARA Connectivity Insights

warning

This documentation is currently under development and subject to change. It reflects outcomes elaborated by 5G-MAG members. If you are interested in becoming a member of the 5G-MAG and actively participating in shaping this work, please contact the Project Office

CAMARA: Connectivity Insights API

Description

With the "Connectivity Insights" API, developers gain visibility into network quality: they can check whether their application's network requirements can be met for a given user session. Based on the API's response, developers can make informed decisions, such as requesting a network boost through the CAMARA Quality on Demand API or adjusting application settings (e.g., video resolution) to ensure the best possible user experience.

This API performs a single, on-demand ("one-shot") check. For continuous monitoring that pushes an event notification whenever network quality changes, see the companion Connectivity Insights Subscriptions API.

Information: Connectivity Insights project page and GitHub repository

The API definitions can be obtained here: ConnectivityInsights API_definitions folder

The Connectivity Insights API definition (YAML) is available at: connectivity-insights.yaml

Operations and dependencies

Connectivity Insights API

POST /check-network-quality with the request body containing an applicationProfileId, device, applicationServer (IP:port) - Check the network quality. Response shows the network's current level of confidence (qualitative) that it can meet an application profile's quality thresholds (according to those defined in the applicationProfileId) for a given end user device.
- Dependency: Requires applicationProfileId from a previous call to the Application Profiles API.

Standardisation context

Connectivity Insights is a CAMARA sandbox/incubating API (OpenAPI 3.0.3, Commonalities-conformant). It is a read-only, request/response API: it does not change any network state and does not create a QoS session. Where a QoS request maps to the NEF AsSessionWithQoS operation (TS 29.522), Connectivity Insights instead draws on the network's monitoring and analytics capabilities. Inside a 5G Core these are exposed as NEF monitoring events and, for predictive or aggregated signals, the Network Data Analytics Function (NWDAF). CAMARA does not require any particular source; an operator may satisfy the check from live measurements, from analytics, or from a mix.

The design decision most relevant to media is the qualitative response. Each threshold field in the reply carries a string such as "meets the application requirements" rather than a measured value; additionalKPIs adds supporting context (for example signalStrength, connectivityType). This keeps the API operator-agnostic (operators do not have to expose raw core measurements), but it limits how much an application can adapt: it learns that a requirement is not met, but not by how much. 5G-MAG's Self-Assessment records this as a gap for professional media, where a quantitative figure (for example the actual latency on the device-to-application-server path) would allow targeted remedies.

The check is instantaneous. It says whether requirements are met now, for the current position and radio conditions of the device; it makes no prediction about a future time window. For a scheduled production, a passing check does not guarantee the resource will still be available when the event starts. Where advance assurance is needed, a reservation-style API (QoS Booking or Network Slice Booking) is more appropriate, and where a boost is needed at the moment, Quality on Demand actually requests QoS rather than merely reporting on it. Connectivity Insights is therefore best read as a decision input, not a guarantee.

Workflow: Media application requesting Connectivity Insights

A user of a media application would like to obtain Connectivity Insights about the ability of the network to meet the requirements. The following steps are executed:

An Application Profile is created first (Step 0), then referenced in a single check-network-quality call (Step 1).

Step 0: Pre-conditions

Create an application profile using the Application Profiles API (with the relevant application requirements).
Create a device object for the device which media flow is to be monitored.
Obtain IP address and port of the application server (Ingest Server of Production).

Step 1: Obtain one-shot information on network quality

POST /check-network-quality, passing the applicationProfileId obtained in step 0, the address/port of an application server, and a device object.

5G-MAG's Self-Assessment

This section records 5G-MAG's practical reading of the API and the open points it raises for media use.

The APIs are likely to be invoked to obtain information about the ability of the network to meet the requirements either before or during operation. However:

The information received is instantaneous. Network status in the future cannot be derived from the response. Information provides no reliability for the actual time in which network should be used.
The information received is qualitative (e.g. "targetMinDownstreamRate": "meets the application requirements"). An application would be unable to understand which parameters to be adapted in order to revert a situation in which requirements cannot be met.

Potential improvements:

If used to monitor resources for which QoS was requested (via a different API) harmonization of Application Profile and QoS Profile for consistency.
an indication of the actual performance parameters (quantitative) for those defined in the Application Profile may provide better insight for potential remedies. E.g. latency cannot be fulfilled, but please respond with the actual latency the link device-AS is experiencing.

Application Profiles API Usage

Check: Application Profiles API. The type of parameters that an applicationProfile defines is shown below.

{
  "networkQualityThresholds": {
    "packetDelayBudget": {
      "value": 12,
      "unit": "Milliseconds"
    },
    "targetMinDownstreamRate": {
      "value": 10,
      "unit": "Bps"
    },
    "targetMinUpstreamRate": {
      "value": 10,
      "unit": "Bps"
    },
    "packetLossErrorRate": 3,
    "jitter": {
      "value": 12,
      "unit": "Milliseconds"
    }
  },
  "computeResources": {
    "targetMinCPU": 0.5,
    "targetMinMemory": {
      "value": 10,
      "unit": "Kb"
    },
    "gpuVendorType": "Nvidia",
    "gpuModelName": "string",
    "targetMinGPU": 1,
    "targetMinGPUMemory": {
      "value": 10,
      "unit": "Kb"
    },
    "targetMinEphemeralStorage": {
      "value": 10,
      "unit": "Kb"
    },
    "targetMinPersistentStorage": {
      "value": 10,
      "unit": "Kb"
    }
  }
}

Device object

This is how a device is defined:

{
  "device": {
    "phoneNumber": "123456789",
    "networkAccessIdentifier": "123456789@domain.com",
    "ipv4Address": {
      "publicAddress": "84.125.93.10",
      "publicPort": 59765
    },
    "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
  }
}

Connectivity Insights API Usage

Obtain information about network quality

With POST /check-network-quality passing:

the ApplicationProfileId,
the device object
identifier for the application server (IPv4 and/or IPv6 address and ports)

{
  "applicationProfileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "device": {
    "phoneNumber": "123456789",
    "networkAccessIdentifier": "123456789@domain.com",
    "ipv4Address": {
      "publicAddress": "84.125.93.10",
      "publicPort": 59765
    },
    "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
  },
  "applicationServer": {
    "ipv4Address": "192.168.0.1/24",
    "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
  },
  "applicationServerPorts": {
    "ranges": [
      {
        "from": 5010,
        "to": 5020
      }
    ],
    "ports": [5060, 5070]
  },
  "monitoringTimeStamp": "2023-07-03T12:27:08.312Z"
}

Type of response: The network's current level of confidence that it can meet an application profile's quality thresholds for a given end user device. Each threshold field carries a qualitative string (for example "meets the application requirements") rather than a measured value; additionalKPIs gives supporting signal information. The exact set of allowed strings is defined in the connectivity-insights.yaml.

{
  "packetDelayBudget": "meets the application requirements",
  "targetMinDownstreamRate": "meets the application requirements",
  "targetMinUpstreamRate": "meets the application requirements",
  "packetlossErrorRate": "meets the application requirements",
  "jitter": "meets the application requirements",
  "additionalKPIs": {
    "signalStrength": "excellent",
    "connectivityType": "5G-SA"
  }
}