Binocular

Binocular is a tool for visualizing data from various software-engineering tools. It works as a command-line tool run from a git-repository. When run, Binocular will gather data from the repository and the GitHub or GitLab API and persist it to a configured ArangoDB instance.

Binocular then hosts interactive visualizations about the gathered data via a web-interface.

Features

Binocular provides visualizations across several categories:

• Commit Analytics - Track code changes, additions/deletions over time, and author contributions
• Issue Tracking - Visualize issue lifecycles, sprint progress, and burndown charts
• Build Monitoring - Monitor CI/CD pipeline status and build success rates
• Code Ownership - Analyze who owns which parts of the codebase over time
• Developer Expertise - Assess knowledge distribution and expertise areas across team members
• Team Collaboration - Discover collaboration patterns and team dynamics through network graphs
• Repository Statistics - Overview dashboards with key project metrics

Preview

• Demo Page
• Screenshots

Dependencies

• node.js 20 LTS
• ArangoDB (tested with 3.12)

Running ArangoDB with Docker

If you don't want to install ArangoDB locally, you can run it using Docker:

docker run -d --name binocular_db -p 8529:8529 -e ARANGO_NO_AUTH=1 arangodb:3.12

Or use the provided docker-compose to start only the database:

docker compose up db

This will start ArangoDB on port 8529 with no authentication. You can then run Binocular locally against this database.

Installation

Binocular is not yet published on the npm registry. To install it, you should clone this repository and then link it:

$ git clone https://github.com/INSO-TUWien/Binocular.git
$ cd Binocular
/Binocular $ npm install # <- this will install the dependencies Binocular needs
/Binocular $ npm link    # <- this will make the `Binocular` executable available in your $PATH

Configuration

As Binocular needs to access an ArangoDB instance (run binocular setup to access the ArangoDB download page), you have to configure the database connection before you can use Binocular. This can be done in the global Binocular configuration file ~/.binocularrc. Additionally, the configuration file also stores authentication credentials for the used APIs. The configuration file is read by the rc module. Check its documentation to see the supported formats. For the purpose of this README, we'll use json.

For simpler configuration there is also a configuration assistant avaliable by executing binocular setup. It will ask you some questions about the repository and generate the config file for you.

Configuration options

