Platform Docs

Agent Docs

Support Docs

Platform Docs

Agent Docs

Support Docs

Core Agent

Some of the languages instrumented by Scout depend on a standalone binary for collecting and reporting data. We call this binary the Core Agent. If the Core Agent is required for your language, the Scout agent library for that language will handle downloading, configuring, and launching the Core Agent automatically. However, you may manually manage the Core Agent through configuration options.

Running Manually

With Docker

Simply run the following:

1.

docker pull scoutapp/scoutapm

2.

docker run -p 6590:6590 --name scoutapm scoutapp/scoutapm

Without Docker

1. Create a directory which your app has permissions to read, write and execute into (for our example we will use: /tmp but can be placed elsewhere) and change to the created directory

cd /tmp
mkdir scout_apm_core && cd "$_"

2. Download and test the core agent:

2.1 Download the core agent tarball

curl https://s3-us-west-1.amazonaws.com/scout-public-downloads/apm_core_agent/release/scout_apm_core-latest-x86_64-unknown-linux-musl.tgz --output core-agent-download.tgz

2.2 Unzip the core-agent

tar -xvzf core-agent-download.tgz

2.3 Test that core agent is executable

./core-agent

If everything has run successfully, you should see something similar to the following output:

core agent startup info/output

3. Start the core agent:

./core-agent start --daemonize true --tcp 127.0.0.1:6590

Note: this will not persist past a reboot. We suggest adding the core agent to upstart, systemd, or any other processes manager you may be using.

For additional startup flags, check the in-executable help with ./core-agent start --help

For agents that use a core-agent version less than 1.3.0, remove the –tcp flag.

4. Check to see that core agent socket is running:

./core-agent probe

Configuring the language agent

You will need to configure the language agent to look in the correct location for the self hosted core-agent. Otherwise, the language agent will launch another core-agent and use this one instead.

If you are using one of the supported languages (PHP, Python, Elixir, and Node.js) with a core-agent version 1.3.0+ (released 2020/09/04) which uses a TCP socket, you will need to set the following configurations:

Note: You can also have the core-agent as a service on a separate host:

If you are using one of the supported languages with a core-agent version less than 1.3.0, you will have to set the following configuration variables to point to the correct UNIX domain socket path (as well as disabling the agent from re-downloading and launching the core agent again):

To check which version of the core-agent you’re using, check with the #changelog for your language’s agent.

While core-agent version’s 1.3.0+ default to using TCP sockets, it’s possible to still use UNIX domain sockets by setting the SCOUT_CORE_AGENT_SOCKET_PATH to the value seen above: SCOUT_CORE_AGENT_SOCKET_PATH=/tmp/scout_apm_core/scout-agent.sock. However, UNIX domain sockets adhere to permissions of the directory they are in. See the below section for potential issues.

Downloading the core agent to another directory

For core-agent versions lower than 1.3.0, by default, the core agent will be downloaded into the /tmp directory.

However due to /tmp being as mounted as not executable, or SELinux configuration, or your umask permissions, you may not be able to execute the core-agent in that directory. To change the directory that Scout downloads to, use the configuration SCOUT_CORE_AGENT_DIR.

Your app must have read, write, and execute permissions for this directory. Read your language’s agent configuration reference for more detail.

Checking if the core agent is executable

In some cases (for core-agent versions lower than 1.3.0), the core agent won’t be able to execute. You may be presented with an error message that looks similar to: [Scout] Failed to launch core agent - exception core-agent exited with non-zero status. Output: sh: 1: /tmp/scout_apm_core/scout_apm_core-v1.2.9-x86_64-unknown-linux-musl/core-agent: Permission denied

Try following Downloading the core agent to another directory above to see if you are able to execute the core agent in another directory to determine if there is a permissions issue with the default location. If you continue having issues, please reach out to us at support@scoutapm.com. ## Available platforms and architectures Builds of the Core Agent are available for these platforms and architectures:

Other languages

The Core Agent API is in our tech preview program.

Want to add tracing but Scout doesn’t support your app’s language? You can instrument just about anything (assuming you can communicate via a Unix Domain Socket) with Scout’s Core Agent API. For information, view the Core Agent API on GitHub.

Pinning The Core Agent

By default, all of our agents pin to the latest core-agent version that was available when the change was released (at this time the latest agents are pinned to 1.5.0). In order to update to the latest core-agent, you will need to update your agent as well.

Self Hosting

You can download the core-agent at the following URL:

https://s3-us-west-1.amazonaws.com/scout-public-downloads/apm_core_agent/release/scout_apm_core-v1.5.0-x86_64-unknown-linux-musl.tgz

Note the ending/release, where it’s “scout_apm_core-${core_agent_version}-${core_agent_triple}.tgz”

You will need to have both the core-agent binary as well as the manifest.json, which can both be found in the .tgz.

Once these have been added, you will also need to add the following environment variables:

SCOUT_CORE_AGENT_DIR=/path/to/code/scout_apm_core #(path to where the binary and manifest.json are)
SCOUT_CORE_AGENT_TRIPLE=x86_64-unknown-linux-musl
SCOUT_CORE_AGENT_VERSION=v1.5.0
SCOUT_CORE_AGENT_DOWNLOAD=false

If you will be manually launching the core-agent (see above), you will also want to set SCOUT_CORE_AGENT_LAUNCH=false

Troubleshooting

The core-agent’s trace logging is much more verbose than our various language agent’s debug levels and can be useful in certain scenarios.

For this example, I’m going to assume you’re using OSX in local, but this can be done using a linux in a local or staging environment as well – the core-agent downloaded will need to match the correct OS.

  1. Create folder to store core-agent and logs
mkdir scout_apm_core && cd "$_"
  1. Download OSX/Darwin core-agent
curl https://s3-us-west-1.amazonaws.com/scout-public-downloads/apm_core_agent/release/scout_apm_core-latest-x86_64-unknown-linux-musl.tgz --output core-agent-download.tgz

https://s3-us-west-1.amazonaws.com/scout-public-downloads/apm_core_agent/release/scout_apm_core-latest-x86_64-apple-darwin.tgz for Mac OSX users

  1. Extract contents
tar -xvzf core-agent-download.tgz
  1. Start core-agent with trace level logging. Note: You may need to stop the other core-agent process, if there is one, else the core-agent will fail to start.
pkill -15 'core-agent'; ./core-agent start --daemonize false --log-level trace  --tcp 127.0.0.1:6590 --log-file ./core-agent.log

It’s important that daemonize is set to false or we won’t capture the logs

Send a request or two to your app, stop the core-agent process (ctrl-c / SIGINT), and then send the core-agent.log file that was created in the directory to support@scoutapm.com

Once you stop this process, the previous/other daemonized core-agent process will be (re)started automatically by the language agent on the next handled request.

Change Log

The core-agent doesn’t require/receive as many updates as the top level agents (Python, PHP, Elixir, etc.) that depend upon it.

However, here are the latest releases for the core-agent:

[1.5.0] 2023-12-11

[1.4.0] 2021-11-04

Added

[1.3.1] 2021-09-21

Changed

[1.3.0] 2020-09-04

Added
Changed

On This Page