Monitor application performance

Administer Bitbucket Data Center and Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

App monitoring can give you a deeper insight into which apps are doing what in your instance. This can be useful when troubleshooting issues with a specific app, or to help you determine whether an app may have contributed to a drop in overall performance or stability.

Set up monitoring

Before you can connect your APM, you need to:

  • configure a JMX exporter, and

  • make sure that JMX metrics are enabled in your instance (which in turn enable App metrics). 

The instructions on this page assume you’ll be using Prometheus. You can use any Application Performance Monitoring (APM) solution, the steps will be very similar for each.

1. Configure the JMX Exporter

The exporter takes the JMX MBeans and transforms them into the right format for Prometheus. It also hosts a HTTP endpoint which Prometheus will connect to. Learn more about the Prometheus JMX exporter.

If you don't plan to use Prometheus, you'll need to check which exporter or agent is required for your APM solution. For example, this Java agent for NewRelic.

To install the exporter:

  1. Download the Prometheus JMX exporter jar file from the GitHub repository.

    $ curl -L https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/0.16.1/jmx_prometheus_javaagent-0.16.1.jar --output jmx-exporter.jar
  2. Create a configuration file for the exporter. You can download an example file from our repository. For more information on the configuration options see the README.md.

  3. Copy the jar file and configuration file to each application node (the local home directory is a good option).

  4. Stop Bitbucket on one node.

  5. Add the following agent properties to $bitbucket_home/bin/_start-webapp.sh of each cluster node to tell Bitbucket where to find the JMX exporter:

    JVM_SUPPORT_RECOMMENDED_ARGS="-javaagent:./jmx-exporter.jar=12345:config.yaml"

    The JMX exporter defaults to port 8080. You’ll need to specify a different port for the exporter if this port is in use by Jira or another application.
     

  6. Start Bitbucket.

  7. To check that the exporter is working, go to localhost:<jmx-exporter-port>. You should see the metrics output.

Repeat these steps for all remaining nodes, if you run Bitbucket in a cluster. You can perform a rolling restart to avoid any downtime.

You'll need to make sure the JMX exporter endpoint is not exposed outside your network, or that you've taken appropriate steps to secure it. 

2. Enable application monitoring in Bitbucket

Make sure that JMX monitoring is enables as application monitoring uses JMX (Java Management Extensions). Learn how to enable JMX monitoring

If you have previously set up JMX monitoring for Bitbucket, there’s nothing else you need to do. The additional application monitoring metrics will be exposed in the same way as existing application metrics. For the full list of things, you might want to monitor see Application metrics reference.

If you don’t have an existing Application Performance Monitoring (APM) solution, see our guide on getting started with Prometheus and Grafana.

JMX monitoring can have a performance impact on your instance. In most cases it’s not significant. However if you do experience any problems with your instance performance or stability, you can disable JMX monitoring.

Identify the app name

App metrics include the plugin key rather that the app's display name. For example,  com.atlassian.troubleshooting.plugin-bitbucket is the plugin key for the Troubleshooting and Support Tools system app for Bitbucket. 

To find the app name:

  1. Go to <base-url>/plugins/servlet/upm/osgi

  2. Enter the plugin key in the Search bundled metadata field

  3. The plugin details will be returned, including the name and vendor.

OSGi admin screen showing search results for a plugin key

You can also use the following REST endpoint /rest/plugins/1.0/<plugin-key>/summary which returns all the details about the app. 

Enable optional tags

App vendors can choose to include additional metadata which can help when troubleshooting a performance issues. These tags are not included by default.

You can use the atlassian.metrics.optional.tags system property to show additional tags for a metric. 

atlassian.metrics.optional.tags.<metric-name>=<tag-key1>,<tag-key2>

For example, if the full metric name is sampleApp.asset.loadtime and the app vendor included a tag to output additional information about the content type.

atlassian.metrics.optional.tags.sampleApp.asset.loadtime=sampleApp-type

The app vendor will be able to tell you the exact metric and tag names.

Troubleshooting

Out of memory errors

Because the monitoring is happening outside your application, we don’t expect there to be a significant impact on your instance performance or stability. If you do experience problems, you can disable JMX and app monitoring.

In the event of out of memory errors (OOME) caused by the monitoring agent, see Bitbucket is reaching resource limits

Last modified on Apr 26, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.