Collecting Information on Incidents for Support
-
When encountering incidents or issues with RavenDB, it is essential to gather as much information as possible to help the support team diagnose and resolve the problem effectively.
-
Follow the steps in this article for collecting the relevant information for RavenDB support.
-
In this page:
Provide incident description
-
Description:
- Provide a detailed description of the incident you are experiencing.
- Include any error messages, warnings, or unexpected behavior you have encountered.
-
Exceptions:
- If applicable, attach the full-stack exception including the error message as plain text.
- Specify the origin of the exception
(e.g. from RavenDB Studio, from the client, from server logs, etc.).
-
Versions:
- Specify the RavenDB Server, Studio, and the client versions that you are using.
Create debug package
Create Debug Package
-
Navigate to Manage Server > Gather Debug Info
-
Select the data source(s) to retrieve. It is recommended to check all options.
-
Select all databases or choose specific databases to gather information from.
-
Select whether to create the package for the entire cluster or the current server.
-
Click 'Download'.
A zip file containing the debug package will be downloaded.
If the Studio is unavailable:
-
Try to download the debug package by issuing an HTTP GET request to the following endpoint:
{SERVER_URL}/admin/debug/info-package
. -
Execute this request for each node in the cluster, replacing
{SERVER_URL}
with the relevant node's URL.
Before sending the debug package zip file, perform the following checks:
- Verify that the zip file can be successfully extracted.
- Verify that the content is similar to the following sample images.
Enable logs for ongoing issues
If the issue you encounter is still ongoing,
then enable the following logs (if not enabled yet) before downloading existing log files:
Enable logs
-
Navigate to Manage Server > Admin Logs and click 'Settings'.
-
Server logs - Log Mode:
- Set the RavenDB server logs level to 'Information'.
-
Traffic Watch log:
- Click 'Configure' to enable Traffic Watch logging to the server logs.
- Keep the default values shown in the popup dialog.
-
Microsoft logs:
- This is an advanced option, set it only if requested by the support team.
- Click 'Configure' to enable the logging of Microsoft logs to the server logs.
- Use the following suggested log configuration:
{ "Microsoft.AspNetCore":"Debug" // Available levels: Trace, Debug, Information, Warning, Error, Critical, None }
-
Be aware that all logs settings will reset to their default values after a server restart.
-
To maintain a specific setting after a server restart, set the following configuration keys
in your default configuration:- Server logs - set Logs.Mode
- Traffic Watch log - set Logs.Microsoft.Disable
- Microsoft logs - set TrafficWatch.Mode
Download logs
Perform the following for each node in your cluster:
Download logs
-
Navigate to Manage Server > Admin Logs and click 'Download Logs'.
-
Either check 'Use minimum' to retrieve logs information from the time the server was started,
or enter a specific (local) time. -
Either check 'Use maximum' to retrieve logs information up to the current time,
or enter a specific (local) time. -
Click 'Download'.
A zip file containing the logs will be downloaded.
If the Studio is unavailable, or if the logs downloaded via the Studio appear problematic,
then copy the log files directly from the disk to another location to ensure that you keep them,
avoiding potential loss due to the retention configuration.
-
The location of the log files is determined by the Logs.Path configuration.
-
Logs deletion time is controlled by the following configurations:
Before sending the log files, perform the following checks:
- Verify that the zip files can be successfully extracted.
- Confirm that the logs correspond to the time of the incident.
- Verify that the content is similar to the following sample images.
Reproduce scenario
-
If the incident is over and you can reproduce it, then first verify logging level is set to 'Information'.
-
See how to enable the logs in Enable logs.
Create failing test
-
If possible, it is advised to create a unit test that showcases the failure in your client code.
-
Refer to Writing your unit test to learn how to use RavenDB's TestDriver.