pg_reporter

名前
概要
説明
使用例
オプション
環境変数
設定ファイル
使用上の注意と制約
詳細
インストール方法
動作環境
関連項目
謝辞

名前

pg_reporter -- PostgreSQLに格納した任意のデータを使って HTML レポートを作成します。

概要

pg_reporter [OPTIONS] [TEMPLATE]

テンプレート TEMPLATE を使って PostgreSQL に格納したデータからレポートを作成します。 pg_repoter には以下の動作モードがあります。詳細は説明を参照してください。

動作モード	概要
初期化モード	CGIモードとhttpdモードで使用するレポート用ディレクトリを初期化
コマンドラインモード	パラメータを直接指定してレポートを作成
CGIモード	レポート作成 CGI として動作
httpdモード	レポート作成 http サーバとして動作

作成できるレポートのサンプルを示します。

説明

pg_reporter は PostgreSQL 用の汎用レポート作成ツールです。ユーザは自由にテンプレートを作成でき、そのテンプレートを元にレポートが出力されます。レポートを作成するには SQL と HTML の知識だけが必要です。

添付のテンプレートを使うと、pg_statsinfo で収集した情報を元にHTML形式のレポートを作成できます。特に CGI モードと HTTPD モードでは、スナップショットの一覧からのナビゲーションもサポートしており、マウスを数クリックするだけでグラフィカルな性能レポートを閲覧できます。

使用例

カレントディレクトリの htdocs を、レポート用ディレクトリとして初期化します。

$ pg_reporter --init=./htdocs

httpdモードで起動します。

$ pg_reporter -D ./htdocs

ブラウザからローカルホストの8080番ポートにアクセスします。

http://localhost:8080/

httpdモードは以下の形式のURLを受け付けます。

http://host/id/template-name?parameters

host : pg_reporter が動作しているホスト
id : データベース接続情報として登録されたID
template-name : レポート作成に使用するテンプレートファイルの拡張子を除いた名称
parameters : "キーワード=値&..." 形式のパラメータ

一方、コマンドラインから直接レポートを作成する場合には、必要な情報をオプションとして指定します。下記の例では、stats というデータベースに接続し、テンプレート details.xml を使い、出力ファイル details.html へレポーを作成しています。

$ pg_reporter -d stats -t details.xml -o details.html -a "begin=1&end=10"

オプション

pg_reporter では、下記のコマンドライン引数を指定できます。

初期化モード・オプション

-i DIR --init=DIR: 初期化を行うディレクトリのパス

コマンドラインモード・オプション

-t TEMPLATE --template=TEMPLATE: レポート作成に使用するテンプレートファイルのパス
-o OUTPUT --output=OUTPUT: 作成したレポートの出力先。デフォルトは標準出力。
-s XSLT --stylesheet=XSLT: レポート作成に使用するXSLTファイルのパス
-a "key1=value1&key2=value2&..." --arg="key1=value1&key2=value2&...": テンプレート内のSQLへ渡されるパラメータのリスト

httpdモード・オプション

-D DIR --httpd-dir=DIR: メインのドキュメントツリーになるディレクトリ
-P PORT --httpd-port=PORT: 接続ポート (デフォルト: 8080)
-L ADDRESS --httpd-listen=ADDRESS: 接続監視アドレス (デフォルト: localhost)。制限をかけない場合は '*' を指定

接続オプション

PostgreSQLに接続するためのパラメータです。

-d DBNAME --dbname=DBNAME: オンライン CLUSTER、または、オンライン VACUUM FULL を行うデータベース名を指定します。データベース名が指定されておらず、-a（または--all）も指定されていない場合、データベース名はPGDATABASE環境変数から読み取られます。この変数も設定されていない場合は、接続時に指定したユーザ名が使用されます。
-h HOSTNAME --host=HOSTNAME: サーバが稼働しているマシンのホスト名を指定します。ホスト名がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
-p PORT --port=PORT: サーバが接続を監視するTCPポートもしくはUnixドメインソケットファイルの拡張子を指定します。
-U USERNAME --username=USERNAME: 接続するユーザ名を指定します。
-W --password: データベースに接続する前に、強制的にパスワード入力を促します。サーバがパスワード認証を要求する場合自動的にパスワード入力を促しますので、これが重要になることはありません。しかし、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。こうした余計な接続試行を防ぐために -W の入力が有意となる場合もあります。

一般オプション

-e --echo: サーバに送信するSQLを表示します。
-E --elevel: ログ出力レベルを設定します。 DEBUG, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, PANIC から選択します。デフォルトは INFO です。
--help: 使用方法について表示します。
--version: バージョン情報を表示します。

環境変数

