API Errors Advanced Troubleshooting configuration enables you to create rules to collect more information about API errors (headers, request/response body content), as well as collect API errors with a status code, not only in the 4XX-5XX range, so you can troubleshoot errors faster.
Use API Errors Advanced Troubleshooting to:
- Setup collection of API errors for network requests where the HTTP status code is below 400.
- See the following types of additional API error details in the Event Stream of Session Replay:
- The HTTP headers of the request and the response
- The body (the data sent by the request or received in the response)
- The body elements (specific elements of the request/response body)
- The query parameters of the request endpoint (of the URL of the information you request for).
- Leverage unencrypted response body elements in Errors Workspace & Alerts and Analysis Context to monitor, identify and quantify errors based on response body content.
Once configured, learn more about how to leverage API error Troubleshooting Details.
Protecting personal data
Depending on the custom headers you add, the troubleshooting details can contain personal data. In order to protect the data from being decrypted easily by anyone, you can and should encrypt custom headers that contain personal data.
Headers and Body elements have the option to be collected un-encrypted for ease and speed when exposing troubleshooting details. This option should only be used if you’re certain that the collected data point you're adding doesn't contain any personal data.
Entire request and/or response body as well as query parameters can only be collected encrypted.
We do not allow you to collect specific headers which contain personal data: cookies, authorization, and proxy-authorization headers, as these contain sensitive data that cannot be processed.
Visit our article on privacy and personal data for more information.
Encrypting troubleshooting details
Prerequisite for encryption setup: A public/private key pair must be set up in advance, before you can add and expose API troubleshooting details for encrypted custom headers.
You can findinstructions for encryption key setup here.
Limitation
On the web, our encryption mechanism relies on 2 browser APIs that are supported widely by most popular browsers (CryptoKey API and Web Cryptography API). However, some browsers and old browser versions don’t support them. In that case, the tag will not proceed with the collection of encrypted data.
Overview of the API error troubleshooting tab
1. Navigate to the Console by clicking your profile icon, followed by 'Console'.
2. Click the 'Advanced errors troubleshooting' tab.
API error collection rules overview
For each rule listed, you can see the following information (from left to right):
- The rule name
- The status code(s) of the rule
- The Request URL
- The date the rule was created and last updated (and the name of the author)
To help you decide whether to create a new rule, or edit an existing one, use the actions below:
- Search rule: search for existing rules based on a term contained in the name, or the status code of the domain.
- Sort rules: click the column headings to sort rules by name, status code, domain or date (created or last updated).
- View rule detail: click on the “eye” icon to the right of the rule to open the side panel and see the collection conditions and collected data points.
The "default rule"
This rule represents the default behavior of collecting all network requests with a status code with the 4XX-500 range, with just the default data points: Request URL, Status code and Method. It cannot be edited or deleted.
Creating a new rule
Step 1: Naming and adding rule conditions
1. Click the ‘+ New rule’ button.
2. Rule name: give your rule a name in the rule name field. This name must be unique.
3. Request URL: The rule will match all requests where the URL contains the value you have added in the field. Note, it’s not possible to use the exact same collection of conditions as another existing rule.
Example (if you want to match the request URL): https://subdomain.domain.com/path/sub-path?query=param
The following value will match it:
- Full URL: https://subdomain.domain.com/path/sub-path?query=param
- Domain & HTTP protocol: https://subdomain.domain.com
- Domain only: domain.com
- Path only: /path/sub-path
- Domain + path: subdomain.domain.com/path/sub-path
4. Status code: you can either select the 4XX-5XX group to match the HTTP status codes covering errors, or you can define a specific status code.
5. Response Body Content: specify what must be written in the body of the response in the Body content field for this rule to be collected. You can enter up to 64 characters. This field is optional for all Status code except if the “200” status code is specified, it is required to specify a response body content, ideally identifying an error. This is made to avoid collecting all network requests as API errors.
Response Body Content logic and limitations
This is a filtering logic and the logic is 'contains' so an exact test is not a requirement. Response body content is not case sensitive (“invalid” will match a value like “INVALID_CODE”).
Example:
You want to collect the request when the response contains an error.
Response body sample:
{ "errors": [ { "message": "Cannot query field 'age' on type 'Customer'.", "code": "1003" } ], "data": { "customer": { "id": "123", "name": "John Doe" } } }
Body content value to use: errors
Body content value to use (with special characters): errors\"\:\[\{
Limit on response body content:
- On Android Mobile apps, the body content match will work if the response body has a maximum size of 1MB.
- On iOS Mobile apps, there is no limit on the response body content size.
- On the web, there is no limit on the response body content size.
6. Click ‘Next’ to continue the rule creation.
Step 2: Adding collected data points
After inputting the name, conditions and request URL to your rule (and body content if status code is 200), you can add collected data points. By default, Contentsquare collects the Request URL, Status code, and Method.
Headers
1. Click “+ Add”. Note, you can add multiple headers at once by clicking on the “+” button. This is useful if they all share the same conditions (request or response, encrypted or unencrypted).
2. Enter the header name.
3. Encryption:
- If encryption is set, the default state will be “encrypted”. Toggle it off to collect the header unencrypted
- If encryption is not set, the header can only be collected unencrypted. Make sure not to collect a header containing personal information.
4. By default “Request” is selected. You can update this to collect a Response instead.
5. Click “Apply”.
Body elements
Get more flexibility in the data points you want to leverage, by collecting specific elements of the request or response body in JSON format, by using JSON Path-based query language.
Note: You cannot edit a body elements, but you can delete and recreate it.
The JSON Path length is limited to 60 characters.
Response body elements for analysis
Used for error grouping and filtering (in the Analysis Context) and for Workspace widget and Alert creation, these are elements on the response body that will be collected unencrypted.
To define a response body elements to collect for analysis:
1. Click “+ Add”.
2. Enter the JSON path of the element you want to collect. You can also add multiple entries at once by clicking on the “+” button.
3. Click “Apply”.
Response body elements for troubleshooting
Visible at the individual event level in Session Replay, these are elements of the request/response body you want to collect for troubleshooting.
To define a response body elements for troubleshooting to collect:
1. Click “+ Add”.
2. Enter the JSON path of the element you want to collect. You can also add multiple entries at once by clicking on the “+” button.
3. Encryption:
- If encryption is set, the default state will be “encrypted”. Toggle it off to collect the body element unencrypted.
- For the response: the body element for troubleshooting can only be collected encrypted, as the unencrypted response body element are added for analysis (in the in section above).
- If encryption is not set, only request body element can be collected unencrypted. Make sure not to collect a body element containing personal information.
4. By default “Response” is selected. You can either collect the body element for the Response or Request.
5. Click “Apply”.
Types of bodies supported
The collection of body elements is available for request/response bodies under the following conditions:
Web | Mobile apps |
Must have a ‘content-type’ header set to ‘application/json’ or ‘application/graphql’ | The body format must be of any JSON type |
Size must be under 64 000 bytes | Size must be under 64 000 bytes |
Examples of body elements:
“errors[0].message” to collect the error message unencrypted
“errors[0].code” to collect the error code unencrypted
“data.emailAddress” to collect the email address encrypted as it is personal data
Entire body (encrypted)
Tick the box to collect either request or response body or both. Try to avoid including endpoints and fields containing sensitive data that cannot be displayed or tracked as this information is not allowed.
Types of bodies supported & limitations
Web | Mobile applications |
application/json |
The SDK will attempt to parse the body as a string, whatever the format
|
Entire body collection limitations:
Request body will be collected if its size does not exceed 64 KB.
Response body will be collected if its size does not exceed: 5 KB
Query params (encrypted)
Tick the box to collect the query parameters. Query parameters will be collected if their size does not exceed 2 KB.
Default data points
By default, we collect the Request URL, Status code and Method.
Editing and deleting rules
From the rules list, click on the “eye” icon at the right of the rule to open the rule side panel.
To edit:
1. Click on the pencil icon of the rule name or Conditions section.
2. Open the rule modal on step 1.
3. Click on the pencil icon of the collected data points section to open the rule modal on step 2.
4. Apply any changes.
5. Navigate to the other modal if needed to apply additional changes.
6. Click “Save” to apply changes.
To delete:
1. Click the “Delete rule” button from the bottom.
2. Confirm the delete action by clicking “Delete” again.
FAQs
Can I retroactively track error troubleshooting details?
No, error troubleshooting details are only collected after the setup is defined.
What happens when a request exceeds the accepted limits?
There are three data points with the following limits:
- Query parameter limit: 2 KB
- Request body size limit: 64 KB
- Response body size limit: 5 KB
Each of these data points is assessed independently from the other. When the limit is reached, we will not collect the data. For each we will push "..." un-encrypted. This will be reflected in the replay's troubleshooting details.
Why does the request or/and response body look like it is encoded, even after decryption?
This may happen if the request has the header Transfer-Encoding
set to gzip
value. Chrome DevTools automatically decompresses the body so this is not noticeable when using it. However, when seen in the Player Troubleshoot modal, the body is not decompressed automatically. Third-party tools can be used to decompress it after decryption.