Contract Signing & Execution Triage

Version history (essential for version mismatch diagnosis):

SELECT
  cv.id, cv.version_number, cv.sub_version_number, cv.action,
  cv.is_current, cv.is_deleted, cv.deleted_at,
  cv.root_version_id, cv.version_description,
  cv.docx_version IS NOT NULL as has_docx,
  cv.pdf_version IS NOT NULL as has_pdf,
  cv.created
FROM `spotdraft-qa.qa_india_public.contracts_v3_contractversion` cv
WHERE cv.contract_id = {contract_id}
ORDER BY cv.version_number DESC, cv.sub_version_number DESC
LIMIT 20

What to look for in version history:

• Multiple rows with is_current = TRUE → version consistency bug
• Alternating EXECUTION_PDF / UPLOADED_TPP_PDF pattern with many retries → ConvertAPI/document merging repeatedly failing
• Unexpected action values for the stage (WORKING_EDITABLE appearing after move to SIGN stage → version mismatch)
• is_deleted = TRUE on the expected current version → wrong version selected

Approval state for a contract:

SELECT
  a.id, a.name, a.current_state, a.order, a.enforcement_point_type,
  a.breakpoint_type, a.approval_type, a.is_deleted
FROM `spotdraft-qa.qa_india_public.approvals_v5_approvalv5` a
WHERE a.linked_to_entity_id = {contract_id}
  AND a.linked_to_entity_type = 'CONTRACT'
  AND a.is_deleted = FALSE
ORDER BY a.order

Environment-to-Dataset Mapping

Prod tables have a public_ prefix, e.g. prod_india_db.public_contracts_v3_contractversion. QA/Dev have no prefix.

GCP Cloud Logging Queries

Use list_log_entries with resourceNames: ["projects/spotdraft-qa"] and orderBy: "timestamp desc":

Search Django app logs for signing/execution errors by contract ID:

resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:"{contract_id}" severity >= ERROR

Search for Word server errors:

resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:("Word server raised an error" OR "ConvertAPI" OR "document generation" OR "document conversion")

Search for signing-specific errors:

resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:("signature" OR "signing" OR "execution" OR "Cannot edit a signature setup")

Search deferred tasks worker for async task failures:

resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app-deffered-tasks" textPayload:("{contract_id}" OR "signing" OR "execution") severity >= ERROR

Prod — pre-sign PDF / SoftTimeLimitExceeded (use when incident is on prod): Prod uses jsonPayload, not textPayload. Use resourceNames: ["projects/spotdraft-prod"]. Cluster label for US prod: resource.labels.cluster_name="prod-usa". Deferred tasks workload: sd-apps-django-app-deffered-tasks.

logName="projects/spotdraft-prod/logs/stderr"
resource.labels.cluster_name="prod-usa"
labels."k8s-pod/app"="sd-apps-django-app-deffered-tasks"
jsonPayload.message=~"SoftTimeLimitExceeded|save_pre_sign_pdf|cf_exporter|generate_docx_for_payload"

Always add a time window (e.g. timestamp >= "YYYY-MM-DDTHH:MM:00Z") to limit volume.

Check nginx for upstream timeouts on contract endpoints:

resource.type="k8s_container" resource.labels.namespace_name="kube-system" textPayload:"upstream timed out" textPayload:"/api/v3/contracts/{contract_id}"

BigQuery Operational Log Queries

Use projectId: "spotdraft-qa" for all queries.

Check DLQ for failed signing/execution tasks:

SELECT task_name, workspace_id, created, signature
FROM `spotdraft-qa.dlq_qa_india.dlq`
WHERE created >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND (task_name LIKE '%sign%' OR task_name LIKE '%execut%' OR task_name LIKE '%convert%' OR task_name LIKE '%document%')
ORDER BY created DESC
LIMIT 20

Check DLQ for a specific workspace's failed tasks:

SELECT task_name, COUNT(*) as failures, MAX(created) as last_failure
FROM `spotdraft-qa.dlq_qa_india.dlq`
WHERE created >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND workspace_id = {wsid}
GROUP BY task_name
ORDER BY failures DESC
LIMIT 20

Check request/response logs for 500 errors on contract endpoints:

SELECT request_path, response_status, time_taken, workspace_id, inserted_at, response_content
FROM `spotdraft-qa.request_response_logs_qa_india.logs`
WHERE inserted_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND response_status >= 500
  AND request_path LIKE '%contract%'
ORDER BY inserted_at DESC
LIMIT 20

Check request/response logs for a specific contract ID:

SELECT request_path, request_method, response_status, time_taken, response_content, inserted_at
FROM `spotdraft-qa.request_response_logs_qa_india.logs`
WHERE inserted_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND request_path LIKE '%{contract_id}%'
ORDER BY inserted_at DESC
LIMIT 20

BigQuery Datasets by Cluster

• QA India: spotdraft-qa.dlq_qa_india.dlq, spotdraft-qa.request_response_logs_qa_india.logs
• QA Europe: spotdraft-qa.dlq_qa_europe.dlq, spotdraft-qa.request_response_logs_qa_europe.logs
• QA USA: spotdraft-qa.dlq_qa_usa.dlq, spotdraft-qa.request_response_logs_qa_usa.logs

Diagnostic Framework

Step 1: Identify the Error Type

Ask the support person for:

• Contract ID and link (e.g., https://app.spotdraft.com/contracts/v2/{id})
• Workspace ID (WSID) and Cluster (IN, US, ME, EU)
• Exact error message shown in the UI
• What action was being performed — sending for signing, executing, previewing, uploading new version?
• Contract kind — template, template-editable, upload-sign, upload-editable?
• Screenshots if available

Step 2: Run Automated Queries

1. Query BQ Django models — Get full contract state + signature setup + version history (for QA contracts)
2. Search GCP logs for the contract ID in Django app and deferred task worker logs (QA only)
3. Search DLQ for failed async tasks related to the contract or workspace
4. Search request/response logs for 500 errors on the contract's API endpoints
5. Check nginx logs for upstream timeouts on the contract's endpoints

Step 3: Check Async Task Logs

Most signing/execution operations are async. Check the admin panel: