Secure Data Connector Developer's Guide: Troubleshooting

The information in this section discusses how to debug a connection over Secure Data Connector


  1. Using Debugging Query Parameters
  2. Health Check Gadget
  3. Configuring Logging Parameters
  4. Connections View
  5. Debugging a Connection
  6. Keepalive Requests for a Successful Connection
  7. Debug Successful Connection Log

Using Debugging Query Parameters

Secure Data Connector allows a special query parameter to be used which will cause a query to return debugging information instead of the requested data. This is useful for understanding why a specific query isn't returning the requested information. It is also useful in making sure that your resource rules correctly allow the access that you want.

To use the debugging query parameter, append X-secureDataConnectorDebug=text to the requested URL or alternatively add X-secureDataConnectorDebug=text to the HTTP request header.

Service Example Debug Command
Gadgets gadgets.io.makeRequest("http://corp.example.com/contacts.csv?X-secureDataConnectorDebug=text", function(response){log(response);}, params);
App Engine URL dataURL = new URL("http://corp.example.com/contacts.csv?X-secureDataConnectorDebug=text")
Spreadsheets =importData("http://corp.example.com/contacts.csv?X-secureDataConnectorDebug=text")

Alternatively with Gadgets and App Engine you can also get the debugging information by setting a header on the request. With Gadgets, headers can be set within makeRequest. In App Engine, HTTP headers can be set with the urlfetch function.

After using either the query parameters or the HTTP headers for debugging, the following list of debug name/value pairs will be returned:

Name Value
request_sdc_agent_domain The Google Apps dopmain for the Secure Data Connector agent
request_url The URL that was requested
request_service The service that performed the request. One of: Gadgets, AppEngine, or Spreadsheets
request_appId The AppId for the application that issued the request
sdc_routing Displays whether the request was routed over the SDC or the Internet. Any request that matches a resource rule will be routed over the SDC
sdc_matched_rule_agentId The agentId for the Secure Data Connector client that processed the request
sdc_matched_rule_ruleNum The resource rule number which matched the request as defined in the resourceRules.xml file
sdc_internet_routing If the request was routed over the internet, this returns the reason. The reason for Internet routing can be
  • NO_MATCHING_RESOURCE - The URL is not specified in your resource rules
  • SDC_NOT_ENABLED_FOR_DOMAIN - SDC has not been enabled in your Google Apps Control Panel
  • USER_NOT_LOGGED_IN - The SDC cannot authenticate the user, because they are not logged in
  • INVALID_DOMAIN - The domain of the user is not a Google Apps domain
  • USER_NOT_HOSTED - The user does not have a Google Apps account
  • BLOCK_ACCESS_DENIED - The user or application is not authorized to access the specified resource in the resource rules file
response_sdc_status A descriptive status message. If there are no errors in the processed request, the reponse will be "ok"
response_latency The amount of time in ms from when the request was received at the SDC agent till a responsed was received from the requested resource
response_content_size The size in bytes of the response generated by the requested resource

Health Check Gadget

Google provides a gadget that domain administrators can use to ensure that SDC agents are connected to Google Apps and have normal connection latency.

To use the Health Check gadget:

  1. Log into Google Sites as the administrator for your domain.
  2. Click Create new page, provide a name, and the type as a User Start Page.
  3. Click Add personal gadgets > Add gadget by URL and specify the following URL:
  4. The gadget shows existing SDC agents, the latency for each agent, and the status of the each agent. Latency depends on network conditions. The status is the most important value and indicates whether the SDC agent is connected or if an HTTP error occurs.

You can debug a client connection using the SDC log files, which reside on the location in your system depending on how you configured Apache Log4j during installation. The log files provide the following information:

Configuring Logging Parameters

The log4j.properties file in the installation directory folder enables you to specify Apache Log4j parameters for logging SDC connection information.

Note: If SDC is already started, it will take 60 seconds before it recognizes the change to the logging file parameter.

For information on each logging parameter, see the Apache Log4j documentation.

An example log4j.properties file is as follows:

# ***** Set root logger level to DEBUG and its only appender to A.
log4j.rootLogger=info, A

# ***** A is set to be a ConsoleAppender.

# ***** A uses PatternLayout.
log4j.appender.A.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

The following table lists the log4j.properties file parameters.

Tag Description
log4j.rootLogger Java-based logging utility root logger.
log4j.appender Logging output appender. You can specify a layout pattern.

Connections View

The following listing provides an example of the SDC log file output:

