PQL available_history() function

available_history() — Returns raw, unbucketed history samples only when raw history values are available for a given node.

Syntax

The available_history() function returns a tree, and takes a tree parameter. It can take 2 optional string parameters:

tree available_history(tree input[,string input[,string input]])

Return value

The available_history() function produces raw, unbucketed history samples only when raw history values are available for a given node.

Description

The available_history() function is identical to the raw_history() function, except that it returns results only when raw history values are available for a given node.

The available_history() function takes a named parameter LIMIT, which expects an integer. This limits how many history elements are returned within the given time range.

You can determine whether the result list the raw history values backwards or forwards in time, by manipulating the from and from parameters. To list the results forward, specify a to time that is more recent than the from time. To list the results backward, specify a from time that is more recent than the to time.

Examples

Example 1: Find raw dhcpd.conf history

To compare available_history() with raw_history(), let's examine the following query.

Query: Find the raw history for file # 4164365.

SELECT raw_history(content) 
FROM /network/device/config_files/config_file 
WHERE /#id = 4164365

Results: This query returns all of the versions of this rather lengthy dhcpd.conf file, which results in thousands of lines of output that are not necessarily useful:

row
  raw_history(content)
    history
       when: 2008-05-01T19:57:34.433031Z
       value: # /etc/nsswitch.conf
#
# Example configuration of GNU Name Service Switch 
# functionality. If you have the `glibc-doc-reference' 
# and `info' packages installed, try:
# `info libc \"Name Service Switch\"' for information 
# about this file.

passwd: compat
group: compat
shadow: compat

hosts: files dns
networks: files
. . .

Now let's look at the equivalent using available_history().

Example 2: Find available dhcpd.conf history

If you substitute available_history() in the same query used in Example 1, the query returns only the times that this file changed. You can then examine the contents of the file each time it underwent a change.

Query: Find available history for this file.

SELECT available_history(content) 
FROM /network/device/config_files/config_file 
WHERE /#id = 4164365

Results: In these two queries, the raw_history() function returns both the timestamp and the content. The available_history() function returns just the timestamp, which has a much smaller size, and produces more relevant information:

row
  available_history(content)
    history
       when: 2008-05-01T19:57:34.433031Z
row
  available_history(content)
    history
       when: 2008-05-01T19:57:34.433031Z
row
  available_history(content)
    history
       when: 2008-05-01T19:57:34.433031Z
       . . .

Example 3: Find raw disk space history

To make another comparison, this example searches for the raw history of free disk space on each system.

Query: Show me the raw history of disk space on each system.

SELECT raw_history(systemname) 
FROM %free disk space% 
WHERE description = 'Local Fixed Disk'

Results: Depending on the database, this query returns results similar to this:

row
  raw_history(systemname)
    history
       when: 2008-05-06T22:04:59.303326Z
       value: ENGLAP032
row
  raw_history(systemname)
    history
       when: 2008-05-06T21:54:54.207658Z
       value: ENGLAP036
row
  raw_history(systemname)
    history
       when: 2008-05-05T22:04:26.795989Z
       value: ENGLAP033
    . . .

Example 4: Find available disk space history

This example searches for the available history of free disk space on each system.

Query: Show me the available history of disk space on each system.

SELECT available_history(systemname) 
FROM %free disk space% 
WHERE description = 'Local Fixed Disk'