mcctl utility Reference Guide

Version: 1.0
Last Modified: 7/1/2020

What is mcctl utility?

The mcctl utility is designed to provide access to the MobiledgeX APIs from the command line. This is a MobiledgeX supported utility and can be downloaded from Artifactory. Binaries for both MacOS and Linux x86_64 are available.

To download the mcctl utility:

  1. Go to artifactory.mobiledgex.net. Log in to Artifactory using the same credentials used to log into the Edge-Cloud Console.
  2. On the left navigation, select your preferred platform and then download.

Artifact Repository Browser
Artifact Repository Browser

Once downloaded, you will need to add execute permission to the file in order to execute it. This can be done by using the terminal to run chmod 755 ./mcctl.

Users of MacOS Catalina will need to take an additional step to authorize the application with Gatekeeper. This involves the following steps:

  1. Open finder in the directory (folder) where you have downloaded the mcctl program. This can be done by running open . in the terminal.
  2. Launch the app you’re trying to run and acknowledge the Gatekeeper warning that prevents the app from running.
  3. Head to System Preferences > Security and Privacy > General, and look for a note at the bottom of the screen about an app launch being denied.
  4. Click Open Anyway to bypass Gatekeeper and launch the app.

Overview of mcctl

Command Help

Running mmctl with either the -h flag or no arguments will cause it to print the usage information. Additionally, the help information will display when invalid commands or arguments are specified (this behavior can be changed by supplying the --silence-usage flag to mcctl).

$ mcctl
Usage:
  mcctl [command]
  User and Organization Commands
    login                   Login using account credentials
    user                    Manage your account or other users
    role                    Manage user roles and permissions
    org                     Manage organizations
    billingorg              Manage billing organizations
  Operator Commands
    cloudlet                Manage Cloudlets
    cloudletpool            Manage CloudletPools
    cloudletpoolinvitation  Manage CloudletPool invitations
    cloudletinfo            Manage CloudletInfos
    trustpolicy             Manage TrustPolicys
    restagtable             Manage ResTagTables
    operatorcode            Manage OperatorCodes
    cloudletrefs            Manage CloudletRefs
    vmpool                  Manage VMPools
  Developer Commands
    cloudletshow            View cloudlets
    cloudletpoolresponse    Manage CloudletPool responses to invitations
    app                     Manage Apps
    clusterinst             Manage ClusterInsts
    appinst                 Manage AppInsts
    autoscalepolicy         Manage AutoScalePolicys
    autoprovpolicy          Manage AutoProvPolicys
    appinstclient           Manage AppInstClients
    appinstrefs             Manage AppInstRefs
    appinstlatency          Manage AppInstLatencys
    runcommand              Run commands on AppInst containers
    runconsole              Get console access on VM AppInsts
    showlogs                Show container logs
  Logs and Metrics Commands
    metrics                 View metrics
    billingevents           View billing events
    events                  Search events and audit events
    usage                   View App, Cluster, etc usage
    alertreceiver           Manage alert receivers
  Other Commands
    version                 Version of mcctl cli utility
  Flags:
        --addr string            MC address (default "http://127.0.0.1:9900")
        --data string            json formatted input data, alternative to name=val args list
        --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
        --debug                  debug
    -h, --help                   help for mcctl
        --output-format string   output format: yaml, json, or json-compact (default "yaml")
        --output-stream          stream output incrementally if supported by command (default true)
        --parsable               generate parsable output
        --silence-usage          silence-usage
        --skipverify             don't verify cert for TLS connections
        --token string           JWT token
Use "mcctl [command] --help" for more information about a command.  

Additionally, using the keyword help along with the command you wish to view help information will provide additional data. For example, to get help on the audit command option, you can simply run:

$ mcctl  --addr https://console.mobiledgex.net  help audit
show audit logs
Usage:
  mcctl audit [command]
Available Commands:
  showself    
  showorg     
Flags:
  -h, --help   help for audit
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token
Use "mcctl audit [command] --help" for more information about a command.  

Output Formats

The mcctl utility will produce output in three different formats:

Using mcctl

Logging In

In order to use mcctl, you must first log into the API to retrieve an authorization token.

$ mcctl login --addr  https://console.mobiledgex.net  name=jschmidt                   
password:
login successful
token saved to /home/jschmidt/.mctoken   

Permissions Error

Commands for which you do not have permission to run will be rejected with a 403 return code from the API.

$ mcctl config  --addr  https://console.mobiledgex.net   show   
Error: Forbidden (403), Forbidden
Usage: mcctl config show [flags] [args]
Required Args:
Optional Args:
Flags:
  -h, --help   help for show
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token   

Specify Array Values to mcctl

A number of inputs to the mcctl utility are passed as arrays of multiple values. These inputs will be shown in the format of somearray:#.somevalue in the help output.

There are two ways to specify array inputs, as described below.

Using a File

Create a yaml file with all the fields and values required by the command. You can view the required information by using mcctl with the command and (if needed) subcommand without any additional arguments. For example, to list the required and options arguments for the app create command, run mcctl app create.

The sample below shows a YAML file that defines two configurations to the MobiledgeX platform as part of creating an application.

Sample YAML File

region: EU
app:
  key:
    name: deleteme
    organization: testmonitor
    version: '1.0'
  image_path: docker.mobiledgex.net/testmonitor/images/myfirst-app:v1
  image_type: 1
  configs:
  - config: "<yaml-content0>"
    kind: helmCustomizationYaml
  - config: "<yaml-content1>"
    kind: helmCustomizationYaml  

Once the YAML file is created, it can be passed to the mcctl utility using the --datafile command line option:

mcctl app create region --datafile <above-filename.yml>

Using the CLI

It is also possible to pass this information on the command line. This requires that you replace the # shown in the help text with a value that corresponds to the number of an element in the array. Note that the array is zero-based.

Sample CLI

This command passes the same information as the yaml file above.

mcctl app create region=EU appname=testapp appvers=1.0 \
app-org=testmonitor imagetype=ImageTypeDocker \
configs:0.kind=helmCustomizationYaml configs:0.config="<yamlcontent0>" \
configs:1.kind=helmCustomizationYaml configs:1.config="<yamlcontent1>"   

Account Management

The mcctl utility can be used to create, update, and delete account level information with the MobiledgeX environment for users with appropriate permissions.

User Management

$ mcctl --addr https://console.mobiledgex.net user

