-
Notifications
You must be signed in to change notification settings - Fork 43
PHP extension
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.
See here: Pinba extension installation.
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 (*).
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.
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 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.
Before version 1.1.0 this value could not be modified using ini_set() function, but this is not true anymore.
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):
- <IP-address> or <hostname>
192.0.32.10 2001:db8::c0:ffee example.com
- <IPv4-address>:<port number> or <host name>:<port number>
192.0.32.10:30002 example.com:30002
- [<IP-address>]:<port number> or [<host]:<port number>
[192.0.32.10]:30002 [2001:db8::c0:ffee]:30002 [example.com]:30002
"pinba.auto_flush" is used to prevent Pinba from sending stats packet at the end of the request.
This option is On by default.
Available since version 1.2.0.
resource pinba_timer_start(array tags[, array data])
Since version 1.2.0:
resource pinba_timer_start(array tags[[, array data], int hit_count])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.
hit_count - optional hit_count parameter, set to 1 be default. Available since version 1.2.0.
Return values:
Always returns new timer resource.
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).
resource pinba_timer_add(array tags, int value[, array data])Creates new timer. This timer is already stopped and have specified time value.
Parameters:
tags - an array of tags and their values in the form of "tag" => "value". Cannot contain numeric indexes for obvious reasons.
value - timer value for new timer.
data - optional array with user data, not sent to the server.
Return values:
Always returns new timer resource.
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.
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.
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.
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.
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.
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
}
bool pinba_timers_stop(void)Stops all running timers.
array pinba_timers_get([int flag = 0])Get all timers.
Parameters:
flag - can be set to PINBA_ONLY_STOPPED_TIMERS
Available since: 1.1.0
bool pinba_hostname_set(string hostname)Set custom hostname instead of the result of gethostname() used by default.
bool pinba_request_time_set(float request_time)Set custom request time.
bool pinba_schema_set(string schema)Set request schema (HTTP/HTTPS/whatever).
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.
bool pinba_server_name_set(string server_name)Set custom server name instead of $_SERVER['SERVER_NAME'] used by default.
bool pinba_tag_set(string tag, string value)Set/update request tag.
string|false pinba_tag_get(string tag)Get previously set request tag value. False for non-existing tags.
bool pinba_tag_delete(string tag)Delete previously set request tag.
array pinba_tags_get()Return an array of all previously set request tags.
string pinba_get_data()Returns the raw packet data.
Available since: 1.1.0
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
}
}
}
void pinba_flush([string script_name][, int flags = 0])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.
flags is an optional argument added in version 1.0.0.
Possible values (it's a bitmask, so you can add the constants):
- PINBA_FLUSH_ONLY_STOPPED_TIMERS - flush only stopped timers (by default all existing timers are stopped and flushed) - available since v. 1.0.0.
- PINBA_FLUSH_RESET_DATA - reset common request data - available since version 1.1.0.
void pinba_reset()Reset common request data.
Available since: 1.1.1
PinbaClient class provides simple interface that allows you to construct arbitrary Pinba data packets in PHP.
PinbaClient PinbaClient::__construct(array servers[, int flags])
Creates and returns new PinbaClient object.
Parameters:
servers - array of strings of hostnames, 'hostname:port' strings or IPv6 hostnames.
flags - optional flags, bitmask.
Possible flags:
- PINBA_FLUSH_ONLY_STOPPED_TIMERS - flush only stopped timers
- PINBA_AUTO_FLUSH - send data automatically when the object is destroyed
bool PinbaClient::setHostname(string hostname)
Set hostname field in the data packet.
bool PinbaClient::setServername(string server_name)
Set server_name field in the data packet.
bool PinbaClient::setScriptname(string script_name)
Set script_name field in the data packet.
bool PinbaClient::setSchema(string schema)
Set schema field in the data packet.
bool PinbaClient::setRequestCount(int request_count)
Set req_count field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setMemoryFootprint(int memory_footprint)
Set memory_footprint field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setMemoryPeak(int memory_peak)
Set memory_peak field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setDocumentSize(int document_size)
Set document_size field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setStatus(int status)
Set status field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setRequestTime(float request_time)
Set request_time field in the data packet. Provided value cannot be less than zero.
bool PinbaClient::setRusage(array rusage)
Set rusage values. This method accepts an array of exactly two numeric values in the following order:
- ru_utime
- ru_stime
bool PinbaClient::setTag(string name, string value)
Set request tag.
Parameters:
name - name of the request tag
value - its value
bool PinbaClient::setTimer(array tags, float value[, array rusage[, int hit_count]])
Creates new timer. If there is a timer with the same tags, it's replaced with the newly created one.
Parameters:
tags - hash of strings with string indexes, which are used as tag names
value - timer value, seconds
rusage - array of two numeric items: ru_utime and ru_stime
hit_count - timer hit count
bool PinbaClient::addTimer(array tags, float value[, array rusage[, int hit_count]])
Updates existing timer or creates a new one. If there is a timer with the same tags, we add it and store the sum of the new and the old timers.
Parameters:
tags - hash of strings with string indexes, which are used as tag names
value - timer value, seconds
rusage - array of two numeric items: ru_utime and ru_stime
hit_count - timer hit count
bool PinbaClient::send([int flags])
Send the data to the server(s).
Parameters:
flags - optional flags, bitmask. Override object flags if specified.
Possible flags:
- PINBA_FLUSH_ONLY_STOPPED_TIMERS - flush only stopped timers
string PinbaClient::getData([int flags])
Returns raw packet data. This is basically a copy of send(), but instead of sending it just returns the data.