Added build scripts for ext-scoutapm

[asgrim]

This patch aims to add support for installing the scoutapm extension from PECL on Heroku environments.

Source: https://github.com/scoutapp/scout-apm-php-ext
PECL package: https://pecl.php.net/package/scoutapm

We only support PHP 7.1+ at this time, so only 7.1+ have been added here. Please let me know if any changes need to be made! Thanks.

[citricacid-pl]

Is this going to be released any soon? Would be great

[dzuelke]

So, generally, we want specific versions for a package formula, this also ensures easier automated building.

This core agent thing we'd also want to explicitly load and start, similar to the other APMs, in order to avoid any overhead at runtime.

It should be its own package, not bundled as in the case of Blackfire.

Unfortunately, there appear to be no docs on the core agent; version history, where to download it, how to configure it, what the command line options are, and so forth. Feel free to email these to me if you don't want to post that info here.

[asgrim]

@dzuelke Thanks for getting back to me. Two things:

The core-agent thing is automatically downloaded & started the first time it detects it's not running (AFAIK, Scout already has customers on Heroku doing this). It is possible to "manually" set this up, and I'm just trying to poke Scout for their docs on this as it doesn't seem to exist. If I can find that, then I can provide docs in the scout PHP agent for how to set that up on Heroku to avoid the runtime overhead 👍

However: the focus of this PR specifically is to just enable the PECL extension scoutapm. All this does is record metrics for a few internal PHP functions (mostly I/O bound stuff), and collect it for the scout-apm-php library (written in PHP). Is the only thing that needs to change here the PECL version needs defining? If so, how does one define that in these build scripts? I copied off one of the other PECL exts I think...

[dzuelke]

Take a look at how all the other extensions are defined - there is a base amqp or redis in the "oldest" extension folder that supports it, and then an amqp-1.2.3 and redis-2.3.4 in every extension folder, so that they're explicitly versioned. Otherwise, you build today and get version 1.0.1, and tomorrow you're getting version 1.0.2, from the same formula, and deploying would overwrite the existing package.

[asgrim]

@dzuelke thanks David, I've rebased onto main and added explicit versions 👍

[asgrim]

@dzuelke hi David, I've updated this branch to add scoutapm support for PHP 8.0 as well as we released that a while ago, we're also on a newer version (1.4.2).

[edmorley]

(Switching review to the PHP SME, to get this out of the languages team review queue)

[rickyPanzer]

is there anything we can do to get this in?

[dzuelke]

Been working on this, @asgrim.

First, could you relay the following to Scout engineering for me please:

1. the core-agent probe command returns with exit status 0, regardless of whether a connection to the agent could be made or not. https://scoutapm.com/docs/core-agent#without-docker lists this as a way of seeing whether the connection is up; not returning a suitable exit status to distinguish the yes/no cases makes it very hard to programmatically determine the result of the probe call (e.g. waiting in a loop calling probe until the core agent is up):

   ~/.heroku/php/opt/scoutapm $ ./core-agent start --daemonize false --socket /tmp/scoutapm-core.sock --log-level info &
   [1] 144
   [2022-05-18T10:26:49][core_agent][INFO] Initializing logger with log level: Info
   [2022-05-18T10:26:49][core_agent][INFO] Starting ScoutApm CoreAgent version: "1.3.0"
   [2022-05-18T10:26:49][socket::server][INFO] Socket Server bound to socket at "/tmp/scoutapm-core.sock"
   
   ~/.heroku/php/opt/scoutapm $ ./core-agent probe --socket /tmp/scoutapm-core.sock
   [2022-05-18T10:27:04][core_agent][INFO] Initializing logger with log level: Info
   [2022-05-18T10:27:04][socket::server][INFO] Unregistered Socket Goodbye on thread: ThreadId(4)
   Agent found: CoreAgentVersion { raw: "1.3.0" }
   ~/.heroku/php/opt/scoutapm $ echo $?
   0
   
   ~/.heroku/php/opt/scoutapm $ ./core-agent probe --socket /tmp/scoutapm-core.NOPE
   [2022-05-18T10:27:28][core_agent][INFO] Initializing logger with log level: Info
   Agent Not Running at Some("/tmp/scoutapm-core.NOPE") or None
   ~/.heroku/php/opt/scoutapm $ echo $?
   0

2. core-agent start does not return an error and does not print any messages if already running:

   ~/.heroku/php/opt/scoutapm $ ./core-agent start --daemonize false --socket /tmp/scoutapm-core.sock --log-level info &
   [1] 137
   [2022-05-18T10:25:52][core_agent][INFO] Initializing logger with log level: Info
   [2022-05-18T10:25:52][core_agent][INFO] Starting ScoutApm CoreAgent version: "1.3.0"
   [2022-05-18T10:25:52][socket::server][INFO] Socket Server bound to socket at "/tmp/scoutapm-core.sock"
   
   ~/.heroku/php/opt/scoutapm $ ./core-agent start --daemonize false --socket /tmp/scoutapm-core.sock --log-level info
   [2022-05-18T10:26:01][core_agent][INFO] Initializing logger with log level: Info
   [2022-05-18T10:26:01][socket::server][INFO] Unregistered Socket Goodbye on thread: ThreadId(4)
   ~/.heroku/php/opt/scoutapm $ echo $?
   0

