'\"macro stdmacro
.\"
.\" Copyright (c) 2019 Red Hat.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMDABPFTRACE 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdabpftrace\f1 \- bpftrace PMDA
.SH DESCRIPTION
\f3pmdabpftrace\f1 is a Performance Co-Pilot (PCP) Performance Metrics
Domain Agent (PMDA) which exports metrics from
.BR bpftrace (8)
scripts.
.SH CONFIGURATION
\f3pmdabpftrace\f1 reads an optional ini-style configuration file:
.IP
.PD 0
.IP
.I \f(CW$PCP_PMDAS_DIR\fP/bpftrace/bpftrace.conf
.PD
.PP
This file may contain \fB[bpftrace]\fP and \fB[dynamic_scripts]\fP
sections.
If you enable the \fBdynamic scripts\fP functionality, please refer to
.B https://pcp.io/docs/lab.auth.html
on how to setup authentication. This is \fBhighly recommended\fP,
as otherwise anyone could run any
.BR bpftrace (8)
script as
.BR root .
.PP
.B [bpftrace]
section specifies values for the following settings
(their default values are shown in parenthesis):
.TP 15
.B bpftrace_path \fR(\fP\fIbpftrace\fP\fR)\fP
Path to the
.BR bpftrace (8)
executable.
.TP
.B script_expiry_time \fR(\fP\fI60\fP\fR)\fP
Unnamed scripts are removed after this period of time (in seconds)
in case there has been no requests for their values.
.TP
.B max_throughput \fR(\fP\fI2097152\fP\fR)\fP
Maximum throughput of bpftrace scripts in bytes.
.PP
.B [dynamic_scripts]
section specifies values for the following settings
(their default values are shown in parenthesis):
.TP 15
.B enabled \fR(\fP\fIfalse\fP\fR)\fP
A boolean value to specify whether script should be started on demand,
by executing pmStore (3) bpftrace.control.register.
This feature needs to be enabled for the PCP bpftrace datasource in grafana-pcp.
.TP
.B auth_enabled \fR(\fP\fItrue\fP\fR)\fP
A boolean value to specify whether authentication is required or not.
Please see the note above on authentication setup.
.TP
.B allowed_users \fR(\fP\fIroot\fP\fR)\fP
A comma-separated list of usernames which are allowed to register
.BR bpftrace (8)
scripts.
.SH INSTALLATION
To install, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bpftrace
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/bpftrace
# ./Remove
.fi
.ft P
.RE
.sp 1
\fBpmdabpftrace\fP is launched by \fBpmcd\fP(1) and should never be
executed directly.
The \fBInstall\fP and \fBRemove\fP scripts notify \fBpmcd\fP(1) when
the agent is installed or removed.
.SH FILES
.TP 5
.I \f(CW$PCP_PMDAS_DIR\fP/bpftrace/bpftrace.conf
configuration file for the \fBpmdabpftrace\fR agent
.TP
.I \f(CW$PCP_PMDAS_DIR\fP/bpftrace/Install
installation script for the \fBpmdabpftrace\fR agent
.TP
.I \f(CW$PCP_PMDAS_DIR\fP/bpftrace/Remove
undo installation script for the \fBpmdabpftrace\fR agent
.TP
.I \f(CW$PCP_LOG_DIR\fP/pmcd/bpftrace.log
default log file for messages from the \fBpmdabpftrace\fR agent
.PP
Note that the usual/default value for \fB$PCP_PMDAS_DIR\fP is
.B /var/lib/pcp/pmdas
and the default for \fB$PCP_LOG_DIR\fP is
.B /var/log/pcp
but these settings are platform dependent.
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fR variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fR(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1)
and
.BR bpftrace (8).