The CLI (Command Line Interface) for Apache SkyWalking.
SkyWalking CLI is a command interaction tool for the SkyWalking user or OPS team, as an alternative besides using browser GUI. It is based on SkyWalking GraphQL query protocol, same as GUI.
As SkyWalking CLI is using Makefile
, compiling the project is as easy as executing a command in the root directory of the project.
git clone https://github.com/apache/skywalking-cli
cd skywalking-cli
make clean && make
and copy the ./bin/swctl
to your PATH
directory, usually /usr/bin/
or /usr/local/bin
, or you can copy it to any directory you like,
and add that directory to PATH
.
Commands in SkyWalking CLI are organized into two levels, in the form of swctl --option <level1> --option <level2> --option
,
there're options in each level, which should follow right after the corresponding command, take the following command as example:
$ swctl --debug service list --start="2019-11-11" --end="2019-11-12"
where --debug
is is an option of swctl
, and since the swctl
is a top-level command, --debug
is also called global option,
and --start
is an option of the third level command list
, there is no option for the second level command service
.
Generally, the second level commands are entity related, there're entities like service
, service instance
, metrics
in SkyWalking,
and we have corresponding sub-command like service
; the third level commands are operations on the entities, such as list
command
will list all the service
s, service instance
s, etc.
There're some common options that are shared by multiple commands, and they follow the same rules in different commands,
--start
and --end
specify a time range during which the query is preformed,
they are both optional and their default values follow the rules below:
- when
start
andend
are both absent,start = now - 30 minutes
andend = now
, namely past 30 minutes; - when
start
andend
are both present, they are aligned to the same precision by truncating the more precise one, e.g. ifstart = 2019-01-01 1234, end = 2019-01-01 18
, thenstart
is truncated (because it's more precise) to2019-01-01 12
, andend = 2019-01-01 18
; - when
start
is absent andend
is present, will determine the precision ofend
and then use the precision to calculatestart
(minus 30 units), e.g.end = 2019-11-09 1234
, the precision isMINUTE
, sostart = end - 30 minutes = 2019-11-09 1204
, and ifend = 2019-11-09 12
, the precision isHOUR
, sostart = end - 30HOUR = 2019-11-08 06
; - when
start
is present andend
is absent, will determine the precision ofstart
and then use the precision to calculateend
(plus 30 units), e.g.start = 2019-11-09 1204
, the precision isMINUTE
, soend = start + 30 minutes = 2019-11-09 1234
, and ifstart = 2019-11-08 06
, the precision isHOUR
, soend = start + 30HOUR = 2019-11-09 12
;
This section covers all the available commands in SkyWalking CLI and their usages.
swctl
is the top-level command, which has some options that will take effects globally.
option | description | default |
---|---|---|
--config |
from where the default options values will be loaded | ~/.skywalking.yml |
--debug |
enable debug mode, will print more detailed information at runtime | false |
--base-url |
base url of GraphQL backend | http://127.0.0.1:12800/graphql |
--display |
display style when printing the query result, supported styles are: json , yaml , table |
json |
service
second-level command is an entry for all operations related to services,
and it also has some options and third-level commands.
service list
lists all the services in the time range of [start
, end
].
option | description | default |
---|---|---|
--start |
See Common options | See Common options |
--end |
See Common options | See Common options |
instance
second-level command is an entry for all operations related to instances,
and it also has some options and third-level commands.
instance list [--service-id=<service id>] [--service-name=<service name>] [--start=<start time>] [--end=<end time>]
instance list
lists all the instances in the time range of [start
, end
] and given --service-id or --service-name.
option | description | default |
---|---|---|
--service-id |
Query service id (priority over --service-name) | |
--service-name |
Query service name | |
--start |
See Common options | See Common options |
--end |
See Common options | See Common options |
instance search [--regex=<instance name regex>] [--service-id=<service id>] [--service-name=<service name>] [--start=<start time>] [--end=<end time>]
instance search
filter the instance in the time range of [start
, end
] and given --regex --service-id or --service-name.
option | description | default |
---|---|---|
--regex |
Query regex of instance name | |
--service-id |
Query service id (priority over --service-name) | |
--service-name |
Query service name | |
--start |
See Common options | See Common options |
--end |
See Common options | See Common options |
linear-metrics
second-level command is an entrance for all operations related to linear metrics,
and it also has some options.
option | description | default |
---|---|---|
--name |
Metrics name, defined in OAL, such as all_p99 , etc. |
|
--start |
See Common options | See Common options |
--end |
See Common options | See Common options |
Clone the source code and simply run make clean && make
in the source directory,
this will download all necessary dependencies and build a binary file in ./bin/swctl
.
make clean && make
All commands files locate in directory commands
, and an individual directory for each second-level command,
an individual go
file for each third-level command, for example, there is a directory service
for command swctl service
,
and a list.go
file for swctl service list
command.
Determine what entity your command will operate on, and put your command go
file into that directory, or create one if it doesn't exist,
for example, if you want to create a command to list
all the instance
s of a service, create a directory commands/instance
,
and a go
file commands/instance/list.go
.
There're some common options that can be shared by multiple commands, check commands/flags
to get all the shared options, and reuse them when possible, an example shares the options is commands/service/list.go
Before submitting a pull request, add some test code to test the added/modified codes, and run the tests locally, make sure all tests passed.
go test -v ./...