blackfire

Table of Contents

1. Description
2. Setup - The basics of getting started with blackfire
   • What blackfire affects
   • Setup requirements
   • Beginning 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

Description

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

Setup

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 https://blackfire.io/account/credentials.

Usage

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
	}
}

Reference

Classes

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.

Parameters

Available parameters for blackfire class

• agent - Configuration for Blackfire Agent
  • ca_cert - PEM encoded certicates
  • collector - URL of Blackfire's data collector. Default is https://blackfire.io
  • 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 https://blackfire.io/account/credentials)
• server_token - Server Token to use for the agent (See https://blackfire.io/account/credentials)

Limitations

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.

Development

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