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:

1. 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.
2. 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.
3. 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.