The following user operations are available with the mcctl user command:

  • create
  • delete
  • show
  • current
  • newpass
  • resendverify
  • verifyemail
  • passwordresetrequest
  • passwordreset
  • restricteduserupdate

Role Management

$ mcctl --addr https://console.mobiledgex.net role

The following user operations are available with the mcctl role command:

  • names
  • add
  • remove
  • show
  • assignment
  • perms

Organization Management

$ mcctl --addr https://console.mobiledgex.net org

The following user operations are available with the mcctl org command:

  • create
  • update
  • delete
  • show

Auto Provision Policy Management

$ mcctl --addr https://console.mobiledgex.net auto provision policy

The following user operations are available with the mcctl auto provision policy command:

  • create
  • show
  • add
Required Args:
  region                              Region name
  app-org                             Name of the organization for the cluster that this policy will apply to
  name                                Policy name
Optional Args:
  deployclientcount                   Minimum number of clients within the auto deploy interval to trigger deployment
  deployintervalcount                 Number of intervals to check before triggering deployment
  cloudlets:#.key.organization        Organization of the cloudlet site
  cloudlets:#.key.name                Name of the cloudlet
  cloudlets:#.loc.latitude            latitude in WGS 84 coordinates
  cloudlets:#.loc.longitude           longitude in WGS 84 coordinates
  cloudlets:#.loc.horizontalaccuracy  horizontal accuracy (radius in meters)
  cloudlets:#.loc.verticalaccuracy    vertical accuracy (meters)
  cloudlets:#.loc.altitude            On android only lat and long are guaranteed to be supplied altitude in meters
  cloudlets:#.loc.course              course (IOS) / bearing (Android) (degrees east relative to true north)
  cloudlets:#.loc.speed               speed (IOS) / velocity (Android) (meters/sec)
  cloudlets:#.loc.timestamp.seconds
  cloudlets:#.loc.timestamp.nanos   

Metric Commands

The same metrics that are presented in the MobiledgeX Web GUI can be viewed from the CLI by using the metrics command to the mcctl utility.

The examples below request the output in JSON format, but it is possible to retrieve the data in YAML or condensed JSON (JSON without extra whitespace formatting).

Note: The mcctl utility provides a stable interface to the MobiledgeX APIs. The API can be accessed directly, but the API interface is subject to change.

$ mcctl --addr https://console.mobiledgex.net metrics

The metrics command will show metrics for:

  • applications
  • clusters
  • cloudlets

All metrics commands can be qualified with a time or duration parameter.

  • last N Shows the last N series of data.
  • starttime datetime Start time of displayed data.
  • endtime datetime End time of displayed data.

Using Start/End Times

Several of the mcctl subcommands accept a start/end time to filter output. Time should be passed through in the format as outlined in RFC 3339. For example, to specify 10:35 PM UTC on August 7, 2019, you would code the time as 2019-08-07T20:35:00Z. Please note that the entire date/time string, including the time zone indicator, must be passed to the command.

Application Usage

mcctl usage app
Required Args:
  region       Region name
  starttime    Time to start displaying usage from
  endtime      Time up to which to display usage
Optional Args:
  appname      App name
  apporg       Organization or Company Name that a Developer is part of
  appvers      App version
  cluster      Cluster namedf
  cloudlet     Name of the cloudlet
  cloudletorg  Organization name owning of the cloudlet
  vmonly       Only show VM based apps
Flags:
  -h, --help   help for app
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage app \
  region=EU starttime="2021-01-28T20:35:00Z" endtime="2021-01-28T23:35:00Z" \
  apporg=demoorg
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "app",
            "apporg",
            "version",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "deployment",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "appinst-usage",
          "values": [
            [
              "EU",
              "k8jaypi",
              "demoorg",
              "1.0",
              "jaycluster02",
              "demoorg",
              "berlin-main",
              "TDG",
              "\u003cnil\u003e",
              "kubernetes",
              "2021-01-28T21:13:15.501752085Z",
              "2021-01-28T23:35:00Z",
              8504498247915,
              "Running"
            ]
          ]
        }
      ]
    }
  ]
}

API Example

API Call

POST /auth/usage/app

Payload

{
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z",
  "AppInst": {
      "cluster_inst_key": {
            "organization": "demoorg",
            "cloudlet_key": {
                    "organization": "TDG",
                    "name": "berlin-main"
                  },
            "cluster_key": {
                    "name": "jaycluster02"
                  }
          },
      "app_key": {
            "organization": "demoorg",
            "name": "k8jaypi",
            "version": "1.0"
          }
    },
  "Region": "EU"
}  

Example

POST /auth/usage/app < payload.json
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "app",
            "apporg",
            "version",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "deployment",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "appinst-usage",
          "values": [
            [
              "EU",
              "k8jaypi",
              "demoorg",
              "1.0",
              "jaycluster02",
              "demoorg",
              "berlin-main",
              "TDG",
              "<nil>",
              "kubernetes",
              "2021-01-28T21:13:15.501752085Z",
              "2021-01-28T23:35:00Z",
              8504498247915,
              "Running"
            ]
          ]
        }
      ]
    }
  ]
}

Application Level Metrics

Required Args:
  region        Region name
  app-org       Organization or Company name of the App
  selector      Comma separated list of metrics to view
Optional Args:
  appname       App name
  appvers       App version
  cluster       Cluster name
  cluster-org   Organization or Company Name that a Cluster is used by
  cloudlet      Name of the cloudlet
  cloudlet-org  Company or Organization name of the cloudlet
  last          Display the last X metrics
  starttime     Time to start displaying stats from
  endtime       Time up to which to display stats   

Data Keys

  • time
  • app
  • ver
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • apporg
  • pod
  • cpu
  • mem
  • disk
  • sendBytes
  • recvBytes

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics app region=EU app/
org=demoorg selector=cpu,mem,disk,network last=1 appname=mexfastapi10
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "pod",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "appinst-network",
          "values": [
            [
              "2020-06-08T22:16:46.88950592Z",
              "mexfastapi10",
              null,
              "fastapiCluster",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "mexfastapi10",
              null,
              null,
              null,
              603979776,
              138412032
            ]
          ]
        },
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "pod",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "appinst-mem",
          "values": [
            [
              "2020-06-08T22:16:46.88950592Z",
              "mexfastapi10",
              null,
              "fastapiCluster",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "mexfastapi10",
              null,
              269588889,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "pod",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "appinst-disk",
          "values": [
            [
              "2020-06-08T22:16:46.88950592Z",
              "mexfastapi10",
              null,
              "fastapiCluster",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "mexfastapi10",
              null,
              null,
              0,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "pod",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "appinst-cpu",
          "values": [
            [
              "2020-06-08T22:16:46.88950592Z",
              "mexfastapi10",
              null,
              "fastapiCluster",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "mexfastapi10",
              0.24,
              null,
              null,
              null,
              null
            ]
          ]
        }
      ]
    }
  ]
}   

