From 296ffb4f1f2fe920e8cc37ed727283937cee8443 Mon Sep 17 00:00:00 2001 From: pennae Date: Tue, 3 Jan 2023 01:18:33 +0100 Subject: [PATCH] nixos/blackfire: convert manual chapter to MD --- .../modules/services/development/blackfire.md | 39 +++++++++++++ .../services/development/blackfire.nix | 2 + .../services/development/blackfire.xml | 57 +++++++++++-------- 3 files changed, 75 insertions(+), 23 deletions(-) create mode 100644 nixos/modules/services/development/blackfire.md diff --git a/nixos/modules/services/development/blackfire.md b/nixos/modules/services/development/blackfire.md new file mode 100644 index 000000000000..e2e7e4780c79 --- /dev/null +++ b/nixos/modules/services/development/blackfire.md @@ -0,0 +1,39 @@ +# Blackfire profiler {#module-services-blackfire} + +*Source:* {file}`modules/services/development/blackfire.nix` + +*Upstream documentation:* + +[Blackfire](https://blackfire.io) is a proprietary tool for profiling applications. There are several languages supported by the product but currently only PHP support is packaged in Nixpkgs. The back-end consists of a module that is loaded into the language runtime (called *probe*) and a service (*agent*) that the probe connects to and that sends the profiles to the server. + +To use it, you will need to enable the agent and the probe on your server. The exact method will depend on the way you use PHP but here is an example of NixOS configuration for PHP-FPM: +``` +let + php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [ + blackfire + ])); +in { + # Enable the probe extension for PHP-FPM. + services.phpfpm = { + phpPackage = php; + }; + + # Enable and configure the agent. + services.blackfire-agent = { + enable = true; + settings = { + # You will need to get credentials at https://blackfire.io/my/settings/credentials + # You can also use other options described in https://blackfire.io/docs/up-and-running/configuration/agent + server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; + server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; + }; + }; + + # Make the agent run on start-up. + # (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138) + # Alternately, you can start it manually with `systemctl start blackfire-agent`. + systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ]; +} +``` + +On your developer machine, you will also want to install [the client](https://blackfire.io/docs/up-and-running/installation#install-a-profiling-client) (see `blackfire` package) or the browser extension to actually trigger the profiling. diff --git a/nixos/modules/services/development/blackfire.nix b/nixos/modules/services/development/blackfire.nix index 054cef9ae80b..7d3365efa84d 100644 --- a/nixos/modules/services/development/blackfire.nix +++ b/nixos/modules/services/development/blackfire.nix @@ -11,6 +11,8 @@ let in { meta = { maintainers = pkgs.blackfire.meta.maintainers; + # Don't edit the docbook xml directly, edit the md and generate it: + # `pandoc blackfire.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > blackfire.xml` doc = ./blackfire.xml; }; diff --git a/nixos/modules/services/development/blackfire.xml b/nixos/modules/services/development/blackfire.xml index 182ff6dafde0..f5e622186329 100644 --- a/nixos/modules/services/development/blackfire.xml +++ b/nixos/modules/services/development/blackfire.xml @@ -1,19 +1,28 @@ - - Blackfire profiler - - Source: - modules/services/development/blackfire.nix - - - Upstream documentation: - - - - Blackfire is a proprietary tool for profiling applications. There are several languages supported by the product but currently only PHP support is packaged in Nixpkgs. The back-end consists of a module that is loaded into the language runtime (called probe) and a service (agent) that the probe connects to and that sends the profiles to the server. - - - To use it, you will need to enable the agent and the probe on your server. The exact method will depend on the way you use PHP but here is an example of NixOS configuration for PHP-FPM: - + + Blackfire profiler + + Source: + modules/services/development/blackfire.nix + + + Upstream documentation: + https://blackfire.io/docs/introduction + + + Blackfire is a + proprietary tool for profiling applications. There are several + languages supported by the product but currently only PHP support is + packaged in Nixpkgs. The back-end consists of a module that is + loaded into the language runtime (called probe) + and a service (agent) that the probe connects + to and that sends the profiles to the server. + + + To use it, you will need to enable the agent and the probe on your + server. The exact method will depend on the way you use PHP but here + is an example of NixOS configuration for PHP-FPM: + + let php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [ blackfire @@ -30,19 +39,21 @@ in { settings = { # You will need to get credentials at https://blackfire.io/my/settings/credentials # You can also use other options described in https://blackfire.io/docs/up-and-running/configuration/agent - server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; - server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; + server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; + server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; }; }; # Make the agent run on start-up. # (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138) # Alternately, you can start it manually with `systemctl start blackfire-agent`. - systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ]; + systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ]; } - - - On your developer machine, you will also want to install the client (see blackfire package) or the browser extension to actually trigger the profiling. - + + On your developer machine, you will also want to install + the + client (see blackfire package) or the + browser extension to actually trigger the profiling. +