Manual:PHP extension

From Pinba.org

The extension is needed to gather and send statistics data and also to manage timers.
At the request time the extension records time and resource usage and at the request shutdown it computes the difference.
After that the extension creates a protobuf packet and sends it to the server by UDP.

Contents 1 Installation 2 Introduction 3 INI Directives 3.1 pinba.enabled 3.2 pinba.server 4 PHP API 4.1 pinba_timer_start() 4.2 pinba_timer_stop() 4.3 pinba_timer_delete() 4.4 pinba_timer_tags_merge() 4.5 pinba_timer_tags_replace() 4.6 pinba_timer_data_merge() 4.7 pinba_timer_data_replace() 4.8 pinba_timer_get_info() 4.9 pinba_timers_stop() 4.10 pinba_get_info() 4.11 pinba_script_name_set() 4.12 pinba_hostname_set() 4.13 pinba_flush()

Installation

See here: Pinba extension installation.

Introduction

Before starting to describe the API we need to explain several basic things about Pinba.
There are several basic design objects you need to understand:

• request - contains all request data (such as script_name, time taken, hostname, servername etc.)
• timer - user can set marks to measure time it takes to execute some parts of the code. This is done using timers. Each request might have an unlimited number of timers (*).
• tag - tags and their values are used to describe timers, so that you could group them afterwards. Each timer might have an unlimited number of tags (*).

Note:
The resulting protobuf packet still has to fit into UDP packet, so there is a limit.

Example:

Say you have a script that connects to the database and performs several queries.
Each SQL operation might use at least two tags:

• group => sql
• operation => insert/select/update etc.

This way you can easily group them by both tags.

INI Directives

pinba.enabled

pinba.enabled enables or disables sending request data to the server.
Can be modified using ini_set() function (PHP_INI_ALL).
Default value: 0, i.e. Pinba extension is disabled by default.

pinba.server

pinba.server is a string specifying IP address and port of Pinba server.
You can use this directive in the two ways:

AAA.BBB.CCC.DDD

or

AAA.BBB.CCC.DDD:XXXX

where "AAA.BBB.CCC.DDD" is IP address and "XXXX" is port number.
Can not be modified using ini_set() function (PHP_INI_SYSTEM|PHP_INI_PERDIR).
The default port value is 30002 (UDP).

Since April 2010 support for IPv6, host names and service names has been added to the Pinba extension. Since IPv6 addresses contain colons, it is not possible to use the above syntax to specify IPv6 addresses with a port number or service name. To work around that problem, the syntax known from the Apache webserver has been implemented, using square brackets to delimit IPv6 addresses.

The following are possible ways to configure the recipient of the UDP packets (since April 2010):

Schema	Example	Explanation
<IP-address> <host name>	192.0.32.10 2001:db8::c0:ffee example.com	A simple IPv4 or IPv6 address or a hostname.
<IPv4-address> ":" <port number> <host name> ":" <port number>	192.0.32.10:30002 example.com:30002	An IPv4-address or a hostname, followed by a colon and a port number. Since IPv6 addresses contain colons it is not possible to use this simple syntax to specify IPv6 addresses with a port number.
"[" <IP-address> "]:" <port number> "[" <host name> "]:" <port number>	[192.0.32.10]:30002 [2001:db8::c0:ffee]:30002 [example.com]:30002	An IP-address or a hostname, enclosed in square brackets, followed by a colon and a port number.

PHP API

pinba_timer_start()

resource pinba_timer_start(array tags[, array data])

Creates and starts new timer.

Parameters:
tags - an array of tags and their values in the form of "tag" => "value". Cannot contain numeric indexes for obvious reasons.
data - optional array with user data, not sent to the server.

Return values:
Always returns new timer resource.

pinba_timer_stop()

bool pinba_timer_stop(resource timer)

Stops the timer.

Parameters:
timer - valid timer resource.

Return values:
Returns true on success and false on failure (if the timer has already been stopped).

pinba_timer_delete()

bool pinba_timer_delete(resource timer)

Deletes the timer.

Available since: 0.0.6

Parameters:
timer - valid timer resource.

Return values:
Returns true on success and false on failure.

pinba_timer_tags_merge()

bool pinba_timer_tags_merge(resource timer, array tags)

Merges $tags array with the timer tags replacing existing elements.

Parameters:
timer - valid timer resource
tags - an array of tags.

pinba_timer_tags_replace()

bool pinba_timer_tags_replace(resource timer, array tags)

Replaces timer tags with the passed $tags array.

Parameters:
timer - valid timer resource
tags - an array of tags.

pinba_timer_data_merge()

bool pinba_timer_data_merge(resource timer, array data)

Merges $data array with the timer user data replacing existing elements.

Parameters:
timer - valid timer resource
data - an array of user data.

Return values:
Returns true on success and false on failure.

pinba_timer_data_replace()

bool pinba_timer_data_replace(resource timer, array data)

Replaces timer user data with the passed $data array.
Use NULL value to reset user data in the timer.

Parameters:
timer - valid timer resource
data - an array of user data.

pinba_timer_get_info()

array pinba_timer_get_info(resource timer)

Returns timer data.

Parameters:
timer - valid timer resource.

Output example:

array(4) {
  ["value"]=>
  float(0.0213)
  ["tags"]=>
  array(1) {
    ["foo"]=>
    string(3) "bar"
  }
  ["started"]=>
  bool(true)
  ["data"]=>
  NULL
}

pinba_timers_stop()

bool pinba_timers_stop(void)

Stops all running timers.

pinba_get_info()

array pinba_get_info(void)

Returns all request data (including timers user data). Example:

array(9) {
  ["mem_peak_usage"]=>
  int(786432)
  ["req_time"]=>
  float(0.001529)
  ["ru_utime"]=>
  float(0)
  ["ru_stime"]=>
  float(0)
  ["req_count"]=>
  int(1)
  ["doc_size"]=>
  int(0)
  ["server_name"]=>
  string(7) "unknown"
  ["script_name"]=>
  string(1) "-"
  ["timers"]=>
  array(1) {
    [0]=>
    array(4) {
      ["value"]=>
      float(4.5E-5)
      ["tags"]=>
      array(1) {
        ["foo"]=>
       string(3) "bar"
      }
      ["started"]=>
      bool(true)
      ["data"]=>
      NULL
    }
  }
}

pinba_script_name_set()

bool pinba_script_name_set(string script_name)

Set custom script name instead of $_SERVER['SCRIPT_NAME'] used by default.
Useful for those using front controllers, when all requests are served by one PHP script.

pinba_hostname_set()

bool pinba_hostname_set(string hostname)

Set custom hostname instead of the result of gethostname() used by default.

pinba_flush()

void pinba_flush([string script_name])

Useful when you need to send request data to the server immediately (for long running scripts).
You can use optional argument script_name to set custom script name.