Wednesday, December 7, 2011

A Walking Tour of the Foxhound FAQ

Is there anything duller than documentation?

Let's see... how about reading Frequently Asked Questions?

Even worse?

How about a walking tour through some new FAQs? Not the big shiny What's New in Foxhound 1.2 entries, but the more obscure ones, like this one:

What environment variables are used by Foxhound?

FOXHOUND1 is the all-important "Foxhound drive-and-path" used by all the Foxhound shortcuts... it's Foxhound's version of %SQLANY12%, if you lose it you'll probably want to set it up again.

FOXHOUND1BIN is the esoteric variable you can set to force Foxhound to start up using the 32-bit version of SQL Anywhere if you have both versions installed... "esoteric" because you almost never need it, Foxhound runs just fine using the 64-bit version. But, if you need it, here's how to use FOXHOUND1BIN (no, you don't need it if only the 32-bit version of SQL Anywhere is installed, Foxhound will use that one automatically).

FOXHOUND1UPGRADE refers to the variable that controls how much data the "post-setup" process will copy from your old Foxhound database when you are upgrading to a new version. The environment variable version of FOXHOUND1UPGRADE sets the initial value, but it defaults to "ALL" and is easy to change during the installation process, so it is rarely used.... the environment variable is rarely used, that is, but the underlying value is very important.


...wait a minute, that wasn't a FAQ, that was three paragraphs about a FAQ. To experience the full measure of dullness you have to follow the links, this article is just a travelogue.

Speaking of FOXHOUND1UPGRADE, this FAQ tells the full story: How do the different FOXHOUND1UPGRADE values work?

There's a lot of logic behind upgrading... it's a big deal if you have a big database, especially if you don't need all the data any more. You can let the purge process slowly delete it over time, or you can let the upgrade process quickly delete-it-by-not-copying it, so "upgrading" to the same version of Foxhound suddenly makes sense: How do I shrink the size of the Foxhound database?

An "alias" feature has been added to process that compiles the FAQ so different questions can point to the same answer. For example, this somewhat obscure question "How can the Heartbeat time be larger than the Sample time?" is answered as part of this longer explanation "How do I measure latency and throughput?"

The FAQ alias feature is most useful in the alphanumeric Messages section where messages containing multiple phrases and numeric codes appear repeatedly in the list. Quite a few messages have two or three entries pointing to the same explanation; this one's the winner with 4 appearances in the sorted list:
23: I/O error Fatal error: A disk read from file "...\foxhound1.db" failed with error code: (23) -- transaction rolled back --

A disk read from file "...\foxhound1.db" failed with error code: (23) -- transaction rolled back --

I/O error Fatal error: A disk read from file "...\foxhound1.db" failed with error code: (23) -- transaction rolled back --

transaction rolled back: I/O error Fatal error: A disk read from file "...\foxhound1.db" failed with error code: (23)

Even more useful than the alias feature is the new Google "Custom Search Engine" link that appears on every single FAQ page:


Go ahead, give it a whirl, type in "adhoc" and do a search.

Speaking of adhoc reporting, it's not new with Foxhound 1.2 but it might as well be; it wasn't documented until now:
How do I run adhoc queries on the Foxhound database?

How do I see the schema for adhoc reporting?

How do I change the ADHOC password?
Plus, a bunch of new columns were added, and new views, to make queries easier; after all, it's all your data!

Here's one of the shorter FAQs:
Question: How do I backup my Foxhound database?

Answer: Use one or both of the Foxhound shortcuts:
All Programs 
   - Foxhound1 
      - Tools 
         - Backup Foxhound Database 
         - Backup Foxhound Transaction Log
The second shortcut, Backup Foxhound Transaction Log, is new to Foxhound 1.2.

So is this explanation
How do the Foxhound backup shortcuts work?
plus, at long last, an explanation of what to do with all those backups:
How do I restore the Foxhound database from a backup?

Some folks like the context-sensitive Help frame on the right side of the Foxhound display, some folks hate it, but one thing everyone hated was the "Hide Help / Show Help" buttons when they didn't work.

Now those buttons are gone, and if you want to turn the Help frame on and off you have to check the "Show Help" box on the Foxhound Options page.

If there was a contest for "Shortest FAQ" this would be a another contestant:
Question: How do I set up Foxhound to monitor a large number of target databases?

Answer: See Section 7. Manage Multiple Monitor Sessions on the Monitor Options page.
It used to be an endless affair starting and stopping 100 sampling sessions: click, click, click, [curse], click, click, click, [curse], ...

Now it's a matter of setting up a text file with all the connection strings, then clicking on one button to start them all, another to stop them all, with nothing stopping you from starting and stopping them individually like before.

And finally, we have the answer to this important question: How much overhead does the Foxhound connection add to the target database?

Here's an excerpt, possibly a candidate for Quote Of The Day:
"Generally speaking, if Foxhound's overhead causes any problems, the target database is already in serious difficulty for other reasons."
That's a true statement, not just for Foxhound but for any performance monitor product: If monitoring performance hurts performance, there is already a problem that needs to be dealt with.

No comments: