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

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]

Available Commands:
  login
  user            manage users
  role            manage user roles
  org             manage organizations
  controller      register country controllers
  alldata         bulk manage data
  region          manage region data
  config          admin config
  audit           show audit logs
  orgcloudlet     manage Org Cloudlets
  orgcloudletpool manage Org CloudletPools
  metrics         view metrics
  events          view events
  help            Help about any command

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:
* YAML
* JSON Data with added whitespace for readability.
* JSON-compact Data without extra whitespace.

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

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:35Z. Please note that the entire date/time string, including the time zone indicator, must be passed to the command.

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 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" ] ] } ] } ] }

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 regionsubcommand provides access to the most commonly used commands for managing a deployment.

Flavor Management

  • CreateFlavor
  • DeleteFlavor
  • UpdateFlavor
  • ShowFlavor
  • AddFlavorRes
  • RemoveFlavorRes
  • FindFlavorMatch

Operator Codes

  • CreateOperatorCode
  • DeleteOperatorCode
  • ShowOperatorCode

Cloudlet Management

  • CreateCloudlet
  • DeleteCloudlet
  • UpdateCloudlet
  • ShowCloudlet
  • AddCloudletResMapping
  • RemoveCloudletResMapping

Cloudlet Pools (Private Edge)

  • CreateCloudletPool
  • DeleteCloudletPool
  • ShowCloudletPool
  • ShowCloudletInfo
  • CreateCloudletPoolMember
  • DeleteCloudletPoolMember
  • ShowCloudletPoolMember

Cluster Management

  • CreateClusterInst
  • DeleteClusterInst
  • UpdateClusterInst
  • ShowClusterInst

Application Management

  • CreateApp
  • DeleteApp
  • UpdateApp
  • ShowApp
  • AddAppAutoProvPolicy
  • RemoveAppAutoProvPolicy

Application Instance Management

  • CreateAppInst
  • DeleteAppInst
  • RefreshAppInst
  • UpdateAppInst
  • ShowAppInst
  • ShowNode
  • ShowAlert

Policy Management

  • CreateAutoScalePolicy
  • UpdateAutoScalePolicy
  • ShowAutoScalePolicy
  • CreateAutoProvPolicy
  • DeleteAutoProvPolicy
  • UpdateAutoProvPolicy
  • ShowAutoProvPolicy
  • AddAutoProvPolicyCloudlet
  • RemoveAutoProvPolicyCloudlet
  • CreatePrivacyPolicy
  • DeletePrivacyPolicy
  • UpdatePrivacyPolicy
  • ShowPrivacyPolicy

Regional Settings

  • UpdateSettings
  • ResetSettings
  • ShowSettings

Resource Tagging

  • CreateResTagTable
  • DeleteResTagTable
  • UpdateResTagTable
  • ShowResTagTable
  • AddResTag
  • RemoveResTag
  • GetResTagTable

Debugging

  • EnableDebugLevels
  • DisableDebugLevels
  • ShowDebugLevels
  • RunDebug

Device Management

  • ShowAppInstClient
  • InjectDevice
  • ShowDevice
  • EvictDevice
  • ShowDeviceReport

Misc Commands

  • RunCommand
  • ShowLogs
  • RunConsole
  • AccessCloudlet

Where to go from here

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