Alerts and MQTT Broker Integration

Provider Connectivity Assurance Alerts

Provider Connectivity Assurance alerts are generated on threshold breach events and pushed to supporting clients via a publicly accessible message broker in MQTT format.

For more information, see Alerting Overview.

Getting Started

To begin, use your preferred MQTT client to explore the format of our alerts. The open-source tool MQTT Explorer (https://mqtt-explorer.com/) may be helpful for this purpose.

Authenticating

Token Requirement

To subscribe to the message broker, you will need a JSON Web Token (JWT). For detailed instructions on how to create one, refer to the article JSON Web Tokens.

Your payload should resemble the example below. Ensure that the necessary mqtt permission is included:

{
    "data": {
        "type": "tokens",
        "attributes": {
            "iss": "<your company>",
            "sub": "<your email>",
            "aud": "<your company>",
            "exp": <epoch time of expiry>,
            "permissions":["mqtt"]
        }
    }
}

Tenant Identifier Requirement

Additionally, you will need to obtain your Provider Connectivity Assurance tenant identifier. Use the following API to retrieve your tenant ID: Get Tenant Id By Alias

GET {{baseUrl}}/v2/tenant-by-alias/<tenant name>

where {{baseUrl}} is most likely https://<tenant name>.analytics.accedian.io/api

This API will return your tenant ID, which you will need—along with a JWT—to connect to the MQTT broker.

Subscribing to the Broker

Below is an example of the required connection settings:

• Protocol: websocket
• Host: tenant-name.analytics.accedian.io
• Port: 443
• Path: mqtt
• Username: tenant id, JWT
• Password: JWT
• Encryption: TLS

You must define a topic to which you want to subscribe. Otherwise, the tool will attempt to subscribe using a broad wildcard, which will fail due to insufficient permissions.

Click the Advanced button in the connection settings window to begin adding a subscription.

Below is an example of a typical topic subscription:

Exploring Alert Data

Use your MQTT client to examine the alert payloads:

Example Session Alert

{
    "alertState": "raised",
    "baseline": 0,
    "direction": 1,
    "dstLat": -33.9249,
    "dstLon": 18.4241,
    "duration": 60000,
    "metadata": {
        "customer_id": "etmartel",
        "demo": "test-the-internet",
        "destination_location": "south africa",
        "source_location": "montreal"
    },
    "metric": "packetsLostPct",
    "mitreTactics": null,
    "objectId": "28a495ca-1531-4f5c-90d4-3e887f769d09",
    "objectName": "aws-af-south-1",
    "objectType": "twamp-sf",
    "policyId": "f736fbaf-6a4d-4b2b-86cc-5ae741bdaff1",
    "policyName": "CR_R2P_PacketLoss",
    "policyType": "micro-tca",
    "processedTimestamp": 1714443043664,
    "source": "skylight-spark",
    "srcLat": 45.5019,
    "srcLon": -73.5674,
    "startTimestamp": 1714442880000,
    "tenantId": "a56b15ca-26d7-44b4-b228-5bc83b418b7b",
    "tenantName": "playground",
    "timestamp": 1714442880000,
    "topology": null,
    "triggeredValue": 1.39,
    "uid": "f123b0d8-90d2-429f-81e6-ad7b0e475468",
    "value": 0.1
}

Note: Session alerts also contain the session metadata.

Example Capture Alert

{
    "alertState": "raised",
    "captureApplicationId": 246,
    "captureLayer": "http",
    "captureMetaCertainty": 1,
    "captureMetaCertainty_percent": 100,
    "captureMetaDate_start": 1714443180,
    "captureMetaDate_stop": 1714443240,
    "captureMetaDesc": "hit.rt went above the configured threshold (1.).\n",
    "captureMetaFiring": true,
    "captureMetaFirst_sent": 1714443463.82,
    "captureMetaHostname": "d5eecb4f24a3",
    "captureMetaLast_sent": 1714443463.82,
    "captureMetaName": "5d339460-cf63-4b2b-9edb-1cd5823ed518 on hit.rt (configurator/static/sniffer/pvql/http#_/directed) triggered for 'application.id':246",
    "captureMetaNow": 1714443463.82,
    "captureMetaSite": "d5eecb4f24a3",
    "captureMetaStart": 1714443180,
    "captureMetaStop": 1714443240,
    "captureMetaThresholds": 1,
    "captureMetaValues": "0.004954,1.61972223256",
    "captureMetaWorker": "configurator/dynamic/5d339460-cf63-4b2b-9edb-1cd5823ed518/alert",
    "duration": 60000,
    "metric": "hit.rt",
    "mitreTactics": null,
    "objectId": "hit.rt",
    "policyId": "5d339460-cf63-4b2b-9edb-1cd5823ed518",
    "policyType": "capture",
    "processedTimestamp": 1714443463820,
    "source": "ramen",
    "startTimestamp": 1714443463820,
    "tenantId": "a56b15ca-26d7-44b4-b228-5bc83b418b7b",
    "tenantName": "playground",
    "timeInViolation": 283819,
    "timestamp": 1714443180000,
    "topology": null,
    "uid": "1655f960-cedc-475f-8c14-df4105be4632"
}