23 Nov 2009 14:31:59,073 [main] INFO  com.google.dataconnector.util.HealthCheckRequestHandler  - healthcheck service started on port 38714
23 Nov 2009 14:31:59,075 [main] INFO  com.google.dataconnector.client.SdcConnection  - Connecting to SDC server
23 Nov 2009 14:31:59,076 [main] INFO  com.google.dataconnector.util.SSLSocketFactoryInit  - Using SSL for client connections.
Setting iddle timeout to 60000 ms.
Setting accept timeout to 60000 ms.
Setting udp timeout to 600000 ms.
23 Nov 2009 14:31:59,376 [jsocks-starter-thread] INFO  com.google.dataconnector.client.JsocksStarter  - Starting JSOCKS listener thread on port 1102
23 Nov 2009 14:31:59,376 [jsocks-starter-thread] INFO  net.sourceforge.jsocks.socks.ProxyServer  - Starting SOCKS Proxy on:
23 Nov 2009 14:31:59,581 [main] INFO  com.google.dataconnector.client.SdcConnection  - Sending initial handshake msg
23 Nov 2009 14:32:00,105 [main] INFO  com.google.dataconnector.client.SdcConnection  - Attemping login
23 Nov 2009 14:32:01,062 [main] INFO  com.google.dataconnector.client.SdcConnection  - Successful login
23 Nov 2009 14:32:01,084 [main] INFO  com.google.dataconnector.registration.v4.Registration  - Sending resources info
agentId: "test_agent.example.com"
socksServerPort: 1102
healthCheckPort: 38714
resourceKey {
  ip: "myrestfulservice.example.com"
  port: 80
  key: 2496070714898765656
resourceKey {
  ip: "mysecurerestfulservice.example.com"
  port: 443
  key: -3836320634892261426
resourcesXml: "<Contents of your resourceRules.xml>"
23 Nov 2009 14:32:01,091 [main] INFO  com.google.dataconnector.util.SdcKeysManager  - Adding rule for Pair[myrestfulservice.example.com, 80]
23 Nov 2009 14:32:01,099 [main] INFO  com.google.dataconnector.util.SdcKeysManager  - Adding rule for Pair[mysecurerestfulservice.example.com, 443]
23 Nov 2009 14:32:01,099 [main] INFO  com.google.dataconnector.util.SdcKeysManager  - Adding rule for Pair[localhost, 38714]
23 Nov 2009 14:32:01,112 [main] INFO  com.google.dataconnector.client.SdcConnection  - starting a thread to watch resources file
23 Nov 2009 14:32:01,112 [Thread-3] INFO  com.google.dataconnector.client.HealthCheckHandler  - healthcheck config is not yet received from the SDC server. will check again in 5 sec
healthCheckTimeout: 15
healthCheckWakeUpInterval: 5

23 Nov 2009 14:32:06,117 [Thread-3] INFO  com.google.dataconnector.client.HealthCheckHandler  - healthcheck thread is started
23 Nov 2009 14:32:13,554 [main] INFO  com.google.dataconnector.client.SocksDataHandler  - Starting new connection. ID 1
23 Nov 2009 14:32:13,581 [jsocks-starter-thread] INFO  net.sourceforge.jsocks.socks.ProxyServer  - [kcgr] Accepted from:localhost.localdomain:58654
23 Nov 2009 14:32:14,524 [Thread-9] INFO  com.google.dataconnector.util.Rfc1929SdcAuthenticator  - [kcgr] Incoming connection for rule id:1 for resource:https://mysecurerestfulservice.example.com cloud-user:john.doe@example.com reported-appId:john-doe-gadget

Debugging a Connection

If the client connects, but after a short period of time no new entries are generated, you can perform the following procedure to debug the connection:

  1. Run /opt/google/secure-data-connector/<version>/bin/runclient.sh --debug
  2. View the log to look for the following entries that verify a successful two way connection:
    • com.google.dataconnector.client.SdcConnection - Successful login
    • com.google.dataconnector.registration.v4.Registration - Sending resources info
    • com.google.dataconnector.util.SdcKeysManager - Adding rule for pair[<resource>]

Keepalive Requests for a Successful Connection

When a client is properly connected, you should see keepalive requests from SDC approximately every 30 seconds:

1929SdcAuthenticator  - [pnfQ] Incoming connection for rule id:1 for resource:http://localhost:38714/test_agent.example.com/__SDCINTERNAL__/healthcheck cloud-user:john.doe@example.com reported-appId:dashboard
23 Nov 2009 14:46:30,425 [Thread-121] INFO  net.sourceforge.jsocks.socks.ProxyServer  - [pnfQ] Connected to localhost/
23 Nov 2009 14:46:30,875 [Thread-122] INFO  net.sourceforge.jsocks.socks.ProxyServer  - [pnfQ] Closing connection.

Debug Successful Connection Log

The following example lists debug output for a successful connection. The statements that show success are:

  • 10 - statusMessage: "Success."
  • 17 - ... registration successful. Received config info from the SDC server.

00 23 Nov 2009 14:51:39,016 [main] DEBUG com.google.dataconnector.protocol.FrameReceiver  - sequence: 1
01 23 Nov 2009 14:51:39,017 [main] DEBUG com.google.dataconnector.protocol.FrameReceiver  - payload length: 24
02 23 Nov 2009 14:51:39,017 [main] DEBUG com.google.dataconnector.protocol.FrameReceiver  - payload: [B@b754b2
03 23 Nov 2009 14:51:39,017 [main] DEBUG com.google.dataconnector.protocol.FrameReceiver  - frame:
04 sequence: 1
06 payload: "\n\bSuccess.\020\001\032\004 \017(\005"
08 23 Nov 2009 14:51:39,017 [main] DEBUG com.google.dataconnector.protocol.FrameReceiver  - frame type recevd: REGISTRATION
09 23 Nov 2009 14:51:39,019 [main] DEBUG com.google.dataconnector.registration.v4.Registration  - Received response to resource registration request
10 statusMessage: "Success."
11 result: OK
12 serverSuppliedConf {
13 healthCheckTimeout: 15
14  healthCheckWakeUpInterval: 5
15 }
17 23 Nov 2009 14:51:39,019 [main] INFO  com.google.dataconnector.registration.v4.Registration  - registration successful. Received config info from the SDC server
18 healthCheckTimeout: 15
19 healthCheckWakeUpInterval: 5