Docs » Integrations Guide » Use the SignalFx Smart Agent » Overview


The SignalFx Smart Agent is a metric agent written in Go for monitoring infrastructure and application services in a variety of different environments. It is meant as a successor to our previous collectd agent, but still uses that internally – so any existing Python or C-based collectd plugins will still work without modification.


The Smart Agent has three main components:

  1. Observers that discover applications and services running on the host
  2. Monitors that collect metrics from the host and applications
  3. The Writer that sends the metrics collected by monitors to SignalFx.


Observers watch the various environments that we support to discover running services and automatically configure the Smart Agent to send metrics for those services.

For a list of supported observers and their configurations, see Observer Config.


Monitors collect metrics from the host system and services. They are configured under the monitors list in the Smart Agent config. For application-specific monitors, you can define discovery rules in your monitor configuration. A separate monitor instance is created for each discovered instance of applications that match a discovery rule. See Auto Discovery for more information.

Many of the monitors are built around collectd, an open source third-party monitor, and use it to collect metrics. Some other monitors do not use collectd. However, either type is configured in the same way.

For a list of supported monitors and their configurations, see Monitor Config.

The Smart Agent is primarily intended to monitor services/applications running on the same host as the Smart Agent. This is in keeping with the collectd model. The main issue with monitoring services on other hosts is that the host dimension that collectd sets on all metrics will currently get set to the hostname of the machine that the Smart Agent is running on. This allows everything to have a consistent host dimension so that metrics can be matched to a specific machine during metric analysis.


The writer collects metrics emitted by the configured monitors and sends them to SignalFx on a regular basis. There are a few things that can be configured in the writer, but this is generally only necessary if you have a very large number of metrics flowing through a single agent.


The Smart Agent is available for Linux in both a containerized and standalone form. Whatever form you use, the dependencies are completely bundled along with the agent, including a Java JRE runtime and a Python runtime, so there are no additional dependencies required. This means that the Smart Agent should work on any relatively modern Linux distribution (kernel version 2.6+). To get started deploying the Smart Agent directly on a host, see the Smart Agent Quickstart guide.


We support the following deployment/configuration management tools to automate the installation process. See Bundles for a list of underlying packages for the Smart Agent.

Installer Script

For non-containerized environments, there is a convenience script that you can run on your host to install the Smart Agent package. This is useful for testing and trials, but for full-scale deployments you will probably want to use a configuration management system like Chef or Puppet. You can view the source for the installer script and use it on your hosts by running:

curl -sSL > /tmp/


We offer a Chef cookbook to install and configure the Smart Agent. See the cookbook source and on the Chef Supermarket.


We also offer a Puppet manifest to install and configure the Smart Agent. See the manifest source and on the Puppet Forge.


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


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

Docker Image

See Docker Deployment for more information.


See our Kubernetes setup instructions and the documentation on Monitoring Kubernetes for more information.

AWS Elastic Container Service (ECS)

See the ECS directory, which includes a sample config and task definition for the Smart Agent.


We offer the Smart Agent in the following forms:

Debian Package

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

curl -sSL > /etc/apt/trusted.gpg.d/signalfx.gpg
echo 'deb /' > /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 make use of with the following commands:

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

yum install -y signalfx-agent

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. 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. Since you aren’t installing from a package, there are three config options that you will especially want to consider:
  • diagnosticsSocketPath - This is the full path to a UNIX domain socket that the Smart Agent will listen on so that the signalfx-agent status command can read diagnostic information from a running agent. It can be blank if you don’t desire that functionality.
  • internalMetricsSocketPath - This is the full path to a UNIX domain socket that the Smart Agent will listen on for requests from the internal-metrics monitor to gather internal metrics about the Smart Agent. It can also be blank to disable this socket.
  • 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 the section on Privileges for information on the capabilities the Smart Agent requires.

  1. Run the Smart Agent by invoking the archive path signalfx-agent/bin/signalfx-agent -config <path to config.yaml>. The Smart Agent logs only to stdout/err so it is up to you to direct that to a log file or other log management system if you wish to persist logs. See the signalfx-agent command doc for more information on supported command flags.


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.


The Smart Agent is configured primarily from a YAML file (by default, /etc/signalfx/agent.yaml, but this can be overridden by the -config command line flag).

For the full schema of the config, see Config Schema.

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.


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.

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_PROXY envvar 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.


The Smart Agent serves diagnostic information on a UNIX domain socket at the path configured by the diagnosticsSocketPath option. The socket takes no input, but simply dumps its current status back upon connection. As a convenience, the command signalfx-agent status will read this socket and dump out its contents.

The Smart Agent status output has the following sections:

  • Version: The Smart Agent version and build time
  • Agent Configuration: The current configuration in use by the Smart Agent, with secret values replaced by *s. Default values will be shown here if they were not set in the Smart Agent config file.
  • Writer Status: The status and metrics about the writer component which writes datapoints to SignalFx.
  • Observers: The active observers in the Smart Agent
  • Monitor Configurations (Not necessarily active): A list of monitor configurations that are in place. If a configuration has a discovery rule but no discovered endpoints match that rule, there will not be any active instances of this monitor.
  • Active Monitors: Monitors instances that are actively monitoring something. There may be multiple instances of these per configuration above if there is a discovery rule that matches multiple services.
  • Discovered Endpoints: A list of the endpoints discovered by the Smart Agent’s observers. The fields shown there will be the fields used when matching discovery rules to a discovered endpoint.
  • Bad Monitor Configurations: This will be a set of monitor configurations that did not validate and the associated error. Bad monitor configuration generally does not prevent the Smart Agent from starting up, but will prevent that monitor from ever instantiating.

Also see our FAQ for more troubleshooting help.


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