Troubleshooting the Service Bus for Windows Server and Relativity service bus

Note: Relativity plans to deprecate Windows Service Bus in Server 2023. We recommend that you begin conversion to RabbitMQ beginning in Server 2022.

You can troubleshoot the Relativity service bus by viewing the log files and by running diagnostic commands that the Service Bus PowerShell utility provides. Additionally, you can use the Service Bus Explorer to view information about the topics and subscriptions used for distributing messages.

Note: The Relativity installation and Upgrading your Relativity service bus pages include information for troubleshooting installation issues for service bus.

See these related pages:

• Relativity service bus
• Relativity service bus entities
• Pre-installation

General troubleshooting tasks for service bus

Use these general troubleshooting tasks to resolve issues with the Relativity service bus. For more information about troubleshooting with PowerShell commands, see Service bus PowerShell cmdlets.

Ensure all services are running

Complete these steps as necessary:

• To ensure that all services are running, execute the Get-SBFarmStatus command.
• If you find that the services aren't running, execute the Stop-SBFarm, and then the Start-SBFarm command.
• If the services still don't start, see Troubleshooting the service bus farm.

Verify instance settings are correct

Verify that the instance settings for the service bus match their respective values from the farm. Execute the Get-SBFarm command. Compare the values returned by this command to those in the following instance settings:

• ServiceBusFullyQualifiedDomainName
• ServiceBusHttpPort
• ServiceBusTcpPort

Check that the Relativity namespace exists

To check that the Relativity namespace exists, execute the Get-SBNamespace command.

If you find that the namespace doesn't exist, complete the following steps:

1. On your machine, click Start > Control Panel > Programs > Programs and Features.
2. Check for Relativity service bus in the program list. If you find the Relativity service bus, uninstall it.
3. Run the Relativity installer with the INSTALLSERVICEBUS=1. For more information, see the Relativity installation or Upgrading your Relativity service bus.
4. Verify that the namespace called Relativity exists.

Service bus connection errors

Review the following list of errors and resolutions to troubleshoot your service bus connection. For more information about troubleshooting with PowerShell commands, see Service bus PowerShell cmdlets.

Service bus PowerShell cmdlets

When you run the installer for Service Bus for windows Server, it automatically adds the Service Bus PowerShell utility. You can use these PowerShell commands for debugging and troubleshooting purposes. For a complete list of commands, see Microsoft.ServiceBus.Commands.

Note: We don't recommend using these commands to change any Authorization rules at this time.

Log in to the machine where you installed the Relativity service bus. Run the PowerShell commands as necessary. The following list includes commands that are useful for debugging:

• Get-SBFarm - retrieves the configuration for the Service Bus for Windows Server farm.
• Get-SBFarmStatus - outputs a list of services on each service bus server in a farm. It also retrieves their statuses, such as Running, Stopped, Start Pending, Stop Pending, and others. Use this cmdlet to quickly get a list of services that are running on different servers.
• Get-SBNamespace - retrieves information about the Service Bus for Windows Server namespaces.
• Stop-SBFarm - stops all services on all servers in a farm. You need to stop the services to make any configuration changes to a farm or the namespace.
• Start-SBFarm - starts all services on all servers in the farm. You can use this cmdlet to restart an entire service bus farm.
• Stop-SBHost - stops all services on the server where you are currently running this cmdlet.
• Start-SBHost - starts all services on the server where you are currently running this cmdlet. You can use this cmdlet to restart specific service bus servers.

Checking logs in the Event Viewer

Similar to other applications running on Windows server, the Relativity service bus logs all errors, warnings, and information events to the event viewer. You can view these events in the application logs of the Windows Event Viewer application. By default, the verbose events aren't logged, but you can enable them.

Use the following steps to enable verbose logs:

1. Open the Event Viewer on your server.
2. On the View menu, click Show Analytic and Debug Logs.
3. Under Applications and Service Logs, open the Microsoft-ServiceBus > Analytic Trace.
4. Right-click on the Analytic Trace and click Enable Log.
5. Repeat these steps to enable the Debug Trace.

   (Click to expand)

   

Using Service Bus Explorer

You can use Service Bus Explorer to troubleshoot the Relativity service bus. With this Microsoft tool, you can also view entities contained in the Relativity service bus, and their current statuses. The following information includes guidelines for using the Service Bus Explorer in a Relativity environment. For additional information, see Service Bus Explorer on Microsoft Developer Network site.

Note: We recommend using the Service Bus Explorer only when other troubleshooting methods have failed. Use the Service Bus Explorer to view the status of Relativity service bus entities. Don't modify any settings through this tool, because such actions may negatively affect the functionality and performance of your Relativity instance. In addition, don't delete messages unless we explicitly recommend this action to resolve an issue with the service bus. Manipulating data in the service bus can adversely affect Relativity functionality.