• gitlab: Object holding gitlab configuration options
  • url: The URL to the GitLab-Instance you want to connect to. Use the base-url, not the API-URL (see the example)!
  • project:
  • token: The personal access token generated by your GitLab user to use for authentication (see https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
• github: Object holding GitHub configuration options
  • auth: Can hold any options that the [github npm-module] can take, check its documentation.
• arango: Object holding arangodb-configuration
  • host: Hostname
  • port: Port
  • user: username
  • password: password
• travis: Object holding travis-ci configuration options
  • token: (Optional for public repositories) holds the different access tokens for public and private repositories (https://blog.travis-ci.com/2013-01-28-token-token-token)
    • access: Access tokens are used to interact with the Travis API
    • travis: If you want to display the status image for a private repository.
  • timeout: (Optional) set the timeout to cancel api request
• indexers: (Optional) Object holding indexer configuration options. Should only be used if the repository could not detect the indexers automatically.
  • its: Holds the name of the issue tracking system indexer, for instance, GitLab or GitHub
  • ci: Since the CI indexer importer is searching for the corresponding file in the repository, it can be necessary to specify the correct indexer like, for example, GitLab or GitHub.
• fileRenameBranches: Array containing all branches for which file renames should be indexed. Additions to files that were later renamed are therefore shown in the visualizations. Without tracking renames, addition numbers for authors may be inaccurate. Comes with a performance penalty at index time.
• ignoreFiles: Array containing files/directories ignored by the indexer. Useful for large files (like package-lock.json) or irrelevant directories. Wildcards (*) are supported, see example below.

A sample configuration file looks like this:

{
  "gitlab": {
    "url": "https://gitlab.com/",
    "token": "YOUR_GITLAB_API_TOKEN"
  },
  "github": {
    "auth": {
      "type": "basic",
      "username": "YOUR_GITHUB_USER",
      "token": "YOUR_GITHUB_OAUTH_TOKEN"
    }
  },
  "arango": {
    "host": "127.0.0.1",
    "port": 8529,
    "user": "YOUR_ARANGODB_USER",
    "password": "YOUR_ARANGODB_PASSWORD"
  },
  "indexers": {
    "its": "github",
    "ci": "github" 
  },
  "fileRenameBranches": [
        "main",
        "develop"
    ],
    "ignoreFiles": [
        "*package-lock.json",
        "*docs/*"
    ]
}

You may override configuration options for specific projects by placing another .binocularrc file in the project's root directory.

You may also modify a config to the gitlab.json file in ./binocular-frontend/config. This file sets the GitLab API settings for the CodeHotspots-visualization for offline execution. This is only necessary if you want to automatically set those options within, for example, a GitLab pipeline.

Configuration options

• server: GitLab API server url
• projectId: GitLab project ID

A sample configuration file looks like this:

{
  "server":"GITLAB_API_URL",
  "projectId":"GITLAB_PROJECT_ID"
}

Usage

Binocular uses a command-based CLI. The main commands are:

• binocular run [targetPath] - Execute the backend indexer
• binocular build - Build the frontend
• binocular export - Export the database
• binocular setup - Configure Binocular

Running Binocular

To run Binocular, execute binocular run from the repository you want to analyze (you can try it on the Binocular-repo itself!). Binocular will try to guess reasonable defaults for configuration based on your .git/config.

Common options for binocular run:

• --no-vcs - Disable Version Control System indexing
• --no-its - Disable Issue Tracking System indexing
• --no-ci - Disable Continuous Integration indexing
• --export - Export the database after indexing

Development

For development, you can run the backend and frontend separately:

npm run dev

Or on Windows (does not support chaining of commands):

npm run dev:concurrently

This will start both the node backend and the frontend dev server.

If you run Binocular for the first time, it may show errors for missing JSON files. This happens because to build the frontend it needs an export of the database. When the indexers finish, it will create the database export automatically.

After the exported JSON files of the database are available, you can build an offline executable version of Binocular:

npm run build:offline

This will create an html and js file in the dist folder that can be opened without the backend running. It is also possible to place exported JSON files from a different mining job under ./binocular-frontend-new/db_export/ and build the frontend. (Not all features will be available in the offline build.)

For more information check binocular -h

Running Frontend Only

To install and run only the frontend:

npm run install:frontend
npm run dev:frontend

Contributors

Core Team

Johann Grabner	Maximilian Zenz	Manuel Stöger	Michael Strasser
Bastian Ferch	Markus Gumpoltsberger	Kai Kastenmeier	Sebastian Watzinger

Bachelor/Master-Theses

Roman Decker	Alexander Nemetz-Fiedler	Michael Thurner	Tamas Schöberl
Amar Kasic	Julian Kotrba	Matthias Weiß	Thomas Mörbauer
Michael Kurz	Valentin Schnabl	Solaiman Nejat	Christian Gröchenig
Rainhard Pfneiszl	Valentin Kastberger	André Mategka	Benedikt Eckerstorfer
Dominik Kidery	Peter Kotouč	Bálint Timár	Manuel Märzinger
Anton Martinovic	Valentin Futterer	Jakub Morávek	Ross Boulton
Martin Weber	Thimon Pelka	Sebastian Schuch	Sarah Biedermann
Mathias Trapl

Contributing

⚠️ Binocular is currently in a transition state from javascript to typescript. Although it is compatible with both javascript and typescript components, new visualizations should be implemented in typescript. Please refer to the change visualization/visualization Component if you are unsure how to implement a visualization in typescript.

For an explanation of Binocular's architecture, please see the Contribution guidelines for this project

For an overview of the database collections and connections Binocular creates, please see the database documentation