When you got started with Blackfire a few chapters ago, you used your Blackfire personal client and server credentials to profile local projects. It was the best way to configure Blackfire on your personal computer.
But what about enabling a team of developers to diagnose problems on production servers? Or configuring Blackfire on a Continuous Integration server? Blackfire is not just useful on a development server, but also on testing, staging, and production servers.
If you were to use your personal server credentials on a shared server, you would be the only one able to profile projects hosted on it. Another developer in your team trying to generate a profile would be rejected as their client credentials would generate a signature that would not match the server credentials. This is the Blackfire security mechanism that protects your servers from unauthorized activities.
Fortunately, Blackfire supports another way to configure shared servers. Environments let teams of developers manage the performance of various servers via common server credentials. An environment is a workspace where generated profiles are only accessible to team members.
Environments are more than just a set of credentials. This feature also allows a team to configure workflows and business logic depending on the server and app on which you collaborate. You can configure specific assertions, test scenarios, scenario triggers, and notifications. Environments also give you access to SQL queries and outgoing HTTP request details, as well as additional reference profiles and longer data retention. These topics will be discussed in a later chapter.
Environments are part of our Premium and Enterprise offerings. Consider starting a free Premium trial so you can follow along with this chapter and the next ones (no credit card required).
A single environment can be used on an unlimited number of servers, projects, and domain names. What's more, it is possible to use more than one set of credentials on a single server. So why would anyone ever create more than one environment?
The main usages for environments are the following:
One best practice is to create several environments per project: one for testing, one for staging, and one for production. At the end of the day, it is up to you to decide how to organize your environments depending on your infrastructure and the way you work.
For development computers, you should use personal server credentials as they have an exclusive feature: they allow you to profile all environments you have access to without switching credentials. However, you may want to create a specific environment for development as well if you are using a project-specific Vagrant box or Docker images shared by all developers.
Create an environment by clicking on "Create Environment" from the Dashboard page. Give your new environment a name, a description (describe what it gives access to for instance), and optionally a canonical URL.
On the environment page, give access to some developers by inviting them via the "Environment Members" tab:
Lastly, configure your server with the server credentials from the "Server Credentials" tab (more on that in the next section):
The easiest way to set up credentials on your server is to paste them into the Blackfire agent's configuration file, which is probably what you have done on your personal computer. It works great for standard setups where a server hosts only one project and the agent is configured locally.
Server credentials can also be configured in various other ways, depending on your hosting strategy: you can use them to secure multiple projects on one server or one project on a farm of servers. Blackfire supports these use cases and more, thanks to the following abilities:
php.ini), allowing you to set up different credential per PHP-FPM pool.
The Configuration chapter in the reference guide describes how this works in practice.
Blackfire environments are a great way to collaborate on profiling activities. They give you a lot of flexibility in terms of configuration and access management.
We have mentioned assertions and scenarios multiple times in this chapter. Now that you have access to these features via the Premium trial, it is time to go beyond profiling. Blackfire is much more than a profiler, and the next chapter will continue our journey with Blackfire assertions.