Synthetics App Agent

Kentik's app agent for synthetics is covered in the following topics:

Notes:
- For a high-level overview of agent types and deployment types for synthetics, see Synthetics Agents.
- For a general explanation of synthetic testing in Kentik, see Synthetics Overview.
- For information on specific modules within the Synthetics section of the Kentik portal, refer to the articles listed under Synthetics in the Contents tab of the KB.
- For assistance with any aspect of the agent setup process, please contact Customer Support.

 

App Agent Versions

Packages for private installation of the ksynth app agent are available for the common Linux distributions shown in the table below.

Debian Ubuntu RedHat Enterprise Linux CentOS
Buster (10.0)
Stretch (9.0)
Jessie (8.0)
Bionic Beaver (18.04 LTS)
Focal Fossa (20.04 LTS)
8.0
7.0
8 (Stream)
7

Note: For versions not listed above, please contact Customer Support.

Downloads are available from the following locations:

 

Hardware Requirements

The following resources must be available (at minimum) to each instance of the ksynth app agent:

  • RAM allocation: 2GB
  • CPU cores: 2

Note: For additional considerations that apply when deploying ksynth agents, see ksynth Deployment Considerations.

 

App Agent Command Line

The ksynth app agent command line is covered in the following topics:

 
top  |  section

App Agent CLI Structure

The ksynth app agent uses a standard UNIX command line that is structured as follows:

ksynth-agent [options]


 
top  |  section

App Agent CLI Arguments

The ksynth app agent command line takes the following arguments:

-b, --browser-max <pool:value...>: Max instances for pools, multiples allowed`-b main:2 -b notls:5`
--browser-path <value>: Absolute path to Chromium browser binary (env: KA_BROWSER_PATH)
--basic-trace: Use basic trace (no paris methods)
-c, --company-id <value>: Init with company id
-d, --disable <value...>: Disable task type (choices: "browser", "scamper")
-e, --elu: Monitor event loop utilization (this has cpu/memory impacts)
--external-repo-url <value>: Override default external repo url
-f, --fuzz-window-ms <value>: Time (ms) to spread start of tasks over (default 60000)
-g, --global: Init as Global agent
--install-scamper: Install scamper from ksynth-agent pre-build binary NOTE: requires elevated permissions
-j, --show-json-export: Show JSON export data
-l, --log-levels <category:level...>: Change logging, multiples allowed `-l info -l httpRequest:debug`
-m, --browser-instance-test-max <value>: Max tests any browser instance will run before being destroyed/respawned
-n, --name <name>: Agent name (default host name)
-p, --pid-path <value>: Path to use for pidfile (default current working directory) (env: KA_PID_PATH)
-r, --region <region>: Region (default: "us")
-s, --scampers-per-worker <value>: size of scamper instance pool
--scamper-archive <value>: Only used with --install-scamper flag, omit this to use default
--scamper-path <value>: Provide absolute path to installed scamper binary
-t, --use-threads: Use worker threads rather than forks (default forks)
-u, --show-udr-export: Show UDR export data
-v, --version: output the version number
-w, --worker-count <value>: Number of worker threads to use (default 1)
-z, --max-concurrent-browser-tests <value>: Max concurrent browser tests
-h, --help: display help for command


 

App Agent Setup

The installation process for the ksynth app agent is covered in the following topics:

Note: Before installing, refer to:
- Hardware Requirements
- ksynth Deployment Considerations

 
top  |  section

App Agent Setup Stages

The setup of a private ksynth app agent instance involves two main stages:

  1. Installation of the agent in your network infrastructure or public cloud instance. The steps vary depending on how you install:
    - To install via a package, see App Agent Package Install.
    - To install via a container, see App Agent Docker Install.
  2. Activation of the ksynth instance with Kentik, which is performed in the Kentik portal (see App Agent Activation).
 
top  |  section

App Agent Package Install

The following steps cover the procedure for installation of the ksynth app agent using a Debian-based or RPM-based package (in case of errors, see Linux Installation Troubleshooting):

  1. On the host where you'll run ksynth, run the following command to install the ksynth repository:
    - For Debian-based packages:
    curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.deb.sh | sudo bash
    - For RPM-based packages:
    curl -s https://packagecloud.io/install/repositories/kentik/ksynth-agent/script.rpm.sh | sudo bash
  2. Create a new directory where agent files will be installed:
    mkdir ksynth-agent && cd ksynth-agent
  3. Use the package manager to install the ksynth service:
    - For Debian-based packages: sudo apt-get install ksynth-agent
    - For RPM-based packages: sudo yum install ksynth-agent
    Note: Depending on the Linux distro/version, the agent may notify you of additional libraries that you'll need to install. Once the missing dependencies have been resolved, continue to the next step.
  4. Install scamper:
    sudo ksynth-agent --install-scamper
  5. Run the ksynth app agent using a terminal multiplexer of your choice; in the below example we use "screen":
    screen -S ksynth-agent systemd-cat -t ksynth-agent ksynth-agent --company-id kentik_company_id --name name_string --region region_code
  6. In the resulting blank terminal, press Ctrl+a+d to detach.
  7. Activate the agent instance in the portal (see App Agent Activation).
  8. Optional: Retrieve the challenge code you'll need to register in the portal (see Register App Agent):
    journalctl -t ksynth-agent -f

In the above screen command (step 5):

  • The screen -S ksynth-agent argument creates a new named session called “ksynth-agent.”
  • The systemd-cat -t ksynth-agent argument writes logs to the journal with a tag “ksynth-agent” for challenge code retrieval in step 8.
  • The value of the optional --company-id argument is your organization's Kentik company ID, which is the number next to “Account #” on the portal's Licenses page (Settings » Licenses).
    Note: If this argument is not specified you will need to manually register this instance of the agent (see Register App Agent).
  • The value that you provide for the optional --name argument will be the name by which the agent will appear in the portal.
  • If your organization uses Kentik's EU cluster, set the optional --region argument to eu. If not specified the agent will default to the US region.

Linux Installation Troubleshooting

If you encounter errors during package installation, try the following common troubleshooting techniques:

  • Error at step 3: If you receive an error message about missing dependencies, run the commands below to install the commonly required dependencies.
    - For Debian-based packages:
    sudo apt-get install ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils
    - For RPM-based packages:
    sudo yum install alsa-lib.x86_64 atk.x86_64 cups-libs.x86_64 gtk3.x86_64 ipa-gothic-fonts libXcomposite.x86_64 libXcursor.x86_64 libXdamage.x86_64 libXext.x86_64 libXi.x86_64 libXrandr.x86_64 libXScrnSaver.x86_64 libXtst.x86_64 pango.x86_64 xorg-x11-fonts-100dpi xorg-x11-fonts-75dpi xorg-x11-fonts-cyrillic xorg-x11-fonts-misc xorg-x11-fonts-Type1 xorg-x11-utils
    After installing dependencies, update the nss library using this command:
    yum update nss -y
  • Error at Step 4: If you receive this error message:
    sudo: ksynth-agent: command not found
    Run this command instead:
    sudo env "PATH=$PATH" ksynth-agent --install-scamper

Notes:
- The dependencies referenced above are subject to change. For the latest information, check the lists at Chrome headless doesn't launch on UNIX.
- If you continue to experience installation errors after trying the above, please contact Customer Support.

 
top  |  section

App Agent Docker Install

Installation of the ksynth app agent from a downloaded Docker image (see App Agent Versions) provides a convenient and easy deployment mechanism for systems that already use Docker-based containerized applications.

To install via Docker:

  1. Pull and run the latest app agent docker image:
    docker run -d --name ksynth-agent -v ksynth-agent:/var/lib/ksynth kentik/ksynth-agent:latest ksynth-agent --company-id kentik_company_id --name name_string --region region_code
  2. Activate the agent instance in the portal (see App Agent Activation).
  3. Optional: Retrieve the challenge code you'll need to register in the portal (see Register App Agent):
    docker logs ksynth-agent

