dx-do v3.4.13

dx-do

Command-line execution of DX SaaS operations

Usage

:warning: using npm install for this package is highly discouraged.

npx dx-do <--config=<config-file>> command-group command <parameter>=<value>

Output

ℹ  info      dx-do v3.4.13 on node v18.20.4 on darwin-arm64 via node (ssl: 3.0.13+quic)
ℹ  info      Attempting to load default config from '/Users/z/.dxdo/default-config.json'
☒  complete  Loaded configuration for THE_LABORATORY/1795
ℹ  info      Looking for mongo config in /Users/z/.dxdo/default.mongo.config
ℹ  info      Loading mongo config from /Users/z/.dxdo/default.mongo.config
ℹ  info      Mongo configuration loaded.
ℹ  info      Allow Insecure HTTPS: false
ℹ  info      DXSaasService instantiated.
ℹ  info      Successfully configured.
✖  error     Usage: dx-do --option[=value]... <command-group> <command> <command-param>=<value>...
ℹ  info      Available command-groups: managementmodule, metricgrouping, alert, notification, universe, agent, graph, vertex, metric, channel, sql, acc, completion, dashboard, help, auth, axa, trace, shiftleft, session, config, perspective, oi, audit, ui, jsextension, experience, tas, attribute, nass, metrex, topographer

Command Groups

managementmodule

⤜ list..............................................: lists all management modules.
⤜ import............................................: imports a management module from json
⤜ create............................................: creates a management module.
⤜ export............................................: exports a management module and its metric groupings, alerts and calculators.
⤜ delete............................................: delete a management module
⤜ download..........................................: downloads a management module
⤜ update............................................: updates a management module.
⤜ copy..............................................: copy a management module.
⤜ list-calculators..................................: lists calculators in a management module

metricgrouping

⤜ list-metrics......................................: lists all live metrics in metric grouping
⤜ list-by-managementmodule..........................: lists all metric groupings in management modules.

alert

⤜ debug-by-management-module........................: debug all alerts in a management module.
⤜ list-by-management-module.........................: lists all alerts in a management module.
⤜ list..............................................: lists all alerts.
⤜ detail............................................: get alert definition
⤜ copy..............................................: copy an alert
⤜ copy-with-metric-grouping.........................: copy an alert with it's metric grouping
⤜ update-summary....................................: update a summary alert.
⤜ update-simple.....................................: update a simple alert.
⤜ disable...........................................: disable an alert.
⤜ disable-all.......................................: disable all alerts for a management module
⤜ enable............................................: enable an alert.
⤜ enable-all........................................: enable all alerts for a management module

notification

⤜ list..............................................: lists all ATC notification services

universe

⤜ delete............................................: deletes a universe
⤜ create............................................: creates a universe
⤜ list..............................................: lists all universes
⤜ detail............................................: provides detail on a single universe
⤜ export............................................: dumps a single universe json
⤜ add-metric-source.................................: adds an agent / regex to a universe definition.
⤜ sanity-check......................................: ensures universe are not set up exceptionally badly.

agent

⤜ query-by-name.....................................: ensure a specific agent exists.
⤜ query-by-regex....................................: query by regex
⤜ vertices..........................................: gets vertices for agent
⤜ attributes........................................: gets attributes for agent vertex
⤜ licensing-config-generate.........................: creates a default licensingConfigFile to be modified for licensing-beta command.
⤜ licensing-beta....................................: generate licensing report with configuration
⤜ licensing.........................................: generate licensing report
⤜ count-via-atc.....................................: count agents using the /atc/agents request.
⤜ trace.............................................: starts trace on specified agents
⤜ statuses..........................................: lists all agents statuses
⤜ metric-count-summary..............................: retrieves metric counts for agents as csv
⤜ list..............................................: lists all agents

graph

⤜ summary...........................................: summarizes vertices & edges
⤜ summary-at........................................: summarizes vertices & edges at a specific time
⤜ summarize-edges...................................: summarizes application edges
⤜ status-check......................................: summarizes vertices alerts
⤜ test-vertex-type-mapping..........................: tests vertexes for type mapping
⤜ export............................................: exports universe graph at a configurable time
⤜ store.............................................: stores vertexes and edges using the (legacy) APM interface

vertex

