Contains the code for the StackState agent V2. Agent integrations are not included in this project and can be found here.

Installation instructions are available on the StackState docs site.

To build the Agent you need:

• Go 1.21 or later. You'll also need to set your $GOPATH and have $GOPATH/bin in your path.
• Python 3.7+ along with development libraries for tooling. You will also need Python 2.7 if you are building the Agent with Python 2 support.
• Python dependencies. You may install these with pip install -r requirements.txt This will also pull in Invoke if not yet installed.
• CMake version 3.12 or later and a C++ compiler

Note: you may want to use a python virtual environment to avoid polluting your system-wide python environment with the agent build/dev dependencies. You can create a virtual environment using virtualenv and then use the invoke agent.build parameters --python-home-2=<venv_path> and/or --python-home-3=<venv_path> (depending on the python versions you are using) to use the virtual environment's interpreter and libraries. By default, this environment is only used for dev dependencies listed in requirements.txt.

Note: You may have previously installed invoke via brew on MacOS, or pip in any other platform. We recommend you use the version pinned in the requirements file for a smooth development/build experience.

Note: You can enable auto completion for invoke tasks. Use the command below to add the appropriate line to your .zshrc file. echo "source <(inv --print-completion-script zsh)" >> ~/.zshrc

Builds and tests are orchestrated with invoke, type invoke --list on a shell to see the available tasks.

To start working on the Agent, you can build the master branch:

1. Checkout the repo: git clone https://github.com/StackVista/stackstate-agent.git $GOPATH/src/github.com/DataDog/datadog-agent.

2. cd into the project folder: cd $GOPATH/src/github.com/StackVista/stackstate-agent.

3. Install go tools: invoke install-tools.

4. Install go dependencies: invoke deps. Make sure that $GOPATH/bin is in your $PATH otherwise this step might fail.

5. Create a development datadog.yaml configuration file in dev/dist/datadog.yaml, containing a valid API key: api_key: <API_KEY>

6. Build the agent with invoke agent.build --build-exclude=systemd.

7. When editing code in VS Code or in Intellij configure it to use the same tags as are used by the previous invoke command (they are visisble in the output, current set is consul ec2 process python gce cri zk containerd zlib jmx secrets kubelet kubeapiserver jetson docker etcd apm netcgo orchestrator). In VS Code this is configurable for the workspace on the Go plugin settings.

   By default, the Agent will be built to use Python 3 but you can select which Python version you want to use:

   • invoke agent.build --python-runtimes 2 for Python2 only
   • invoke agent.build --python-runtimes 3 for Python3 only
   • invoke agent.build --python-runtimes 2,3 for both Python2 and Python3

   You can specify a custom Python location for the agent (useful when using virtualenvs):

   invoke agent.build \
     --python-runtimes 2,3 \
     --python-home-2=$GOPATH/src/github.com/StackVista/stackstate-agent/venv2 \
     --python-home-3=$GOPATH/src/github.com/StackVista/stackstate-agent/venv3 .
   

   Running invoke agent.build:

   • Discards any changes done in bin/agent/dist.
   • Builds the Agent and writes the binary to bin/agent/agent.
   • Copies files from dev/dist to bin/agent/dist. See https://github.com/DataDog/datadog-agent/blob/main/dev/dist/README.md for more information.

   If you built an older version of the agent, you may have the error make: *** No targets specified and no makefile found. Stop.. To solve the issue, you should remove CMakeCache.txt from rtloader folder with rm rtloader/CMakeCache.txt.

Run tests using invoke test. During development, add the --skip-linters option to skip straight to the tests.

invoke test --targets=./pkg/aggregator

You can also use invoke lint-go to run just the go linters.

invoke lint-go

When testing code that depends on rtloader, build and install it first.

invoke rtloader.make && invoke rtloader.install
invoke test --targets=./pkg/collector/python

You can run the agent with:

./bin/agent/agent run -c bin/agent/dist/stackstate.yaml

The file bin/agent/dist/datadog.yaml is copied from dev/dist/datadog.yaml by invoke agent.build and must contain a valid api key.

To install the official release:

$ curl -o- https://stackstate-agent-3.s3.amazonaws.com/install.sh | STS_API_KEY="xxx" STS_URL="yyy" bash
 or
$ wget -qO- https://stackstate-agent-3.s3.amazonaws.com/install.sh | STS_API_KEY="xxx" STS_URL="yyy" bash

If you want to install a pre-release build use the pre-release repository:

$ curl -fLo- https://sts-agent-prerelease.s3.amazonaws.com/install.sh | STS_API_KEY="xxx" STS_URL="yyy" CODE_NAME="RELEASE_BRANCH" bash
 or
$ wget -qO- https://sts-agent-prerelease.s3.amazonaws.com/install.sh | STS_API_KEY="xxx" STS_URL="yyy" CODE_NAME="RELEASE_BRANCH" bash

and replace RELEASE_BRANCH with the release branch name (e.g. stackstate-7.78.2).

Only the release branch is published here: the publishing job runs on pushes to that branch and uses the branch name as the apt codename. Per-branch builds such as master or STAC-xxxx are no longer produced — historical ones remain readable at https://stackstate-agent-3-test.s3.amazonaws.com.

$ docker pull registry.tooling.stackstate.io/quay/stackstate/stackstate-agent-2:latest

$ docker pull registry.tooling.stackstate.io/quay/stackstate/stackstate-agent-2-test:latest

To install the official release:

$ . { iwr -useb https://stackstate-agent-3.s3.amazonaws.com/install.ps1 } | iex; install -stsApiKey "xxx" -stsUrl "yyy"

If you want to install a branch version use the test repository:

$ . { iwr -useb https://stackstate-agent-3-test.s3.amazonaws.com/install.ps1 } | iex; install -stsApiKey "xxx" -stsUrl "yyy" -codeName "PR_NAME"

and replace PR_NAME with the branch name (e.g. master, STAC-xxxx).

Other arguments can be passed to the installation command.

Linux arguments:

• STS_HOSTNAME = Instance hostname
• $HOST_TAGS = Agent host tags to use for all topology component (by default os:linux will be added)
• SKIP_SSL_VALIDATION = Skip ssl certificates validation when talking to the backend (defaults to false)
• STS_INSTALL_ONLY = Agent won't be automatically started after installation

Windows arguments:

• hostname = Instance hostname
• tags = Agent host tags to use for all topology component (by default os:windows will be added)
• skipSSLValidation = Skip ssl certificates validation when talking to the backend (defaults to false)
• agentVersion = Version of the Agent to be installed (defaults to latest)

We ended up checking in a patched gem file under omnibus/vendor/cache/libyajl2-1.2.1.gem, to make windows builds work with newer msys toolchain. The source of this can be found here https://github.com/StackVista/libyajl2-gem/tree/1.2.0-fixed-lssp. Ideally we'd be able to drop this hack once we bump the ruby version > 2.6.5 because libyajl2 compiles proper on those ruby versions.

If you want to speed up the GitLab pipeline and run only the steps related to the cluster agent, include the string [cluster-agent] in your commit message.

The acceptance tests in our pipeline use the stackstate-agent helm chart to install the agent in a test cluster. If you make changes to the stackstate-agent helm chart, you probably want to test if our acceptance tests will work after your changes.

When you open a merge request on the helm-chart repository, a test version of that chart will be published to a test helm repository stackstate-test. You can add that test repo in your machine by running the following commands:

helm repo add stackstate-test https://helm-test.stackstate.io && helm repo update

You can then install this version of the cluster-agent helm chart by running:

helm upgrade --install \
  --create-namespace \
  --namespace <namespace> \
  --set-string 'stackstate.apiKey'='<api-key>' \
  --set-string 'stackstate.cluster.name'='<cluster-name' \
  --set-string 'stackstate.url'='<stackstate-url>' \
  stackstate-agent stackstate-test/stackstate-agent --version <version>

<version> is the new version you've set on helm-charts/stable/stackstate-agent/Chart.yaml on your feature branch. Install it directly with helm upgrade --install from the stackstate-test repository; the agent pipeline no longer carries a chart-version override.