PGDATABASE PGHOST PGPORT PGUSER: デフォルトの接続パラメータです。

また、このユーティリティは、他のほとんどの PostgreSQL ユーティリティと同様、libpq でサポートされる環境変数を使用します。詳細については、環境変数の項目を参照してください。

設定ファイル

データベース接続情報は .dbnames で指定します。

書式
- id host port database username [password]
パラメータ詳細
- id
  - URLに指定されたときに本ファイルから接続情報を検索するために付与する名称。
  - 指定可能文字は、半角英数字です。
- host
  - 接続するデータベースが動作しているマシンのホストの名称。
- port
  - データベースへ接続するために使用するポート番号。
- database
  - 接続するデータベースの名称。
- usernname
  - データベース接続に使用するデータベースユーザ名。
- password
  - データベース接続時の認証で使用されるパスワード。
  - パスワードなしで接続できる場合は省略可能です。

記述例

DB001	db1.example.com	5432	postgres	postgres	postgres
DB002	db2.example.com	5432	stats		postgres	postgres

備考
- 1行につき1つのレコードという形式で記述できます。1つのレコードは行をまたいで記述できません。
- # から行末までをコメントとみなします。 # は、任意の位置から記述可能です。
- パラメータの区切りは、スペースもしくはタブ、もしくはその両方が指定可能です。
- 同一のidが複数指定されていた場合は、最初に検索した情報を使用します。

使用上の注意と制約

pg_reporter を使用する際には、以下の使用上の注意と制約があります。

httpdモードは簡易的な実装であり、十分にテストされていません。: 高い負荷には耐えられず、セキュリティの面でも LAN での利用に限ってください。
CGIモードでは、レポート用ディレクトリとHTTP ServerのDOCUMENT_ROOTの一致が必要です。: サブディレクトリには配置することができません。

詳細

全体構成

以下は pg_reporter のシステム図です。シングルスレッドで動作します。

ディレクトリ構成

初期化モードで作成されるレポート用ディレクトリの構成を以下に示します。

css : カスケード・スタイルシート格納ディレクトリ
files : 一般ファイル用ディレクトリ
js : JavaScript格納ディレクトリ
template : テンプレートファイル格納ディレクトリ
xsl : XSLスタイルシート格納ディレクトリ
.dbnames : データベース接続情報ファイル

動作モード選択

動作モードは以下の基準で選ばれます。

動作モード	必要オプション
初期化モード	--init オプション
コマンドラインモード	テンプレートファイル指定または--templateオプション
CGIモード	オプション指定無し
httpdモード	--httpd-dir オプション

インストール方法

ビルド

pg_reporter のインストールは、標準のcontribモジュールと同様です。 pgxs を使ってビルドできます。

$ cd pg_reporter
$ make USE_PGXS=1
$ make USE_PGXS=1 install

データベースへの登録

pg_reporter に付属するレポート・テンプレートは pg_statsinfo のレポジトリを表示させるためのものです。前もって pg_statsinfo のレポジトリを初期化してください。スキーマ情報表示のみであれば、特にデータベースへの登録作業は必要ありません。

Apache HTTP Server の設定

この操作は、CGIモードを使用しない場合は不要です。まず、Apache HTTP Server のインストールを行います。

# rpm -ivh httpd-2.2.11-1.x86_64.rpm

次に、Apache HTTP Serverの設定ファイルに以下を追加します。

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^/files$ /report [R,L,QSA]
  RewriteRule ^/([0-9A-Za-z]+)/([^\./]+)$ \
              /cgi-bin/pg_reporter?id=$1&template=$2 [R,L,QSA]
</IfModule>
<Directory "/var/www/html/report">
  Options Indexes
</Directory>

Apache HTTP ServerのCGI格納ディレクトリにpg_reporterを格納します。そして、レポート用ディレクトリを初期化します。

$ cp $PGHOME/bin/pg_reporter /var/www/cgi-bin/
$ pg_reporter -i /var/www/html

データベース接続情報ファイルを記述します

$ vi /var/www/html/.dbnames

Apache HTTP Server を起動します

# service httpd start

動作環境

PostgreSQLバージョン: PostgreSQL 8.4, 9.0
OS: RHEL 5.3, CentOS 5.3, Windows XP
HTTP Server: Apache HTTP Server 2.2
ブラウザ: Firefox 3.5, 3.6

謝辞

pg_reporterでは、Report の作成に「HTML5.JP - 次世代HTML標準 HTML5情報サイト(http://www.html5.jp/)」のJavaScriptライブラリを活用させていただいております。感謝いたします。

pg_reporter 1.0 Alpha 1

名前

概要

説明

使用例