Prerequisites for Service Bus Explorer

You must complete the following prerequisites before using Service Bus Explorer:

• Obtain the executable for the Service Bus Explorer:
  • Download Service Bus Explorer.
  • Extract the contents of the Service Bus Explorer.zip file.
  • In the C# folder, locate the 2.1.zip file. Create a new folder and copy this file to it.

    Note: Relativity service bus requires Service Bus Explorer 2.1.3.0.

  • Extract the contents of the 2.1.zip file.
  • Double-click on the ServiceBusExplorer.exe to launch the application.
• Run Service Bus Explorer on any machine that can connect to the Relativity service bus, and the required certificates.
• Run Service Bus Explorer as a user with administrative and manage user privileges on the Service Bus for Windows Server.

Connecting to a Relativity namespace

After installing the Service Bus Explorer, you must configure a connection string for your Relativity service bus namespace .

Use the following steps to connect to a namespace:

1. Open Service Bus Explorer.
2. Click File > Connect.
3. In the Service Bus Namespaces drop-down, select Enter connection string.
4. Enter the following string in the Connection String textbox. Replace <FarmDns>, <HttpsPort>, and <TcpPort> with these values from your service bus farm configuration.

   Endpoint=sb://<FarmDns>/Relativity;StsEndpoint=https://<FarmDns>:<HttpsPort>/Relativity;RuntimePort=<TcpPort>;ManagementPort=<HttpsPort>

   Note: You can also use the Get-SbClientConfiguration command instead of manually entering the connection string. This command outputs two connection strings. The second connection string is used for Relativity. Copy this connection string in to the textbox.

5. Click OK. You now view topics and subscriptions in the Service Bus Namespace browser.

Viewing entities in a namespace

The Service Bus Namespace browser displays a list of topics and subscriptions that your namespace contains. You can view additional information and settings for an entity by selecting it in the browser. You need to manually refresh the data when you select an entity. Select an entity and press F5, or right-click on an entity in the browser and click Refresh.

The following screen shot illustrates how the Service Bus Explorer displays conversion topics and subscriptions on the Relativity service bus. The integers that appear after a subscription indicate the number of messages and dead letters respectively.

(Click to expand)

For additional information about using this tool, see Service Bus Explorer on Microsoft Developer Network site.

Troubleshooting with Service Bus Explorer

To troubleshoot with the Service Bus Explorer, you can use the Peek Messages operation to view messages in a subscription or queue without modifying them.

Note: Don't use the Receive operation because it removes messages from the entity, and may cause application failures.

Use the Service Bus Explorer to perform the following troubleshooting tasks. You need to refresh the data when selecting a different entity. See Viewing entities in a namespace.

• Verify that your Relativity namespace exists.
• Confirm that the expected topics and subscriptions exist in your Relativity namespace.
• Determine whether topics are receiving messages and whether messages are backed up in topics. You can also use it to determine whether the dead-letter queues are holding undelivered or unprocessed messages.

Uninstalling the service bus farm

To the remove the Service Bus for Windows Server from a farm node or from the farm entirely, see Uninstalling on the Microsoft website.

Creating a namespace for the service bus

You can use these steps to create a namespace for the service bus without installing or upgrading Relativity. In most cases, you would use these steps when you are troubleshooting your service bus as described in Service bus returns a 401 error.

Use the following steps to create a namespace:

1. Open the Service Bus PowerShell tool.
2. Execute the following cmdlet to create the Relativity namespace, if it doesn't exist:

   New-SBNamespace -Name Relativity -ManageUsers yourDomain\yourUserName

3. Execute the following cmdlet to create the Relativity authorization rule:

   New-SBAuthorizationRule -NamespaceName Relativity -Name Relativity -Rights Manage,Send,Listen

4. Complete the following steps to update the instance settings for the Relativity service bus:
   1. Execute the Get-sbfarm cmdlet. In the list of hosts, note the values for theHttpsPort, TcpPort, and Name.
   2. Execute the following cmdlet: Get-SBAuthorizationRule -NamespaceName Relativity -Name Relativity. Note the value of the PrimaryKey.
   3. Update the following instance settings with the values obtained from the previous steps. All of the settings are located in the Relativity.ServiceBus section of the instance setting table.

      Name	Value
      ServiceBusHttpPort	HttpsPort value from step 4a
      ServiceBusTcpPort	TcpPort value from step 4a
      SharedAccessKey	PrimaryKey value from step 4b
      SharedAccessKeyName	Relativity