Maintenance Guide of ActivityTimeline Server/DC

Owned by Instructor
Last updated: Sept 03, 2024 by Oleh Vasyliv [Reliex]
8 min read

This page is an overview and a guide for a maintainer of ActivityTimeline app for Jira Server and Jira Data Center platforms.

It includes an architecture overview, configuration options and troubleshooting scenarios.

Architecture overview

ActivityTimeline app for Jira Server

ActivityTimeline app for Jira Data Center

 

In the diagrams above, “ActivityTimeline Service” corresponds to a child process that ActivityTimeline app starts. The app is using this process for synchronization between nodes as well as keeping the planning, tracking, work and report dashboards up to date.

This process automatically starts on a single node that is called a “Master node”. If the service is terminated on a Master node or the whole Jira Node goes down then another random alive node is automatically promoted to the Master node status. The ActivityTimeline Service will be automatically launched there.
ActivityTimeline Service automatically terminates itself on uninstallation/disabling the app or Jira shutdown.

All Jira DC nodes must be able to communicate between each other through http or https. So, it is required to have a <Connector> tag in each Jira DC node’s server.xml file with either “http” or “https” scheme.

 

Configuration options

There is a variety of configuration options within the app that are covered in the Admin and User Guides.
This section describes the additional optional settings that allow to tweak the launch parameters of the “ActivityTimeline Service” process.

The configuration options can be defined in a special service configuration file that is located at <JIRA_SHARED_HOME>/plugins/activitytimeline/config/at.properties file.

The settings should be defined in the following format, one per line:
NAME_OF_SETTING=VALUE_OF_SETTING

Here is the list of available options:

  • at.java_home.path specifies a path to java executable to launch the Service with.

    • It should be set only in one case - if Jira is not running on Java 8. Read more here.

    • Default Value: not set

  • at.java_startup.args - defines the list of additional java command line options when starting the ActivityTimeline service.

    • It is possible to set custom java heap memory settings, temp folder path etc.

    • Default Value: not set

  • at.service.port - defines port that ActivityTimeline will launch the service on. By default, the app picks a random free port available in the operating system. You may set this setting and the app will always use the specified port number.

    • Possible values: number in range between 1025 and 65536

    • Default Value: not set

  • at.manager_service.port - defines port that ActivityTimeline manager service will listen to. It controls the state of ActivityTimeline service. By default, the app picks a random free port available in the operating system. You may set this setting and the app will always use the specified port number.

    • Possible values: number in range between 1025 and 65536

    • Default Value: not set

  • at.jira_connection.url - Defines a local accessible Jira home URL or IP address with context path. This setting is determined automatically and there is no need to customize it in 99% of environments.

    • Allowed value: string, Url or IP address of Jira including context path. Example: https://1.2.3.4:8080/jira

    • Default Value: not set

  • at.jira.node1.url, at.jira.node2.url, at.jira.node3.url, at.jira.node4.url 9.4.0+at.jira.node5.url, at.jira.node6.url, at.jira.node7.url, at.jira.node8.url 9.6.0+
    These settings can override the connection URL of each Jira node. Allows to manually specify local URL of each Jira DC node (e.g. when using external proxy/lb, different docker public/private ports etc.). Supports up to 4 Jira DC nodes 9.4.0+ or up to 8 Jira DC nodes 9.6.0+.

    • Format: [node id]@[node url]

    • Example: "at.jira.node1.url=node-11111111@http://serveraddress:8080"

    • Default Value: not set

  • at.force_https_for_internal_communication_between_nodes - This setting can force internal communication to use https scheme instead of http. By default, the system automatically picks the proper scheme based on available Jira instance Tomcat connectors. It could be set to true only if there is a Jira Connector on https scheme with configured SSL on Tomcat: SSLEnabled=”true”.

    • Possible values: true; false

    • Default Values: not set

  • at.db_connections_max 8.2.0+ - This setting specifies the maximum number of active connections to database the app can maintain at any given time. By default, it can maintain up to 25 simultaneous active connections. The value must be larger than at.db_connections_max_idle and at.db_connections_min_idle.

    • Possible values: integer number starting from 10

    • Default Value: not set

  • at.db_connections_max_idle 8.2.0+ - This setting specifies the maximum number of idle connections to database the app can maintain at any given time. By default, it maintains up to 15 idle connections. The value must be larger than at.db_connections_max_idle and less than at.db_connections_max.

    • Possible values: integer number starting from 5

    • Default Value: not set

  • at.db_connections_min_idle 8.2.0+ - This setting specifies the minimum number of idle connections to database the app should maintain at any given time. By default, it maintains 1 idle connection. The value must be less than at.db_connections_max_idle and at.db_connections_max.

    • Possible values: integer numbers starting from 1

    • Default Value: not set

  • at.use_v2_communication 9.8.1+ - This setting specifies the approach version of communication between Jira DC nodes. Set it to “true” to enable the v2 of the communication mechanism. Remove the setting altogether or set it to an empty value to keep the current v1 approach.
    By default, it uses v1 communication mechanism.

    • Possible values: true or empty

    • Default Value: not set

 

It is required to restart the “ActivityTimeline Service” from the Maintenance Page or disable/enable ActivityTimeline app from the “Manage apps” page for the changes to take effect.

 

Troubleshooting

This section describes possible error conditions and ways to troubleshoot or fix them.
If none of troubleshooting options helps then you can contact us by creating a support request at
https://reliex.com/support/ link.

Please make sure to include logs from all Jira nodes as well as ActivityTimeline log zip file in the request:

  • Jira logs can be downloaded at Jira → Administration → System → Troubleshooting and support tools → Create support zip → Create zip button.

  • ActivityTimeline logs can be downloaded from ActivityTimeline Maintenance Page at Jira → Administration → Manage Apps → ACTIVITYTIMELINE section on the left panel → Settings → Maintenance Page → Download Logs button at the bottom of that page.