⤜ generate-patch-from-csv...........................: generates a bulk-patch file from a CSV
⤜ query-mapped-metrics..............................: executes metric query for a vertex's mapped metrics.
⤜ vertex-type-metric-mapping........................: dumps metric mapping for a vertex type
⤜ attribute-values..................................: gets values for an attribute
⤜ bulk-patch-schema.................................: generates the bulk-patch schema
⤜ bulk-patch-rollback...............................: rolls back a bulk-patch with a rollback file.
⤜ bulk-patch........................................: patches mutiple vertices using the bulk-patch file.
⤜ attributes........................................: list ATC attributes
⤜ search-all........................................: search for matching vertices in all universes
⤜ search............................................: search for matching vertices in a universe
⤜ patch-universe....................................: patch matching vertices in a universe
⤜ state.............................................: provides state on a single vertex
⤜ detail............................................: provides detail on a single vertex
⤜ all-metric-mappings...............................: dumps all metric mappings for all vertices
⤜ override-vertex-metric-mapping....................: dumps performance specifier and metric root for a vertex type
⤜ vertex-definitions................................: dumps all metric mappings for all vertices
⤜ vertex-definition.................................: dumps vertex definition for a single vertex type
⤜ add-vertex-definition.............................: add vertex definition from a file

metric

⤜ test-time-format..................................: allows testing of time parsing
⤜ create-metric-data-expression-file-from-metric-grouping: creates a metric data expression file for use with 'metric data' expressionFile option
⤜ create-example-metric-data-expression-file........: creates an example of a metric data expression file for use with 'metric data' expressionFile option
⤜ data..............................................: gets metric values
⤜ id................................................: gets metric id for a single metric.
⤜ data-metric.......................................: gets metric values for a single metric.
⤜ attributes........................................: gets attributes for metric (or metric's agent, if metric doesn't belong to a vertex)

channel

⤜ enable-channel....................................: enable a channel
⤜ disable-channel...................................: disable a channel
⤜ list..............................................: lists all channels
⤜ list-policies.....................................: lists all channel policies
⤜ list-templates....................................: lists all channel templates
⤜ create-template...................................: create a channel message template
⤜ update-template...................................: update an existing channel message template
⤜ export............................................: exports all channels/templates to file
⤜ import............................................: imports channels/templates from file

sql

⤜ query.............................................: executes an APM sql query
⤜ examples..........................................: shows example queries
⤜ date-to-timestamp.................................: converts dates to timestamps for use in queries

acc

⤜ initialize-bundle-directory.......................: initialize a prepared bundle directory
⤜ import-bundle.....................................: import bundle from a bundle tar.gz file
⤜ import-packages...................................: import packages from an export file
⤜ export-packages...................................: exports packages to a file
⤜ package-bundles...................................: gets package bundles
⤜ package-details...................................: gets package details
⤜ list-packages.....................................: lists acc packages
⤜ bundle-details....................................: gets bundle details
⤜ download-bundle...................................: downloads bundle
⤜ list-bundles......................................: lists acc bundles

completion

⤜ find-zsh..........................................: find zsh (mac) completion script
⤜ find-bash.........................................: find bash (v4) completion script
⤜ generate-zsh......................................: generate zsh (mac) completion script
⤜ generate-bash.....................................: generate bash (v4) completion script

dashboard

⤜ get-dashboard-refresh-options.....................: shows current dashboard refresh options
⤜ set-dashboard-refresh-options.....................: sets dashboard refresh options
⤜ set-folder-refresh-options........................: sets refresh options for all dashboards in folder
⤜ get-dashboard-tags................................: shows current dashboard tags
⤜ summarize-dashboard-tags..........................: shows a summary of all dashboards' tags.
⤜ add-dashboard-tags................................: adds tags to a dashboard
⤜ add-folder-tags...................................: adds tags to all dashboards in a folder
⤜ replace-dashboard-tags............................: replaces tags for a dashboard
⤜ replace-folder-tags...............................: replaces tags for all dashboards in a folder
⤜ get-theme.........................................: shows the current theme
⤜ set-theme.........................................: sets the current theme
⤜ dashboard-variables-list..........................: shows current values of dashboard variables
⤜ folder-import.....................................: imports a folder and its dashboards from an export file.
⤜ folder-export.....................................: exports a folder and all dashboards in it.
⤜ dashboard-list-by-folder..........................: lists dashboards in folder
⤜ dashboard-import..................................: creates a new dashboard from an export file.
⤜ dashboard-update..................................: updates a dashboard from an export file.
⤜ dashboard-export..................................: exports a single dashboard
⤜ dashboard-search..................................: finds dashboards
⤜ user-search.......................................: finds dashboard users
⤜ user-list.........................................: looks up a user by email
⤜ folder-add-permission.............................: adds folder permission for a user by email or userId
⤜ folder-permissions................................: gets permissions for a folder
⤜ folder-create.....................................: creates a folder
⤜ folder-list.......................................: show id/uid/title of all folders.
⤜ folder-details....................................: show details for folder
⤜ delete-dashboard-api-key..........................: deletes a dashboard api key
⤜ list-dashboard-api-keys...........................: lists dashboard api keys.
⤜ create-dashboard-api-key..........................: creates a grafana API key from a browser session cookie

