Docker

Search…
StackState version 4.4
Docker
Overview
StackState Agent V2
StackState Agent V2 can run in a Docker container. The Agent collects data from the host where it is running and can be configured to integrate with external systems. Retrieved data is pushed to StackState, to work with this data the StackState Agent V2 StackPack must be installed in your StackState instance. For details of the data retrieved and available integrations, see the StackPack integration documentation.
In Docker Swarm mode, the StackState Cluster Agent can be deployed on the manager node to retrieve topology data for the cluster.
Setup
Single container
To start a single Docker container with StackState Agent V2, run the following command:
1
docker run -d \
2
    --name stackstate-agent \
3
    --privileged \
4
    --network="host" \
5
    --pid="host" \
6
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
7
    -v /proc/:/host/proc/:ro \
8
    -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
9
    -e STS_API_KEY="API_KEY" \
10
    -e STS_STS_URL="https://your.stackstate.url/receiver/stsAgent" \
11
    -e HOST_PROC="/host/proc" \
12
    -e HOST_SYS="/host/sys" \
13
    docker.io/stackstate/stackstate-agent-2:latest
Copied!
Docker compose
To run StackState Agent V2 with Docker compose:
1.Add the following configuration to the compose file on each node where the Agent will run:
1
stackstate-agent:
2
 image: docker.io/stackstate/stackstate-agent-2:latest
3
 network_mode: "host"
4
 pid: "host"
5
 privileged: true
6
 volumes:
7
   - "/var/run/docker.sock:/var/run/docker.sock:ro"
8
   - "/proc/:/host/proc/:ro"
9
   - "/sys/fs/cgroup/:/host/sys/fs/cgroup:ro"
10
   - "/etc/passwd:/etc/passwd:ro"
11
   - "/sys/kernel/debug:/sys/kernel/debug"
12
 environment:
13
   STS_API_KEY: "API_KEY"
14
   STS_STS_URL: "https://your.stackstate.url/receiver/stsAgent"
15
   STS_PROCESS_AGENT_URL: "https://your.stackstate.url/receiver/stsAgent"
16
   STS_APM_URL: "https://your.stackstate.url/receiver/stsAgent"
17
   HOST_PROC: "/host/proc"
18
   HOST_SYS: "/host/sys"
Copied!
2.Run the command:
1
docker-compose up -d
Copied!
Docker swarm mode
In Docker Swarm mode, the StackState Cluster Agent can be deployed on the manager node to retrieve basic topology data (services, containers and the relations between them). To retrieve full data, StackState Agent V2 must also be deployed on each node as a Docker compose setup.
To run StackState Cluster Agent in Docker Swarm mode:
1.Create a file docker-compose.yml with the following content. Update to include details of your StackState instance:
STS_API_KEY - the API Key for your StackState instance
STS_STS_URL - the URL of the StackState Receiver API
STS_CLUSTER_NAME - the name you would like to give this cluster
1
stackstate-agent:
2
    image: docker.io/stackstate/stackstate-cluster-agent:latest
3
    deploy:
4
      placement:
5
        constraints: [ node.role == manager ]
6
    volumes:
7
      - /var/run/docker.sock:/var/run/docker.sock:ro
8
      - /etc/passwd:/etc/passwd:ro
9
      - /sys/kernel/debug:/sys/kernel/debug
10
    environment:
11
      STS_API_KEY: "API_KEY"
12
      STS_STS_URL: "http://receiver:7077/stsAgent"
13
      STS_COLLECT_SWARM_TOPOLOGY: "true"
14
      STS_LOG_LEVEL: "debug"
15
      STS_LOG_TO_CONSOLE: "true"
16
      DOCKER_SWARM: "true"
17
      STS_CLUSTER_NAME: <cluster_name>