CPU Example

AppInst CPU usage for an app with 2 containers. CPU value format is in percentages.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"}}},"selector":"cpu","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 02:33:19 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "pod_1",
                        "cpu"
                    ],
                    "name": "appinst-cpu",
                    "tags": {
                        "pod": "facedetectiondemo-deployment-6f677d9544-kvkxq"
                    },
                    "values": [
                        [
                            "2020-04-19T02:33:17.611999988Z",
                            "facedetectiondemo",
                            "10",
                            "facedetectiondemo-deployment-6f677d9544-kvkxq",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "facedetectiondemo-deployment-6f677d9544-kvkxq",
                            0.0005218471385100763
                        ]
                    ]
                },
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "pod_1",
                        "cpu"
                    ],
                    "name": "appinst-cpu",
                    "tags": {
                        "pod": "facedetectiondemo-deployment-6f677d9544-687sp"
                    },
                    "values": [
                        [
                            "2020-04-19T02:33:17.611999988Z",
                            "facedetectiondemo",
                            "10",
                            "facedetectiondemo-deployment-6f677d9544-687sp",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "facedetectiondemo-deployment-6f677d9544-687sp",
                            0.0006513207573001638
                        ]
                    ]
                }
            ]
        }
    ]
}  

Memory Example

The current memory footprint of a given app instance in bytes.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<</
 {"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":\
 "facedetectiondemo","version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},\
 "cloudlet_key":{"organization":"mexdev","name":"localtest"}}},"selector":"mem","last":1}'\
 HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:21:38 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "pod_1",
                        "mem"
                    ],
                    "name": "appinst-mem",
                    "tags": {
                        "pod": "facedetectiondemo-deployment-6f677d9544-c62wp"
                    },
                    "values": [
                        [
                            "2020-04-19T01:21:36.528000116Z",
                            "facedetectiondemo",
                            "10",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            315060224
                        ]
                    ]
                }
            ]
        }
    ]
}  

Disk Example

The fileystem usage for an app instance in bytes.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"}}},"selector":"disk","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:22:08 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "pod_1",
                        "disk"
                    ],
                    "name": "appinst-disk",
                    "tags": {
                        "pod": "facedetectiondemo-deployment-6f677d9544-c62wp"
                    },
                    "values": [
                        [
                            "2020-04-19T01:22:03.615999937Z",
                            "facedetectiondemo",
                            "10",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            43507712
                        ]
                    ]
                }
            ]
        }
    ]
}  

Network example

Application instance Tx/Rx traffic rate in bytes/seconds averaged over 1 minute.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":"facedetectiondemo",\
"version":"1.0"},"cluster_inst_key":{"cluster_key":{"name":"AppCluster"},\
"cloudlet_key":{"organization":"mexdev","name":"localtest"}}},"selector":"network","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:22:37 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "pod_1",
                        "sendBytes",
                        "recvBytes"
                    ],
                    "name": "appinst-network",
                    "tags": {
                        "pod": "facedetectiondemo-deployment-6f677d9544-c62wp"
                    },
                    "values": [
                        [
                            "2020-04-19T01:22:36.046999931Z",
                            "facedetectiondemo",
                            "10",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "facedetectiondemo-deployment-6f677d9544-c62wp",
                            28,
                            56
                        ]
                    ]
                }
            ]
        }
    ]
}  

Connection Example

App instance connection information by port; number of accepted, active, and handled connections, as well as the total number of bytes that are sent/received, and a histogram of session times in milliseconds. For example, P50 is the 50th percentile in session time. In the example below, 50% of all sessions lasted 6ms or less.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/app <<<\
'{"region":"local","appinst":{"app_key":{"organization":"DevOrg","name":\
"facedetectiondemo","version":"1.0"},"cluster_inst_key":{"cluster_key":\
{"name":"AppCluster"},"cloudlet_key":{"organization":"mexdev","name":"localtest"}}},\
"selector":"connections","last":1}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:25:47 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "app",
                        "ver",
                        "pod",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "apporg",
                        "port",
                        "active",
                        "handled",
                        "accepts",
                        "bytesSent",
                        "bytesRecvd",
                        "P0",
                        "P25",
                        "P50",
                        "P75",
                        "P90",
                        "P95",
                        "P99",
                        "P99.5",
                        "P99.9",
                        "P100"
                    ],
                    "name": "appinst-connections",
                    "tags": {
                        "pod": ""
                    },
                    "values": [
                        [
                            "2020-04-19T01:25:41.29373Z",
                            "facedetectiondemo",
                            "10",
                            null,
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            "DevOrg",
                            "8008",
                            2,
                            6,
                            6,
                            2068,
                            12243,
                            59,
                            60,
                            190,
                            3900,
                            9760,
                            9780,
                            9796,
                            9798,
                            9799.6,
                            9800
                        ]
                    ]
                }
            ]
        }
    ]
}  

API Example

  • Valid selector: api
  • Valid method names: RegisterClient, VerifyLocation, FindCloudlet, GetLocation, AppinstList, FqdnList, DynamicLocGroup, QosPosition.
  • Cellid 0 is invalid.

FindCloudet Example

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
 {"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
 "someapplication1","version":"1.0"}},"method":"FindCloudlet","selector":"api","last":1}'\
 HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:45:04 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "100ms",
                        "10ms",
                        "25ms",
                        "50ms",
                        "5ms",
                        "app",
                        "apporg",
                        "cellID",
                        "cloudlet",
                        "cloudletorg",
                        "errs",
                        "foundCloudlet",
                        "foundOperator",
                        "inf",
                        "method",
                        "reqs",
                        "ver"
                    ],
                    "name": "dme-api",
                    "values": [
                        [
                            "2020-04-19T01:42:21.588926Z",
                            0,
                            0,
                            0,
                            0,
                            2,
                            "someapplication1",
                            "AcmeAppCo",
                            "1234",
                            "tmus-cloud-1",
                            "tmus",
                            0,
                            "tmus-cloud-2",
                            "tmus",
                            0,
                            "FindCloudlet",
                            2,
                            "1.0"
                        ]
                    ]
                }
            ]
        }
    ]
}  
  • 100ms, 10ms, 25ms, 50ms, 5ms: Latency buckets for the API call RTT
  • cellID: Cell Id of the tower where the API request came from. This can be used in geolocation grouping.
  • err: Number of errors returned for this AppInst, method, and cellID for this timestamp
  • foundCloudlet: Cloudlet name that was returned as a result of this FindCloudlet api call
  • foundOperator: Operator name that was returned as a result of this FindCloudlet api call
  • id: Hostname where DME is(Unused)
  • inf: UNUSED
  • method: One of RegisterClient, VerifyLocation, FindCloudlet, GetLocation, AppInstList, FqdnList, DynamicLocGroup, QosPosition
  • oper: Operator name where the DME is
  • reqs: Number of requests sent since last collection