help

⤜ bulk-patch........................................: explains vertex bulk-patch
⤜ configuration.....................................: explains configuration
⤜ time-formats......................................: explains time formats for 'metric data' and 'agent get-trace-sumaries'.
⤜ dashboard.........................................: explains dashboard command setup.
⤜ commands..........................................: explains commands.
⤜ commands-md.......................................: explains commands in md format

auth

⤜ validate-configuration-keys.......................: validates keys
⤜ user-search.......................................: searches for users
⤜ list-groups.......................................: shows all authentication group names
⤜ current...........................................: shows auth of current token

axa

⤜ list-sessions.....................................: dumps filtered AXA session events
⤜ dump-sessions-events..............................: dumps filtered AXA session events
⤜ upload-application-ba-extension...................: upload new custom AXA BrowserAgent extension javascript.
⤜ get-application-ba-extension......................: gets AXA BrowserAgent extension javascript.
⤜ get-application-snippet...........................: gets AXA BrowserAgent snippet for an application
⤜ list-profiles.....................................: lists all AXA data collection profiles
⤜ export-profile....................................: exports a AXA data collection profile
⤜ update-profile....................................: updates a AXA data collection profile
⤜ import-profile....................................: import a AXA data collection profile
⤜ get-application-profile...........................: gets the profile/id for an AXA Application
⤜ set-application-profile...........................: sets the profile by id for an AXA Application
⤜ list-applications.................................: lists all AXA application names/keys
⤜ create-application................................: creates a new AXA application definition.
⤜ delete-application................................: delete an existing AXA application.
⤜ crash-summary.....................................: summary of crashes
⤜ crash-list-by-group...............................: list crashes by group
⤜ crash-detail......................................: get details for a crash
⤜ crash-all.........................................: list all crashes
⤜ list-activities...................................: lists the business activities defined for an AXA Application
⤜ list-screens......................................: lists the screens available for business activities defined for an AXA Application
⤜ create-activity...................................: create a business activity for an AXA Application
⤜ show-activity-tree................................: shows activity tree from session events

trace

⤜ get-agent-traces..................................: retrieves traces
⤜ get-agent-trace-summaries.........................: retrieves trace summaries
⤜ get-vertex-traces.................................: retrieves traces
⤜ get-vertex-trace-summaries........................: retrieves trace summaries for vertices
⤜ trace-details.....................................: get trace details for traceId
⤜ get-threaddump....................................: retrieve a previously collected threaddump
⤜ collect-threaddump................................: trigger a trace on an agent
⤜ query-threaddumps.................................: find threaddumps for an agent

shiftleft

⤜ dump..............................................: dumps a universe for future comparison
⤜ list-dumps........................................: lists previous dumps
⤜ compare...........................................: compares two dumps
⤜ get-dump-graph....................................: gets graph for dump
⤜ bookmark-create...................................: creates a bookmark
⤜ bookmark-list.....................................: lists bookmarks

session

⤜ test..............................................: validate session api

config

⤜ debug-jwt.........................................: shows decoded jwt
⤜ debug.............................................: shows configuration details
⤜ upgrade...........................................: upgrade legacy dx-do configuration to current version
⤜ create............................................: create new configuration interactively

perspective

⤜ list..............................................: List Map View Perspectives
⤜ export............................................: Export Map View Perspective
⤜ delete............................................: Delete Map View Perspective
⤜ import............................................: Import Map View Perspective

oi

⤜ service-list......................................: lists services
⤜ situations........................................: lists situations
⤜ alarms............................................: lists alarms
⤜ alarm-detail......................................: provides alarm-detail

