From 991a67d45368c331be13ba9414ec9e626c801577 Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Sun, 4 Oct 2020 01:49:09 +0200
Subject: [PATCH] nixos/blackfire: init

---
 nixos/modules/module-list.nix                 |  1 +
 .../services/development/blackfire.nix        | 65 +++++++++++++++++++
 .../services/development/blackfire.xml        | 45 +++++++++++++
 3 files changed, 111 insertions(+)
 create mode 100644 nixos/modules/services/development/blackfire.nix
 create mode 100644 nixos/modules/services/development/blackfire.xml

diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index 76263a321383..77f8d27d8592 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -331,6 +331,7 @@
   ./services/desktops/tumbler.nix
   ./services/desktops/zeitgeist.nix
   ./services/development/bloop.nix
+  ./services/development/blackfire.nix
   ./services/development/hoogle.nix
   ./services/development/jupyter/default.nix
   ./services/development/jupyterhub/default.nix
diff --git a/nixos/modules/services/development/blackfire.nix b/nixos/modules/services/development/blackfire.nix
new file mode 100644
index 000000000000..6fd948cce38d
--- /dev/null
+++ b/nixos/modules/services/development/blackfire.nix
@@ -0,0 +1,65 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.services.blackfire-agent;
+
+  agentConfigFile = lib.generators.toINI {} {
+    blackfire =  cfg.settings;
+  };
+
+  agentSock = "blackfire/agent.sock";
+in {
+  meta = {
+    maintainers = pkgs.blackfire.meta.maintainers;
+    doc = ./blackfire.xml;
+  };
+
+  options = {
+    services.blackfire-agent = {
+      enable = lib.mkEnableOption "Blackfire profiler agent";
+      settings = lib.mkOption {
+        description = ''
+          See https://blackfire.io/docs/configuration/agent
+        '';
+        type = lib.types.submodule {
+          freeformType = with lib.types; attrsOf str;
+
+          options = {
+            server-id = lib.mkOption {
+              type = lib.types.str;
+              description = ''
+                Sets the server id used to authenticate with Blackfire
+
+                You can find your personal server-id at https://blackfire.io/my/settings/credentials
+              '';
+            };
+
+            server-token = lib.mkOption {
+              type = lib.types.str;
+              description = ''
+                Sets the server token used to authenticate with Blackfire
+
+                You can find your personal server-token at https://blackfire.io/my/settings/credentials
+              '';
+            };
+          };
+        };
+      };
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    environment.etc."blackfire/agent".text = agentConfigFile;
+
+    services.blackfire-agent.settings.socket = "unix:///run/${agentSock}";
+
+    systemd.services.blackfire-agent = {
+      description = "Blackfire agent";
+
+      serviceConfig = {
+        ExecStart = "${pkgs.blackfire}/bin/blackfire-agent";
+        RuntimeDirectory = "blackfire";
+      };
+    };
+  };
+}
diff --git a/nixos/modules/services/development/blackfire.xml b/nixos/modules/services/development/blackfire.xml
new file mode 100644
index 000000000000..ad4af35788db
--- /dev/null
+++ b/nixos/modules/services/development/blackfire.xml
@@ -0,0 +1,45 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="module-services-blackfire">
+ <title>Blackfire profiler</title>
+ <para>
+  <emphasis>Source:</emphasis>
+  <filename>modules/services/development/blackfire.nix</filename>
+ </para>
+ <para>
+  <emphasis>Upstream documentation:</emphasis>
+  <link xlink:href="https://blackfire.io/docs/introduction"/>
+ </para>
+ <para>
+  <link xlink:href="https://blackfire.io">Blackfire</link> 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 <firstterm>probe</firstterm>) and a service (<firstterm>agent</firstterm>) that the probe connects to and that sends the profiles to the server.
+ </para>
+ <para>
+  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:
+<programlisting>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/configuration/agent
+      server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
+      server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
+    };
+  };
+
+  # Make the agent run on start-up.
+  # Alternately, you can start it manually with `systemctl start blackfire-agent`.
+  systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ];
+}</programlisting>
+ </para>
+ <para>
+  On your developer machine, you will also want to install <link xlink:href="https://blackfire.io/docs/up-and-running/installation#install-a-profiling-client">the client</link> (see <package>blackfire</package> package) or the browser extension to actually trigger the profiling.
+ </para>
+</chapter>