|
The following is a list of steps required to implement Warehouse access to Google Analytics data.
To begin, we need to make certain we have everything required. If you are missing anything, see the
Requirements section above. Note that the Java Virtual Machine library name is usually not needed on Microsoft Windows because the Java installation writes the name to the Windows registry. (If there is an issue on Windows, the library is in a file called jvm.dll, e.g.
C:\Program Files\Java\jre7\bin\client\jvm.dll)
| |
Item required |
Example |
|
Java Virtual Machine library (not needed on Windows) |
/usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so |
| |
ID for Google Analytics |
306757946 |
|
Credentials file name |
"C:\Program Files\Taurus\ga4credentials.json" |
Warehouse finds the Java libraries it needs by looking in the ga4javalib directory in the Warehouse installation directory.
Java .jar files may also be listed in the wh.ini file.
The wh.ini file resides in the Warehouse installation directory.
Setup of wh.ini is not typically necessary on Microsoft Windows systems.
To edit wh.ini, use a text file editor such as Notepad on Windows or gedit on Linux.
The first line of the file must be:
[Warehouse]
After that, you need another line pointing to your libraries. Long lines may be continued by putting an ampersand (&) at the end of a line to be continued. JVMCLASSPATH
is a list of .jar files separated by semicolons (;) like this:
JVMCLASSPATH=JarFile1;JarFile2;...
On Unix/Linux systems you need another line pointing to your Java Virtual Machine library using JVMLIB:
JVMLIB=JavaVirtualMachineLibrary
Here is an example snippet from wh.ini on Unix/Linux:
| |
[Warehouse]
JVMCLASSPATH=&
/var/taurus/warehouse/ga4java/animal-sniffer-annotations-1.21.jar;&
/var/taurus/warehouse/ga4java/guava-31.0.1-jre.jar;&
/var/taurus/warehouse/ga4java/threetenbp-1.5.2.jar
JVMLIB=/usr/jdk/instances/jdk1.6.0/jre/lib/i386/libjvm.so |
A simple Warehouse script can be used to verify your Google Analytics setup. The following script displays the number of visits to your website within the last 30 days:
|
open g ga4 id=yourGoogleViewID credentials=yourGoogleCredentialsFileName
|
| |
format ga4fmt : record
au : ga4 metric activeUsers
end
read gr = g format ga4fmt for &
StartDate = "2022-01-01" and EndDate = "today"
print au
endread
|
The Google ID is required to access data, but not to establish a connection to Google. A Warehouse FORMAT statement is required to specify the dimensions and metrics to return. Google Analytics access must always have a start date and end date in YYYY-MM-DD format or Google returns an error.
2.3.1 Request for Permission
You may be required to grant permission the first time DataBridger or Warehouse accesses your Google Analytics 4 data.
To allow access, use a browser to login to your Google Analytics administrator and grant access to your new system.
This step is only required once per system.
A 32-bit version of Warehouse is shipped with DataBridger Studio.
DataBridger Studio version 7.0 supports local Google Analytics 4 data sources. On older 32-but version of Windows, simply follow these instructions
using the Warehouse program shipped with DataBridger Studio.
If your DataBridger Studio installation directory is C:\Program Files\Taurus\DataBridger
you should be able to put the wh.ini here with no trouble.
However, if your DataBridger Studio installation directory is C:\Program Files (x86)\Taurus\DataBridger
(note the x86), you are running on a 64-bit Windows operating system. Since DataBridger Studio is a 32-bit program,
32-bit Java must be installed.
You can test by checking the directory
"C:\Program Files (x86)\Java" If this directory does not exist, you need to install 32-bit Java by following the instructions at Java on Microsoft Windows.
The Warehouse server program resides in the same directory as the Warehouse
client program and shares the wh.ini file.
Therefore no special setup is required for the Warehouse server. Once the wh.ini file has been setup and
the test script runs correctly, the Warehouse server needs only to be stopped and restarted since
wh.ini is only read at startup.
Once the server is running, you can verify it by using the instructions here: Checking the Warehouse Server.
|
3 Troubleshooting
|
|
This section describes ways to diagnose and solve problems. The methods assume
access to a command prompt or terminal window so commands can be entered to diagnose
problems. After opening the command window, you should then change directory (cd command)
to the Warehouse installation directory. Example:
| |
| |
cd C:\Program Files\Taurus\Warehouse |
Windows example |
| |
cd /var/taurus/whii/warehouse |
Unix/Linux example |
| |
To check if Warehouse can access the Java virtual machine, run Warehouse with the
-showinfo parameter which shows a list of diagnostic information.
Look near the bottom for an item called Java Virtual Machine.
If it says Available, the Java virtual machine is available and you may move to the next step.
If it says Unavailable, then either Java is not installed or Warehouse could not find the virtual machine library.
If you cannot find "Java Virtual Machine", then look at the first line Program version.
Warehouse versions prior to 3.04 cannot access Java, so you will need to upgrade Warehouse. Example:
| |
wh.exe -showinfo |
Windows example |
| |
./warehouse -showinfo |
Unix/Linux example |
If Java is unavailable on Windows, the typical cause is that Java is not installed or that you are running 64-bit Windows,
but a 32-bit Warehouse (shipped with DataBridger Studio). To install, see
above Java on Microsoft Windows.
If you need 32-bit Java on a 64-bit system, the -showinfo above will show:
| |
| |
Java Virtual Machine : Unavailable (Need 32-bit Java) |
If this is the case, see the instructions for installing 32-bit Java above Java on Microsoft Windows.
If Java is installed, you may have a more unusual
problem and should contact Taurus Software customer support at (650) 482-2022 x200.
The file MSG992 is required. It is included in your installation, so you should not usually be concerned about this file. Once Java is available, you can test for MSG992
by running Warehouse with -c and pressing ENTER at the first prompt. After ENTER, Warehouse checks for MSG992 and if it finds it, then prompts for Google login information. If MSG992 is not found, Warehouse silently quits.
Example, showing MSG992 installed correctly:
|
.\wh.exe -c |
| |
Enter name or IP address of server -> |
| |
Enter Google Analytics 4 ID (optional) -> |
-
Java code is compiled into class files and class files are often grouped in .jar files.
Google distributes their libraries as .jar files. Warehouse needs to know where the Google .jar files
are so Warehouse can tell the Java Virtual Machine. This is done by adding the .jar file locations to the wh.ini file. We can test the Google libraries
by running Warehouse with -c and entering our Google login information. Example:
.\wh.exe -c
Warehouse 7.00.0050-U (c) Taurus Software, Inc. 2022
Warehouse Server Connection Verification.
Enter name or IP address of server ->
Enter Google Analytics 4 ID (optional) -> 503667957
Enter Google credentials file name -> C:\Wh\credentials\mycreds.json
Warehouse OPEN statement with encrypted password:
OPEN dbtag GA4 ID=503667957 &
CREDENTIALS="C:\Wh\credentials\mycreds.json"
Connection to Google Analytics 4 SUCCESSFUL.
If you see an error that looks like the one below, the Google Analytics libraries could not be found.
This is usually because your wh.ini file does not point to the Google Analytics .jar files in he JVMCLASSPATH section. Verify
the JVMCLASSPATH section in the wh.ini file.
| |
Error opening GA 4 connection (step new com.google.analytics.data.v1beta.BetaAnalyticsDataClient): Error finding class com/google/an
alytics/data/v1beta/BetaAnalyticsDataClient: java.lang.NoClassDefFoundError: com/google/analytics/data/v1beta/BetaAnalyticsDataClient DJERR 8431 (WHERR 19606)
|
| |
| |
*** Connection to Google Analytics 4 FAILED!.
|
Decoding the meaning of error messages from Google can be trying.
Here is a list of some of the more common script errors and what they mean:
Example 1: |
Error message: |
Error getting Google Analytics data: Exception occurred in method get: java.lang .IllegalArgumentException: Parameter ids must conform to the pattern ga:[0-9]+ D JERR 8442 |
Cause: |
This error message is caused when attempting to read data without specifying an ID on the OPEN statement |
Solution: |
Provide a valid ID on the OPEN statement in your Warehouse script.
See Google Analytics ID.
|
Example 2: |
Error message: |
Error setting up to read GA 4 call RunReportRequest.build(): Exception occurred in method runReport: com.google.api.gax.rpc.InvalidA
rgumentException: io.grpc.StatusRuntimeException: INVALID_ARGUMENT: Invalid property ID: . A numeric Property ID is required. To lea
rn more about Property ID, see https://developers... (WHERR 19608) |
Cause: |
This error message is caused when attempting to read data
with an invalid ID specified on the OPEN statement. |
Solution: |
Provide a valid ID on the OPEN statement in your Warehouse script.
See step 3 here: Giving access to your Google Analytics data.
|
Example 3: |
Error message: |
Error opening GA 4 connection (step call create()): Exception occurred in method create: java.io.IOException: The Application Default Credentials are not available. They are available if running in Google Compute Engine. Otherwise, the environment variable GOOGLE_
APPLICATION_CREDENTIALS must be defined ... (WHERR 19606) |
Cause: |
This error message is caused when attempting to read data
without specifying a credentials .json file on the OPEN statement. A credentials .json must be obtained
from Google before Google Analytics 4 data may be accessed.
|
Solution: |
Provide a valid credentials .json file on the OPEN statement in your Warehouse script.
See Get Your Credentials.
|
Example 4: |
Error message: |
Start date end end date are both required. (WHERR 19633) |
Cause: |
This error message is caused when attempting to read data
without specifying both a start date and an end date.
The important part of this message is where it says required.
|
Solution: |
Provide both a start date and an end date on the READ statement in your Warehouse script.
|
Since the Warehouse server program resides in the same directory as the Warehouse client program, once the wh.ini file has been setup and
the test script runs correctly, the Warehouse server needs only to be stopped and restarted. Run the Warehouse client program with the -serverinfo serverName parameter to show diagnostic information from the server. Example:
| |
wh.exe -serverinfo myserver |
Windows example |
| |
./warehouse -serverinfo myserver |
Unix/Linux example |
If -serverinfo fails, either the Warehouse server
is not running or you have a network/firewall issue.
In this case, please check with your network administrator.
Look near the bottom of the -serverinfo output for an item called Java Virtual Machine. If it says Available Warehouse can access Java. If it says Unavailable, then use a window to login to the server and troubleshoot the Warehouse client program.
We can test the Google access to a Warehouse Server
by running Warehouse with -c and entering our Google login information.
|
.\wh.exe -c |
| |
Enter name or IP address of server -> |
Enter server name |
| |
Enter user name on server (Optional) -> |
Enter server user name |
| |
Enter password -> |
Enter server user password |
| |
Enter remote database type (optional) -> |
Enter GA4 |
| |
Enter Google Analytics 4 ID (optional) -> |
Enter Google ID |
| |
Enter Google credentials file name -> |
Enter full name of credentials .json file |
If everything is correct, you will see a sample OPEN statement with an encrypted password followed by:
| |
Connection to Warehouse server myserver SUCCESSFUL. |
If the connection is unsuccessful, use a window to login to the server and troubleshoot the Warehouse client program.
A simple Warehouse script can be used to verify Warehouse server access to your Google Analytics data.
The following script displays the number of visits to your website within the last 30 days:
| |
open g remote user=yourServerUser pass=yourServerPassword & |
| |
ga4 id=yourGoogleClientID credentials=yourGoogleCredentialsFile |
| |
format ga4fmt : record
au : ga4 metric activeUsers
se : ga4 metric sessions
end
read gr = g format gafmt for StartDate = &
($now - convert(str2date("30","NN"),"interval") pic "YYYY-MM-DD") &
and EndDate = "today"
print au, se
endread
|
If your server has been setup correctly and the connection informatiom in this script is correct,
then this script will complete successfully.
|
|
