Drizzled Public API Documentation

probes.d
00001 /* -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-
00002  *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
00003  *
00004  *  Copyright (C) 2009 Sun Microsystems, Inc.
00005  *
00006  *  This program is free software; you can redistribute it and/or modify
00007  *  it under the terms of the GNU General Public License as published by
00008  *  the Free Software Foundation; version 2 of the License.
00009  *
00010  *  This program is distributed in the hope that it will be useful,
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  *  GNU General Public License for more details.
00014  *
00015  *  You should have received a copy of the GNU General Public License
00016  *  along with this program; if not, write to the Free Software
00017  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00018  */
00019 
00020 /*
00021   The actual probe names in DTrace scripts will replace '__' by '-'. Thus
00022   insert__row__start will be insert-row-start.
00023 
00024   Recommendations for adding new probes:
00025 
00026   - each probe should have the minimal set of arguments required to
00027   unambiguously identify the context in which the probe fires. Redundant
00028   probes (i.e. the ones that can be obtained in user scripts from previous
00029   probes' arguments or otherwise) may be added for convenience.
00030 
00031   - try to avoid computationally expensive probe arguments. If impossible,
00032   use *_ENABLED() macros to check if the probe is activated before
00033   performing expensive calculations for a probe argument.
00034 
00035   - all *-done probes should have a status argument wherever applicable to make
00036   it possible for user scripts to figure out whether the completed operation
00037   was successful or not.
00038   
00039   - for all status arguments, a non-zero value should be returned on error or
00040   failure, 0 should be returned on success.
00041 */
00042 
00043 provider drizzle {
00044   
00045   /* The following ones fire when creating or closing a client connection */
00046   probe connection__start(unsigned long conn_id);
00047   probe connection__done(unsigned long conn_id);
00048 
00049   /*
00050    * Fire at the start/end of any client command processing (including SQL
00051    * queries).
00052   */
00053   probe command__start(unsigned long conn_id, int command);
00054   probe command__done(int status);
00055   
00056   /*
00057    * The following probes fire at the start/end of any SQL query processing,
00058    * respectively.
00059    *
00060    * query_start() has a lot of parameters that can be used to pick up
00061    * parameters for a lot of other probes here.  For simplicity reasons we also
00062    * add the query string to most other DTrace probes as well. Hostname is
00063    * either the hostname or the IP address of the Drizzle client.
00064    */
00065   probe query__start(const char *query,
00066                      unsigned long conn_id,
00067                      const char *db_name);
00068   probe query__done(int status); 
00069 
00070   /* Fire at the start/end of SQL query parsing */
00071   probe query__parse__start(const char *query);
00072   probe query__parse__done(int status);
00073 
00074   /*
00075    * This probe fires when the actual query execution starts
00076    */
00077   probe query__exec__start(const char *query,
00078                            unsigned long connid,
00079                            const char *db_name);
00080   probe query__exec__done(int status);
00081 
00082   /*
00083    * These probes fire in the query optimizer
00084    */
00085   probe query__opt__start(const char *query,
00086                           unsigned long connid);
00087   probe query__opt__done(int status);
00088   probe query__opt__choose__plan__start(const char *query,
00089                                         unsigned long connid);
00090   probe query__opt__choose__plan__done(int status);
00091 
00092   /* These probes fire when performing write operations towards any Cursor */
00093   probe insert__row__start(const char *db, const char *table);
00094   probe insert__row__done(int status);
00095   probe update__row__start(const char *db, const char *table);
00096   probe update__row__done(int status);
00097   probe delete__row__start(const char *db, const char *table);
00098   probe delete__row__done(int status);
00099 
00100   /*
00101    * These probes fire when calling external_lock for any Cursor 
00102    * depending on the lock type being acquired or released.
00103    */
00104   probe cursor__rdlock__start(const char *db, const char *table);
00105   probe cursor__wrlock__start(const char *db, const char *table);
00106   probe cursor__unlock__start(const char *db, const char *table);
00107   probe cursor__rdlock__done(int status);
00108   probe cursor__wrlock__done(int status);
00109   probe cursor__unlock__done(int status);
00110   
00111   /*
00112    * These probes fire when a filesort activity happens in a query.
00113    */
00114   probe filesort__start(const char *db, const char *table);
00115   probe filesort__done(int status, unsigned long rows);
00116   /*
00117    * The query types SELECT, INSERT, INSERT AS SELECT, UPDATE, DELETE
00118    * are all probed.
00119    * The start probe always contains the query text.
00120    */
00121   probe select__start(const char *query);
00122   probe select__done(int status, unsigned long rows);
00123   probe insert__start(const char *query);
00124   probe insert__done(int status, unsigned long rows);
00125   probe insert__select__start(const char *query);
00126   probe insert__select__done(int status, unsigned long rows);
00127   probe update__start(const char *query);
00128   probe update__done(int status,
00129                      unsigned long rowsmatches, unsigned long rowschanged);
00130   probe delete__start(const char *query);
00131   probe delete__done(int status, unsigned long rows);
00132 
00133 };