Skip to content

Latest commit

 

History

History
263 lines (142 loc) · 14.6 KB

advanced-install-options.md

File metadata and controls

263 lines (142 loc) · 14.6 KB

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 https://splunk.jfrog.io/splunk/signalfx-agent-deb/splunk-B3CD4420.gpg > /etc/apt/trusted.gpg.d/splunk.gpg
echo 'deb https://splunk.jfrog.io/splunk/signalfx-agent-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
[signalfx-agent]
name=SignalFx Agent Repository
baseurl=https://splunk.jfrog.io/splunk/signalfx-agent-rpm/release
gpgcheck=1
gpgkey=https://splunk.jfrog.io/splunk/signalfx-agent-rpm/splunk-B3CD4420.pub
enabled=1
EOH

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 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-agentstatus 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 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 the section on Privileges for information on the capabilities the Smart Agent requires.

4.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

If you don’t want to use the installer script, we offer a .zip that can be deployed to the target host. This bundle is available for download on the Github Releases Page for each new release.

Before proceeding make sure the following requirements are installed.

.Net Framework 3.5 (Windows 8+)

Visual C++ Compiler for Python 2.7

To use the bundle:

  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. The main thing that the installer script provides – 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 two config options that you will especially want to consider:

    • internalStatusHost - This is the hostname 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-agentstatus 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.

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

  3. Run the Smart Agent by invoking the Smart Agent executable

SignalFxAgent\bin\signalfx-agent.exe-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.

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

Install Service

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

Start Service

PS> SignalFx\SignalFxAgent\bin\signalfx-agent.exe -service "start"

Install Smart Agent on Multiple Hosts

After you have installed the SignalFx 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 and on the Chef Supermarket.

Puppet: We also offer a Puppet manifest to install and configure the agent on Linux. See the manifest source and 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 the documentation on 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:

observers:
  - 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:

monitors:
  - 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

Linux

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.

Windows

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:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080/"
Environment="HTTPS_PROXY=https://proxy.example.com:8081/"

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-agentstatus will read this server and dump out its contents. That command will also explain how to get further diagnostic information.

Also see the FAQ for more troubleshooting help.

Development

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