Metrics¶

Defining a Metric Selector¶

Defining a metric is all about selecting a sub-set of the profile function calls. A selector first character defines how to interpret the rest of the expression:

• =: Matches the expression exactly;
• ^: Matches everything starting with the expression;
• /: Interprets the expression as a regex that should match;
• !: Interprets the expression as a regex that should not match;
• |: Similar to =, but matches any object that is an instance of the class;

The second part of the selector defines which function calls to match.

Here are some selector examples:

• =Class::method: Matches the method function calls on Class;
• =func: Matches the func function calls;
• ^ArrayObject::: Matches all function calls from the ArrayObject class;
• ^exif_: Matches all function calls for which the function starts with exif_;
• /^Class::(method1|method2)$/: Matches method1 and method2 calls from Class;
• !^spl_autoload_call$!: Matches any function/method calls but spl_autoload_call ones.
• |Psr\Log\LoggerInterface::log: Matches any calls to log on objects that are an instance of Psr\Log\LoggerInterface.

Capturing Arguments¶

Besides matching nodes, a metric can also be used to gather function call arguments (to be precise, you can get at most one argument for a function call).

Blackfire aggregates all calls to a function into one node to make it easy to reason about resources consumed by it. But sometimes, being able to have different nodes for a function call depending on one argument can help if the argument makes the function behave very differently (think of a database function call that is very sensitive to the SQL statement that needs to be executed for instance).

When defining argument capturing, you determine which argument you want to capture (1-based index) and when to capture it (^ means that Blackfire needs to always get the argument; ^http would only get the argument if it starts with the http string, all other calls would be aggregated into one node).

Argument capturing is only available in .blackfire.yaml file.

Examples¶

1
2
3
4
5
6
7
8

metrics:
  cache.write: # metric name
    label: "Cache::write() calls"
    matching_calls:
      php:
        - callee:
            selector: '=Cache::write' # aggregate the costs of all Cache::write calls
            argument: { 1: "^" }  # but create separate nodes by the first argument value