Summary
We want to ensure that any issues you experience are resolved as quickly as possible. Toward that end, please ensure you follow these three guidelines:
- Always answer "What happened and when?" Your TSE will always need to know (a) what you were trying to do, (b) what issue you encountered, (c) when the issue began, and (d) if it is ongoing. This will help us properly triage and understand severity, narrow down the scope of our investigation, and avoid wasting time on triage.
- Include specific calls to and responses from the Paxos API. If you encounter a problem, we'll always need to know what service you were calling and, if you're creating or updating an object, what payload you used when the problem occurred. We do not log payloads.
- Include text, not screenshots, wherever possible. If you submit a screenshot of an error message or JSON payload rather than text in the ticket description, TSEs have to read and manually type out the payload rather than copying and pasting. This is time consuming and error prone and will slow down
Examples
Example 1: Production Outage
Bad
Subject: URGENT ISSUE
Description: Our application is down please advise
Good
Subject: Production appears down
Description: We began observing 503 errors from all services beginning at 13:02 UTC. The issue is ongoing.
Comments
The first example does not include any details about what occurred or when, and an application may be down due to an issue outside of Paxos. The TSE would have to begin by triaging and clarifying what happened, which might delay resolution. However, all services responding with 503 errors would indicate to the TSE that something is broken on Paxos's side and move us past the triage stage immediately. The details that the issue is ongoing tells us it's an ongoing Sev1 issue, and the timestamp that it started would help us pinpoint what change resulted in the issue.
Example 2: Troubleshooting Request
Bad
Subject: Identity service not working
Description: Please fix
Good
Subject: Receiving 400 response from identity service
Description: When I post the following payload to the identity service, I receive a 400 error. Why?
{
"person_details": {
"first_name": "John"
"last_name": "Smith",
"date_of_birth": "1900-07-31",
"govt_id": "XXX-XX-XXXX",
"govt_id_type": "SSN",
"address": {
"country": "USA",
"address1": "4677 Main St",
"city": "Atlanta",
"province": "GA", "zip_code": "30301"
},
"nationality": "USA",
"verifier_type": "PASSTHROUGH",
"passthrough_verifier_type": "JUMIO",
"passthrough_verified_at": "2021-07-21T22:26:50.916442Z"
}
}
Comments
The second ticket includes the payload, which is needed to determine why the error is being encountered (in this case, a missing comma on line 3 means the JSON is invalid.