RegisterClient Example

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
'{"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
"someapplication1","version":"1.0"}},"method":"RegisterClient","selector":"api","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:46:13 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "100ms",
                        "10ms",
                        "25ms",
                        "50ms",
                        "5ms",
                        "app",
                        "apporg",
                        "cellID",
                        "cloudlet",
                        "cloudletorg",
                        "errs",
                        "foundCloudlet",
                        "foundOperator",
                        "inf",
                        "method",
                        "reqs",
                        "ver"
                    ],
                    "name": "dme-api",
                    "values": [
                        [
                            "2020-04-19T01:42:21.588926Z",
                            0,
                            0,
                            0,
                            0,
                            4,
                            "someapplication1",
                            "AcmeAppCo",
                            "1234",
                            "tmus-cloud-1",
                            "tmus",
                            0,
                            null,
                            null,
                            0,
                            "RegisterClient",
                            4,
                            "1.0"
                        ]
                    ]
                }
            ]
        }
    ]
}  

Note: foundCloudlet and foundOperator fields are “null“, these are only available for FindCloudlet method.

All methods example with start and end time, rather than last N elements

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/client <<<\
'{"region":"local","appinst":{"app_key":{"organization":"AcmeAppCo","name":\
"someapplication1","version":"1.0"}},"selector":"api","starttime":"2020-04-\
19T01:42:21Z","endtime":"2020-04-19T01:42:22Z"}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 01:49:08 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "100ms",
                        "10ms",
                        "25ms",
                        "50ms",
                        "5ms",
                        "app",
                        "apporg",
                        "cellID",
                        "cloudlet",
                        "cloudletorg",
                        "errs",
                        "foundCloudlet",
                        "foundOperator",
                        "inf",
                        "method",
                        "reqs",
                        "ver"
                    ],
                    "name": "dme-api",
                    "values": [
                        [
                            "2020-04-19T01:42:21.588926Z",
                            0,
                            0,
                            0,
                            0,
                            4,
                            "someapplication1",
                            "AcmeAppCo",
                            "1234",
                            "tmus-cloud-1",
                            "tmus",
                            0,
                            null,
                            null,
                            0,
                            "RegisterClient",
                            4,
                            "1.0"
                        ],
                        [
                            "2020-04-19T01:42:21.588926Z",
                            0,
                            0,
                            0,
                            0,
                            2,
                            "someapplication1",
                            "AcmeAppCo",
                            "1234",
                            "tmus-cloud-1",
                            "tmus",
                            0,
                            "tmus-cloud-2",
                            "tmus",
                            0,
                            "FindCloudlet",
                            2,
                            "1.0"
                        ]
                    ]
                }
            ]
        }
    ]
}  

Note: This allows for a single call with all the results.

Cluster Usage

mcctl usage cluster
Required Args:
  region       Region name
  starttime    Time to start displaying usage from
  endtime      Time up to which to display usage
Optional Args:
  cluster      Cluster name
  clusterorg   Organization or Company Name that a Developer is part of
  cloudletorg  Organization name owning of the cloudlet
  cloudlet     Name of the cloudlet
Flags:
  -h, --help   help for cluster
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage cluster \
 region=EU starttime="2021-01-28T20:35:00Z" endtime="2021-01-28T23:35:00Z" \
 clusterorg=demoorg    
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "jaycluster02",
              "demoorg",
              "berlin-main",
              "TDG",
              "m4.small",
              2,
              "IP_ACCESS_SHARED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "mdxcluster",
              "demoorg",
              "munich-main",
              "TDG",
              "m4.medium",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "jaycluster01",
              "demoorg",
              "munich-main",
              "TDG",
              "m4.small",
              2,
              "IP_ACCESS_SHARED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    }
  ]
}  

API Example

POST /auth/usage/cluster

Payload

{
  "ClusterInst": {
      "cluster_key": {
            "name": "jaycluster02"
          },
      "cloudlet_key": {
            "name": "berlin-main",
            "organization": "TDG"
          },
      "organization": "demoorg"
    },
  "Region": "EU",
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z"
}  

Example

POST /auth/usage/cluster < payload.json
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "jaycluster02",
              "demoorg",
              "berlin-main",
              "TDG",
              "m4.small",
              2,
              "IP_ACCESS_SHARED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    }
  ]
}  

Cluster Level Metrics

Required Args:
  region        Region name
  cluster-org   Organization or Company Name that a Cluster is used by
  selector      Comma separated list of metrics to view

Optional Args: cluster Cluster name cloudlet-org Company or Organization name of the cloudlet cloudlet Name of the cloudlet last Display the last X metrics starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • cpu
  • mem
  • disk
  • sendBytes
  • recvBytes

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics cluster \
region=EU cluster-org=demoorg selector=cpu,mem,disk,network, tcp, udp last=1
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-network",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              null,
              null,
              675353748,
              30297980534
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-mem",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              6.191279821549256,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-disk",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              null,
              null,
              15.501801142916749,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "cpu",
            "mem",
            "disk",
            "sendBytes",
            "recvBytes"
          ],
          "name": "cluster-cpu",
          "values": [
            [
              "2020-06-08T22:22:38.972597948Z",
              "action-test-cluster",
              "demoorg",
              "munich-main",
              "TDG",
              0,
              null,
              null,
              null,
              null
            ]
          ]
        }
      ]
    }
  ]
}   

CPU example

The CPU value format is in percentages.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":\
"cpu","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:28:05 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "cpu"
                    ],
                    "name": "cluster-cpu",
                    "values": [
                        [
                            "2020-04-19T00:27:59.930999994Z",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            3.368800199773451
                        ]
                    ]
                }
            ]
        }
    ]
}  

Network Example

Cluster Tx/Rx traffic rate in bytes/sec averaged over 1 minute.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":\
"network","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:29:24 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "sendBytes",
                        "recvBytes"
                    ],
                    "name": "cluster-network",
                    "values": [
                        [
                            "2020-04-19T00:29:21.539000034Z",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            1002472,
                            728685
                        ]
                    ]
                }
            ]
        }
    ]
}  

TCP Example

The total number of established TCP connections.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":"tcp",\
"last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:30:00 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "tcpConns",
                        "tcpRetrans"
                    ],
                    "name": "cluster-tcp",
                    "values": [
                        [
                            "2020-04-19T00:29:54.068000078Z",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            192,
                            99
                        ]
                    ]
                }
            ]
        }
    ]
}  

UDP Example

The total number of Tx/Rx UDP datagrams in this cluter and the total number of UDP errors.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cluster <<<\
'{"region":"local","clusterinst":{"cluster_key":{"name":"AppCluster"},"cloudlet_key":\
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"},"selector":"udp",\
"last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Sun, 19 Apr 2020 00:30:26 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cluster",
                        "clusterorg",
                        "cloudlet",
                        "cloudletorg",
                        "udpSent",
                        "udpRecv",
                        "udpRecvErr"
                    ],
                    "name": "cluster-udp",
                    "values": [
                        [
                            "2020-04-19T00:30:21.153000116Z",
                            "AppCluster",
                            "DevOrg",
                            "localtest",
                            "mexdev",
                            418,
                            418,
                            0
                        ]
                    ]
                }
            ]
        }
    ]
}  

Cloudlet Metrics

Required Args:
  region        Region name
  cloudlet-org  Company or Organization name of the cloudlet
  selector      Comma separated list of metrics to view, utilization, network, ipusage  
Optional Args:
  cloudlet      Name of the cloudlet
  last          Display the last X metrics
  starttime     Time to start displaying stats from
  endtime       Time up to which to display stats  

Data Keys

  • time
  • cloudlet
  • cloudletorg
  • vCpuUsed
  • vCpuMax
  • memUsed
  • memMax
  • diskUsed
  • diskMax
  • netSend
  • netRecv
  • floatingIpsUsed
  • floatingIpsMax
  • ipv4Used
  • ipv4Max

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json metrics cloudlet\
region=EU cloudlet-org=TDG selector=utilization,network,ipusage last=1
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-utilization",
          "values": [
            [
              "2020-06-08T22:38:00.458128973Z",
              "munich-main",
              "TDG",
              188,
              200,
              350208,
              512000,
              920,
              5000,
              null,
              null,
              null,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-network",
          "values": [
            [
              "2020-06-08T01:52:29.244553765Z",
              "berlin-main",
              "TDG",
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              0,
              null,
              null,
              null,
              null
            ]
          ]
        },
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "vCpuUsed",
            "vCpuMax",
            "memUsed",
            "memMax",
            "diskUsed",
            "diskMax",
            "netSend",
            "netRecv",
            "floatingIpsUsed",
            "floatingIpsMax",
            "ipv4Used",
            "ipv4Max"
          ],
          "name": "cloudlet-ipusage",
          "values": [
            [
              "2020-06-08T22:38:08.425162762Z",
              "munich-main",
              "TDG",
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              null,
              0,
              10,
              33,
              1004
            ]
          ]
        }
      ]
    }
  ]
}  

Utilization example
Cloudlet utilization information.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"mexdev","name":"localtest"},"selector":\
"utilization","last":1}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 23 Jan 2020 21:38:00 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cloudlet",
                        "cloudletorg",
                        "vCpuUsed",
                        "vCpuMax",
                        "memUsed",
                        "memMax",
                        "diskUsed",
                        "diskMax"
                    ],
                    "name": "cloudlet-utilization",
                    "values": [
                        [
                            "2020-01-23T21:37:58.623117Z",
                            "localtest",
                            "mexdev",
                            12,
                            12,
                            10854,
                            16384,
                            156,
                            233
                        ]
                    ]
                }
            ]
        }
    ]
}  
  • diskMax: Maximum available Disk size in GBs
  • diskUsed: Disk used at a timestamp in GBs
  • memMax: Maximum memory on this cloudlet in MBs
  • memUsed: Memory used at timestamp in MBs
  • vCpuMax: Maximum available number of vCPUs on this cloudlet
  • vCpuUsed: Number vCPUs on this cloudlet at timestamp

Network Example
The total number of data sent and received in the Cloudlet in bytes. This is currently not supported on OpenStack.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"mexdev","name":"localtest"},"selector":\
"network","last":1}'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 23 Jan 2020 21:38:24 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cloudlet",
                        "cloudletorg",
                        "netSend",
                        "netRecv"
                    ],
                    "name": "cloudlet-network",
                    "values": [
                        [
                            "2020-01-23T21:38:23.661953Z",
                            "localtest",
                            "mexdev",
                            null,
                            14483833
                        ]
                    ]
                }
            ]
        }
    ]
}  

IPUsage Example

Cloudlet utilization information.

$ http --verify=false --auth-type=jwt --auth=$SUPERPASS POST https://console.mobiledgex.net/api/v1/auth/metrics/cloudlet <<<\
'{"region":"local","cloudlet":{"organization":"TDG","name":"levfrankfurt"},\
"selector":"ipusage","last":2}'\
HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 19 Nov 2019 05:24:56 GMT
Transfer-Encoding: chunked
{
    "data": [
        {
            "Messages": null,
            "Series": [
                {
                    "columns": [
                        "time",
                        "cloudlet",
                        "cloudletorg",
                        "floatingIpsUsed",
                        "floatingIpsMax",
                        "ipv4Used"
                        "ipv4Max",
                    ],
                    "name": "cloudlet-ipusage",
                    "values": [
                        [
                            "2019-11-19T05:24:24.282198Z",
                            "lev-frankfurt",
                            "TDG",
                            2,
                            10,
                            51,
                            1004
                        ]
                    ]
                }
            ]
        }
    ]
}  
  • floatingIpsMax: Max available number of floating IP addresses
  • floatingIpsUsad: Number floating IP addresses on this cloudlet at timestamp
  • ipv4Max: Max available number of external IPv4 addresses
  • ipv4Used: Number external IPv4 addresses on this cloudlet at timestamp

Event Commands

The same events that are presented in the MobiledgeX Web GUI can be viewed from the CLI by using the events command to the mcctl utility. The examples below request the output in JSON format, but it is possible to retrieve the data in YAML or condensed JSON (JSON without extra whitespace formatting).

Note: The mcctl utility provides a stable interface to the MobiledgeX APIs. The API can be accessed directly, but the API interface is subject to change.

$ mcctl --addr https://console.mobiledgex.net events

The events command will show events for:

  • applications
  • clusters
  • cloudlets

All events commands can be qualified with a time or duration parameter.

  • last N Shows the last N series of data.
  • starttime datetime Start time of displayed data.
  • endtime datetime End time of displayed data.

Application Events

Required Args:
  region       Region name
  apporg       Organization or Company Name that a Developer is part of
Optional Args:
  appname      App name
  appvers      App version
  cluster      Cluster name
  cloudlet     Name of the cloudlet
  cloudletorg  Organization name owning of the cloudlet
  last         Display the last X Events
  starttime    Time to start displaying stats from
  endtime      Time up to which to display stats  

Data Keys

  • time
  • app
  • ver
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • apporg
  • event
  • status

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json events app region=EU\
apporg=demoorg
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "app",
            "ver",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "apporg",
            "event",
            "status"
          ],
          "name": "appinst",
          "values": [
            [
              "2020-06-11T21:45:37.030622125Z",
              "leotest",
              "1.1",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-11T16:17:18.954135649Z",
              "leotest",
              "1.1",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-11T16:09:28.014006366Z",
              "leotest",
              "1.0",
              "autoclusterleotest",
              "demoorg",
              "hamburg-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-05-22T16:50:59.47204115Z",
              "helm3-test",
              "1.0",
              "autoclusterhelm3-test",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "demoorg",
              "DELETED",
              "DOWN"
            ]
          ]
        }
      ]
    }
  ]
}  

Cluster Events

Required Args:
  region       Region name
  clusterorg   

Optional Args: cluster Cluster name cloudletorg Organization name owning of the cloudlet cloudlet Name of the cloudlet last Display the last X Events starttime Time to start displaying stats from endtime Time up to which to display stats

Data Keys

  • time
  • cluster
  • clusterorg
  • cloudlet
  • cloudletorg
  • flavor
  • vcpu
  • ram
  • disk
  • other
  • event
  • status

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json events cluster region=EU\
clusterorg=demoorg
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "vcpu",
            "ram",
            "disk",
            "other",
            "event",
            "status"
          ],
          "name": "clusterinst",
          "values": [
            [
              "2020-06-11T21:45:37.030373227Z",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-11T16:16:56.117330464Z",
              "autoclusterleotest",
              "demoorg",
              "dusseldorf-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-11T16:09:28.013967166Z",
              "autoclusterleotest",
              "demoorg",
              "hamburg-main",
              "TDG",
              "m4.small",
              2,
              2048,
              20,
              "map[]",
              "DELETED",
              "DOWN"
            ]
          ]
        }
      ]
    }
  ]
}  

Cloudlet Events

Required Args:
  region       Region name
  cloudletorg  Organization name owning of the cloudlet
Optional Args:
  cloudlet     Name of the cloudlet
  last         Display the last X Events
  starttime    Time to start displaying stats from
  endtime      Time up to which to display stats  

Data Keys

  • time
  • cloudlet
  • cloudletorg
  • event
  • status

Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json events cloudlet region=EU\
cloudletorg=TDG   
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "time",
            "cloudlet",
            "cloudletorg",
            "event",
            "status"
          ],
          "name": "cloudlet",
          "values": [
            [
              "2020-06-08T18:29:37.15500575Z",
              "berlin-test",
              "TDG",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-08T12:43:46.058384029Z",
              "berlin-test",
              "TDG",
              "CREATED",
              "UP"
            ],
            [
              "2020-06-04T19:11:49.067685911Z",
              "Berlin-Main-Test",
              "TDG",
              "DELETED",
              "DOWN"
            ],
            [
              "2020-06-04T19:09:28.727345388Z",
              "Berlin-Main-Test",
              "TDG",
              "CREATED",
              "UP"
            ],
            [
              "2020-05-15T17:22:31.181937143Z",
              "frankfurt-5glab",
              "TDG",
              "CREATED",
              "UP"
            ]
          ]
        }
      ]
    }
  ]
}  

Cloudletpool Usage

mcctl usage cloudletpool
Required Args:
  region           Region name
  cloudletpool     Name of the CloudletPool to pull usage from
  cloudletpoolorg  Organization or Company Name that a Operator is part of
  starttime        Time to start displaying usage from
  endtime          Time up to which to display usage
Optional Args:
Flags:
  -h, --help   help for cloudletpool
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token

Example

$ mcctl --output-format json --addr https://console.mobiledgex.net usage \
 cloudletpool region=EU starttime="2021-01-28T20:35:00Z" \
 endtime="2021-01-28T23:35:00Z" cloudletpoolorg=BT cloudletpool=BT-Pool
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "umsclusterbtgpu",
              "UMS",
              "Ipswich2",
              "BT",
              "mex.small-gpu",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "umsclusterbt",
              "UMS",
              "Ipswich2",
              "BT",
              "m4.large",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "fdcluster",
              "BT_dev",
              "Ipswich",
              "BT",
              "m4.medium",
              1,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    },
    {
      "Series": [
        {
          "columns": [
            "region",
            "app",
            "apporg",
            "version",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "deployment",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "appinst-usage",
          "values": []
        }
      ]
    }
  ]
}

API Example

API Call

POST /auth/usage/cloudletpool  

Payload

{
  "Region": "EU",
  "StartTime": "2021-01-28T20:35:00Z",
  "EndTime": "2021-01-28T23:35:00Z",
  "CloudletPool": {
      "name": "BT-Pool",
      "organization": "BT"
    }
}  

Example

$ POST /auth/usage/cloudletpool
{
  "data": [
    {
      "Series": [
        {
          "columns": [
            "region",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "numnodes",
            "ipaccess",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "cluster-usage",
          "values": [
            [
              "EU",
              "umsclusterbt",
              "UMS",
              "Ipswich2",
              "BT",
              "m4.large",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "fdcluster",
              "BT_dev",
              "Ipswich",
              "BT",
              "m4.medium",
              1,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ],
            [
              "EU",
              "umsclusterbtgpu",
              "UMS",
              "Ipswich2",
              "BT",
              "mex.small-gpu",
              0,
              "IP_ACCESS_DEDICATED",
              "2021-01-28T20:35:00Z",
              "2021-01-28T23:35:00Z",
              10800000000000,
              "Running"
            ]
          ]
        }
      ]
    },
    {
      "Series": [
        {
          "columns": [
            "region",
            "app",
            "apporg",
            "version",
            "cluster",
            "clusterorg",
            "cloudlet",
            "cloudletorg",
            "flavor",
            "deployment",
            "startime",
            "endtime",
            "duration",
            "note"
          ],
          "name": "appinst-usage",
          "values": []
        }
      ]
    }
  ]
}  

Audit Commands

The mcctl utility can be used to pull audit information for the current user or the current organization.

Self Audit Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json audit showself
[
  {
    "operationname": "/api/v1/auth/metrics/app",
    "username": "jay.schmidt",
    "clientip": "172.17.0.1",
    "status": 400,
    "starttime": 1591654143039652,
    "duration": 274,
    "request": "{\"appinst\":{\"app_key\":{\"organization\":\"demoorg\"}},\"region\":\"EU\",\"selector\
    ":\"cpu,mem,disk,network,tcp,udp\"}",\
    "response": "{\"message\":\"Invalid appinst selector: tcp\"}",\
    "error": "",
    "traceid": "442ca89d3418b6af"
  },
  {
    "operationname": "/api/v1/auth/metrics/cloudlet",
    "username": "jay.schmidt",
    "clientip": "172.17.0.1",
    "status": 400,
    "starttime": 1591654011509158,
    "duration": 193,
    "request": "{\"cloudlet\":{\"organization\":\"TDG\"},\"region\":\"EU\",\"selector\":\"cpu\"}",
    "response": "{\"message\":\"Invalid cloudlet selector: cpu\"}",
    "error": "",
    "traceid": "04a229ee7dfde458"
  },
  {
    "operationname": "/api/v1/login",
    "username": "jay.schmidt",
    "clientip": "172.17.0.1",
    "status": 400,
    "starttime": 1591641868552332,
    "duration": 1082826,
    "request": "{\"username\":\"jay.schmidt\",\"password\":\"\"}",
    "response": "{\"message\":\"Invalid username or password\"}",
    "error": "",
    "traceid": "5d425c8cb9dbc53c"
  }
]  

Organization Audit Example

$ mcctl  --addr https://console.mobiledgex.net  --output-format json audit showorg
[
  {
    "operationname": "/api/v1/login",
    "username": "mcviewer",
    "clientip": "172.17.0.1",
    "status": 200,
    "starttime": 1591656362716240,
    "duration": 94992,
    "request": "",
    "response": "{\"token\":\"\"}",
    "error": "",
    "traceid": "1ab4474ed71c4a40"
  },
  {
    "operationname": "/api/v1/login",
    "username": "cloudops-monitor",
    "clientip": "172.17.0.1",
    "status": 200,
    "starttime": 1591656304644725,
    "duration": 100843,
    "request": "{\"username\":\"cloudops-monitor\",\"password\":\"\"}",
    "response": "{\"token\":\"\"}",
    "error": "",
    "traceid": "7de5361a1c17af69"
  },
  {
    "operationname": "/api/v1/login",
    "username": "mcviewer",
    "clientip": "172.17.0.1",
    "status": 200,
    "starttime": 1591656242564764,
    "duration": 87877,
    "request": "",
    "response": "{\"token\":\"\"}",
    "error": "",
    "traceid": "7b3a4699aef3dcad"
  }
]  

Regional commands

The region subcommand provides access to the most commonly used commands for managing a deployment.

Flavor Management

  • flavor create
  • flavor delete
  • flavor update
  • flavor show
  • flavor addres
  • flavor removeres
  • cloudlet findflavormatch

Operator Codes

  • operatorcode create
  • operatorcode delete
  • operatorcode show

Cloudlet Management

  • cloudlet create
  • cloudlet delete
  • cloudlet update
  • cloudlet show
  • cloudlet addresmapping
  • cloudlet removeresmapping

Cloudlet Pools (Private Edge)

  • cloudletpool create
  • cloudletpool delete
  • cloudletpool show
  • cloudletinfo show
  • cloudletpool addmember
  • cloudletpool removemember
  • cloudletpoolinvitation showgranted

Cluster Management

  • clusterinst create
  • clusterinst delete
  • clusterinst update
  • clusterinst show

Application Management

  • app create
  • app delete
  • app update
  • app show
  • app addautoprovpolicy
  • app removeautoprovpolicy

Application Instance Management

  • appinst create
  • appinst delete
  • appinst refresh
  • appinst update
  • appinst show
  • node show (Admin-Only)
  • alert show (Admin-Only)

Policy Management

  • autoscalepolicy create
  • autoscalepolicy update
  • autoscalepolicy show
  • autoprovpolicy create
  • autoprovpolicy delete
  • autoprovpolicy update
  • autoprovpolicy show
  • autoprovpolicy addcloudlet
  • autoprovpolicy removecloudlet
  • trustpolicy create
  • trustpolicy delete
  • trustpolicy update
  • trustpolicy showself

Regional Settings

  • settings update (Admin-Only)
  • settings reset (Admin-Only)
  • settings show (Admin-Only)

Resource Tagging

  • restagtable create
  • restagtable delete
  • restagtable update
  • restagtable show
  • restagtable addrestag
  • restagtable removerestag
  • restagtable get

Debugging

  • debug enabledebuglevels (Admin-Only)
  • debug disabledebuglevels (Admin-Only)
  • debug showdebuglevels (Admin-Only)
  • debug rundebug (Admin-Only)

Device Management

  • appinstclient showappinstclient
  • device inject (Admin-Only)
  • device show (Admin-Only)
  • device evict (Admin-Only)
  • device showreport (Admin-Only)

Misc Commands

  • RunCommand
  • showlogs
  • runconsole
  • accesscloudlet (Admin-Only)

AlertReceiver Example

Alert notification will only be sent for AppInstDown.

Note that alertreceiver create command utilizes the same arguments.

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver delete --help
Usage: mcctl alertreceiver delete [flags] [args]
Required Args:
  name              Unique name of this receiver
  type              Receiver type - email, or slack
  severity          Alert severity level - one of "info", "warning", "error"
Optional Args:
  Region            Region where alert originated
  email             Email address receiving the alert (by default email associated with the account)
  slack-channel     Slack channel to be receiving the alert
  slack-api-url     Slack webhook url
  pagerduty-integration-key  PagerDuty Integration key
  pagerduty-api-version      PagerDuty API version("v1" or "v2"). By default "v2" is used
  appname           App Instance name
  appvers           App Instance version
    app-org           Organization or Company name of the App Instance
  app-cloudlet      Cloudlet name where app instance is deployed
  app-cloudlet-org  Company, or Organization that owns the cloudlet
  cluster           App Instance Cluster name
  cluster-org       Company, or Organization Name that a Cluster is owned by
  cloudlet          Name of the cloudlet
  cloudlet-org      Company, or Organization name of the cloudlet
Flags:
  -h, --help   help for delete
Global Flags:
      --addr string            MC address (default "http://127.0.0.1:9900")
      --data string            json formatted input data, alternative to name=val args list
      --datafile string        file containing json/yaml formatted input data, alternative to name=val args list
      --debug                  debug
      --output-format string   output format: yaml, json, or json-compact (default "yaml")
      --output-stream          stream output incrementally if supported by command (default true)
      --parsable               generate parsable output
      --silence-usage          silence-usage
      --skipverify             don't verify cert for TLS connections
      --token string           JWT token  

Below is an example for a create/delete/show for the master controller alert receiver APIs.

The following creates a receiver that will process email notifications about appinstance-specific alerts.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/create <<< '{"name":"DevOrgReceiver1","type":"email","severity":"error","appinst":{"app_key":{"organization":"DevOrg","name":"Face DetectionDemo","version":"1.0"},"clusterinstkey":{"clusterkey":{"name":"AppCluster"},"cloudlet_key":
{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"}}}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 01:53:00 GMT
$

mmctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver create name=DevOrgReceiver1 type=email severity=error appname="Face Detection Demo" app-org="DevOrg" appvers="1.0" cluster=AppCluster cluster-org=DevOrg app-cloudlet=localtest app-cloudlet-org=mexdev
$  

The above command will send all the alerts for this AppInstance to the email address associated with the user making this request(as specified in the $TOKEN env var in HTTP rest call).

Here is an example of a Slack receiver:

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/create <<< '{"name":"DevOrgReceiver1Slack","type":"slack","slackchannel":"#alerts","slackwebhook":"https://hooks.slack.com/services/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","severity":"error","appinst":{"app_key":{"organization":"DevOrg","name":"Face Detection Demo","version":"1.0"},"clusterinstkey":{"clusterkey":{"name":"AppCluster"},"cloudlet_key":{"organization":"mexdev","name":"localtest"},"organization":"DevOrg"}}}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 01:53:00 GMT
$

mcctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver create name=DevOrgReceiver1Slack type=slack slack-channel="#alerts" slack-api-url="https://hooks.slack.com/services/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" severity=error appname="Face Detection Demo" app-org="DevOrg" appvers="1.0" cluster=AppCluster cluster-org=DevOrg app-cloudlet=localtest app-cloudlet-org=mexdev
$

The command options include the following:

  • region - If specified, only alerts from this region will be sent to the receiver
  • name - Name of the alert receiver. name+type+severify+user has to be unique together
  • type - Type of the receiver. Currently “email“ and “slack“ are valid strings.
  • severity - Valid severities are “error“, “warn“, and “info“
  • email - If specified, this email will be used to receive the notifications, by default it’s the email associated with the user configuring the alert receiver.

To check which receivers are present for the current user, the following API can be used:

Note: For Slack receivers, we hide API url( token is shown instead), since it’s something that can be used by a malicious user to send random messages to that Slack channel.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/show
HTTP/1.1 200 OK
Content-Length: 310
Content-Type: application/json; charset=UTF-8
Date: Fri, 25 Sep 2020 19:48:11 GMT
[
    {
        "AppInst": {
            "app_key": {
                "name": "Face Detection Demo",
                "organization": "DevOrg",
                "version": "1.0"
            },
            "cluster_inst_key": {
                "cloudlet_key": {
                    "name": "localtest",
                    "organization": "mexdev"
                },
                "cluster_key": {
                    "name": "AppCluster"
                },
                "organization": "DevOrg"
            }
        },
        "Cloudlet": {},
        "Name": "DevOrgReceiver1",
        "Severity": "error",
        "Type": "email"
    },
    {
        "AppInst": {
            "app_key": {
                "name": "Face Detection Demo",
                "organization": "DevOrg",
                "version": "1.0"
            },
            "cluster_inst_key": {
                "cloudlet_key": {
                    "name": "localtest",
                    "organization": "mexdev"
                },
                "cluster_key": {
                    "name": "AppCluster"
                },
                "organization": "DevOrg"
            }
        },
        "Cloudlet": {},
        "Name": "DevOrgReceiver1Slack",
        "Severity": "error",
        "Type": "slack",
        "SlackChannel": "#alerts",
        "SlackWebhook": "<hidden>"
    }
]
$  

mcctl:

$ mcctl --addr https://0.0.0.0:9900 --skipverify alertreceiver show
- name: DevOrgReceiver1
  type: email
  severity: error
  appinst:
    appkey:
      organization: DevOrg
      name: Face Detection Demo
      version: "1.0"
    clusterinstkey:
      clusterkey:
        name: AppCluster
      cloudletkey:
        organization: mexdev
        name: localtest
      organization: DevOrg
- name: DevOrgReceiver1Slack
  type: slack
  severity: error
  slackchannel: '#alerts'
  slackwebhook: <hidden>
  appinst:
    appkey:
      organization: DevOrg
      name: Face Detection Demo
      version: "1.0"
    clusterinstkey:
      clusterkey:
        name: AppCluster
      cloudletkey:
        organization: mexdev
        name: localtest
      organization: DevOrg
$  

If a receiver is no longer needed, you can delete it.

HTTP REST:

$ http --verify=false --auth-type=jwt --auth=$TOKEN POST https://127.0.0.1:9900/api/v1/auth/alertreceiver/delete <<< '{"name":"DevOrgReceiver1","type":"email","severity":"error"}'
HTTP/1.1 200 OK
Content-Length: 0
Date: Thu, 10 Sep 2020 02:03:27 GMT
$  

mcctl:

$ mcctl --addr https://127.0.0.1:9900 --skipverify alertreceiver delete name=DevOrgReceiver1 type=email severity=error
$  

Where to go from here

To learn how to use the mcctl utility for developers, refer to the How to use the mcctl utility for Developers guide.