Platform Docs

Agent Docs

Support Docs

Platform Docs

Agent Docs

Support Docs

PHP Features

Note: These docs do not cover out of the box features of the agents, such as metric and trace collection.

Highly Recommended: While we strive for a minimal setup experience, there are a few features that may require additional setup: PECL Extension, Deploy Tracking, Request Queueing and Custom Context.

PECL Extension

Several instruments require the native extension to be included, including timing of Redis, Elasticsearch, and Memcached.

For more information, or to compile manually, the README has additional instructions.

sudo pecl install scoutapm

Deploy Tracking

Scout can track deploys, making it easier to correlate specific deploys to changes in performance.

Scout identifies deploys via the following approaches:

Request Queuing

Our PHP integration can measure the time it takes a request to reach your application from farther upstream (a load balancer or web server). This appears in Scout as “Request Queueing” and provides an indication of your application’s capacity. Large request queueing time is an indication that your app needs more capacity.

Please view request queueing section to learn how to get these insights.

Custom Context

Context lets you see the key attributes of requests. For example, you can add custom context to answer critical questions like:

It’s simple to add custom context to your app:

use Scoutapm\Laravel\Facades\ScoutApm; // Laravel only: Add near the other use statements

ScoutApm::addContext("Key", "Value");

// for example, passing in the user_id
// ScoutApm::addContext("user_id", Auth::id());

// or if you have an $agent instance:
$agent->addContext("Key", "Value");

Context Key Restrictions

The Context key must be a String with only printable characters. Custom context keys may contain alphanumeric characters, dashes, and underscores. Spaces are not allowed.

Attempts to add invalid context will be ignored.

Context Value Types

Context values can be any json-serializable type. Examples:

PII

To best help protect your data, we suggest using ids instead of explicit names and emails

Custom Instrumentation

You can extend Scout to trace transactions outside our officially supported libraries (e.g. Cron jobs and other web frameworks) and time the execution of sections of code that falls outside our provided instrumentation.

Transactions & Timing

Scout’s instrumentation is divided into 2 areas:

  1. Transactions: these wrap around an entire flow of work, like a web request or Cron job. The Scout Web UI groups data under transactions.
  2. Timing: these measure small pieces of code that occur inside of a transaction, like an HTTP request to an outside service, or a database call. This is displayed within a transaction trace in the UI.

Instrumenting Transactions

A transaction groups a sequence of work under in the Scout UI. These are used to generate transaction traces. For example, you may create a transaction that wraps around the entire execution of a PHP script that is ran as a Cron Job.

The Laravel instrumentation does this all for you. You only will need to manually instrument transactions in special cases. Contact us at support@scoutapm.com for help.

Limits

We limit the number of unique transactions that can be instrumented. Tracking too many uniquely named transactions can impact the performance of the UI. Do not dynamically generate transaction names in your instrumentation as this can quickly exceed our rate limits. Use context to add high-dimensionality information instead.

Web or Background transactions?

Scout distinguishes between two types of transactions:

$agent->webTransaction("GET Users", function() { ... your code ... });
$agent->send();

Timing functions and blocks of code

In existing transactions, both automatically created with Laravel instruments, and also manually created, you can time sections of code that are interesting to your application.

Traces that allocate significant amount of time to Controller or Job layers are good candidates to add custom instrumentation. This indicates a significant amount of time is falling outside our default instrumentation.

Limits

We limit the number of metrics that can be instrumented. Tracking too many unique metrics can impact the performance of our UI. Do not dynamically generate metric types in your instrumentation as this can quickly exceed our rate limits.

For high-cardinality details, use tags.

Getting Started

With existing code like:

$request = new ServiceRequest();
$request->setApiVersion($version);

It is wrapped with instrumentation:

// At top, with other imports
use Scoutapm\Laravel\Facades\ScoutApm;

// Replacing the above code
$request = ScoutApm::instrument(
    "Custom", // Kind
    "Building Service Request", // Name
    function ($span) use ($version) {
        $request = new ServiceRequest();
        $request->setApiVersion($version);
        return $request;
    }
);
Version:
Repository: scoutapp/scout-apm-php

On This Page