pyrox.dev
lol
nixos/blackfire: convert manual chapter to MD
+75
-23
+39
nixos/modules/services/development/blackfire.md
+39
nixos/modules/services/development/blackfire.md
···
1
+
# Blackfire profiler {#module-services-blackfire}
2
+
3
+
*Source:* {file}`modules/services/development/blackfire.nix`
4
+
5
+
*Upstream documentation:* <https://blackfire.io/docs/introduction>
6
+
7
+
[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.
8
+
9
+
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:
10
+
```
11
+
let
12
+
php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [
13
+
blackfire
14
+
]));
15
+
in {
16
+
# Enable the probe extension for PHP-FPM.
17
+
services.phpfpm = {
18
+
phpPackage = php;
19
+
};
20
+
21
+
# Enable and configure the agent.
22
+
services.blackfire-agent = {
23
+
enable = true;
24
+
settings = {
25
+
# You will need to get credentials at https://blackfire.io/my/settings/credentials
26
+
# You can also use other options described in https://blackfire.io/docs/up-and-running/configuration/agent
27
+
server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
28
+
server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
29
+
};
30
+
};
31
+
32
+
# Make the agent run on start-up.
33
+
# (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138)
34
+
# Alternately, you can start it manually with `systemctl start blackfire-agent`.
35
+
systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ];
36
+
}
37
+
```
38
+
39
+
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.
+2
nixos/modules/services/development/blackfire.nix
+2
nixos/modules/services/development/blackfire.nix
···
11
11
in {
12
12
meta = {
13
13
maintainers = pkgs.blackfire.meta.maintainers;
14
+
# Don't edit the docbook xml directly, edit the md and generate it:
15
+
# `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`
14
16
doc = ./blackfire.xml;
15
17
};
16
18
+34
-23
nixos/modules/services/development/blackfire.xml
+34
-23
nixos/modules/services/development/blackfire.xml
···
1
-
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="module-services-blackfire">
2
-
<title>Blackfire profiler</title>
3
-
<para>
4
-
<emphasis>Source:</emphasis>
5
-
<filename>modules/services/development/blackfire.nix</filename>
6
-
</para>
7
-
<para>
8
-
<emphasis>Upstream documentation:</emphasis>
9
-
<link xlink:href="https://blackfire.io/docs/introduction"/>
10
-
</para>
11
-
<para>
12
-
<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 <emphasis>probe</emphasis>) and a service (<emphasis>agent</emphasis>) that the probe connects to and that sends the profiles to the server.
13
-
</para>
14
-
<para>
15
-
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:
16
-
<programlisting>
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-blackfire">
2
+
<title>Blackfire profiler</title>
3
+
<para>
4
+
<emphasis>Source:</emphasis>
5
+
<filename>modules/services/development/blackfire.nix</filename>
6
+
</para>
7
+
<para>
8
+
<emphasis>Upstream documentation:</emphasis>
9
+
<link xlink:href="https://blackfire.io/docs/introduction" role="uri">https://blackfire.io/docs/introduction</link>
10
+
</para>
11
+
<para>
12
+
<link xlink:href="https://blackfire.io">Blackfire</link> is a
13
+
proprietary tool for profiling applications. There are several
14
+
languages supported by the product but currently only PHP support is
15
+
packaged in Nixpkgs. The back-end consists of a module that is
16
+
loaded into the language runtime (called <emphasis>probe</emphasis>)
17
+
and a service (<emphasis>agent</emphasis>) that the probe connects
18
+
to and that sends the profiles to the server.
19
+
</para>
20
+
<para>
21
+
To use it, you will need to enable the agent and the probe on your
22
+
server. The exact method will depend on the way you use PHP but here
23
+
is an example of NixOS configuration for PHP-FPM:
24
+
</para>
25
+
<programlisting>
17
26
let
18
27
php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [
19
28
blackfire
···
30
39
settings = {
31
40
# You will need to get credentials at https://blackfire.io/my/settings/credentials
32
41
# You can also use other options described in https://blackfire.io/docs/up-and-running/configuration/agent
33
-
server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
34
-
server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
42
+
server-id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
43
+
server-token = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
35
44
};
36
45
};
37
46
38
47
# Make the agent run on start-up.
39
48
# (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138)
40
49
# Alternately, you can start it manually with `systemctl start blackfire-agent`.
41
-
systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ];
50
+
systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ];
42
51
}
43
52
</programlisting>
44
-
</para>
45
-
<para>
46
-
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 <literal>blackfire</literal> package) or the browser extension to actually trigger the profiling.
47
-
</para>
53
+
<para>
54
+
On your developer machine, you will also want to install
55
+
<link xlink:href="https://blackfire.io/docs/up-and-running/installation#install-a-profiling-client">the
56
+
client</link> (see <literal>blackfire</literal> package) or the
57
+
browser extension to actually trigger the profiling.
58
+
</para>
48
59
</chapter>