Enable Byteman for additional logging in Fisheye and Crucible

Still need help?

The Atlassian Community is here for you.

Ask the community


While troubleshooting issues, the support team can request to enable Byteman so that additional logging is generated.

This page explains how to enable Byteman and covers the most common issues and how to address them.


Enable Byteman

On Linux:

  • Create a file called byteman_rule.btm on the server hosting Fisheye
  • Add the content provided by support to the file
  • Set the following environment variables
# Enable Byteman
# Specify the path to the byteman rule file
export FISHEYE_BYTEMAN_SCRIPT=</path/to/byteman rule file>
  • Stop Fisheye/Crucible
  • Start Fisheye/Crucible
  • From the command line on the server, run the following command to load the Byteman rule
cd <Fisheye installation directory>/tools/byteman
./load-rules.sh </path/to/byteman rule file>/byteman_rule.btm 
  • Typically at this stage, it is required to reproduce the problem

On Windows (not running as a service):

  • Create a file called byteman_rule.btm on the server hosting Fisheye
  • Add the content provided by support to the file
  • Stop Fisheye/Crucible
  • Using the start.bat script from the bin directory of your Fisheye Installation Directory, start Fisheye with the SET FISHEYE_LOAD_BYTEMAN=1 flag before it. So it should look something like this in the terminal:

    CMD /C "SET FISHEYE_LOAD_BYTEMAN=1 && start.bat"
  • Allow Fisheye to complete its startup first and ensure that you're able to access the UI
  • When the UI is available, navigate to <Fisheye installation directory>/tools/byteman
  • Execute the script load-rules.bat \path\to\byteman_rules.
  • At this stage, reproduce the problem

On Windows (installed as Windows service by installer):

  • Stop Fisheye service
  • Edit the service:

    <Fisheye installation directory>\bin\service.bat manage
  • Switch to Java tab
  • Append to the java options:

    -javaagent:<Fisheye installation directory>\tools\byteman\lib\byteman.jar=listener:true,script:<path\to\script>
  • Save the changes and start the service

Disable Byteman / Load new rules

Once the issue has been reproduced or if new rules need to be loaded, the following command can be used to unload the current ones:

cd <Fisheye installation directory>/tools/byteman

In case of byteman has been set via javaagent, just remove that line from the service configuration.

Check if Byteman has been enabled


  • Once Byteman has been activated and the problem has been reproduced, the Fisheye logs will contain a reference to Byteman
# The line will be different depending on the Byteman rule but the "Byteman" reference will be available
INFO  [main ] Byteman NativeMethodAccessorImpl-invoke0 - -> CrossRepLuceneIndex#removingRepoFromIndex(<repository name>)


The application.xml, a file generated when creating a Support Zip but not available on the server, will contain the following additional lines:

<FISHEYE_BYTEMAN_SCRIPT></path/to/byteman rule file>/byteman_rule.btm</FISHEYE_BYTEMAN_SCRIPT>

Common issues

Connection refused

One of the Byteman commands fails with Connection refused:

./load-rules.sh </path/to/byteman rule file>/byteman_rule.btm 
Failed to process request: java.net.ConnectException: Connection refused
java.net.ConnectException: Connection refused
at java.net.PlainSocketImpl.socketConnect(Native Method)
at java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:345)
at java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:206)
at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:188)
at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392)
at java.net.Socket.connect(Socket.java:589)
at java.net.Socket.connect(Socket.java:538)
at java.net.Socket.<init>(Socket.java:434)
at java.net.Socket.<init>(Socket.java:211)
at org.jboss.byteman.agent.submit.Submit$Comm.<init>(Submit.java:881)
at org.jboss.byteman.agent.submit.Submit.submitRequest(Submit.java:787)
at org.jboss.byteman.agent.submit.Submit.listAllRules(Submit.java:176)
at org.jboss.byteman.agent.submit.Submit.main(Submit.java:1121)
fisheyeuser@minntest3:/Atlassian/fecru/tools/byteman$ org.jboss.byteman.agent.submit.Submit


  • Make sure that Fisheye is up and running
  • Make sure that the Environment variables have been correctly set before starting Fisheye

Last modified on Aug 5, 2020

Was this helpful?

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