1. Create a directory for the install. Suggested: mkdir -p /opt/circonus/cloud-agent
  2. Download the latest release
  3. Unpack the release in the directory created in first step
  4. In this directory, create a config folder. Suggested: mkdir /opt/circonus/cloud-agent/etc/gcp.d
  5. Auto-create a service specific configuration template in the desired format (yaml, toml, or json). Suggested: sbin/circonus-cloud-agentd --enable-gcp --gcp-example-conf=yaml > etc/gcp.d/gcp-config.yaml
    • Note, the id in the template is defaulted to the filename. This should be changed to a name that will be unique across all cloud-agents used in Circonus
    • Follow configuration instructions to finish config settings.
  6. Setup as a system service or run in foreground ensuring that --enable-gcp is specified


$  sbin/circonus-cloud-agentd -h
The Circonus Cloud Agent collects metrics from cloud infrastructures and fowards them to Circonus.

  circonus-cloud-agent [flags]

      --gcp-conf-dir string         GCP configuration directory (default "/opt/circonus/cloud-agent/etc/gcp.d")
      --gcp-example-conf string     Show GCP config (json|toml|yaml) and exit
  -c, --config string               config file (default: circonus-cloud-agent.yaml|.json|.toml)
  -d, --debug                       [ENV: CCA_DEBUG] Enable debug messages
      --enable-gcp                  Enable GCP metric collection client
  -h, --help                        help for circonus-cloud-agent
      --log-level string            [ENV: CCA_LOG_LEVEL] Log level [(panic|fatal|error|warn|info|debug|disabled)] (default "info")
      --log-pretty                  [ENV: CCA_LOG_PRETTY] Output formatted/colored log lines [ignored on windows]
  -V, --version                     Show version and exit



  1. Find project to monitor in GCP UI
  2. Add service account to project
    • Set service account name, e.g. ‘circonus-cloud-agent’
    • Add description
    • Click create
    • Add roles: project>viewer, monitoring>monitoring viewer, compute engine>compute viewer
    • Create key, type JSON (note where the key is downloaded)
      • Place the JSON file downloaded in GCP setup somewhere and ensure that the user running circonus-cloud-agentd will be able to read the file (e.g. nobody on linux when run as a systemd service).
      • Ensure that the configuration file setting gcp.credentials_file is set to the full filespec of where the service account JSON file was placed.
  3. The following APIs must be enabled for the project
    • Cloud Resource Manager API - role project>viewer is used to obtain the project meta data: ensure it is an active project, project name is used to create check bundle, project labels are added as a base set of stream tags along with project id
    • Stackdriver Monitoring API - role monitoring>monitoring viewer is used to retrieve available metrics and metric data
    • Compute Engine API - role compute engine>compute viewer is used to obtain a list of instances, obtain state/status of an instance, name, labels (for stream tags), etc.
  4. Add these to the gcp section of the configuration file.


  1. Use Circonus UI to create or identify an API Token to use
  2. Add the key to the config file under the circonus section

Example configuration

Minimum configuration:

id: ...
  credentials_file: ...
  key: ...