Click here to see your recently viewed pages and most viewed pages.

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 (No longer supported)
  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"", function(response){log(response);}, params);
App Engine URL dataURL = new URL("")
Spreadsheets =importData("")

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

The Health Check Gadget is no longer supported.

Configuring Logging Parameters

The 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 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 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  - healthcheck service started on port 38714
23 Nov 2009 14:31:59,075 [main] INFO  - Connecting to SDC server
23 Nov 2009 14:31:59,076 [main] INFO  - 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  - 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  - Sending initial handshake msg
23 Nov 2009 14:32:00,105 [main] INFO  - Attemping login
23 Nov 2009 14:32:01,062 [main] INFO  - Successful login
23 Nov 2009 14:32:01,084 [main] INFO  - Sending resources info
agentId: ""
socksServerPort: 1102
healthCheckPort: 38714
resourceKey {
  ip: ""
  port: 80
  key: 2496070714898765656
resourceKey {
  ip: ""
  port: 443
  key: -3836320634892261426
resourcesXml: "<Contents of your resourceRules.xml>"
23 Nov 2009 14:32:01,091 [main] INFO  - Adding rule for Pair[, 80]
23 Nov 2009 14:32:01,099 [main] INFO  - Adding rule for Pair[, 443]
23 Nov 2009 14:32:01,099 [main] INFO  - Adding rule for Pair[localhost, 38714]
23 Nov 2009 14:32:01,112 [main] INFO  - starting a thread to watch resources file
23 Nov 2009 14:32:01,112 [Thread-3] INFO  - 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  - healthcheck thread is started
23 Nov 2009 14:32:13,554 [main] INFO  - 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  - [kcgr] Incoming connection for rule id:1 for resource: 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/ --debug
  2. View the log to look for the following entries that verify a successful two way connection:
    • - Successful login
    • - Sending resources info
    • - 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/ 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  - sequence: 1
01 23 Nov 2009 14:51:39,017 [main] DEBUG  - payload length: 24
02 23 Nov 2009 14:51:39,017 [main] DEBUG  - payload: [B@b754b2
03 23 Nov 2009 14:51:39,017 [main] DEBUG  - frame:
04 sequence: 1
06 payload: "\n\bSuccess.\020\001\032\004 \017(\005"
08 23 Nov 2009 14:51:39,017 [main] DEBUG  - frame type recevd: REGISTRATION
09 23 Nov 2009 14:51:39,019 [main] DEBUG  - 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  - registration successful. Received config info from the SDC server
18 healthCheckTimeout: 15
19 healthCheckWakeUpInterval: 5