3. should/could core-agent read SCOUT_CORE_AGENT_SOCKET_PATH and SCOUT_LOG_LEVEL (or SCOUT_CORE_AGENT_LOG_LEVEL) and a maybe few others from the environment?
4. would it be possible to add a magic stderr log file name? Others, e.g. New Relic, have that, since it's not always possible to use something like /dev/stderr in a portable manner. Right now, the agent by default logs to stdout.

Second, what's the general workflow people use in your experience for the extension? Do folks list it in composer.json, and have it just sitting around doing nothing on local dev boxes? Or is it typically staging/production only?

I am wondering if the extension should get the same automagic installation treatment that Blackfire and New Relic have, for when $SCOUT_KEY is detected; either way I'd like to start core-agent if $SCOUT_KEY is there so that the PHP client library doesn't have to do its "download an executable from the internet and launch it" stuff.

[asgrim]

Hi @dzuelke sorry for the delay, always busy 😁

First, could you relay the following to Scout engineering for me please:

I've opened issues for each of these on the core-agent repo. I've actually started working a bit on this myself, so I might be able to look at some of these. On the last one would it be possible to add a magic stderr log file name? could you elaborate on this a little please? I'm unsure what you mean. Do you just mean a redirect, something like $ core-agent <stuff> 2>&1 ?

Second, what's the general workflow people use in your experience for the extension? Do folks list it in composer.json, and have it just sitting around doing nothing on local dev boxes? Or is it typically staging/production only?

ext-scoutapm could indeed be defined in composer.json - the ext is not actually activated unless explicitly asked to do so, although I've noticed an improvement in that if scoutapp/scout-apm-php is even invoked (even if instrumentation is configured OFF with something like SCOUT_MONITOR=false), the scoutapm_enable_instrumentation() function is still called. Created scoutapp/scout-apm-php#275 to handle this improvement.

I am wondering if the extension should get the same automagic installation treatment that Blackfire and New Relic have, for when $SCOUT_KEY is detected; either way I'd like to start core-agent if $SCOUT_KEY is there so that the PHP client library doesn't have to do its "download an executable from the internet and launch it" stuff.

That would be a cool improvement! If there's anything I can do to assist with that please do let me know. The PHP library won't download/launch if the following envs are set:

SCOUT_CORE_AGENT_DOWNLOAD_ENABLED=false
SCOUT_CORE_AGENT_LAUNCH_ENABLED=false
SCOUT_CORE_AGENT_SOCKET_PATH=tcp://1.2.3.4:1234 # replace with IP/port of core-agent runner

[dzuelke]

On the last one would it be possible to add a magic stderr log file name? could you elaborate on this a little please? I'm unsure what you mean. Do you just mean a redirect, something like $ core-agent <stuff> 2>&1 ?

Basically core-agent --log-file stderr. New Relic allows this, too, and Blackfire similarly has a magic "stderr" file name. The reasoning is that core-agent --log-file /dev/stderr does not always work in all environments (LXC permissions, don't get me started...).

I am wondering if the extension should get the same automagic installation treatment that Blackfire and New Relic have, for when $SCOUT_KEY is detected; either way I'd like to start core-agent if $SCOUT_KEY is there so that the PHP client library doesn't have to do its "download an executable from the internet and launch it" stuff.

That would be a cool improvement! If there's anything I can do to assist with that please do let me know. The PHP library won't download/launch if the following envs are set:

SCOUT_CORE_AGENT_DOWNLOAD_ENABLED=false
SCOUT_CORE_AGENT_LAUNCH_ENABLED=false
SCOUT_CORE_AGENT_SOCKET_PATH=tcp://1.2.3.4:1234 # replace with IP/port of core-agent runner

Nice, that should just work "out of the box" then if Heroku sets those env vars for the PHP library.

[asgrim]

Basically core-agent --log-file stderr. New Relic allows this, too, and Blackfire similarly has a magic "stderr" file name. The reasoning is that core-agent --log-file /dev/stderr does not always work in all environments (LXC permissions, don't get me started...).

Thank you for the clarification on that, I understand now. We've got a ticket to look into this 👍

Nice, that should just work "out of the box" then if Heroku sets those env vars for the PHP library.

Awesome! 😁 as I said, if there's anything I can do to help please let me know.

It's worth adding that Scout also has the same core-agent for other supported languages (e.g. Ruby, Python), but I don't know if their language libraries work in the same way (i.e. lazily download the core-agent and run it by default).