Docs » Advanced Installation Options

Advanced Installation Options πŸ”—

See Quick Install for simplified Smart Agent command-line installation on a single host.

Advanced Installation on a Single Host πŸ”—

Packages and other methods of installation on a single host are discussed below.

Packages πŸ”—

We offer the agent in the following packages:

Debian Package πŸ”—

We provide a Debian package repository that you can use with the following commands:

curl -sSL > /etc/apt/trusted.gpg.d/splunk.gpg;
echo 'deb release main' > /etc/apt/sources.list.d/signalfx-agent.list
apt-get update
apt-get install -y signalfx-agent

RPM Package πŸ”—

We provide a RHEL/RPM package repository that you can use with the following commands:

cat <<EOH > /etc/yum.repos.d/signalfx-agent.repo
name=SignalFx Agent Repository

yum install -y signalfx-agent

Linux Standalone tar.gz πŸ”—

If you don’t want to use a distro package, we offer a .tar.gz that can be deployed to the target host. This bundle is available for download on the GitHub Releases Page for each new release.

To use the bundle:

  1. Unarchive it to a directory of your choice on the target system.

  2. Go into the unarchived signalfx-agent directory and run bin/patch-interpreter $(pwd). This ensures that the binaries in the bundle have the right loader set on them if your host loader is not compatible.

  3. Ensure a valid configuration file is available somewhere on the target system. The main thing that the distro packages provide – but that you will have to provide manually with the bundle – is a run directory for the Smart Agent to use. Because you aren’t installing from a package, there are three config options to particularly consider:

    • internalStatusHost - This is the host name that the Smart Agent will listen on so that the signalfx-agent status command can read diagnostic information from a running agent. This is also the host name the agent will listen on to serve internal metrics about the Smart Agent. These metrics can be scraped by the internal-metrics monitor. This will default to localhost if left blank.
    • internalStatusPort - This is the port that the Smart Agent will listen on so that the signalfx-agent status command can read diagnostic information from a running agent. This is also the host name the Smart Agent will listen on to serve internal metrics about the Smart Agent. These metrics can be scraped by the internal-metrics monitor. This will default to 8095.
    • collectd.configDir - This is where the Smart Agent writes the managed collectd config, since collectd can only be configured by files. Note that this entire dir will be wiped by the Smart Agent upon startup so that it doesn’t pick up stale collectd config, so be sure that it is not used for anything else. Also note that these files could have sensitive information in them if you have passwords configured for collectd monitors, so you might want to place this dir on a tmpfs mount to avoid credentials persisting on disk.

    See Privileges for information on the capabilities the Smart Agent requires.

  4. (Optional) To override the default user and group names, at a minimum, you must have permission to:

  • Execute the extracted files in signalfx-agent/bin/
  • Read the agent.yaml and any remote config files referenced in the agent.yaml

Based on how the agent has been configured and started and where the bundle is extracted, you may need additional permissions. For example, if the agent is configured for collectd monitors, then you must also have create, read, and write permissions for the /var/run/signalfx-agent directory.

Alternatively, the configDir option in the agent.yaml can be configured for a collectd run directory that is accessible to non-root users. To learn more, see Config schema.

  1. Run the Smart Agent by invoking the archive path:
 signalfx-agent/bin/signalfx-agent -config <path to config.yaml>

By default, the Smart Agent logs only to stdout/err. If you want to persist logs, you must direct the output to a log file or other log management system. See the signalfx-agent command doc for more information on supported command flags.

Windows Standalone .zip πŸ”—

A .zip bundle is also available that can be deployed to the target host. To obtain the bundle, go to Github Releases Page and download the most recent release.

Before proceeding, you should ensure that .Net Framework 3.5 or later is installed.

As an optional step, if you want to invoke a Python script for non-default monitors, specifically exec, then you must have Python installed.

To use the bundle (requires user with Administrator privileges):

  1. Unzip it to a directory of your choice on the target system.
  2. Ensure a valid configuration file is available somewhere on the target system. By default, the Smart Agent will look for a configuration file at \ProgramData\SignalFxAgent\agent.yaml. A sample configuration file can be found at SignalFxAgent\etc\signalfx\agent.yaml in the extracted directory. See Configuration for more information on how to configure the Smart Agent.
  3. Run the Smart Agent by invoking the Smart Agent executable
& "<extracted path>\SignalFxAgent\bin\signalfx-agent.exe" -config <path to config file>.

By default, the Smart Agent runs as a process in the foreground and logs only to stdout/err.

You may optionally install the Smart Agent as a Windows service and log the output to the Windows Event Viewer by invoking the agent executable and specifying a few command line flags. The examples below show how to install and start the Smart Agent as a Windows service.

Install Service

& "<extracted path>\SignalFxAgent\bin\signalfx-agent.exe" -service "install" -logEvents -config <path to config file>

Start Service

& "<extracted path>\SignalFxAgent\bin\signalfx-agent.exe" -service "start"

To stop or uninstall the Smart Agent service:

Stop Service

& "<extracted path>\SignalFxAgent\bin\signalfx-agent.exe" -service "stop"

Uninstall Service

& "<extracted path>\SignalFxAgent\bin\signalfx-agent.exe" -service "uninstall"

Install Smart Agent on Multiple Hosts πŸ”—

After you have installed the Smart Agent on a single host and discovered some of its capabilities, you may want to install the agent on multiple hosts using Configuration Management tools.

Configuration Management Tools πŸ”—

We support the following configuration management tools to automate the Smart Agent installation for multiple hosts.

Chef: We offer a Chef cookbook to install and configure the agent. See the cookbook source on the Chef Supermarket.

Puppet: We also offer a Puppet manifest to install and configure the agent on Linux. See the manifest source on the Puppet Forge.

Ansible: We also offer an Ansible Role to install and configure the Smart Agent on Linux. See the role source.

Salt: We also offer a Salt Formula to install and configure the Smart Agent on Linux. See the formula source.

Docker Image: See Docker Deployment for more information.

AWS Elastic Container Service (ECS): See the ECS directory, which includes a sample config and task definition for the agent.

Kubernetes: See Kubernetes Setup and Monitoring Kubernetes for more information.

Configuration πŸ”—

The Smart Agent is configured primarily from a YAML file. By default, the Smart Agent config is installed at and looked for at /etc/signalfx/agent.yaml on Linux and \ProgramData\SignalFxAgent\agent.yaml on Windows. This can be overridden by the -config command line flag.

For details and the full schema of the config, see Agent Configuration.

For information on how to configure the Smart Agent from remote sources, such as other files on the filesystem or KV stores such as Etcd, see Remote Configuration.

Add Monitors πŸ”—

You may also want to add and configure various monitors for your environment. A limited set of Smart Agent monitors are configured by default in the config file, and many more are available. See the Integrations page for monitor selection.

Configure optional metrics for your monitors πŸ”—

For metric configuration for your monitor, see individual Windows or Linux monitor pages from the lists directly above or see the Integrations tab in the SignalFx application for Monitor Services.

Explore Dashboards to display and compare data from various sources πŸ”—

See Built-In Dashboards and Charts.

You can also create your own custom dashboards.

See best practices for Better Dashboards.

To learn more about how your data is presented in SignalFx, see the 15-Minute SignalFx Quick Start.

Additional material πŸ”—

Observers πŸ”—

Example of adding a new observer:

To start collecting docker container metrics, first add a docker observer.

Your observer list would then look similar to this:

  - type: host
  - type: docker

Next, add a docker metrics monitor to the agent.yaml file. Your type list would now include this monitor (docker-container-stats) as shown below:

  - type: cpu
  - type: docker-container-stats

The agent automatically picks up any changes to the configuration file, so a restart is not required.

For complete details, see Observer Configuration.

Privileges πŸ”—


When using the host observer, the Smart Agent requires the Linux capabilities DAC_READ_SEARCH and SYS_PTRACE, both of which are necessary to allow the agent to determine which processes are listening on network ports on the host. Otherwise, there is nothing built into the Smart Agent that requires privileges.

When using a package to install the Smart Agent, the Smart Agent binary is given those capabilities in the package post-install script, but the Smart Agent is run as the signalfx-agent user. If you are not using the host observer, then you can strip those capabilities from the Smart Agent binary if so desired.

You should generally not run the Smart Agent as root unless you can’t use capabilities for some reason.


On Windows, the Smart Agent must be installed and run under an administrator account.

Logging πŸ”—

Linux πŸ”—

Currently, the Smart Agent only supports logging to stdout/stderr, which will generally be redirected by the init scripts we provide to either a file at /var/log/signalfx-agent.log or to the systemd journal on newer distros. The default log level is info, which will log anything noteworthy in the Smart Agent without spamming the logs too much. Most of the info level logs are on startup and upon service discovery changes. debug will create very verbose log output and should only be used when trying to resolve a problem with the agent.

Windows πŸ”—

On Windows, the Smart Agent will log to the console when executed directly in a shell. If the Smart Agent is configured as a windows service, log events will be logged to the Windows Event Log. Use the Event Viewer application to read the logs. The Event Viewer is located under Start > Administrative Tools > EventViewer. You can see logged events from the Smart Agent service under Windows Logs > Application.

Proxy Support πŸ”—

To use an HTTP(S) proxy, set the environment variable HTTP_PROXY and/or HTTPS_PROXY in the container configuration to proxy either protocol. The SignalFx ingest and API servers both use HTTPS. If the NO_PROXYenvvar exists, the Smart Agent will automatically append the local services to the envvar to not use the proxy.

If the Smart Agent is running as a local service on the host, refer to the host’s service management documentation for how to pass environment variables to the agent service in order to enable proxy support when the Smart Agent service is started.

For example, if the host services are managed by systemd, create the /etc/systemd/system/signalfx-agent.service.d/myproxy.conf file and add the following to the file:


Then execute systemctl daemon-reload and systemctl restart signalfx-agent.service to restart the Smart Agent service with proxy support.

Diagnostics πŸ”—

The Smart Agent serves diagnostic information on an HTTP server at the address configured by the internalStatusHost and internalStatusPort option. As a convenience, the command signalfx-agent status will read this server and dump out its contents. That command will also explain how to get further diagnostic information.

See the FAQ for more troubleshooting help.

Development πŸ”—

If you want to contribute to the Smart Agent, see the Developer’s Guide.