audit

⤜ get-audit-events..................................: retrieves audit events

ui

⤜ serve.............................................: (highly experimental) starts the ui server + browser

jsextension

⤜ upload............................................: upload a js extension file
⤜ delete............................................: delete js extension
⤜ list..............................................: list
⤜ enable............................................: enable js extension
⤜ disable...........................................: disable js extension

experience

⤜ list..............................................: lists Experience names & ids 
⤜ settings..........................................: lists Experience settings
⤜ create............................................: creates an experience
⤜ delete............................................: delete an experience carefully
⤜ mapping...........................................: shows mapping from Experience Top-Level to Settings ID
⤜ dashboard.........................................: summarizes experience dashboard
⤜ summarize.........................................: summarizes an experience
⤜ drilldown.........................................: segments an experience by layer attributes
⤜ report............................................: reports on various parts of an experience hierarchy.
⤜ export............................................: exports an experience configuration
⤜ import............................................: imports an experience configuration from file 

tas

⤜ query-all.........................................: finds everything
⤜ query-agents......................................: finds everything
⤜ query-json........................................: executes a query defined in a json file
⤜ store-graph.......................................: stores vertexes and edges

attribute

⤜ dump..............................................: dumps all attributes by layer

nass

⤜ register-metric...................................: registers a metric
⤜ report-metric-value...............................: reports a single metric value to a metric
⤜ query.............................................: executes a nass query from file containing nassql query json
⤜ query-metadata....................................: executes a nass metadata query
⤜ query-metric-data.................................: executes a nass metric data query
⤜ update-metadata-attribute.........................: updates a metric's metadata attribute
⤜ query-metadata-by-ids.............................: executes a nass metadata query

metrex

⤜ generate-vertex-definition........................: generate a vertex definition from a metrex configuration
⤜ generate-sample...................................: generate a sample metrex configuration schema
⤜ test-configuration................................: test a metrex configuration
⤜ dump-schema.......................................: dumps the metrex configuration schema (for use in IDE)
⤜ associate-vertex-metrics..........................: associate metrics to vertices using the output of test-configuration command.

topographer

⤜ generate-sample...................................: generate a sample topographer configuration
⤜ dump-schema.......................................: dumps the topographer configuration schema (for use in IDE)
⤜ test-configuration................................: test a topographer configuration

Options

Insecure HTTPS for Non-Proxied On-Prem

You may set the ALLOW_INSECURE_HTTPS environment variable to true in order to use self-signed or expired certificates

export ALLOW_INSECURE_HTTPS=true
npx dx-do alert list

new configFile Format

{
  "configurationVersion": "3"
  "tenantCN": "<tenant-name>",
  "tenantId": "<tenant-id>",
  "tenantToken": "<tenant-token>",
  "userToken": "<user-token>",
  "hostUrl": "https://apmgw.dxi-na1.saas.broadcom.com/",
  "axaHostUrl": "https://axa.dxi-na1.saas.broadcom.com/",
  "oiHostUrl": "https://oi.dxi-na1.saas.broadcom.com/",
  "axaSessionHostUrl": "https://axaservices-es-exporter.dxi-na1.saas.broadcom.com/",
  "dashboardHostUrl": "https://dxi-dashboard.dxi-na1.saas.broadcom.com/",
}

config

--config=<configFilename>

proxyConfig

--proxyConfig=<proxyConfigFilename>

proxy config File Format

{
  "protocol": "http", // or https
  "host": "localhost",
  "port": 8888,
  "auth": {
    "username": "myuser",
    "password": "mypass"
  }
}

non interactive mode (suitable for running from a script)

--noninteractive

old configFile Format

{
    "hostUrl":"https://apmgw.dxi-na1.saas.broadcom.com/",
    "apiKey":"<APM_API_TOKEN>",
    "tenantCN":"TENANT_NAME",
    "tenantId":"000"
    "oiUserKey": "<OI_USER_TOKEN>",
    "axaHostUrl": "https://axa.dxi-na1.saas.broadcom.com/",
    "oiHostUrl": "https://oi.dxi-na1.saas.broadcom.com/",
}

deprecated commandline tenant properties

--apiKey=<token>

--tenantCN=<tenant CN>

--tenantId=<tenant number>

--caManagementCookie=<CA_CLOUD_MANAGEMENT cookieValue>

non interactive mode (suitable for running from a script)

--noninteractive