|
| 1 | +# synctl |
| 2 | +Command to manage synthetic test and location easily |
| 3 | + |
| 4 | +## Features |
| 5 | +- query/create/delete/patch/update synthetic test, support simple ping, API script, browser script |
| 6 | +- query/delete synthetic location |
| 7 | +- support multiple backend server |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +``` |
| 12 | +# depend on requests https://pypi.org/project/requests/ |
| 13 | +# use pip3 to install requests module |
| 14 | +pip3 install requests |
| 15 | +# or use python3 -m pip |
| 16 | +/usr/bin/python3 -m pip install requests |
| 17 | +
|
| 18 | +# clone code and copy it to /usr/local/bin/ |
| 19 | +git clone git@github.ibm.com:instana/synthetic-synctl.git |
| 20 | +
|
| 21 | +cd synthetic-synctl |
| 22 | +chmod +x synctl && cp synctl /usr/local/bin/synctl |
| 23 | +
|
| 24 | +# if no permissions, use sudo |
| 25 | +chmod +x synctl && sudo cp synctl /usr/local/bin/synctl |
| 26 | +``` |
| 27 | + |
| 28 | +**Note:** This project was tested with Python 3.9.6, and the code should work on Python versions greater than or equal to 3.6. |
| 29 | + |
| 30 | +## Config an Instana Backend |
| 31 | +`synctl` support three types of configurations, config file, set `--host` and `--token` and use ENVIRONMENT. |
| 32 | + |
| 33 | +### Use a config file (Recommended) |
| 34 | + |
| 35 | +``` |
| 36 | +# set your backend host and token, and give it an alias name, and set it as default |
| 37 | +synctl config set \ |
| 38 | + --host "https://test-instana.pink.instana.rocks" \ |
| 39 | + --token "Your Token" \ |
| 40 | + --name "pink" \ |
| 41 | + --default |
| 42 | +
|
| 43 | +# list configs |
| 44 | +synctl config list |
| 45 | +
|
| 46 | +# set pink as default |
| 47 | +synctl config use --name pink --default |
| 48 | +
|
| 49 | +# remove a config |
| 50 | +synctl config remove --name pink |
| 51 | +``` |
| 52 | +**Note:** By default, config file is `~/.synthetic/config.json`. |
| 53 | + |
| 54 | +### Run command with --host and --token, no need to set a config file |
| 55 | + |
| 56 | +``` |
| 57 | +# retrieve all tests with --host and --token |
| 58 | +synctl get test --host "https://test-instana.pink.instana.rocks" --token <Your-Token> |
| 59 | +
|
| 60 | +# get all locations with host and token |
| 61 | +synctl get location --host "https://test-instana.pink.instana.rocks" --token <Your-Token> |
| 62 | +``` |
| 63 | + |
| 64 | +### Use environment vars |
| 65 | + |
| 66 | +``` |
| 67 | +# set SYN_SERVER_HOSTNAME and SYN_API_TOKEN |
| 68 | +export SYN_SERVER_HOSTNAME="https://test-instana.pink.instana.rocks" |
| 69 | +export SYN_API_TOKEN="Your Token" |
| 70 | +
|
| 71 | +# then run command with no options |
| 72 | +# retrieve all tests |
| 73 | +synctl get test |
| 74 | +
|
| 75 | +# retrieve all location |
| 76 | +synctl get location |
| 77 | +``` |
| 78 | + |
| 79 | + |
| 80 | +## Query Synthetic Test |
| 81 | + |
| 82 | +``` |
| 83 | +# Display all tests |
| 84 | +synctl get test |
| 85 | +
|
| 86 | +# get test by synthetic type |
| 87 | +# HTTPAction(0), HTTPScript(1), BrowserScript(2) and WebpageScript(3) are supported |
| 88 | +# use 0, 1, 2, 3 represent each type instead of HTTPAction, HTTPScript, BrowserScript |
| 89 | +# and WebpageScript for simple |
| 90 | +synctl get test -t <type> |
| 91 | +
|
| 92 | +# get HTTPAction test, and specify its type 0 |
| 93 | +synctl get test -t 0 |
| 94 | +
|
| 95 | +
|
| 96 | +# get synthetic test result with --window-size, support [1, 60]m, [1-24]h |
| 97 | +synctl get test --window-size 30m |
| 98 | +
|
| 99 | +synctl get test --window-size 6h |
| 100 | +
|
| 101 | +# show test details |
| 102 | +synctl get test <id> --show-details |
| 103 | +
|
| 104 | +# other options, --save-script, --show-script, --show-json |
| 105 | +synctl get test <id> --save-script |
| 106 | +synctl get test <id> --show-script |
| 107 | +synctl get test <id> --show-json |
| 108 | +``` |
| 109 | + |
| 110 | +## Create a synthetic test |
| 111 | + |
| 112 | +``` |
| 113 | +synctl create test -t <type> --label <label> ... |
| 114 | +
|
| 115 | +options: |
| 116 | + -t <type>: synthetic type |
| 117 | + 0 HTTPAction |
| 118 | + 1 HTTPScript |
| 119 | + 2 BrowserScript |
| 120 | + 3 WebpageScript |
| 121 | + --label <label> test name |
| 122 | + --location [LOCATION ...] location id, support multiple locations id |
| 123 | + --description DESCRIPTION, -d DESCRIPTION |
| 124 | + description of synthetic test |
| 125 | + --frequency FREQUENCY The range is from 1 to 120min, default is 15 |
| 126 | + --app-id, --application-id APP_ID |
| 127 | + set application id |
| 128 | + --url URL HTTP Request URL |
| 129 | + --operation OPERATION HTTP Request Method, GET, POST, HEAD, PUT, etc. |
| 130 | + --headers HEADERS HTTP Headers |
| 131 | + --body BODY HTTP Body |
| 132 | + --from-file FROM_FILE synthetic script, specify a file name |
| 133 | + --bundle BUNDLE synthetic script encoded with base64 |
| 134 | + --script-file SCRIPT_FILE bundle script entry file, e.g, myscript.js |
| 135 | + --retries {0,1,2} retry times, value is from [0, 2] |
| 136 | + --retry-interval {1,2,3,4,5,6,7,8,9,10} retryInvertal |
| 137 | + --follow-redirect {true,false,True,False} |
| 138 | + followRedirect default True |
| 139 | + --expect-status EXPECT_STATUS |
| 140 | + expectStatus default 200 |
| 141 | + --expect-json EXPECT_JSON |
| 142 | + expectJson |
| 143 | + --expect-match EXPECT_MATCH expectMatch |
| 144 | + --expect-exists EXPECT_EXISTS |
| 145 | + expectExists |
| 146 | + --expect-not-empty EXPECT_NOT_EMPTY |
| 147 | + expectNotEmpty |
| 148 | + --allow-insecure {false,true} |
| 149 | + allowInsecure |
| 150 | + --browser {chrome,firefox} |
| 151 | + set browser type |
| 152 | +``` |
| 153 | + |
| 154 | +Examples: |
| 155 | + |
| 156 | +- Create a simple ping test |
| 157 | + |
| 158 | +``` |
| 159 | +# get location id |
| 160 | +synctl get location |
| 161 | +synctl create test -t 0 --label "simple-ping" --url "https://httpbin.org/get" --location "$LOCATION" --frequency 5 |
| 162 | +
|
| 163 | +# or schedule multiple pops |
| 164 | +synctl create test -t 0 --label "simple-ping" --url "https://httpbin.org/get" --location "$LOCATION1" "$LOCATION2" "$LOCATION3" ... |
| 165 | +
|
| 166 | +``` |
| 167 | + |
| 168 | +- Create an API script test |
| 169 | + |
| 170 | +``` |
| 171 | +# a simple API script |
| 172 | +synctl create test -t 1 --label "simple-api-script" --from-file http-scripts/http-get.js --location "$LOCATION" --frequency 5 |
| 173 | +
|
| 174 | +# create bundle test |
| 175 | +synctl create test -t 1 --label "syn-bundle-test" \ |
| 176 | + --bundle "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" \ |
| 177 | + --script-file index.js \ |
| 178 | + --location "$LOCATION" \ |
| 179 | + --frequency 5 |
| 180 | +``` |
| 181 | + |
| 182 | +- Create BrowserScript |
| 183 | + |
| 184 | + |
| 185 | +``` |
| 186 | +synctl create test -t 2 \ |
| 187 | + --label "browserscript-test" \ |
| 188 | + --location "$LOCATION" --frequency 15 \ |
| 189 | + --browser firefox \ |
| 190 | + --script-file mytest.js \ |
| 191 | + --bundle "UEsDBAoAAAAAAHltFlUAAAAAAAAAAAAAAAAEABwAbGliL1VUCQADlRcDY2izBGN1eAsAAQToAwAABOgDAABQSwMEFAAIAAgA1FkYVQAAAAAAAAAAVAMAAA8AHABsaWIvbXlzY3JpcHQuanNVVAkAA6CXBWOglwVjdXgLAAEE6AMAAAToAwAAlVPBbuIwEL3zFSOLQ5C65t5qVwIpB9RuVbW5R8YMidVgp56hWYT67zsOoUuLkFifEue9N2/eTGzwxLAHQ4SR4QN+QsS3rYuYKVsbpyZ3I0M7b2G99ZZd8MBIPHe+yiawH41AznQK3ry7yjACB+i6Ti8FoG3Y9N+tFAkN6iZUmfp1ftQNqJm1SASJB62pMBVOXNMZxzBextCJQ10hZ6pmbm+n09M6CX700mJch7gBQhNtDaa3/R9GEpwgrAeBC07GmdK0LFOl8u0C5lCasokm9Kt73FGmJEyukZ1VJ7fjVXTvQpAXnT8W+fNED11kJ40NQ0rxADtuEJY7kESK9CzjMK3roQ0eQP29TPQ8w4ExmO5ltYzdNCf+4Ae8HAK4+ac2UK4J8unT5i18kzg2xOYVgWxE9FQHvlq6EN7LJ+1C+PwFdGx2vGXXaOfJVTWTTED2qVg8lcXzYp6Xj7Pfefkwm+cPqQyFDXItG9Zv18fdaBNWW7GGf9oQmSTZfa95/CMSRM5fUEsHCJkl42ODAQAAVAMAAFBLAwQUAAgACAB5bRZVAAAAAAAAAAARAQAACQAcAG15dGVzdC5qc1VUCQADlRcDYxC7BGN1eAsAAQToAwAABOgDAABdjzEOwjAMRfeewooYgoTSHcTCFdjY2mAVozQOiRkK4u6kVEjgzXp+/0u/CSjwBMEiB4oDvGAPGW93ymiNawP17TgVnymJuxaz3jWN51g4oAs8WJM4bc0GVmWKckEh7yqp1p90xqWBOCr556NDQiM+OKJKzPhUsdZD12MoSl6gVo/SZQHhz+p50ne9rfcbUEsHCA5zkg+OAAAAEQEAAFBLAQIeAwoAAAAAAHltFlUAAAAAAAAAAAAAAAAEABgAAAAAAAAAEAD/QQAAAABsaWIvVVQFAAOVFwNjdXgLAAEE6AMAAAToAwAAUEsBAh4DFAAIAAgA1FkYVZkl42ODAQAAVAMAAA8AGAAAAAAAAQAAAP+BPgAAAGxpYi9teXNjcmlwdC5qc1VUBQADoJcFY3V4CwABBOgDAAAE6AMAAFBLAQIeAxQACAAIAHltFlUOc5IPjgAAABEBAAAJABgAAAAAAAEAAAD/gRoCAABteXRlc3QuanNVVAUAA5UXA2N1eAsAAQToAwAABOgDAABQSwUGAAAAAAMAAwDuAAAA+wIAAAAA" |
| 192 | +``` |
| 193 | + |
| 194 | +- Create WebpageScript |
| 195 | + |
| 196 | + |
| 197 | +``` |
| 198 | +synctl create test -t 3 \ |
| 199 | + --label "webpagescript-test" \ |
| 200 | + --location "$LOCATION" --frequency 15 \ |
| 201 | + --from-file browser-scripts/browser.json \ |
| 202 | + --browser chrome |
| 203 | +``` |
| 204 | + |
| 205 | +- Create Synthetic Test using json payload |
| 206 | + |
| 207 | +``` |
| 208 | +synctl create test -t <type> --from-json payload-examples/api-script.json |
| 209 | +``` |
| 210 | + |
| 211 | + |
| 212 | +**Note:** Support specify appliation id when create synthetic test, get an application id through command `synctl get app`. |
| 213 | + |
| 214 | + |
| 215 | + |
| 216 | +### Patch a Synthetic Test |
| 217 | + |
| 218 | +``` |
| 219 | +# set frequency to 5 |
| 220 | +synctl patch test <synthetic-id> --frequency 5 |
| 221 | +
|
| 222 | +# set timeout to 120s |
| 223 | +synctl patch test <synthetic-id> --timeout 120s |
| 224 | +
|
| 225 | +# disable synthetic test |
| 226 | +synctl patch test <synthetic-id> --active false |
| 227 | +
|
| 228 | +# update synthetic script |
| 229 | +# save script to local, script name is test <label>.js |
| 230 | +synctl get test <synthetic-id> --save-script |
| 231 | +
|
| 232 | +# edit script file, and update synthetic test with new script |
| 233 | +synctl patch test <synthetic-id> --script-file simple-api-script.js |
| 234 | +``` |
| 235 | + |
| 236 | +### Update a Synthetic Test |
| 237 | + |
| 238 | + |
| 239 | +``` |
| 240 | +# get synthetic configuration |
| 241 | +synctl get test <synthetic-id> --show-json |
| 242 | +
|
| 243 | +# edit json and update |
| 244 | +synctl update test <synthetic-id> --from-data 'json data' |
| 245 | +``` |
| 246 | + |
| 247 | + |
| 248 | +### Delete synthetic test |
| 249 | + |
| 250 | +``` |
| 251 | +# delete a synthetic test |
| 252 | +synctl delete test <synthetic-id> |
| 253 | +
|
| 254 | +# delete several synthetic tests |
| 255 | +synctl delete test <synthetic-id-1> n<synthetic-id-2> <synthetic-id-3> ... |
| 256 | +
|
| 257 | +
|
| 258 | +# delete test with --match-regex, support regex, for regex refer |
| 259 | +# Regular expression operations https://docs.python.org/3/library/re.html |
| 260 | +# delete all tests which label match regex "^ping-test-*" |
| 261 | +synctl delete test --match-regex "^ping-test-*" |
| 262 | +
|
| 263 | +# delete all tests |
| 264 | +synctl delete test --match-regex ".*" |
| 265 | +
|
| 266 | +# delete all tests with <location-id> |
| 267 | +# it will not delete tests with multiple locations |
| 268 | +# For example, `synctl delete test --match-location A` will not delete test with location [A, B] |
| 269 | +synctl delete test --match-location <location-id> |
| 270 | +
|
| 271 | +# delete all tests which has no locations |
| 272 | +synctl delete test --no-locations |
| 273 | +``` |
| 274 | + |
| 275 | + |
| 276 | +## Query Application |
| 277 | + |
| 278 | +### Get application list |
| 279 | + |
| 280 | +``` |
| 281 | +# get all application |
| 282 | +synctl get app |
| 283 | +
|
| 284 | +# filter application by --name-filter, or pattern that application name contains |
| 285 | +synctl get app --name-filter <application-name> |
| 286 | +
|
| 287 | +# then create test with application id |
| 288 | +synctl create test -t 0 --app-id <application-id> ... |
| 289 | +``` |
| 290 | + |
| 291 | +## Query and Delete Synthetic Location |
| 292 | + |
| 293 | +### Query synthetic location |
| 294 | + |
| 295 | +``` |
| 296 | +synctl get location |
| 297 | +``` |
| 298 | + |
| 299 | +### Delete synthetic location |
| 300 | + |
| 301 | +``` |
| 302 | +# delete a synthetic location |
| 303 | +synctl delete location <location-id> |
| 304 | +
|
| 305 | +# delete several synthetic location |
| 306 | +synctl delete location <location-id-1> <location-id-2> <location-id-3> ... |
| 307 | +``` |
| 308 | + |
0 commit comments