Forge Home


Module for managing and configuring Blackfire PHP Profiler


6,274 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.6.1 (latest)
  • 1.6.0
  • 1.5.2
  • 1.5.1
  • 1.5.0
  • 1.4.2
  • 1.4.1
  • 1.4.0
  • 1.3.0
  • 1.2.2
  • 1.2.1
  • 1.2.0
  • 1.1.0 (deleted)
released Feb 18th 2019
This version is compatible with:
  • Puppet Enterprise 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >=3.0.0 <6.0.0
  • , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 's12v-blackfire', '1.6.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add s12v-blackfire
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install s12v-blackfire --version 1.6.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Tags: php


s12v/blackfire — version 1.6.1 Feb 18th 2019

Build Status Puppet Forge


Table of Contents

  1. Description
  2. Setup - The basics of getting started with blackfire
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module


Puppet module for installing, configuring and managing Blackfire PHP profiler.


What blackfire affects

  • The module adds blackfire repository and overwrites blackfire configuration file.
  • It does not restart any service, you have to do it manually.

Setup requirements

Make sure blackfire is installed after PHP.

Beginning with blackfire

The module includes a single public class blackfire.

Minimal configuration

You need to provide at least server_id and server_token parameters. Also you might want to subscribe your service to be restarted when configuration has changed:

class { 'blackfire':
    server_id    => 'b54114a9-df8a-563b-8ba3-e5457155010e',
    server_token => '7315b1cf617bf51575ba463e813156ed97c85d8ca5c5691db37bbfe36a622a4f',
    notify => Service['php5-fpm']

You can get these parameters on


If you want to provide additional parameters to Agent or PHP extension:

class { 'blackfire':
    server_id    => 'b54114a9-df8a-563b-8ba3-e5457155010e',
    server_token => '7315b1cf617bf51575ba463e813156ed97c85d8ca5c5691db37bbfe36a622a4f',
    agent => {
        log_level => 2
    php => {
        log_level => 3



Public classes

  • blackfire: Main class

Private classes

  • blackfire::agent: Manages the Agent
  • blackfire::agent::install: Handles the packages.
  • blackfire::agent::config: Handles the configuration file.
  • blackfire::agent::service: Handles the service.
  • blackfire::php: Manages the PHP extension (Probe)
  • blackfire::php::install: Handles the packages.
  • blackfire::php::config: Handles the configuration file.
  • blackfire::repo: Handles the repository.


Available parameters for blackfire class

  • agent - Configuration for Blackfire Agent
    • ca_cert - PEM encoded certicates
    • collector - URL of Blackfire's data collector. Default is
    • http_proxy - Http proxy to use
    • https_proxy - Https proxy to use
    • log_file - The path of the log file. Use "stderr" to log to stderr. Default is stderr
    • log_level - Log verbosity level (4: debug, 3: info, 2: warning, 1: error). Default is 1
    • manage - Manage Agent. Default is true
    • manage_service - Manage Agent service. Default is true
    • service_ensure - Default is running
    • socket - The socket the agent will listen to. Default is unix:///var/run/blackfire/agent.sock
    • spec - The path to the json specifications file
    • version - Which version of the agent to install. Default is latest
  • manage_repo - Manage Blackfire repository. Default is true
  • php - Configuration for Blackfire PHP extension
    • agent_socket - The agent socket. Default is unix:///var/run/blackfire/agent.sock
    • agent_timeout - The agent timeout. Default 0.25
    • log_file - The path of the log file.
    • log_level - Log verbosity level (4: debug, 3: info, 2: warning, 1: error). Default is 1
    • manage - Manage PHP extension. Default is true
    • version - Which version of the probe to install. Default is latest
    • ini_path - Path of the blackfire.ini file to be generated. If not set, will try find out the path by installed PHP Version. Default is empty
  • server_id - Server ID to use for the agent (See
  • server_token - Server Token to use for the agent (See


This module is currently tested on:

  • Ubuntu (16.04, 14.04, 12.04, 10.04)
  • Centos (7.0, 6.6)
  • Debian (8.0, 7.8, 6.0)

It may work on other distros.


Module testing

  • bundle exec rake validate - Check syntax of Ruby files and call :syntax and :metadata / Validate manifests, templates, and ruby files
  • bundle exec rake lint - Check puppet manifests with puppet-lint / Run puppet-lint
  • bundle exec rake spec - Run spec tests in a clean fixtures directory (using spec_helper)

Acceptance testing with beaker

  • bundle exec rake beaker_nodes - List available beaker nodesets
  • BLACKFIRE_SERVER_ID=... BLACKFIRE_SERVER_TOKEN=... bundle exec rake beaker - Run beaker acceptance tests (default nodeset)
  • BEAKER_set=centos-70-x64 BLACKFIRE_SERVER_ID=... BLACKFIRE_SERVER_TOKEN=... bundle exec rake beaker - Run beaker acceptance tests for the nodeset