Add support for an application_name parameter, which is displayed in

pg_stat_activity and recorded in log entries.

Dave Page, reviewed by Andres Freund

3 files changed, 118 insertions, 41 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 2cb006fa75..d5f55e0539 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.234 2009/11/28 16:21:31 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.235 2009/11/28 23:38:06 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -2882,6 +2882,26 @@ local0.*    /var/log/postgresql
 
      <variablelist>
 
+     <varlistentry id="guc-application-name" xreflabel="application_name">
+      <term><varname>application_name</varname> (<type>string</type>)</term>
+      <indexterm>
+       <primary><varname>application_name</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        The <varname>application_name</varname> can be any string of less than
+        <symbol>NAMEDATALEN</> characters (64 characters in a standard build).
+        It is typically set by an application upon connection to the server.
+        The name will be displayed in the <structname>pg_stat_activity</> view
+        and included in CSV log entries.  It can also be included in regular
+        log entries via the <xref linkend="guc-log-line-prefix"> parameter.
+        Only printable ASCII characters may be used in the
+        <varname>application_name</varname> value. Other characters will be
+        replaced with question marks (<literal>?</literal>).
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><varname>debug_print_parse</varname> (<type>boolean</type>)</term>
       <term><varname>debug_print_rewritten</varname> (<type>boolean</type>)</term>
@@ -3049,7 +3069,7 @@ local0.*    /var/log/postgresql
          that are replaced with status information as outlined below.
          Unrecognized escapes are ignored. Other
          characters are copied straight to the log line. Some escapes are
-         only recognized by session processes, and do not apply to
+         only recognized by session processes, and are ignored by
          background processes such as the main server process.
          This parameter can only be set in the <filename>postgresql.conf</>
          file or on the server command line. The default is an empty string.
@@ -3065,6 +3085,11 @@ local0.*    /var/log/postgresql
             </thead>
            <tbody>
             <row>
+             <entry><literal>%a</literal></entry>
+             <entry>Application name</entry>
+             <entry>yes</entry>
+            </row>
+            <row>
              <entry><literal>%u</literal></entry>
              <entry>User name</entry>
              <entry>yes</entry>
@@ -3287,19 +3312,35 @@ FROM pg_stat_activity;
      <title>Using CSV-Format Log Output</title>
 
        <para>
-        Including <literal>csvlog</> in the <varname>log_destination</> list 
-        provides a convenient way to import log files into a database table. 
+        Including <literal>csvlog</> in the <varname>log_destination</> list
+        provides a convenient way to import log files into a database table.
         This option emits log lines in comma-separated-value format,
-        with these columns: timestamp with milliseconds, user name, database
-        name, process ID, host:port number, session ID, per-session or -process line
-        number, command tag, session start time, virtual transaction ID,
-        regular transaction id, error severity, SQL state code, error message,
-        error message detail, hint, internal query that led to the error (if
-        any), character count of the error position thereof, error context,
+        with these columns:
+        timestamp with milliseconds,
+        user name,
+        database name,
+        process ID,
+        client host:port number,
+        session ID,
+        per-session line number,
+        command tag,
+        session start time,
+        virtual transaction ID,
+        regular transaction ID,
+        error severity,
+        SQL state code,
+        error message,
+        error message detail,
+        hint,
+        internal query that led to the error (if any),
+        character count of the error position therein,
+        error context,
         user query that led to the error (if any and enabled by
-        <varname>log_min_error_statement</>), character count of the error
-        position thereof, location of the error in the PostgreSQL source code
-        (if <varname>log_error_verbosity</> is set to <literal>verbose</>).
+        <varname>log_min_error_statement</>),
+        character count of the error position therein,
+        location of the error in the PostgreSQL source code
+        (if <varname>log_error_verbosity</> is set to <literal>verbose</>),
+        and application name.
         Here is a sample table definition for storing CSV-format log output:
 
 <programlisting>
@@ -3327,6 +3368,7 @@ CREATE TABLE postgres_log
   query text,
   query_pos integer,
   location text,
+  application_name text,
   PRIMARY KEY (session_id, session_line_num)
 );
 </programlisting>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 85ba6dadd1..b93e381b1e 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.289 2009/05/28 20:02:10 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.290 2009/11/28 23:38:06 tgl Exp $ -->
 
 <chapter id="libpq">
  <title><application>libpq</application> - C Library</title>
@@ -249,6 +249,32 @@
          </listitem>
         </varlistentry>
 
+        <varlistentry id="libpq-connect-application-name" xreflabel="application_name">
+         <term><literal>application_name</literal></term>
+         <listitem>
+          <para>
+           Specifies a value for the <xref linkend="guc-application-name">
+           configuration parameter.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry id="libpq-connect-fallback-application-name" xreflabel="fallback_application_name">
+         <term><literal>fallback_application_name</literal></term>
+         <listitem>
+          <para>
+           Specifies a fallback value for the <xref
+           linkend="guc-application-name"> configuration parameter.
+           This value will be used if no value has been given for
+           <literal>application_name</> via a connection parameter or the
+           <envar>PGAPPNAME</envar> environment variable.  Specifying
+           a fallback name is useful in generic utility programs that
+           wish to set a default application name but allow it to be
+           overridden by the user.
+          </para>
+         </listitem>
+        </varlistentry>
+
         <varlistentry id="libpq-connect-tty" xreflabel="tty">
          <term><literal>tty</literal></term>
          <listitem>
@@ -5672,7 +5698,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGHOST</envar></primary>
       </indexterm>
-      <envar>PGHOST</envar> behaves the same as <xref
+      <envar>PGHOST</envar> behaves the same as the <xref
       linkend="libpq-connect-host"> connection parameter.
      </para>
     </listitem>
@@ -5682,7 +5708,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGHOSTADDR</envar></primary>
       </indexterm>
-      <envar>PGHOSTADDR</envar> behaves the same as <xref
+      <envar>PGHOSTADDR</envar> behaves the same as the <xref
       linkend="libpq-connect-hostaddr"> connection parameter.
       This can be set instead of or in addition to <envar>PGHOST</envar>
       to avoid DNS lookup overhead.
@@ -5694,7 +5720,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGPORT</envar></primary>
       </indexterm>
-      <envar>PGPORT</envar> behaves the same as <xref
+      <envar>PGPORT</envar> behaves the same as the <xref
       linkend="libpq-connect-port"> connection parameter.
      </para>
     </listitem>
@@ -5704,7 +5730,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGDATABASE</envar></primary>
       </indexterm>
-      <envar>PGDATABASE</envar> behaves the same as <xref
+      <envar>PGDATABASE</envar> behaves the same as the <xref
       linkend="libpq-connect-dbname"> connection parameter.
       </para>
     </listitem>
@@ -5714,9 +5740,8 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGUSER</envar></primary>
       </indexterm>
-      <envar>PGUSER</envar> behaves the same as <xref
+      <envar>PGUSER</envar> behaves the same as the <xref
       linkend="libpq-connect-user"> connection parameter.
-      database.
      </para>
     </listitem>
 
@@ -5725,12 +5750,12 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGPASSWORD</envar></primary>
       </indexterm>
-      <envar>PGPASSWORD</envar> behaves the same as <xref
+      <envar>PGPASSWORD</envar> behaves the same as the <xref
       linkend="libpq-connect-password"> connection parameter.
       Use of this environment variable
-      is not recommended for security reasons (some operating systems
+      is not recommended for security reasons, as some operating systems
       allow non-root users to see process environment variables via
-      <application>ps</>); instead consider using the
+      <application>ps</>; instead consider using the
       <filename>~/.pgpass</> file (see <xref linkend="libpq-pgpass">).
      </para>
     </listitem>
@@ -5751,7 +5776,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGSERVICE</envar></primary>
       </indexterm>
-      <envar>PGSERVICE</envar> behaves the same as <xref
+      <envar>PGSERVICE</envar> behaves the same as the <xref
       linkend="libpq-connect-service"> connection parameter.
      </para>
     </listitem>
@@ -5777,7 +5802,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGOPTIONS</envar></primary>
       </indexterm>
-      <envar>PGOPTIONS</envar> behaves the same as <xref
+      <envar>PGOPTIONS</envar> behaves the same as the <xref
       linkend="libpq-connect-options"> connection parameter.
      </para>
     </listitem>
@@ -5785,9 +5810,19 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
     <listitem>
      <para>
       <indexterm>
+       <primary><envar>PGAPPNAME</envar></primary>
+      </indexterm>
+      <envar>PGAPPNAME</envar> behaves the same as the <xref
+      linkend="libpq-connect-application-name"> connection parameter.
+     </para>
+    </listitem>
+
+    <listitem>
+     <para>
+      <indexterm>
        <primary><envar>PGSSLMODE</envar></primary>
       </indexterm>
-      <envar>PGSSLMODE</envar> behaves the same as <xref
+      <envar>PGSSLMODE</envar> behaves the same as the <xref
       linkend="libpq-connect-sslmode"> connection parameter.
      </para>
     </listitem>
@@ -5797,7 +5832,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGREQUIRESSL</envar></primary>
       </indexterm>
-      <envar>PGREQUIRESSL</envar> behaves the same as <xref
+      <envar>PGREQUIRESSL</envar> behaves the same as the <xref
       linkend="libpq-connect-requiressl"> connection parameter.
      </para>
     </listitem>
@@ -5807,7 +5842,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGSSLCERT</envar></primary>
       </indexterm>
-      <envar>PGSSLCERT</envar> behaves the same as <xref
+      <envar>PGSSLCERT</envar> behaves the same as the <xref
       linkend="libpq-connect-sslcert"> connection parameter.
      </para>
     </listitem>
@@ -5817,7 +5852,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGSSLKEY</envar></primary>
       </indexterm>
-      <envar>PGSSLKEY</envar> behaves the same as <xref
+      <envar>PGSSLKEY</envar> behaves the same as the <xref
       linkend="libpq-connect-sslkey"> connection parameter.
      </para>
     </listitem>
@@ -5827,7 +5862,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGSSLROOTCERT</envar></primary>
       </indexterm>
-      <envar>PGSSLROOTCERT</envar>  behaves the same as <xref
+      <envar>PGSSLROOTCERT</envar>  behaves the same as the <xref
       linkend="libpq-connect-sslrootcert"> connection parameter.
      </para>
     </listitem>
@@ -5837,7 +5872,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGSSLCRL</envar></primary>
       </indexterm>
-      <envar>PGSSLCRL</envar>  behaves the same as <xref
+      <envar>PGSSLCRL</envar>  behaves the same as the <xref
       linkend="libpq-connect-sslcrl"> connection parameter.
      </para>
     </listitem>
@@ -5847,7 +5882,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGKRBSRVNAME</envar></primary>
       </indexterm>
-      <envar>PGKRBSRVNAME</envar>  behaves the same as <xref
+      <envar>PGKRBSRVNAME</envar>  behaves the same as the <xref
       linkend="libpq-connect-krbsrvname"> connection parameter.
      </para>
     </listitem>
@@ -5857,7 +5892,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGGSSLIB</envar></primary>
       </indexterm>
-      <envar>PGGSSLIB</envar> behaves the same as <xref
+      <envar>PGGSSLIB</envar> behaves the same as the <xref
       linkend="libpq-connect-gsslib"> connection parameter.
      </para>
     </listitem>
@@ -5867,7 +5902,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
       <indexterm>
        <primary><envar>PGCONNECT_TIMEOUT</envar></primary>
       </indexterm>
-      <envar>PGCONNECT_TIMEOUT</envar>  behaves the same as <xref
+      <envar>PGCONNECT_TIMEOUT</envar>  behaves the same as the <xref
       linkend="libpq-connect-connect-timeout"> connection parameter.
      </para>
     </listitem>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 7bd21a74b4..94fbce63ad 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.71 2009/06/26 22:08:17 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.72 2009/11/28 23:38:07 tgl Exp $ -->
 
 <chapter id="monitoring">
  <title>Monitoring Database Activity</title>
@@ -238,12 +238,12 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
       name, process <acronym>ID</>, user OID, user name, current query,
       query's waiting status, time at which the current transaction and
       current query began execution, time at which the process was
-      started, and client's address and port number.  The columns that
-      report data on the current query are available unless the parameter
-      <varname>track_activities</varname> has been turned off.
-      Furthermore, these columns are only visible if the user examining
-      the view is a superuser or the same as the user owning the process
-      being reported on.
+      started, client's address and port number, and application name.
+      The columns that report data on the current query are available unless
+      the parameter <varname>track_activities</varname> has been turned off.
+      Furthermore, these columns and the application name are only visible if
+      the user examining the view is a superuser or the same as the user
+      owning the process being reported on.
      </entry>
      </row>