In the above docker run command (step 1):

  • The Docker --name argument (as distinct from the ksynth --name argument later in the command) names the Docker container. If not included the container will be assigned an ID, which you'll have to know in order to run any future commands on the container.
  • The -v argument (volume) will cause a ksynth directory to be created on the server (if it doesn't already exist) and mounted in the Docker container at /var/lib/ksynth. When ksynth runs, the ksynth.id ID file will, by default, be written to this location, where it will persist between container upgrades (otherwise every Docker image upgrade will prompt an attempt to register a new agent).
  • The kentik/ksynth-agent:latest statement will run ksynth-agent, passing to it the agent subcommand arguments that follow (--company-id, etc.).
  • The value of the optional --company-id argument is your organization's Kentik company ID, which is the number next to “Account #” on the portal's Licenses page (Settings » Licenses).
    Note: If this argument is not specified you will need to manually register this instance of the agent (see Register App Agent).
  • The value that you provide for the optional --name argument will be the name by which the agent will appear in the portal.
  • If your organization uses Kentik's EU cluster, set the optional --region argument to eu. If not specified the agent will default to the US region.

Note: For a reference to the CLI values in the above run command, see App Agent Command Line.

 

App Agent Activation

Registration and activation of an installed instance of the app agent is covered in the following topics:

 
top  |  section

About ksynth Activation

Activation of a private instance of ksynth involves securely associating the agent with your Kentik account (trial or customer), which you'll do on the Agent Management page in the Synthetics section of the portal. The specific steps depend on whether your organization's company ID has been passed with the --company-id argument during installation.

Company Specified at Install

If you've passed the company ID at install, the agent will be registered automatically and you need only activate the agent directly in the portal (see Activate App Agent). The company ID can be passed in the following ways:

  • Package-based installs (Debian/RPM): The company ID is specified with the --company-id argument in the command line of your screen command. See step 5 in App Agent Package Install.
  • Docker-based installs: The company ID is specified with the --company-id argument in the CLI of your docker run command. See step 1 in App Agent Docker Install.

Note: Providing the company ID during the installation process facilitates mass or scripted ksynth deployment.

Company Not Specified at Install

If you haven't specified the company ID at install then the information required for registration won't be passed automatically to the Kentik portal. For each deployment you do this way you'll need to manually register the ksynth instance, at which point it will be automatically activated. To do so you get a challenge code from the agent and enter the code on the Agent Management page (see Register App Agent).

 
top  |  section

Activate App Agent

To activate an installed instance of the ksynth app agent:

  1. In the portal, go to the Agent Management page (Synthetics » Agent Management) and find the newly installed agent in the Private Agents tab of the Agents List. The agent's status will be indicated as Pending.
  2. Click the agent to open the Agent Details drawer (right sidebar).
  3. Click the Activate button in the drawer, which opens the Activate Agent dialog.
  4. Review the settings in the dialog and make any needed changes, then click the Activate button. The dialog will close.
  5. In the Private Agents tab of the Agents List, the agent's status will now be indicated as Active.
 
top  |  section

Register App Agent

When the company ID was not specified during installation (see Company Not Specified at Install), you will need to manually register the ksynth instance, which will automatically activate it. Manual ksynth registration involves getting a challenge code from the agent and entering the code on the portal's Agent Management page.

  1. In ksynth, run one or the other of the following commands:
    - For Debian/RPM installations: journalctl -t ksynth-agent -f
    - For Docker package installations: docker logs ksynth-agent
  2. ksynth will return a challenge code, as shown in the following example:
    [INFO] authenticate - Activation challenge code: f4dd8632fbdb09714a38c17a7b536a4fe84d973beb4172d01abbba1c77exxxxx
  3. In the portal, go to the Agent Management page (Synthetics » Agent Management) and click the Enter Challenge Code button.
  4. In the resulting Register Agent dialog, enter the code and click the Register button. The dialog will close.
  5. The agent instance corresponding to the entered code will now appear in the Private Agents tab of the Agents List, and the agent's status will be indicated as Active.

Note: To register multiple installed ksynth instances repeat the above steps with the challenge code corresponding to each instance.

© 2014- Kentik
In this article:
×