Copied!
2.Run the command:
1
docker stack deploy -c docker-compose.yml
Copied!
Running the StackState Cluster Agent in Docker Swarm mode will collect basic topology data from the cluster. To retrieve more data, including telemetry, StackState Agent V2 must also be installed on each node in the Swarm cluster as a Docker compose setup.
Upgrade
To upgrade StackState Agent V2 running inside a Docker container.
1.Stop the running container and remove it.
1
docker stop stackstate-agent
2
docker container rm stackstate-agent
Copied!
1.Run the container using the instructions provided in setup.
Configure
Agent configuration
The StackState Agent V2 configuration is located in the file /etc/stackstate-agent/stackstate.yaml. The configuration file contains the STS_API_KEY and STS_STS_URL environment variables set when the Docker command is run. No further configuration should be required, however, a number of advanced configuration options are available.
Advanced Agent configuration
A number of advanced configuration options are available for StackState Agent V2. These can be set using environment variables and are described in detail on the page advanced Agent configuration.
Integration configuration
StackState Agent V2 can be configured to run checks that integrate with external systems. Each integration has its own configuration file that is used by the associated Agent check. Configuration files for integrations that will run through the StackState Agent in Docker should be added as a volume to the directory /etc/stackstate-agent/conf.d/ when the container is started.
For example, the Agent Docker configuration below includes a volume with a check configuration file for the ServiceNow integration:
1
stackstate-agent:
2
    image: docker.io/stackstate/stackstate-agent-2:latest
3
    network_mode: "host"
4
    pid: "host"
5
    privileged: true
6
    volumes:
7
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
8
      - "/proc/:/host/proc/:ro"
9
      - "/sys/fs/cgroup/:/host/sys/fs/cgroup:ro"
10
      - "/etc/passwd:/etc/passwd:ro"
11
      - "/sys/kernel/debug:/sys/kernel/debug"
12
      - "/etc/stackstate-agent/conf.d/servicenow.d/conf.yaml:/servicenow.d/conf.yaml:ro"
13
    environment:
14
      STS_API_KEY: "API_KEY"
15
      STS_STS_URL: "https://your.stackstate.url/receiver/stsAgent"
16
      HOST_PROC: "/host/proc"
17
      HOST_SYS: "/host/sys"
Copied!
Documentation for the available StackState integrations, including how to configure the associated Agent checks, can be found on the StackPacks > Integrations pages.
Self-Signed Certificates
If StackState Agent V2 will run checks that are configured to use self-signed certificates for HTTPs requests, override the CURL_CA_BUNDLE environment variable:
1
  CURL_CA_BUNDLE = ""
Copied!
Traces
StackState Agent V2 can be configured to collect traces via a StackState tracing integration. If the Agent will be used in conjunction with a language specific trace client, make sure to configure your app to use the host’s PID namespace:
1
  service:
2
    ...
3
    pid: "host" # should match with processes reported by the StackState process Agent
4
    ...
Copied!
Commands
Start or stop the Agent
To start, stop or restart StackState Agent V2, start or stop the container it is running in:
1
# Start container
2
docker start stackstate-agent
3
​
4
# Stop container
5
docker stop stackstate-agent
Copied!
Status and information
For status information, refer to the Docker log files for the container.
To run the Agent status command inside a container:
1
docker exec stackstate-agent bash -c 'agent status'
Copied!
Manually run a check
Use the command below to manually run an Agent check.
1
# Execute a check once and display the results.
2
docker exec stackstate-agent bash -c 'agent check <CHECK_NAME>'
3
​
4
# Execute a check once with log level debug and display the results.
5
docker exec stackstate-agent bash -c 'agent check -l debug <CHECK_NAME>'
Copied!
Troubleshooting
To troubleshoot the Agent, try to check the Agent status or manually run a check.
Log files
Docker logs for the StackState Agent container can be followed using the command:
1
docker logs -f stackstate-agent
Copied!
Inside the running container, StackState Agent V2 logs are in the following files:
/var/log/stackstate-agent/agent.log
/var/log/stackstate-agent/process-agent.log
Set log level
To troubleshoot the StackState Agent container, set the logging level to debug using the STS_LOG_LEVEL environment variable:
1
STS_LOG_LEVEL: "DEBUG"
Copied!
Support knowledge base
Troubleshooting steps for any known issues can be found in the StackState support knowledge base.
Uninstall
To uninstall StackState Agent V2, stop the Docker container it is running in and remove it.
1
docker stop stackstate-agent
2
docker container rm stackstate-agent
Copied!
See also
​About the StackState Agent​
​StackState Agent V2 StackPack​
​StackPack integration documentation​
​StackState Agent V2 (github.com)​
About the StackState Agent
Kubernetes
Last modified 2mo ago