Bitbucket Mesh sidecar
On this page:
Learn what the Bitbucket Mesh sidecar is, what role it plays in performance monitoring, and how to enable and use it.
What is the Bitbucket Mesh sidecar?
The sidecar pattern enables the deployment of an application's components into separate processes, ensuring their encapsulation, isolation, and security.
In Bitbucket 8.0, the Git source code management (SCM) logic was factored out of the Bitbucket main process into the sidecar process, running in the Bitbucket Mesh application. Since then, the sidecar has been used for repository access but it doesn't leverage concepts like replication or partitions.
In essence, the sidecar is a Mesh node paired to a Bitbucket node and using Git data from the shared home directory. The sidecar has its own Mesh home directory located at <bitbucket-home>/mesh and follows the same hierarchy as a remote Mesh home directory. However, it doesn't contain data on Git repositories.
The following diagram briefly shows how the Bitbucket sidecar process is integrated with the other processes in the application.
Where previously the Bitbucket application made Java method calls to access process-local SCM code, now it makes a gRPC call to the sidecar process to do the same.
Learn more about the sidecar and Bitbucket Mesh in the Bitbucket Mesh whitepaper.
Mesh sidecar for Bitbucket JMX monitoring
The Bitbucket Mesh sidecar has been designed to address failures and improve the overall performance of Bitbucket Data Center.
Starting from Bitbucket 8.0, the Mesh sidecar handles SCM-related metrics and Git operations run in the sidecar by default. The rest of the JMX metrics are managed by the Bitbucket main process. That’s why, to enable full JMX monitoring for Bitbucket 8.0 and later, you should enable JMX for both the Bitbucket main process and the Mesh sidecar process.
The sidecar JVM is launched directly from the Bitbucket JVM and therefore, doesn’t have startup scripts. This means you should configure the sidecar JVM options through the Bitbucket server for items like JMX settings, heap dump, or GC logging configuration.
You can add JMX-related parameters for the Mesh sidecar through the bitbucket.properties file.
The challenge is that the file allows you to define only one IP address even if you have a multi-node setup. To resolve this, each Bitbucket node must have a local bitbucket.properties file with a corresponding local node IP. Each node with this local file must then be symbolically linked to the BITBUCKET_HOME/shared/ directory.
Alternatively, you can include the JMX-related configuration in a local bitbucket.properties file within the $BITBUCKET_HOME directory itself.
To do this, create a $BITBUCKET_HOME/bitbucket.properties file and move all the JMX-related parameters to this file. At the same time, in the $BITBUCKET_HOME/shared/bitbucket.properties file, only the common parameters and configurations that are consistent across all other Bitbucket nodes should remain.
Enable the Mesh sidecar for JMX monitoring
To enable JMX monitoring on the Bitbucket Mesh sidecar:
Enable JMX on the
BITBUCKET_HOME/mesh/mesh.propertiesfiles on all the nodes by adding the following line:jmx.enabled=trueModify the
bitbucket.propertiesfile as follows to add JVM arguments to the Mesh Sidecar Java process:plugin.bitbucket-git.mesh.sidecar.jvmArgs[0]=-Dcom.sun.management.jmxremote.port=4444 plugin.bitbucket-git.mesh.sidecar.jvmArgs[1]=-Djava.rmi.server.hostname=<node_ip_address> plugin.bitbucket-git.mesh.sidecar.jvmArgs[2]=-Dcom.sun.management.jmxremote.ssl=false plugin.bitbucket-git.mesh.sidecar.jvmArgs[3]=-Dcom.sun.management.jmxremote.password.file=/var/atlassian/bitbucket_jmx.access
For more information on adding JVM arguments to the Mesh sidecar process, check How to pass JVM arguments to the Mesh sidecar. After restarting Bitbucket, you should now see JMX enabled on the Bitbucket Mesh sidecar process.
Troubleshooting
Check the following pages to learn how to fix issues with the Mesh sidecar.