Symptoms:

Empty page or infinite loading animation when accessing any ActivityTimeline menu page

This usually happens if there is no connection between ActivityTimeline app/Jira and the ActivityTimeline service process; Or when ActivityTimeline service cannot start.

Troubleshooting options:

  1. Make sure there is at least 1.5GB of free RAM still available for Jira process before enabling ActivityTimeline app. ActivityTimeline app & service is using up to 1GB of RAM in the default configuration.

  2. before 9.0.0 Make sure Jira is running on Java 8. If Jira is running on Java 11 or higher then please make sure to follow this guide to configure ActivityTimeline service to utilize Java 8 even if Jira is running on Java 11 at this page: ActivityTimeline on Jira Server/DC that is running on Java 11

  3. If Jira instance is configured to have just an AJP Tomcat connector for communication with Apache HTTPD proxy service then it is required to add an additional http or https scheme Connector in Jira’s Tomcat server.xml configuration file.

  4. Check firewall rules. Please make sure the firewall does not block local (localhost) connections between Jira process and ActivityTimeline process or their ports. You may set specific ports for ActivityTimeline service/manager service (mentioned above) if you would like to define specific firewall rules for them.

  5. Check the antivirus software configuration and its vault on the Jira server. An antivirus software may quarantine the app file or block the service process in very rare cases.

 

Updates from Jira are not reflected on ActivityTimeline dashboards

This can happen if the synchronization job fails to pull the latest incremental updates from Jira API.
For example, if the specific user was set as Synchronization User and then got disabled or removed from Jira later on.

Troubleshooting options:

  1. Update the default Synchronization User (admin user who installed the app) or “ActivityTimeline Addon Sync User” (addon_activitytimeline_sync_user) if:

    1. that user was disabled or removed from Jira

    2. that user does not have Browse Project permission to specific Jira Projects

  2. Open Jira → ActivityTimeline → Configuration → Setup Wizard page. Choose to use the current user or custom app user (addon_activitytimeline_sync_user) and click the NEXT button. You may close the page now and skip the remaining steps of Setup Wizard as the synchronization user is already updated and saved.

 

Issues from some projects are missing on ActivityTimeline dashboards

This can happen if the specific projects are not enabled to be managed within ActivityTimeline app or the synchronization user does not have Jira permission to “see” issues of that project (Browse Project permission).

Troubleshooting options:

  1. Check if that project is enabled in ActivityTimeline at Jira → ActivityTimeline → Configuration → Projects page. Check if there is a checkbox ticked next to the missing project. Tick that checkbox and then click on a small green sync icon next to it to reload/refresh issues of that project into ActivityTimeline dashboards.

  2. Check permissions of Synchronization user (you may login into Jira as that user and check if issues or required projects are visible to that user).

 

ActivityTimeline dashboards behave slower than usual

This can happen if there is an increased number of simultaneous users that perform changes on ActivityTimeline dashboards, generate reports and track time.

Troubleshooting options:

  1. Increase the default memory limit for ActivityTimeline app/service. Instructions are available at the following page: Increasing memory for ActivityTimeline Service on a large Jira Server/DC instance

 

The previous ActivityTimeline service process did not stop after Jira restart

This situation can happen on a very rare occasion when there are not enough system resources like RAM to initiate a proper shutdown of ActivityTimeline service and free up its resources.
By default, ActivityTimeline service checks if it is bound to a Jira/ActivityTimeline app process every 10 minutes. If it finds out that it is an orphan (was linked to the previous Jira process) then it will automatically terminate itself.

Troubleshooting options:

  1. If ActivityTimeline did not shutdown itself properly after more than 15 minutes then it is possible to simply kill the process using native Linux or Windows commands/UI.

  2. You can find the process by the launch parameters of the process and terminate it manually:

    1. Linux:

      1. ps -ef | grep ActivityTimelineService.jar

      2. sudo kill -9 <PROCESS_ID_FROM_PREVIOUS_COMMAND>

    2. Windows

      1. Open process explorer

      2. find java.exe process that has ActivityTimelineService.jar listed in the launch parameters

      3. terminate that process

 

ActivityTimeline is not accessible from non-master node

Users are reporting that ActivityTimeline is not functioning for some users, displaying the error message: “ActivityTimeline is initializing, it can take up to 3 minutes to finish.”

Troubleshooting options:

  1. Verify Connection Errors on Non-Master Nodes:

  • Navigate to the maintenance page to check for connection errors on non-master nodes.

  • Ensure the URL specified under ‘Node URL’ in the master node section on the maintenance page is accessible from each node:

  1. Configuration of Node URLs:

  • ActivityTimeline connects to the nodes using URLs, not IP addresses. Therefore, it is essential to map node URLs to their corresponding IP addresses.

  1. Updating Hosts File (Linux Example):

  • Open the /etc/hosts file and update the configuration to include the IP addresses and server names of each node. Example:

10.0.0.1  node1servername
10.0.0.2  node2servername
10.0.0.3  node3servername 

  1. Alternatively, you can assign node URLs in the configuration file. Example:

at.jira.node1.url=node1@http://10.3.14.41:8080

at.jira.node2.url=node2@http://10.3.14.42:8080

at.jira.node3.url=node3@http://10.3.14.43:8080

  1. Restart ActivityTimeline:

  • After updating the configurations, perform a force restart of ActivityTimeline from the maintenance page.

 

If you are experiencing some other problem that is not described here, please don’t hesitate to contact our team at support@reliex.com.